Files
tdc-rs/docs/runbook.md
T
adminandClaude Code 2e7f9b1975 feat(b5): 工程化外壳(文档层)—— 契约四件套 + 两本手册 + 第四把尺子
把 v3 spec §11.2 要求的整套文档层补齐,并把 spec §11.1 欠下的
「浏览器验收重跑」在真实上游 SPA 上补做完(内核浏览器 aix 驱动)。

新增文档:

- `docs/contract.md`(重写):**132 端点全表** + 4 种响应形状 + 数据模型 + 时间口径,
  唯一真源。端点表由 `scripts/check-contract.sh` 与源码注册路由**逐条对账**。
- `docs/decisions.md`(重写):逐条裁决 D1–D21。
- `docs/known-limitations.md`(重写):L1–L7,含 §5.4 权限敞开的显式条目(L4)。
- `docs/runbook.md`(新):怎么起 / 怎么冒烟 / 常见故障。
- `MIGRATION.md`(新):Java TDC ⇄ Rust 逐件翻译表 + 口令换算 + 数据 ETL。
- `HOWTO_ENTITY.md`(新):加一个实体(含子表挂载面)。
- `docs/ACCOUNT-LAYER.md`(新):`base_user` 账号层(官方双 md5 公式)。
- `docs/CONSOLE-ACCEPTANCE.md`(重写):**B5 重跑版**浏览器验收。

新增尺子(第四把 + 两把专项):

- `scripts/check-contract.sh`:端点表 vs 实际注册路由对账(132 == 132)。
- `scripts/check-citations.py`:文档里 `文件:行号` 引用逐条校验(139 条 0 失效)。
- `scripts/upstream-action-census.py`:上游动作端点普查(只读上游克隆,可复算)。
- `scripts/contract_probe.py`:动作端点形状探针(109 条逐条打过,零偏差)。

影响:

- **L5 数字纠正**:原先记的「111 条上游动作端点未实现」口径错了
  (`grep -rhoE` 只抓带参数的映射、且跨了全部 31 个控制器)
  ⇒ 真实数字 **109**(122 声明 − 11 CRUD 基线 − 2 聚合详情 = 26 形态 A + 83 形态 B)。
- **L7(新增)**:**26 条**上游动作端点**不会 404** ⇒ 被通用详情路由 `/{Entity}/{id}`
  吞掉(`src/tdc/controller/crud.rs:65-93`)⇒ GET 返回 **200 + `code:400`**、
  POST 返回 **405** ⇒ 上游前端下拉框静默变空。**只判 HTTP 状态码会误判成成功**。
- **CONSOLE-ACCEPTANCE §4 纠正**:服务目录 / 我的账单**已实现**(P4),
  失败点在**连接器身份闸门**(`f_tds_space_id` / `f_tds_connector_id` 为空 ⇒ 出向前 fail-closed),
  **不是** TDS NOOP 降级、也不是代理 404。
- `CLAUDE.md` 同步:目录树、红线、坑位表(「上游动作端点不 404」新增一行)。

实测:cargo test **246** 项全绿 0 failed(1 ignored)· smoke.sh PASS=80 FAIL=0 ·
check-boundary.sh exit 0 · check-entity.sh PASS=13 FAIL=0 ·
check-contract.sh 132 条端点一致 · check-citations.py 139 条引用 0 失效 ⇒ **六把尺子全绿**。

⚠️ 口径更正:此前(B4 提交信息与记忆文件)记的「172 lib + 62 集成 = 236」是**误数**
—— `src/` 与 `tests/` 自 B4 起未变,逐二进制实测就是 246 ⇒ 从本批起统一用 246。

Co-Authored-By: Claude Code <[email protected]>
2026-10-27 00:56:09 +08:00

227 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Runbook(怎么起 / 怎么冒烟 / 常见故障)
> 🔴 本文件是**运维视角**的操作手册:起服务、跑尺子、排故障。
> 契约口径见 `docs/contract.md`;架构约定见 `CLAUDE.md`。
---
## 1. 起服务
### 1.1 最简(本地调试)
```bash
cd /Users/xs/Desktop/workspace/tdc-rs
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` 账号 + 种三个角色(**幂等**)。
```bash
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 生产档最低要求
```bash
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(出向)
```bash
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 条端点` 一致 |
```bash
# 一次跑完(建议改代码后都跑一遍)
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 '*'`。
```bash
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
bash scripts/reset-data.sh # 把 data/tdc.pg 移进访达回收站(可恢复)
# 再起一次 ⇒ 全量重建
```
🔴 `reset-data.sh` **不删**文件,是 `mv` 到 `~/.Trash`(访达回收站)。
### 3.4 `/api/health` 的 `tables` 不对
先核对 schema 文件:
```bash
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
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/` |