# Runbook(怎么起 / 怎么冒烟 / 常见故障) > 🔴 本文件是**运维视角**的操作手册:起服务、跑尺子、排故障。 > 契约口径见 `docs/contract.md`;架构约定见 `CLAUDE.md`。 --- ## 1. 起服务 ### 1.1 最简(本地调试) ```bash 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` 账号 + 种三个角色(**幂等**)。 ```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://:' \ 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/` |