# runbook —— ssw-jnpf-lite-rust 怎么起、怎么冒烟、坏了怎么办 > 契约见 [`contract.md`](contract.md);红线与坑位清单见 [`../CLAUDE.md`](../CLAUDE.md)。 > 🔴 **路径口径(2026-11-04 重映射)**:本文件是**历史技术报告**。它原先引用的 > `src/backend/src/platform/*.rs` 是技能仓那份**自研平台**的位置 —— 那份实现已删除, > 平台现在在**平台仓 `ssw-platform` 的 `sspf` 包里**。 > 文中 `ssw-platform:…` 前缀的路径都指**平台仓**(不在本技能仓);行号已随代码重组失效, > **以符号名 / 模块名为准**(对照表见本文件顶部或 `SKILL.md` 的目录树)。 > > 映射:`platform/cipher.rs` → `crates/sspf-core/src/cipher.rs` · `platform/permission.rs` → > `crates/sspf-compat-permission/src/permission.rs` · `platform/sys.rs` → > `crates/sspf-compat-system/src/system.rs` · `platform/jnpf.rs` → > `crates/sspf-compat-core/src/helper.rs`(+ `res.rs` 的 VO 形状)· `platform/db.rs` → > `crates/sspf-store/src/db.rs` · `platform/{config,state,session,seed,guard,crud,auth}.rs` → > `crates/sspf-{store,core}/src/*.rs` · `platform/{entity,menu,envelope,ids}.rs` → > `crates/sspf-contract/src/*.rs`。 --- ## 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`/…),平台走 `.cargo/config.toml` 的 `--extern` | | **SC4** | 每个业务包**不声明外部依赖**,且 `Cargo.toml` / `pack.toml` / `schema/001_init.sql` / `src/lib.rs` 齐全 | | **SC5** | `Cargo.toml`(workspace 与成员)里**不出现 `sspf`**;平台由 `.cargo/config.toml` 的 `--extern` 提供 | | **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 '