- 新增 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 只编本仓
9.4 KiB
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
首次启动会:
- 打开
data/tdc.pg(pglite 进程内 PostgreSQL),不存在则按schema/migrate.sql建 30 张tdc_*+ 3 张base_*表; - 引导连接器身份(
tdc_identity)⇒ 首次会打印一次性secretKey(只打一次,抄下来); - 引导账号层(
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 登录报「账号或密码错误」
排查顺序:
- 账号存在吗?⇒
GET /api/permission/Users(需管理员会话或内部令牌)。 - 账号被禁用了吗?⇒ 出参
enabledMark;禁用 ⇒ msg 是「账号已被禁用」。 - 口令公式对吗?⇒
f_password = md5(lower(md5(明文)) + lower(f_secretkey))(见docs/ACCOUNT-LAYER.md§2)。 - 🔴 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/ |