Files
tdc-rs/docs/runbook.md
T
admin 400d883e1a feat(p6): 平台改为预编译 rlib 接入,依赖全部来自包内闭包
- 新增 scripts/fetch-platform.sh:读 .sspf-version 解包 vendor/ + 生成 .cargo/config.toml(rustflags + rustdocflags),只校工具链 channel
- Cargo.toml 的 [dependencies]/[dev-dependencies] 清空:17 个 crate 全部 --extern 自平台闭包
- release profile lto 由 thin 改 false(平台 rlib bitcode-free,开 LTO 找不到 __bitcode)
- tower-http 不在闭包 ⇒ 自研 platform::static_files(ServeDir 等价,含 Range 206)与 platform::cors(permissive 等价)
- reqwest 与 extern tokio 双 runtime 必 panic(no reactor running)⇒ 自研 platform::http(HTTP/1.1 明文)
- tests/auth_flow 的 reqwest 调用改用 lib 客户端;tds_biz 的头白名单补 connection
- 新增尺子 check-platform-package.sh:依赖单一来源 + 真编一次证明平台闭包零重编
- 验收:cargo test 306 passed / 七把尺子 + 新尺子全绿;dev 构建 2.5s 只编本仓
2026-11-05 13:01:27 +08:00

9.4 KiB
Raw Permalink Blame History

Runbook(怎么起 / 怎么冒烟 / 常见故障)

🔴 本文件是运维视角的操作手册:起服务、跑尺子、排故障。 契约口径见 docs/contract.md;架构约定见 CLAUDE.md。


1. 起服务

1.1 最简(本地调试)

cd /Users/xs/Desktop/workspace/tdc-rs
bash scripts/fetch-platform.sh   # 首次/换机/升级平台包:取预编译 rlib 包(生成 .cargo/config.toml)
cargo build
PORT=30000 ./target/debug/tdc-connector

首次启动会:

  1. 打开 data/tdc.pg(pglite 进程内 PostgreSQL),不存在则按 schema/migrate.sql 建 30 张 tdc_* + 3 张 base_* 表;
  2. 引导连接器身份(tdc_identity)⇒ 首次会打印一次性 secretKey(只打一次,抄下来);
  3. 引导账号层(base_user)⇒ 建 admin 账号 + 种三个角色(幂等)。
curl -s --noproxy '*' http://127.0.0.1:30000/api/health
# ⇒ {"status":"UP",...,"tables":30,"baseTables":3}

🔴 本机 curl 走系统代理 ⇒ 打 localhost 必须加 --noproxy '*',否则得到 502。

🔴 首启会打印一次性 secretKey ⇒ 不要把 stdout 落进 /dev/null (进程会以 100 退出)或提交进仓库。

1.2 环境变量

变量 默认 含义
PORT 30000 监听端口
TDC_DATA_DIR <项目目录>/data 数据目录(绝对路径;pglite 会 chdir 进去)
SSW_INTERNAL_TOKEN ssw-internal-token-e2e 入向内部令牌(X-Internal-Token 头)
SSW_TDS_INTERNAL_TOKEN ssw-internal-token-e2e 出向 TDS 内部令牌(方向相反,别混用)
SSW_TDS_BASE_URL 空 TDS 出向地址;空 ⇒ NOOP 降级(不出网)
TDC_LOCAL_STANDALONE / TDC_STANDALONE 自动 单机模式(on/off)
TDC_STRICT_SECRETS 关 1 ⇒ 管理员仍用默认口令 ⇒ 启动即失败
TDC_IDENTITY_CODE LOCAL-CONNECTOR 本连接器的身份码
TDC_IDENTITY_NAME 本地连接器 身份名
TDC_IDENTITY_SECRET 随机签发一次 身份密钥(不设 ⇒ 引导时生成并只打印一次)
TDC_BOOTSTRAP_ADMIN_ACCOUNT admin 引导管理员账号名(只对空库生效)
TDC_BOOTSTRAP_ADMIN_PASSWORD admin 引导管理员口令(只对空库生效)

1.3 生产档最低要求

TDC_STRICT_SECRETS=1 \
TDC_BOOTSTRAP_ADMIN_PASSWORD='<强口令>' \
SSW_INTERNAL_TOKEN='<随机长串>' \
SSW_TDS_BASE_URL='http://<tds-host>:<port>' \
PORT=30000 ./target/release/tdc-connector

🔴 部署退出门槛(D11):账号发放只给受信人 —— 「任何登录用户可写全部 18 个实体」是上游同款(见 docs/known-limitations.md L4), 所以本机多一个普通账号 = 多一条全量写通道。

1.4 配 TDS(出向)

cd tds-stub && node server.js     # 契约桩,:30100
SSW_TDS_BASE_URL='http://127.0.0.1:30100' ./target/debug/tdc-connector

🔴 出向 reqwest 走 .no_proxy() ⇒ 不吃系统代理(内网直连)。


2. 跑尺子(四把)

尺子 命令 覆盖 期望
单元 / 集成 cargo test 进程内逻辑 全绿,0 failed
HTTP 契约 bash scripts/smoke.sh 状态码 / 响应头 / 原始 JSON / 4 种形状 / 隐藏字段 / 分页信封 PASS=80 FAIL=0
边界静态 bash scripts/check-boundary.sh 平台层不含业务知识 · 引擎零 match api_name exit 0
实体静态 bash scripts/check-entity.sh 表在 migrate.sql · 路由齐全 · hidden_fields · 编码前缀 PASS=13 FAIL=0
契约对账(B5 新增) bash scripts/check-contract.sh docs/contract.md 端点表 ↔ 实际注册路由 132 条端点 一致
# 一次跑完(建议改代码后都跑一遍)
cargo test && bash scripts/smoke.sh && bash scripts/check-boundary.sh \
  && bash scripts/check-entity.sh && bash scripts/check-contract.sh

🔴 跑测试前先看一眼信号量余量(见 §3.5)。

2.1 浏览器验收(人工)

docs/CONSOLE-ACCEPTANCE.md —— 上游 SPA(static/)的端到端验收清单。 🔴 自动化跑浏览器时用 aix(内核浏览器,不要起 Chromium);后台标签页会冻结 rAF / CSS transition(测试环境假象,见该文档 §5)。


3. 常见故障

3.1 curl localhost 得 502

根因:本机 curl 读系统 HTTP 代理,把 loopback 也劫持了。 处理:加 --noproxy '*'。

curl -s --noproxy '*' http://127.0.0.1:30000/api/health

3.2 postmaster.pid 锁冲突 / 起第二个实例就挂

根因:pglite 是单实例独占数据目录 ⇒ 同一个 data/tdc.pg 只能有一个进程。 处理:① 停掉占着它的旧进程;② 或给第二个实例不同的 TDC_DATA_DIR。

3.3 改了 schema/migrate.sql 但新表没出现

根因:启动探针只看「public schema 里有没有表」⇒ 有表就跳过整个迁移 ⇒ 上次失败留下的「建了一半」的库,此后每次启动都跳过迁移。 处理:

bash scripts/reset-data.sh      # 把 data/tdc.pg 移进访达回收站(可恢复)
# 再起一次 ⇒ 全量重建

🔴 reset-data.sh 不删文件,是 mv 到 ~/.Trash(访达回收站)。

3.4 /api/health 的 tables 不对

先核对 schema 文件:

grep -cE '^CREATE TABLE public\.tdc_' schema/migrate.sql   # 期望 30
grep -cE '^CREATE TABLE public\.base_' schema/migrate.sql  # 期望 3

tables / baseTables 是真查库(不是静态 JSON)⇒ 对不上就是 §3.3。

3.5 initdb failed: … could not create semaphores: No space left on device

根因:macOS 不回收进程退出时创建的 SysV 信号量集(且系统没有 ipcrm) ⇒ 每轮 cargo test 的 PGlite 实例各漏 20 个信号量 ⇒ 攒够就把 kern.sysv.semmns(87381) 撑满 ⇒ 任何新的 PG 实例都起不来。

处理:

bash scripts/reap-ipc-leaks.sh            # 回收
bash scripts/reap-ipc-leaks.sh --dry-run  # 只报不删

🔴 口径宁可漏回收,不误伤活进程:只回收 ① nsems==20(PGlite 指纹) ② 创建者 uid == 当前用户 ③ 最近一次操作距今 > 1 小时。

3.6 登录报「账号或密码错误」

排查顺序:

  1. 账号存在吗?⇒ GET /api/permission/Users(需管理员会话或内部令牌)。
  2. 账号被禁用了吗?⇒ 出参 enabledMark;禁用 ⇒ msg 是「账号已被禁用」。
  3. 口令公式对吗?⇒ f_password = md5(lower(md5(明文)) + lower(f_secretkey)) (见 docs/ACCOUNT-LAYER.md §2)。
  4. 🔴 B4 之前的老账号登不上(载体从 data/accounts.json 换成了 base_user, 存量不导入)⇒ 这是预期行为,不是 bug。

3.7 出向 TDS 得 502 / 连接超时

根因:reqwest 读了系统代理(HTTP_PROXY / macOS 网络设置)⇒ loopback 被劫持。 处理:出向客户端已用 ClientBuilder::no_proxy()(TDS 是内网直连服务); 若仍不通,先确认 SSW_TDS_BASE_URL 指向内网地址。

3.8 出向 TDS 拿到 200 却当成功

根因:TDS 业务失败也走 HTTP 200 + code != 200。 处理:判 body.code == 200(解包型端点 ⇒ src/tdc/client/tds.rs:38 的 unwrap_data)/ unwrap_envelope(整包型端点 ⇒ src/tdc/controller/tds_biz.rs:200) —— 别混用这两种返回风格。

3.9 405 返回 HTML / 丢 Allow 头

根因:用了 axum 的 method_not_allowed_fallback(只对调用那一刻已注册的路由生效)。 处理:用 src/platform/mw.rs:59 的 json_method_not_allowed(响应改写中间件,挂链尾)。

3.10 DDL 能从 HTTP 下载

根因:DDL 落在 web root。 处理:schema/migrate.sql 刻意不在 static/;另有两层兜底 (src/platform/fallback.rs 的 ddl_guard 前置守卫 + ddl_content_guard 内容兜底)。 🔴 Range 分段请求也要拦(该守卫已覆盖)。

3.11 cargo test 并行用例互相撞车

根因:tdc_identity 有唯一约束;账号层进的是共享的 per-binary PGlite。 处理:每个用例用唯一身份码 + 唯一账号名 (如 dave-upstream / bob-nonadmin / carol-manage)。


4. 危险操作清单

操作 后果 正确做法
rm -rf data/tdc.pg 数据不可恢复 bash scripts/reset-data.sh(⇒ 访达回收站)
同一 data/ 起第二个实例 pglite 锁冲突 换 TDC_DATA_DIR
手改 schema/migrate.sql 后不清数据 新表永远补不上 reset-data.sh 后重起
把 secretKey / 口令打进 stdout 日志 凭据外泄 首启打印只取一次;日志落 data/ 而非提交
未经明确要求 git push 未经审阅的推送 先问

5. 排障信息去哪看

想知道 去哪
对外契约(端点 / 形状 / 命名) docs/contract.md
为什么这么定 docs/decisions.md
已知偏差 docs/known-limitations.md
账号层细节 docs/ACCOUNT-LAYER.md
上游差异 docs/superpowers/2026-10-26-tdc-rs-upstream-diff.md
上游动作端点契约 docs/TDC-TDS-CONTRACT.md
浏览器验收 docs/CONSOLE-ACCEPTANCE.md
踩坑历史 CLAUDE.md §已知踩坑清单 + .workbuddy/memory/