Files
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

228 lines
9.4 KiB
Markdown
Raw Permalink 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
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://<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/` |