把 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]>
227 lines
9.3 KiB
Markdown
227 lines
9.3 KiB
Markdown
# 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/` |
|