数据库与初始化数据
跑起来需要什么
PostgreSQL 与 Redis 7+。单节点 PG 即完整 ACID,事务不再对部署拓扑有要求(MongoDB 时代必须是 副本集,这一维已随 ADR 0021 消失)。本地开发用 apps/server/docker/docker-compose.dev.yml 一条 docker compose up -d 起齐库与缓存。
连接参数由后端那份 env 决定(apps/server/env-local/.env.${NODE_ENV ?? development} 里的 DATABASE_PG_* 一组:host / port / user / pass / name),不是一条拼出来的 URI —— 这一点决定了 下面的工具都按同一份 env 连接。
表结构由 TypeORM migration 管理(迁移文件跟 api app 走,应用启动不自动跑迁移), 首次初始化在 apps/server/ 下执行:
pnpm migration:run # 结构演进只经显式命令;回滚对应 migration:revert初始化数据(seed)
装好库、跑完 migration、再播一条命令,应用就能起来:界面有字、权限树完整、请求签名可用的密钥也就位了。
pnpm db:seed:pg # 幂等:按 id upsert,重复跑安全
pnpm db:seed:pg --dry-run # 只看会写什么,不落库
pnpm db:seed:pg --only sys_role # 只播某几个集合数据本身在 apps/server/db/seed/, 格式是每个表一个 PG 行数组:{ "id": "<uuid>", "created_at": "2026-…", … }(列名就是 PG 列名, 时间列是 ISO 字符串,jsonb 列是 JSON 值),junction 表(sys_user_role / sys_role_menu)各有独立文件。 没有中间映射层:文件里是什么列就写什么列,列/主键/外键/jsonb 的判据全部从 PG 元数据读 (播表顺序 = FK 拓扑序、自引用 FK 按深度排序、jsonb 绑参前 stringify)。
2026-11 批次 5-B 之前这里存的是 Mongo Extended JSON(
{"$oid": …}/{"$date": …}), 靠 938 行seed-map.ts在运行期映射 —— 加一列要同步改映射且没有门禁。重建后packages/tooling/scripts/src/db/ejson.ts只保留「导入历史导出」的能力,不再是真源格式 (pnpm lint:seed会把残留的$oid/$date判红)。
仓库是这份数据的唯一真源,而且 seed 是幂等可重放的(已存在的行整行刷新为仓内值,junction 只补缺不回收,密钥缺了才现造):
pnpm lint:seed # 形态门禁:必需/禁入表、体积、凭据形状、引用完整性、无 EJSON 残留
pnpm db:seed:pg --admin <账号> --password <口令> # 在**本环境**给某账号建口令凭证并当场验证登录再生成真源是两步、不手写任何一行:
pnpm db:export:pg --out apps/server/.tmp/pg-export # ① 库 → 快照(Extended JSON,uuid 本体)
pnpm db:seed:reshape --from apps/server/.tmp/pg-export # ② 快照 → 行形态(默认写仓内 seed)db:export:pg 的两个行为(批次 5-B,2026-11-03 起改的,别按旧习惯写命令)
- 默认输出目录就是
apps/server/.tmp/pg-export(DEFAULT_EXPORT_OUT)——上面第 ① 步的--out可以整段省略,省了不报错、也不落进仓里;显式写出来只是让命令自解释。 默认值指向临时目录是有意的:快照是中间物(消费方是db:seed:reshape),不是真源。 --out指到apps/server/db/seed会直接失败:命令在连库之前就抛PreconditionError—— 终端上是「前置条件未满足:导出结果不能写进 seed 目录…」, 退出码 2(0 通过 / 1 查出违规 / 2 前置条件未满足,口径在packages/tooling/scripts/src/lib/cli.ts),一个文件都不会写。 理由:那里是行形态真源,把 Extended JSON 快照写进去等于把真源打回旧格式(pnpm lint:seed也会判红)。--anonymize是另一条同样的红线(脱敏有损,永远不许覆盖真源)。
⚠️ 拦截判据是「
--out等于 seed 目录」,不包括它的子目录 —— 别把快照放进apps/server/db/seed/下面的任何一层,那里除了行形态真源不该有别的东西。
两步之后 git diff 就是「库与仓的差」,逐行可审。db:export:pg 的产物仍按 _id 排序、套同一份 裁剪规则(policy.ts),所以快照 diff 与仓内文件 diff 同形。
改动 seed 形态 / 映射表 / 播种器之后,跑一次双库对拍(旧 seed + 旧管线 与 新 seed 各灌一个空库, 逐表逐列比 + 导出文件比):
pnpm db:seed:verify # 对着 07dacfd6(批次 5-B 基线)
pnpm db:seed:verify --baseline-ref <sha> # 换基线它会 DROP/建 walnut_seed_a / walnut_seed_b 两个库(不碰现有库),基线代码与数据从 git 取 (apps/server/.tmp/seed-verify/,gitignored)。它不进 prepush/CI:需要真实 PG 实例。
口令为什么不随仓库发:OPAQUE 的服务端 serverSetup 就是 AUTH_OPAQUE_SECRET,客户端的注册 记录由 OPRF 输出派生的密钥加密 ⇒ 换一个 secret 必然登不进去。所以 seed 只发无凭证的账号档案, 口令由 --admin 在目标环境现生成(走与线上完全相同的协议),并在写入后跑一遍完整登录握手验证。
哪些数据刻意不在仓里
| 不在仓里的 | 为什么 | 谁来补 |
|---|---|---|
密钥表(app_key) | 里面是真实密钥材料(RSA 私钥 PEM、AES key)。提交进公开仓既是泄密,也会被本仓的凭据门禁判红 | db:seed:pg 现生成一套 ACTIVE 的 AES + RSA —— 每个安装各自一套,本来也更对 |
口令凭证(sys_user_identity) | OPAQUE 的注册记录绑定服务端的 AUTH_OPAQUE_SECRET(该 secret 就是 OPAQUE 的 serverSetup)⇒ 换环境必然登不进去,发布它等于发布一份在别人机器上无效的凭证 | 装好后走应用的注册流程建立第一个管理员;演示账号用 --admin 现建 |
| MFA 密文 / OAuth 绑定 | 密文用 env 密钥加密(跨环境解不开),且属用户隐私;OAuth 是运行时状态 | 各自在使用中产生 |
用户设备(sys_device / sys_user_device) | 设备信息、IP 与地理位置历史 —— 运行时状态 + 个人数据。设备指纹不落库、不参与身份派生:B5 起 device_id 由服务端随机签发,客户端自报的指纹只在请求面当风控特征 | 各自在使用中产生 |
行政区划(shared_area) | 数量巨大的参考数据,不是配置,刻意不进 git 也不进发版资产 | 本仓的历史数据由 ETL 一次性搬入(见下节归档说明);跨环境搬运走 pnpm db:export:pg --areas <文件> 另存的资产 |
一次性历史任务:Mongo → PG 的 ETL(已归档)
本地存量数据从 MongoDB 搬进 PostgreSQL 走的是 ETL 通道(读本地 Mongo、映射写入 PG,id 由 ObjectId 经 uuid v5 派生,派生实现见 packages/tooling/scripts/src/db/uuid5.ts)。它是一次性历史 任务(ADR 0021 Decision 6:本地为准、线上不迁),Mongo 读取端、打包入口与运行期映射层 (seed-map.ts)已随 2026-11 批次 5-B 全部退役 —— 现在 id 只存在于数据里(seed 文件写 uuid 本体), 运行时不再有派生步骤。要复核迁移正确性时,判据是行级的:同 id 即同源,按表对行数与抽样字段。
注意:这不是"清库工具"
db:seed:pg 只做 upsert,不删库里多出来的行 —— 别指望它把开发数据扫干净。 要重建一个干净环境:清掉 schema(或换一个库名)→ pnpm migration:run → pnpm db:seed:pg。
环境之间的数据流动:三个通道(不做库对库的双向同步)
开发环境与线上环境之间总有数据要来回走,但成熟做法不是把两个库同步起来,而是按数据性质拆成三条 单向通道,中间用一个可审阅的边界连接。判据只有一句:这条数据该不该进仓库?
通道 1:参考数据(菜单 / 字典 / 语言包 / 应用设置)—— 仓 → 各环境,单向
这是"双向需求"的真实来源:你在开发库调菜单,线上运营也在后台改菜单。正确做法是给这条链加一段回灌, 而不是加一个同步:
- 线上被人改过 →
pnpm db:export:pg拉回仓库形态 → 与仓内 seed 做行级对账(导出按 id 排序、 套同一份裁剪规则,diff 可审); - 差异进 PR 审 —— 这一步才是关键:它把"谁改的、改了什么、要不要带走"变成可追溯的决策;
- 合并后再随发版推到各个环境。
往生产推:部署工作流每次部署都会跑 db:seed:pg(按 id upsert,库收敛到该 tag 的仓内形态, 见 deploy/README.md)—— 所以运维在后台改过的行必须走上面的回灌进仓,否则下次部署会被冲掉。这是相对 mongoimport 时代 "非空整集跳过"的有意变更:跳过语义有个结构性副作用(后续版本新增的行永远到不了已有数据的库), 收敛语义没有。手工侧就是同一条 pnpm db:seed:pg(幂等,重放收敛到仓)。
部署侧的操作步骤与复核命令见 deploy/README.md 的「首次部署后注入参考数据」。
推送方向永远是仓 → 环境。环境上的运行时数据(用户、日志、设备、业务单据)不属于这条通道 —— 它们不该被同步,各环境各活各的。判断标准:它该进仓吗?不该进的数据,也不该被"同步"。
通道 2:线上 → 开发(排障、复现)—— 单向 + 必须脱敏
# 从线上拉一份快照到本地(脱敏是有损的,所以必须换一个目录,别覆盖仓内 seed)
pnpm db:export:pg --anonymize --out apps/server/.tmp/prod-snapshot- 导入前必须过一遍脱敏(邮箱、手机、设备指纹、IP 与地理位置历史、MFA 密文都属个人数据)。
- 脱敏规则在
packages/tooling/scripts/src/db/anonymize.ts:按键名判定(不按表路径 —— 路径写法等于把 schema 抄一遍,字段一改规则就静默失效),掩码保留形状(邮箱a***@example.com、 手机138****1111、IP203.0.*.*、密文<redacted:32>、坐标降到城市级)。规则库无关, 直接作用在反向映射后的文档上。 - 同一套规则也挂在
pnpm lint:seed上:仓内 seed 里出现未脱敏的个人数据会被点名到字段路径。 - 反向(开发 → 线上)不做:把开发库的数据直接写进线上,主键冲突事小,同文档互相覆盖与 "删除算谁的"事大。
通道 3:开发 → 线上的业务数据 —— 不做同步,做成"版本化数据变更"
要往线上多几条字典/菜单/设置:把它写进仓(通道 1),随发版走。 PG 世界把"结构变更"制度化这件事,本仓就是 TypeORM migration 本身(migration:run 跑显式命令、 迁移文件进 PR 审,见上文);真要迁一批业务数据(整理好的组织、用户等):写成一次性、有版本号、 可回滚的迁移脚本(migration 或幂等 SQL),同样进 PR 审。
什么时候才该考虑"实时双向"
只有一条:两个环境都要能写同一批数据,且必须秒级互相可见。那是另一个量级的工程, 成熟选项只有三类:
- 逻辑复制(PostgreSQL 内置 publication / subscription,或 pglogical 这类扩展);
- 触发器队列 / CDC 自研消费者(灵活,但槽位管理、目标端映射、消费监控全要自己管);
- 云厂商 DTS(开箱即用,但绑定云环境,私有化场景不可用)。
代价清单必须提前认下来:同表并发写的冲突解决、删除语义、复制槽与 WAL 容量窗口、断点续传、 一致性校验(行数 + 抽样哈希)、延迟告警,以及双向必须防回环。给一个中后台模板项目上这套, 维护成本远超收益 —— 真要做,务实做法是按表拆单一写入方(例如语言包只允许开发环境写、 用户数据只允许线上写),而不是全库双向。
参考:PostgreSQL 逻辑复制官方文档 (publication / subscription 模型与冲突语义)、 生产数据脱敏克隆到本地这类工具的设计。