Files
ssw-jnpf-lite-rust/docs/runbook.md
T
admin fe9f84b7c1 refactor(skill): 改为依赖已发布的 sspf v0.4.0,删除自研平台、迁入示例业务包
- 平台改由 sspf 门面提供(workspace 锁 git tag v0.4.0),应用瘦成 ~500 行薄壳
- 删除 src/backend/src/platform(17 文件)、routes.rs、bootstrap.rs、db/schema.sql、7 个旧集成测试
- 迁入 4 个示例业务包 packs/{demo,shop,books,asset},依赖从 sspf-sdk 改门面 sspf
- 新增 check-scaffold.py(SC1-SC6 + 反自证 6/6)、重写 pack-sync.py、新增 new-pack 与 verify.sh
- 删除测「本仓平台实现」的四把静态闸门(platform 搬走后无测量对象,留着即假绿)
- 契约补入 asset:MENU_TREE 9 菜单、ENDPOINT +3、FACE A=28
- 前端 dist 入库(后端直接托管,免 npm build)
- 验收:check-scaffold 6/6 + 自证 6/6;perm-smoke 32/32;perm-smoke-jnpf 18/18;verify.sh 7/7
2026-11-04 22:36:13 +08:00

341 lines
19 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 —— ssw-jnpf-lite-rust 怎么起、怎么冒烟、坏了怎么办
> 契约见 [`contract.md`](contract.md);红线与坑位清单见 [`../CLAUDE.md`](../CLAUDE.md)。
---
## 0. 前置
| 工具 | 版本(本机实测) | 用途 |
|---|---|---|
| Rust | ≥ 1.85(edition 2021;本机实测 rustc 1.95.0) | 后端 |
| Node / npm | node v26.8.1 · npm 11.19.0 | 前端(vite 5) |
| jq | 1.7.1(`/usr/bin/jq`) | 冒烟脚本的 JSON 取值(无则 python3 兜底) |
| python3 | 3.14.5 | 冒烟脚本的 JSON 取值兜底 |
🔴 **后端与 `scripts/perm-smoke.sh` 零 node 依赖** —— 冒烟脚本用后端自己的 `--enc` 子命令自证 cipher。
前端用 npm/vite 是它本来的工具链,允许。
---
## 1. 第一次上手
```bash
cd ~/Desktop/workspace/ssw-jnpf-lite-rust
bash run.sh install # cargo fetch + npm --prefix src/frontend install
bash run.sh build # cargo build --release + vite build(产出 src/frontend/dist)
```
`install` 用的是 `npm install`(**可能更新 `package-lock.json`**)。想严格按 lock 装、不碰 lock,用:
```bash
npm --prefix src/frontend ci
```
> ⚠️ 本机 npm 11 会打印 `install-scripts 2 packages have install scripts not yet covered by allowScripts`
> (`esbuild` / `fsevents`)。**不影响构建** —— vite 用的二进制来自平台包 `@esbuild/darwin-*`。
> 万一 vite 报「esbuild binary not found」,再执行:
> `npm --prefix src/frontend install-scripts approve esbuild && npm --prefix src/frontend install`。
---
## 2. 日常启动
```bash
bash run.sh dev # 后台起后端(30010) + 前端(5173)
bash run.sh logs # 看 .logs/backend.log + .logs/frontend.log 尾部
bash run.sh stop # 停(幂等:无进程时也不报错,退出码 0)
```
- 前端:**http://127.0.0.1:5173**
- 后端:**http://127.0.0.1:30010**
- 账号:**`admin` / `123456`**(首次启动自动种;密码用浏览器侧 `utils/cipher.ts` 加密后提交)
—— 登录后的 **token 寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**);
响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**。
- PID 在 `.run/{backend,frontend}.pid`,日志在 `.logs/{backend,frontend}.log`(两者都在 `.gitignore` 里)
单起一半:
```bash
bash run.sh backend # 前台跑后端(Ctrl-C 停)
bash run.sh frontend # 前台跑 vite
```
`run.sh` 退出码:**0** 成功 / **1** 运行期失败 / **2** 用法错(无参、未知子命令)。
`bash run.sh --help` 打印用法并退出 **0**(且**不会**创建 `.run/` `.logs/` 目录 —— 目录只在真正要写日志/PID 的分支里建)。
🔴 **端口是本仓硬约定**:后端固定 **30010**、前端固定 **5173**。
守卫**只对 `dev` / `backend` 生效**(这两个子命令真的会起后端,后端会继承 `PORT` 并真的绑那个端口):
`PORT` 被设成别的值 ⇒ `run.sh dev` / `run.sh backend` **明确报错并退出 2**
(不会去清别的端口、也不会打印错的 URL)。
其它子命令(`--help` / 无参 / `logs` / `install` / `build` / `stop` / `frontend`)**不碰端口**
⇒ **完全不受 `PORT` 影响**(环境里恰好有个 `PORT` 不会让它们失败)。
要用别的端口请直接跑二进制:`PORT=xxxx ./target/release/ssw-jnpf-lite-rust`。
🔴 **后端默认只监听 `127.0.0.1`**(`BIND_ADDR` 可覆盖)—— 本仓的种子口令是 `admin/123456`、
token 永不过期 ⇒ 默认不监听所有网卡;要在容器 / 反代里对外暴露才设 `BIND_ADDR=0.0.0.0`。
🔴 **`run.sh` 的 `kill_ports` 是 `kill -9`** ⇒ 它只会清 **30010** 和 **5173** 两个端口。
**兄弟项目 `tdc-rs` 的端口不在列表里**(打死它就是破坏兄弟项目)。
🔴 **`dev` 会等后端与前端都真的就绪**(后端轮询 `/api/health`,最长 30 秒;前端轮询 vite 根路径,最长 60 秒)
⇒ 任一没真正起来(数据库路径写错 / 依赖没装 / 端口被占 / `npm run dev` 立刻报错退出)时,
**脚本退出码 1** 并打印对应日志尾部(后端失败 ⇒ `.logs/backend.log`;前端失败 ⇒ `.logs/frontend.log`),
**不会**「报成功但其实没有服务」。
此时**本次刚起的前端进程会被一并收掉**(**PID 文件 SIGTERM → SIGKILL** + **按端口 `kill -9` 兜底**)⇒
**不会在 5173 上留残进程**(`stop_pid` 依赖 npm 把 SIGTERM 转发给 vite —— 那是 npm 的内部实现细节、
不是保证 ⇒ 必须有 `kill_ports` 兜底)。
🔴 前端没就绪时**不收后端**(后端可能只是慢;下一次 `dev` / `stop` 的 `kill_ports 30010` 会自愈),
脚本会明确提示「后端仍在 30010 上运行,要停请执行 `./run.sh stop`」。
🔴 **`stop` 的实际停止路径 = PID 文件(SIGTERM → 1s → SIGKILL)+ `kill_ports`(按端口 `kill -9`)**;
`pkill` 只是最后兜底,且模式收窄到**后端本体的完整路径**
(macOS/BSD 的 `pkill -f` 匹配**完整命令行**,宽模式会连「命令行里提到本仓名字」的无关进程一起杀掉)。
vite 由 `kill_ports 5173` 按**端口**收 ⇒ 不会误杀别的项目的 vite dev server。
🔴 **后端收到 SIGTERM / SIGINT 会优雅关闭**嵌入式 PostgreSQL(先收完在途请求,再正常关库)
⇒ 不再被 SIGKILL 打断(以前每次停机都是 SIGKILL 掉嵌入式 PG ⇒ 下次启动要 crash recovery、
数据目录里还留 `postmaster.pid`);`./run.sh stop` 的 1 秒宽限期对优雅停机足够(实测 < 200ms)。
> ℹ️ 停机瞬间 `.logs/backend.log` 里可能出现**几十行**
> `FATAL: terminating connection because protocol synchronization was lost` ——
> 那是 **pglite-rs 0.2.7 的收尾噪音**(PG 收到 Terminate 后 postmaster 反复拉起后端),
> **无害**:PG 本身是干净关库的(`postmaster.pid` 会被清掉)。
> 后端会在 PG 干净关库后**立刻**退出(日志尾行 `ssw-jnpf-lite-rust 已停止(嵌入式 PostgreSQL 已优雅关闭)。`)。
🔴 **`backend` 子命令用 `exec`** ⇒ **后端自己的退出码原样透传**(后端 panic 时是 **101**,不是 1)。
---
## 3. 环境变量(`.env`)
`run.sh` 会把仓库根的 `.env` 导出给子进程(`set -a; . .env; set +a`)。样例见 `.env.example`。
| 变量 | 默认 | 说明 |
|---|---|---|
| `PORT` | `30010` | 后端监听端口(**非法值回落 30010**) |
| `BIND_ADDR` | `127.0.0.1` | 后端监听地址 —— 🔴 **默认只监听本机**;要在容器 / 反代里对外暴露才设 `0.0.0.0`(只接受**字面 IP**,主机名会被判非法 ⇒ 回落 127.0.0.1) |
| `PGLITE_DIR` | `<项目根>/src/backend/data/lite.pg` | 数据目录(**绝对路径**,与 cwd 无关) |
| `SSW_PROFILE` | `dev` | 部署档位 —— `dev` = 一律不判弱口令;`prod` = 六条弱口令判据生效,违规**拒绝启动** |
| `SEED_ADMIN_PASSWORD` | `123456` | 首启 admin 的**种子口令**(明文)—— **只在空库首启时生效** |
🔴 **`PGLITE_DIR` 只能写绝对路径**。`config.rs` 对它是**原样使用** ⇒ 相对路径会相对**当前工作目录**解析
⇒ 换个 cwd 就换一份库,而且**静默**。要临时库就写 `PGLITE_DIR=memory://`
(pglite-rs 0.2.7 没有真内存模式,走的是系统临时目录里的一次性数据目录,进程退出即销毁)。
---
## 4. 冒烟与自检
### 4.1 权限闭环冒烟(32 条断言)
```bash
bash scripts/perm-smoke.sh # 期望:PASS=32 FAIL=0,退出码 0(**后端不用先起**,见 4.1.1)
B=http://127.0.0.1:30010 bash scripts/perm-smoke.sh # 打别的地址(**显式指定 ⇒ 不自起**)
JQ_BIN="" bash scripts/perm-smoke.sh # 强制走 python3 兜底路径(两条路径判据一致)
```
退出码:**0** 全绿 / **1** 有断言失败 / **2** 前置错误(后端不可达、缺 jq+python3、缺 `--enc` 二进制)。
断言覆盖:未登录 `600` → 加密登录 → 菜单树分组 → 建用户 → 重复账号 `400`(不是 500)→
一维/二维授权写入 → 非管理员菜单收窄 → `403` → 未知路由 `404` → 管理员短路 →
Product/Book 往返(36 位 UUID、numeric 是 JSON 字符串 `"9.90"`、int 是 JSON 数字 `100`)。
### 4.1.1 尺子自起隔离后端(**默认行为**)
两把契约尺子(`perm-smoke.sh` / `perm-smoke-jnpf.sh`)**默认自己把后端起起来**(助手在
`scripts/smoke_backend.sh`,被两把尺子 `source`)。口径:
| 情况 | 行为 |
|---|---|
| **没给 `B`** + `:30010` **通** | 就用它(保留「跑开发中的后端」这个习惯) |
| **没给 `B`** + `:30010` **不通** | **自起隔离实例**:空闲端口 + `mktemp -d` 临时数据目录 ⇒ 打印「ℹ️ 已自起隔离后端:…」 |
| **显式给了 `B`** + 不可达 | **不自起**(尊重外部后端)⇒ 前置错误,**退出码 2** |
为什么:不自起的话 ① 两把尺子**互相踩**(面 A 改了库里的角色/菜单 ⇒ 面 B 的前置状态被污染);
② 跑完**留脏数据**在 `src/backend/data/lite.pg`;③ **CI 里没法跑**(没人替你起后端)。
⇒ 自起时库里的痕迹**随临时目录一起消失** ⇒ 断言可重复、两把尺子互不污染。
🔴 隔离实例的 `PGLITE_DIR` 是**临时目录下的绝对路径**(契约:只接受绝对路径或 `memory://`),
进程退出即销毁;退出时尺子先 `TERM` 后端(等 6s 再兜底 `KILL`)再删临时目录。
### 4.2 面 B 冒烟(官方 JNPF 形状,18 条断言)
```bash
bash scripts/perm-smoke-jnpf.sh # 期望:PASS=18 FAIL=0 SKIP=0,退出码 0(**后端不用先起**,见 4.1.1)
B=http://127.0.0.1:30010 bash scripts/perm-smoke-jnpf.sh # 显式指定 ⇒ 不自起
```
退出码:**0** 全绿 / **1** 有断言失败或未全覆盖 / **2** 前置错误(后端不可达等)。
🔴 **它打的是面 B**(官方 JNPF 形状)⇒ 请求必须带判别头 **`Vue-Version: 3`**(脚本自带)。
断言覆盖:面 A 未受影响 · 两面登录 · 面 B `CurrentUser` 5 字段 · `menuList` 节点 15 字段 ·
`permissionList` 是数组 · 未登录 `602` · 未知路由仍 `404` · 用户/角色列表是 `PageListVO` ·
列表项无 `password`/`secretkey` 且 `isAdministrator` 是**数字** · `ModuleBySystem` 返 `ListVO` ·
授权写(官方完整 body)真落库 · 授权读是 **POST**。
### 4.3 一键验收(推荐先跑这个)
```bash
bash scripts/verify.sh # 全量 7 步:pack-sync --check → check-scaffold → 自证 → cargo test → build → 两把尺子
bash scripts/verify.sh --fast # 只静态 + 测试(4 步,不起服务)
```
### 4.4 脚手架判据:本仓只准有业务(SC1–SC6)
```bash
python3 scripts/check-scaffold.py # 期望:PASS=6 FAIL=0
python3 scripts/check-scaffold.py --self-test # 期望:反自证 6/6
```
平台(登录 / 权限 / 面 B / `base_*` / CRUD 引擎)在**已发布的 `sspf` 包**里,不在本仓。
这条尺子钉的就是「别把平台抄回来」:
| 判据 | 内容 |
|---|---|
| **SC1** | 本仓没有平台实现(`src/backend/src/platform/` · `routes.rs` · `bootstrap.rs` · `db/schema.sql` · `crates/`) |
| **SC2** | 业务侧没有 `base_*` 建表语句(`docs/` 里的参考 DDL 不算 —— 它不参与运行) |
| **SC3** | 应用 crate 只依赖门面 `sspf`(+ axum/tokio + 业务包),不直接依赖 `sspf-*` 内部 crate |
| **SC4** | 每个业务包只依赖 `sspf`,且 `Cargo.toml` / `pack.toml` / `schema/001_init.sql` / `src/lib.rs` 齐全 |
| **SC5** | `sspf` 只从 workspace 的 **git tag** 来;成员不许另写 `git` / `path` / `version` |
| **SC6** | 生成物与 `packs/*` 不漂移(复用 `pack-sync.py --check`) |
🔴 **反自证**:`--self-test` 给 6 条判据各造一个**真实违规**(抄回 `platform/`、写
`CREATE TABLE base_user`、应用依赖 `sspf-core`、包依赖 `axum`、`sspf` 改成 path 依赖、
改 `pack.toml` 让生成物漂移),断言**该条恰好变红**,且注入前基线全绿 ——
否则这条尺子就是「永远绿」的空壳。
### 4.5 生成物漂移(加包忘了跑 sync)
```bash
python3 scripts/pack-sync.py # 同步(幂等)
python3 scripts/pack-sync.py --check # 期望:✅ 4 个包 / 4 个模块,生成物无漂移
python3 scripts/pack-sync.py --dry-run # 打印将要写入的内容
```
四处派生位置(都由 `packs/*` + `modules/*` 生成,**不许手改**):
`packs_gen.rs` 的 `GEN:PACKS` / `GEN:MANIFESTS`、`modules/mod.rs` 的五个段、
应用 `Cargo.toml` 的 `GEN:PACK_DEPS`。
### 4.6 加/改业务包
```bash
bash scripts/new-pack.sh blog Post --name "文章" --columns "title:VARCHAR(255),price:NUMERIC(12,2)"
```
建 `packs/blog/`(表 + 列 + 菜单 + 面 B 路由)+ `modules/blog.rs`(面 A),并自动跑生成。
细节见 [`HOWTO_MODULE.md`](../HOWTO_MODULE.md)。
### 4.7 macOS SysV 信号量回收(`cargo test` 跑多了会攒)
```bash
bash scripts/reap-ipc-leaks.sh # 扫 + 回收本仓的孤儿信号量集
bash scripts/reap-ipc-leaks.sh --dry-run # 只扫不删
```
🔴 **为什么需要**:pglite 的 `initdb` 会 `semget` 一个 `nsems=20` 的信号量集,
而 macOS(XNU)**不回收**进程退出时留下的信号量集(Linux 有 `ipcrm`,macOS 没有)⇒
`cargo test` 跑久了会攒到几千个 ⇒ 撞上 `kern.sysv.semmns`(本机 87381)上限 ⇒
`semget` 失败 ⇒ 测试莫名其妙起不来。
脚本用 `nsems==20` 这个 **PGlite 指纹**定位(零业务内容),只回收**当前用户**的。
### 4.8 生产档弱密钥守卫
```bash
SSW_PROFILE=prod SEED_ADMIN_PASSWORD=123456 ./target/release/ssw-jnpf-lite-rust
# ⇒ [启动失败] 生产档弱密钥守卫未通过(SSW_PROFILE=prod):
# - SEED_ADMIN_PASSWORD:判据③:值等于已知弱值(123456)
# - SEED_ADMIN_PASSWORD:判据⑥:长度 6 < 12
# ⇒ 退出码 1
```
🔴 **六条判据**:① 键不在清单里 ⇒ 跳过 ② 空/空白 ③ 精确等于已知弱值
④ **含**已知弱值(反绕过,`123456x` 也拦)⑤ 命中弱标记词(**整体词**,`administrator` 不误伤)
⑥ 长度 < 12。
🔴 **两道检查**:配置级(本次用的种子口令)+ **库内级**(回读 `base_user` 的 admin 行)——
库内级是必须的:种子口令只对**空库**生效 ⇒ 生产库里那个可能是当初种下的 `123456`,
运维后来才设了 `SEED_ADMIN_PASSWORD` ⇒ 只查配置 = 守卫形同虚设。
🔴 **不做误伤**:管理员**合法改过**口令后,库里那个不再等于任何已知弱值 ⇒ 放行。
---
## 5. 前端手验清单(验收门④)
```bash
bash run.sh dev
```
浏览器打开 **http://127.0.0.1:5173**:
1. `admin` / `123456` 登录 ⇒ 进 Dashboard;
2. 菜单树正确:系统管理(用户管理 / 角色管理 / 机构管理 / 菜单管理)+ Demo 示例 + 产品管理 + 图书超市;
3. 5 个管理页可增删改(用户 / 角色 / 机构 / 菜单 / 授权);
4. 3 个业务页可用(DemoItem / Product / Book);
5. 退出再登录 ⇒ 仍正常。
**代理自检**(不开浏览器也能验):
```bash
curl --noproxy '*' -s http://127.0.0.1:5173/ | grep '<div id="root">'
curl --noproxy '*' -s http://127.0.0.1:5173/api/health
# => {"ok":true,"tables":10,"version":"0.1.0"} ← 说明 vite 代理把 /api 转到了 30010
```
---
## 6. 常见故障
### 6.1 本机特有
| 症状 | 根因 | 处理 |
|---|---|---|
| `curl http://127.0.0.1:5173` 连不上 / 502 | 本机 curl 走**系统代理** | 加 `--noproxy '*'` |
| `localhost:5173` 连不上 | macOS 上 vite 默认只 bind `::1` | 用 `127.0.0.1:5173`(`vite.config.ts` 已强制 IPv4) |
| 起后台进程后工具一返回就没了 | `nohup … &` 会被回收 | 用 Bash 工具的 `run_in_background`;stdout **不要**指向 `/dev/null`(进程会以 100 退出) |
| vite 报端口被占 | `strictPort: true`(故意不自动换端口) | `lsof -ti:5173` 看清是谁;或 `bash run.sh stop` |
| `npm install` 卡在 esbuild | npm 11 的 `allowScripts` 闸门 | `npm --prefix src/frontend install-scripts approve esbuild && npm --prefix src/frontend install` |
| 第二个后端实例起不来 | **pglite 单实例独占数据目录** | 换 `PGLITE_DIR` 或换端口 |
### 6.2 契约层(与 `CLAUDE.md` 的踩坑清单一一对应)
| 症状 | 根因 | 处理 |
|---|---|---|
| 登录必失败(400 账号或密码错误) | cipher key 当成 16 字节原始摘要 ⇒ AES-128 | key = `md5_hex` 的 **32 个 ASCII 字节** ⇒ AES-256 |
| `f_price` 回显 `9.9` 而不是 `"9.90"` | `row_to_json` 把 numeric 给了数字 | 投影里 `f_price::text AS price` |
| 角色授权写了不生效 | 写进 `base_role_relation.f_user_id`(**不存在此列**) | 用户 id 写 `f_object_id` + `f_object_type='user'` |
| 组织/岗位授权不生效 | 写进 `base_role_relation` | 写 `base_user_relation`(那里才有 `f_user_id`) |
| 授权接口返 200 但一行没写 | `objectType` 传了 `'Role'`(大写) | 必须小写 `'role'`;`module` 传一维数组 |
| 非管理员拿到了全部菜单 | 只查了角色授权 | 四源合并(直授+角色+组织+岗位) |
| 菜单授权没生效但接口放行 | 菜单 `f_url_address` ≠ 前端 Route path | 三处(urlAddress / Route path / 守卫 key)必须一字不差 |
| 405 返回 HTML / 丢 `Allow` 头 | 用了 axum 的 `method_not_allowed_fallback` | 用响应改写中间件(链尾) |
| DDL 能从 HTTP 下载 | DDL 落在 web root | 移到 `db/` + 兜底守卫 |
---
## 7. 数据重置
库是**嵌入式 pglite 数据目录**(默认 `src/backend/data/lite.pg`),**没有独立的 PG 服务**。
```bash
bash run.sh stop
mv src/backend/data src/backend/data.bak-$(date +%s) # 改名备份(可恢复),下次启动重建空库
bash run.sh dev # 空库 ⇒ 重新种子(admin/123456)
```
🔴 **schema 只在首次建表时执行** ⇒ 改了 `src/backend/db/schema.sql` 之后**必须**走这一步,否则改动不生效。
---
## 8. 边界(别越界)
- `tdc-rs` 兄弟项目:**不共享**代码 / 端口 / 数据目录。`run.sh` 的 `kill_ports` 只清 30010 与 5173。
- `~/Desktop/workspace/skills/ssw-jnpf-lite-react/`(参照物):**只读**。本仓 `src/frontend/` 是它的逐字复制,
唯一改动是 `vite.config.ts` 的代理端口**改成 30010**(连注释行一起改);
`src/api/request.ts` 的**陈旧端口注释**(写的仍是旧端口号)与 `:31` 的 axios **30 秒超时**
(`timeout` 毫秒数,**不是**端口)**刻意逐字节不动**。
`vite.config.ts:11` 的注释里仍写着「NestJS 后端」(本仓是 Rust)—— 同样**刻意逐字保留**,只记档。
- `src/backend/**`、`docs/contract.md`、`scripts/perm-smoke.sh`:**已定稿**,改动需走评审。
- **前端 Dashboard 只渲染「目录的子项」**(`node.children`)⇒ `Demo 示例` / `产品管理` / `图书超市`
是**顶层页面型菜单**(`parent_id='0'`、无子项)⇒ **Dashboard 里没有它们的按钮**,
只能按 URL 直达(`/demo-item`、`/shop/Product`、`/books/Book`)。
这是**参照物原样行为**且与契约 §8.4 一致 ⇒ **不改**,只记档。
- `/favicon.ico` 在 vite dev server 上返 **404**(`index.html` 没有 favicon 引用)⇒ 浏览器 console 两条 404;无害。