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

19 KiB
Raw Blame History

runbook —— ssw-jnpf-lite-rust 怎么起、怎么冒烟、坏了怎么办

契约见 contract.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. 第一次上手

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,用:

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 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 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 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 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 scripts/verify.sh        # 全量 7 步:pack-sync --check → check-scaffold → 自证 → cargo test → build → 两把尺子
bash scripts/verify.sh --fast # 只静态 + 测试(4 步,不起服务)

4.4 脚手架判据:本仓只准有业务(SC1–SC6)

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)

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 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。

4.7 macOS SysV 信号量回收(cargo test 跑多了会攒)

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 生产档弱密钥守卫

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 run.sh dev

浏览器打开 http://127.0.0.1:5173:

  1. admin / 123456 登录 ⇒ 进 Dashboard;
  2. 菜单树正确:系统管理(用户管理 / 角色管理 / 机构管理 / 菜单管理)+ Demo 示例 + 产品管理 + 图书超市;
  3. 5 个管理页可增删改(用户 / 角色 / 机构 / 菜单 / 授权);
  4. 3 个业务页可用(DemoItem / Product / Book);
  5. 退出再登录 ⇒ 仍正常。

代理自检(不开浏览器也能验):

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 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;无害。