admin/dsh_shenxian
1
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
e6207aa6914ff26bee7e999b72db153d00e2d096
dsh_shenxian/dsh-server-docs/03-数据库/DB-00-专区入口.md
T
admin e6207aa691
build / build-and-scan (push) Waiting to run
Details
chore(仓库对齐): 文档库结构治理 + IM/插件线落地 
文档库：目录改为编号制（01-规范/02-架构设计/03-数据库/04-调整方案/
05-交接单/06-ops/07-scripts/08-skills/09-archive），顶层散文件归入 01-规范/；
INDEX.md 与 docs-manifest.json 重刷（档案 146 篇）；旧目录名引用全量对齐。

IM 线：src/im/**（SDK / hub / store / presence / ws / gateway-token）、
src/web/routes/im.ts、src/db/plugin-data/**、src/supervisor/plugin-assembly.ts
及对应 test/**。

插件线：poc/{im-agent-bridge,im-connection-gateway,im-conversation-tabs,
business-plugins-im,carbon-mcp-probe}、src/web/routes/{sessions,overlay-device}.ts、
src/net/relay/{device-grant,instance-credential}.ts。

仓库卫生：清出 40 个历史误入库 / 已改名文件（34 个交接单归档 + 6 个旧结构，
本地均有副本）；dsh-server-docs/.gitignore 补 tmp/；交接单不入库（政策）。
2026-09-24 07:25:16 +08:00

5.6 KiB
Raw Blame History

数据库专区 · 00 专区入口

状态：✅ 已落文档库（2026-09-20）｜ 专区：03-数据库/

目标位置 = 文档库新目录 dsh-server-docs/03-数据库/（与本 README 同级放置 01 / 02 / 03）。 立稿：2026-09-20 ｜ 起草会话 IM插件数据面-专门文档## 这是什么

「数据怎么存、存哪、怎么演进」的单一入口。 平台里凡涉及"要持久化"的事（账号 / 房间 / 插件数据 / 用户文件 / 大对象 / 缓存队列），都先来这里对一遍判据，再动手。

什么时候读：① 要新增任何持久化结构；② 要接数据库（含插件）；③ 要改表结构 / 加迁移；④ 判断"这份数据该放哪一层"。

目录

文档 回答什么问题
DB-00-专区入口.md（本文件） 专区怎么用、有哪几份、迁入清单
DB-01-接入指南.md 各种情况怎么接：内核表 / 插件表 / 实例 home / Worker 本地库 / 大对象桶 / 缓存队列（6 种情形逐条给「判据 + 怎么做 + 禁止 + 验收」）
DB-02-表结构台账与迭代.md 表结构持续迭代：迁移台账（v1–v13 现状 + 规划 v14）· 内核表全集 · 三条硬纪律 · 四步跨版本 · 评审门禁 · 台账维护规则
DB-03-插件数据面规范.md 插件那一侧的完整契约（声明式建表 / 迁移 / 访问 API / 配额审计 / 卸载）—— 见本目录 DB-03-插件数据面规范.md

判据速查（2026-09-22 按「一插件一库」更新）

  1. 先判库：跟平台全局走 ⇒ 控制面库 dshs；跟某个用户走 ⇒ 该插件的库 dshs_pl_<pluginId> 内带 user_id 的行；跨用户共享 ⇒ 同库内带 room_id 的行；是文件内容 ⇒ 对象存储（库里只存索引）。
  2. 库名即归属：控制面库 = dshs；插件库 = dshs_pl_<pluginId>（每插件一个，同一 PG 13.23 实例）；看不到第三种。库内表名 p_<pluginId>_* = 该插件的表。
  3. 不直连：插件（乃至任何业务代码）不持有连接、不写 SQL，一律走内核 API；库路由由内核按调用方插件身份决定。
  4. 归属列强制：插件库内每张业务表必须带 user_id 或 room_id（内核构建时自动补）—— 这是「按用户备份 / 迁移」能成立的前提。
  5. 双后端：任何新结构都要在 sqlite 与 pg 上都建得起来（sqlite 下「一个插件 = 一个文件」）。
  6. 只增不减：加表 / 加列（带默认值）/ 加索引；改类型与删列走"四步跨版本"。

与既有文档的关系

  • 02-架构设计/数据-分库与权威存储架构.md（2026-09-22 定稿） ⇒ 分库与权威存储的架构定稿（分库维度 = 插件）；本专区是它的落地规范，冲突时以它为准。
  • 档案 142 §3.6（三条平台保护：插件不直连 DB / 插件故障不拖垮房间 / 能力吃预算）⇒ 本专区是它的落地规范。
  • 04-调整方案/140（配置外置） ⇒ 连接串 / 桶端点 / 密钥一律走 config/platform.env（不入库、默认值中性）。
  • 05-交接单/IM群组-01-房间内核与DB.md §九（内核侧裁决）与 D-插件SDK与扩展点契约.md §九（插件侧契约）⇒ 条款收拢进本专区，冲突时以本专区为准并回改那两处。
  • 类比：01-规范/06-工作台UI规范.md 之于界面 = 本专区之于数据。

迁入记录（2026-09-20 执行完毕，保留作追溯）

  1. 抢锁：bash dsh-server-docs/07-scripts/handoff-guard.sh --claim-exec "<会话名>"；抢不到 = 停手。
  2. 建目录并落文件：mkdir dsh-server-docs/03-数据库/ → 落 DB-00-专区入口.md（本文件改名）· DB-01-接入指南.md · DB-02-表结构台账与迭代.md · DB-03-插件数据面规范.md。⚠️ 新建目录不需要占号（04-调整方案/ 的 .lock-<NN> 规则只针对档案号）。
  3. 登记 INDEX.md（按该文件既有章节追加，只做单行追加）。
  4. 🔴 修正 A 单（最重要的一步，现状会误导执行者）：05-交接单/IM群组-01-房间内核与DB.md
    • 「只读前置 #1」把「现有迁移到 v11 为止 / 新增 v12」改为「最新已 v13（v12 = 序㊻ overlay_devices、v13 = 序㊼ 会话/设备类型）；IM 三表取 v14」；
    • 同时改掉原判据里「若已 >11 ⇒ 说明别人先做了 ⇒ 停手回报」—— 这句现在会误判，应改为「若目标版本已被占 ⇒ 取下一个空号，不要停」；
    • §五-1 的 SQLITE_V12 / PG_V12 同步改 V14。
  5. D 单 §九 顶部加一行指针：「完整契约见 03-数据库/DB-03-插件数据面规范.md」。
  6. 删草案（⛔ 不留双源）：确认落库无误后删除 tmp/数据库专区_草案_20260920/ 与 tmp/插件数据面规范_草案_20260920.md。
  7. 验收：python 07-scripts/docs-audit.py RC=0 / 无 P0；新档纯 LF（CR=0）；git status 只含本次声明文件。

待定

  • 插件配额具体数值（总行数 / 单行字节 / 每房行数）⇒ 与档案 142 §六-2（房间上限与发言预算）同一批压测标定。
  • im.data 是否提供聚合查询（groupBy / sum）⇒ 先只给 count。
  • 插件跨房共享表（scope: plugin）默认关闭，需 admin 审核后生效（对齐档案 142 §六-4）。
  • 主从落地时机：现在是单机 PG 13.23；只读副本等"读成为瓶颈"再上。
  • ⚠️ 原「⛔ 不提前分库」已作废（2026-09-22 用户拍板分库）：分库维度 = 插件，见 02-架构设计/数据-分库与权威存储架构.md。
Reference in new issue View Git Blame Copy Permalink