fix(final): 前端就绪校验 + 绑 127.0.0.1 + 413 信封化 + 优雅停机 + 文档事实修正

- run.sh: dev 增加前端就绪轮询(60s),失败收前端(PID 文件 + 按端口兜底)、打印 frontend.log 尾部、退出码 1,并写明后端仍在运行
- 后端默认只监听 127.0.0.1(BIND_ADDR 可覆盖,非法值回落 127.0.0.1),横幅打印实际绑定地址
- 响应改写层新增 413 ⇒ 信封(保留 HTTP 413 状态码),并补一条 >2MB body 的单测
- SIGTERM/SIGINT 优雅停机:先收完在途请求,再关嵌入式 PG(数据目录不再留 postmaster.pid)
- 文档事实修正:畸形百分号编码的假断言、memory:// 的口径、模块表 API、门④命令、端口口径、token 实际寿命

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-26 05:22:57 +08:00
1 parent 621e636e76
commit 1539892d86
9 files changed
+337 -47

No files matched your search

+10
View File
@@ -8,6 +8,16 @@
# 两套服务必须彻底分开(不共享端口 / 数据目录 / 代码)。
PORT=30010
# 后端监听地址。
#
# 🔴 **默认只监听本机**(127.0.0.1):本仓的种子口令是 admin/123456、token 永不过期
# ⇒ 若默认监听所有网卡,局域网内可以直接连上后端 ⇒ 必须朝安全方向默认。
# 要在容器 / 反代里对外暴露,才把它改成 0.0.0.0。
#
# 🔴 只接受**字面 IP**(127.0.0.1 / 0.0.0.0 / ::1);写主机名(如 localhost)
# 会被判非法 ⇒ 回落 127.0.0.1。
BIND_ADDR=127.0.0.1
# pglite 数据目录。
#
# 🔴 **留空** ⇒ 用后端的默认值 `<项目根>/src/backend/data/lite.pg`
+25 -11
View File
@@ -72,7 +72,7 @@ Redis+Sa-Token / 分页 / `secretkey` 的官方双层 md5 算法。理由见 `CL
tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
├── Cargo.toml ← 【workspace 根】members=["src/backend"] + [profile.release]
├── src/backend/ ← 名字保留是为了将来抽技能时目录与 react 版对齐
│ ├── src/*.rs ← 14 个模块(见 §3.3)
│ ├── src/*.rs ← 16 个模块(见 §3.3)
│ ├── db/schema.sql ← 10 张表完整 DDL
│ └── data/ ← 运行期(gitignore)
├── src/frontend/ ← react 技能前端逐字复制(零改)
@@ -81,9 +81,14 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
└── .env.example
```
**端口**:后端 `30010`(`PORT` 可覆盖)· 前端 `5173`(vite)· vite proxy `/api` → `http://127.0.0.1:30010`。
**端口**:后端 `30010` · 前端 `5173`(vite)· vite proxy `/api` → `http://127.0.0.1:30010`。
🔴 **本仓端口是硬约定**:`run.sh` 的端口常量不许改 —— `PORT` 被设成 ≠ 30010 时
`run.sh dev` / `run.sh backend` **报错退出 2**(要换端口请**直接跑二进制**);
**后端二进制本身**确实吃 `PORT`(非法值回落 30010)。
🔴 后端**默认只监听 `127.0.0.1`**(`BIND_ADDR` 可覆盖);`BIND_ADDR=0.0.0.0` 才对外暴露。
**数据库**:`pglite-rs`,默认落盘 `src/backend/data/lite.pg`;`PGLITE_DIR=memory://` ⇒ 纯内存。
**数据库**:`pglite-rs`,默认落盘 `src/backend/data/lite.pg`;`PGLITE_DIR=memory://` ⇒ **临时库**
(系统临时目录里的一次性数据目录,进程退出即销毁;pglite-rs 0.2.7 **没有**真内存模式)。
### 3.2 契约逐字对齐表(对着 react 技能源码抄)
@@ -149,11 +154,11 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
| 模块 | 职责 | 备注 |
|---|---|---|
| `main.rs` | 启动装配:开库 → 起 schema → seed → 建路由 → 挂中间件 → 监听 | `with_state` 必须是最后一步 |
| `config.rs` | `PORT` / `PGLITE_DIR` / 静态目录 / 种子开关 | 环境变量 |
| `db.rs` | pglite 封装:`query_json()` / `query_rows()` / `exec()` / `ensure_schema()` / `valid_table()` | 单 backend ⇒ 进程级 `db_lock` |
| `main.rs` | 启动装配:开库 → 起 schema → seed → 建路由 → 挂中间件 → 监听(+ 优雅停机) | `with_state` 必须是最后一步 |
| `config.rs` | `PORT` / `BIND_ADDR` / `PGLITE_DIR` / 静态目录 / 种子开关 | 环境变量 |
| `db.rs` | pglite 封装:`open()` / `open_temp()` / `ensure_schema()` / `query_json()` / `query_json_params()` / `exec()` / `exec_params()` / `scalar_text()` | 单 backend ⇒ 进程级 `db_lock` |
| `cipher.rs` | `md5_hex()` / `encrypt_password()` / `decrypt_to_md5()` | **逐字对齐 `cipher.ts`** + 上游向量单测 |
| `envelope.rs` | `ActionResult{code,msg,data}` + `ok/fail/fail_code` | 业务失败恒 HTTP 200 |
| `envelope.rs` | `ActionResult{code,msg,data}` + `ok()` / `fail()` | 业务失败恒 HTTP 200 |
| `ids.rs` | `new_uuid()` → 36 位 UUID v4 | **不是** tdc-rs 的雪花 |
| `session.rs` | 内存 token 表(`lite-` 前缀 + 32 hex) | 进程重启即失效 |
| `auth.rs` | 登录 / CurrentUser / `require_login()` / `require_module()` | 守卫返回 `ActionResult`(600 / 403) |
@@ -162,7 +167,9 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
| `sys.rs` | 5 组 `base_*` 的显式 handler 语义 | 用户/角色/机构/菜单/授权 |
| `crud.rs` | spec 驱动的通用 CRUD(List/Save/Delete) | 业务实体用 |
| `entities.rs` | 业务实体 spec 表(表名 / 列 / 类型 / 数值列 / 守卫菜单 key) | 加业务模块 = 加一条 spec |
| `routes.rs` | 路由装配 | |
| `routes.rs` | 路由装配(404 / 405 / 413 改写 / catch-all 三层兜底) | |
| `state.rs` | `AppState{config, db, sessions}`(三个字段全是 `Arc`) | axum `State` 的载体 |
| `lib.rs` | 库入口:`pub mod` 声明全部模块 | 让单测 / 集成测试能直接引用各模块 |
### 3.4 三个关键取舍
@@ -223,7 +230,7 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
| step | 内容 | 完成判据 |
|---|---|---|
| **0** | 建 **cargo workspace**(根 `Cargo.toml`:`[workspace] members=["src/backend"]` + `[profile.release]`)+ 成员 crate(依赖照 tdc-rs:axum 0.8 / tokio / tower-http 0.6 / serde / serde_json / serde_urlencoded 0.7 / rand 0.8 / hex 0.4 / aes 0.8 / ecb 0.1 / md-5 0.10 / uuid v4 / pglite-rs 0.2 / chrono 0.4) | 根目录 `cargo build` 通过(哪怕是空 main) |
| **0** | 建 **cargo workspace**(根 `Cargo.toml`:`[workspace] members=["src/backend"]` + `[profile.release]`)+ 成员 crate(依赖照 tdc-rs:axum 0.8 / tokio / serde / serde_json / serde_urlencoded 0.7 / rand 0.8 / hex 0.4 / aes 0.8 / ecb 0.1 / md-5 0.10 / uuid v4 / pglite-rs 0.2 / chrono 0.4) | 根目录 `cargo build` 通过(哪怕是空 main) |
| **1** | `src/cipher.rs` + 单测 | 上游向量**逐字节**相等;`md5_hex` 与 `decrypt_to_md5` 往返一致 |
| **2** | `src/envelope.rs` + 单测 | 业务失败 HTTP 200 + `code=400`;`code=600/403` 同形 |
| **3** | `src/db.rs` + `src/config.rs` + `db/schema.sql`(10 张表) | 进程能开库并建表;`query_json()` 能取回 JSON |
@@ -377,8 +384,9 @@ bash run.sh dev # 日常:后台起后端(30010) + 前端(5173)
```
- 前端:**http://127.0.0.1:5173**(vite dev server,`/api` 代理到后端)
- 后端:**http://127.0.0.1:30010**
- 后端:**http://127.0.0.1:30010**(**默认只监听本机**;`BIND_ADDR=0.0.0.0` 才对外暴露)
- 账号:**`admin` / `123456`**(首次启动自动种子)
- `bash run.sh dev` 的**后端与前端都就绪**才算成功(任一没就绪 ⇒ 退出码 1 并打印对应日志尾部)
- `bash run.sh logs` 看日志(`.logs/backend.log`、`.logs/frontend.log`);`bash run.sh stop` 停(幂等)
- 🔴 `run.sh` 的 `kill_ports` 是 `kill -9` ⇒ 只清 **30010 / 5173**,**绝不碰兄弟项目 `tdc-rs` 的端口**
- 🔴 打 localhost 用 curl **必须**加 `--noproxy '*'`(本机 curl 走系统代理)
@@ -413,12 +421,18 @@ bash run.sh dev # 日常:后台起后端(30010) + 前端(5173)
- **(k)** release 二进制**没有** catch-all 的自动化覆盖(触发 panic 的端点是 `#[cfg(test)]` 专属;
catch-all 中间件代码在测试构建与 release 构建里**逐字相同**,且 release profile **没有**启用 abort 型 panic ⇒ 行为等价)。
- **(l)** `Path<String>` 遇**畸形百分号编码** ⇒ axum 默认返**纯文本 400(非信封)**(handler 签名由契约 §S17 定死,改它要动 `sys.rs`)。
- **(l)** ~~`Path<String>` 遇**畸形百分号编码** ⇒ axum 默认返**非信封的 400 响应**~~ ⇒ 🔴 **已推翻**
(最终整体评审修复轮 R=3 实测):axum 0.8.9 **接受**该转义 ——
`PUT /api/permission/Authority/Data/%zz` 实测返回 **HTTP 200 + `{"code":600,"msg":"未登录","data":null}`**
(信封,正常)⇒ **不存在**「返非信封 400」这种破口,原裁决的前提不成立 ⇒ **不改代码**。
- **(m)** 冒烟脚本**每次跑**会往库里留一行 `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user`
(react 同款行为;契约 §13 未要求清理 ⇒ 不改)。
- **(n)** 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file`(观感,判据不受影响)。
- **(o)** 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的**前置提示文案**不同
(`code=无` vs `code=ERR`),退出码都是 2。
- **(p)** **token 的真实寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**):
登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**
(进程不重启就永不过期);契约未覆盖 TTL ⇒ **不改**。
Task 12 修复轮 R=1 另记两条 `run.sh` 的**行为口径**(不是缺陷,是刻意设计):
+9 -4
View File
@@ -22,6 +22,7 @@ bash run.sh build
bash run.sh dev
# 前端 http://127.0.0.1:5173 后端 http://127.0.0.1:30010
# 账号 admin / 123456
# (**后端与前端都就绪**才算成功;任一没就绪 ⇒ 退出码 1 并打印对应日志尾部)
bash run.sh stop # 停(幂等)
bash run.sh logs # 看日志尾部
@@ -29,7 +30,7 @@ bash run.sh logs # 看日志尾部
| 端口 | 谁 | 说明 |
|---|---|---|
| `30010` | 后端(Rust) | `PORT` 可覆盖;**兄弟项目 `tdc-rs` 占了 `:30000`,本仓不碰** |
| `30010` | 后端(Rust) | **硬约定**:`run.sh` 的端口不许改 —— `PORT` ≠ 30010 时 `run.sh dev` / `run.sh backend` 报错退出 2(要换端口请**直接跑二进制**)。**后端二进制本身**吃 `PORT`(非法值回落 30010)。默认**只监听 `127.0.0.1`**;`BIND_ADDR=0.0.0.0` 才对外暴露 |
| `5173` | 前端(vite dev) | `strictPort: true` ⇒ 端口被占直接报错,不自动换端口 |
---
@@ -40,7 +41,7 @@ bash run.sh logs # 看日志尾部
tds-lite-rs/
├── Cargo.toml # cargo workspace 根(成员 = src/backend)+ release profile
├── run.sh # install / build / dev / backend / frontend / stop / logs
├── .env.example # PORT / PGLITE_DIR(PGLITE_DIR 只能写绝对路径或 memory://)
├── .env.example # PORT / BIND_ADDR / PGLITE_DIR(PGLITE_DIR 只能写绝对路径或 memory://)
├── src/backend/ # Rust 后端(axum 0.8 + pglite-rs 0.2,10 张表,27 条路由)
├── src/frontend/ # react 技能前端**逐字复制**(只改 vite 代理端口 30000 → 30010)
├── scripts/perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖)
@@ -78,7 +79,7 @@ tds-lite-rs/
| ① 编译 | `cargo build --release` | 0 error **0 warning** |
| ② 单测 | `cargo test` | 全绿(当前 **177 passed / 0 failed**) |
| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **PASS=32 FAIL=0**(需后端已起在 `:30010`) |
| ④ 前端手验 | `bash run.sh frontend` | `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 |
| ④ 前端手验 | `bash run.sh dev` | `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 |
外加:`bash scripts/check-module.sh`(9 接触点静态自检)—— 加业务模块后立刻跑的前置闸门。
@@ -100,7 +101,11 @@ tds-lite-rs/
- **release 二进制没有 catch-all 的自动化覆盖**:触发 panic 的端点是 `#[cfg(test)]` 专属;
catch-all 中间件代码在测试构建与 release 构建里逐字相同,且 release profile **无** `panic = "abort"` ⇒ 行为等价。
- **`Path<String>` 遇畸形百分号编码** ⇒ axum 默认返纯文本 400(**非信封**);handler 签名由契约定死。
- **`Path<String>` 遇畸形百分号编码** ⇒ **实测 axum 0.8.9 接受该转义**:`PUT /api/permission/Authority/Data/%zz`
返回 **HTTP 200 + `{"code":600,"msg":"未登录","data":null}`**(信封,正常)⇒ **不存在**「返非信封 400」这种破口。
- **token 的真实寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**):
登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**
(进程不重启就永不过期);契约未覆盖 TTL ⇒ 不改。
- **冒烟脚本每次跑会往库里留一行** `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user`(react 同款行为,契约未要求清理)。
- 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file`(观感,判据不受影响)。
- 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的前置提示文案不同(退出码都是 2)。
+23 -4
View File
@@ -51,6 +51,8 @@ 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` 里)
单起一半:
@@ -70,18 +72,34 @@ bash run.sh frontend # 前台跑 vite
其它子命令(`--help` / 无参 / `logs` / `install` / `build` / `stop` / `frontend`)**不碰端口**
⇒ **完全不受 `PORT` 影响**(环境里恰好有个 `PORT` 不会让它们失败)。
要用别的端口请直接跑二进制:`PORT=xxxx ./target/release/tds-lite-rs`。
🔴 **后端默认只监听 `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 秒)⇒ 后端起不来(数据库路径写错等)时
**脚本退出码 1 并打印 `.logs/backend.log` 尾部**,不会「报成功但其实没有服务」。
此时**本次刚起的前端进程会被一并收掉**(按 PID 文件 SIGTERM → SIGKILL)⇒ **不会在 5173 上留残进程**。
🔴 **`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 干净关库后**立刻**退出(日志尾行 `tds-lite-rs 已停止(嵌入式 PostgreSQL 已优雅关闭)。`)。
🔴 **`backend` 子命令用 `exec`** ⇒ **后端自己的退出码原样透传**(后端 panic 时是 **101**,不是 1)。
@@ -93,7 +111,8 @@ vite 由 `kill_ports 5173` 按**端口**收 ⇒ 不会误杀别的项目的 vite
| 变量 | 默认 | 说明 |
|---|---|---|
| `PORT` | `30010` | 后端监听端口 |
| `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 无关) |
🔴 **`PGLITE_DIR` 只能写绝对路径**。`config.rs` 对它是**原样使用** ⇒ 相对路径会相对**当前工作目录**解析
+41 -4
View File
@@ -8,6 +8,7 @@
# ./run.sh install 安装依赖(cargo fetch + npm install)
# ./run.sh build 构建(cargo build --release + vite build)
# ./run.sh dev 后台起后端(30010) + 前端(5173),日志进 .logs/,PID 写入 .run/
# (**后端与前端都就绪**才算成功;任一没就绪 ⇒ 退出码 1)
# ./run.sh backend 前台起后端
# ./run.sh frontend 前台起前端
# ./run.sh stop 用 PID 文件停后台进程 + 兜底 kill_ports
@@ -57,7 +58,7 @@ usage() {
用法: ./run.sh <子命令>
install 安装依赖(cargo fetch + npm install)
build 构建(cargo build --release + vite build)
dev 后台起后端(30010) + 前端(5173)
dev 后台起后端(30010) + 前端(5173);**后端与前端都就绪**才算成功
backend 前台起后端
frontend 前台起前端
stop 停止后台进程
@@ -103,6 +104,22 @@ wait_backend_ready() {
return 1
}
# 🔴 **就绪轮询(前端)**:与 wait_backend_ready 同形,轮 vite 的根路径。
# 超时 60 秒(比后端长):vite 首次启动要做依赖预打包,冷启动可能十几秒。
# 没有它 ⇒ 前端 vite 起不来(依赖没装 / 端口被占 / npm run dev 立刻报错退出)时,
# 脚本照样打印「服务已在后台启动」⇒ **脚本报成功、实际没有前端**。
# 本机 curl 走系统代理 ⇒ 必须带 --noproxy '*'。
wait_frontend_ready() {
local i
for i in $(seq 1 60); do
if curl --noproxy '*' -fsS -m 2 "http://127.0.0.1:${FRONTEND_PORT}/" >/dev/null 2>&1; then
return 0
fi
sleep 1
done
return 1
}
# 用 PID 文件优雅停(先 SIGTERM,1s 后 SIGKILL),清理 root 进程树
stop_pid() {
local f="$1"
@@ -171,15 +188,35 @@ case "${1:-}" in
echo "[启动失败] 后端在 30 秒内没就绪(/api/health 不通)。"
# 🔴 本次刚起的前端**一并收掉** —— 不许把一个 vite dev server 残在后台占着 5173
# (用户看到「启动失败」,机器上却留着一个前端 dev server,极难联想到是同一次启动留下的)。
# 用 PID 文件收(SIGTERM → 1s → SIGKILL);**不用** pkill(模式太宽会误杀别的项目)。
# **两条都做**:`stop_pid` 走 PID 文件(SIGTERM → 1s → SIGKILL),
# `kill_ports` 按端口 kill -9 **兜底** ——
# 因为 `stop_pid` 依赖 npm 把 SIGTERM 转发给 vite(npm 的内部实现细节,**不是保证**),
# 有了 `kill_ports` 兜底 ⇒「不会在 5173 上留残进程」**无条件**成立。
# **不用** pkill(模式太宽会误杀别的项目)。
stop_pid "$RUN/frontend.pid"
echo " ↳ 本次刚起的前端进程已一并收掉(按 PID 文件 SIGTERM → SIGKILL)"
kill_ports "$FRONTEND_PORT"
echo " ↳ 本次刚起的前端进程已一并收掉(PID 文件 SIGTERM → SIGKILL + 按端口 kill -9 兜底)"
echo "--- .logs/backend.log 尾部 ---"
tail -n 20 "$LOGS/backend.log" 2>/dev/null || true
exit 1
fi
# 🔴 就绪校验(前端):vite 起不来时同样**不许**报成功。
if ! wait_frontend_ready; then
echo
echo "[启动失败] 前端在 60 秒内没就绪(http://127.0.0.1:${FRONTEND_PORT}/ 不通)。"
# 🔴 同上:PID 文件 + 按端口兜底,两条都做 ⇒ 不在 5173 上留残进程。
stop_pid "$RUN/frontend.pid"
kill_ports "$FRONTEND_PORT"
echo " ↳ 本次刚起的前端进程已一并收掉(PID 文件 SIGTERM → SIGKILL + 按端口 kill -9 兜底)"
# 🔴 本仓既定裁决:dev 失败**不收后端**(后端可能只是慢;下一次 dev/stop 的
# kill_ports ${BACKEND_PORT} 会自愈)⇒ 但必须把后端的去留**说清楚**。
echo " ↳ 后端仍在 ${BACKEND_PORT} 上运行,要停请执行「./run.sh stop」"
echo "--- .logs/frontend.log 尾部 ---"
tail -n 20 "$LOGS/frontend.log" 2>/dev/null || true
exit 1
fi
echo
echo "服务已在后台启动。后端: http://127.0.0.1:${BACKEND_PORT} 前端: http://127.0.0.1:${FRONTEND_PORT}"
echo "服务已在后台启动(后端与前端**都已就绪**)。后端: http://127.0.0.1:${BACKEND_PORT} 前端: http://127.0.0.1:${FRONTEND_PORT}"
echo "日志:tail -f $LOGS/{backend,frontend}.log"
echo "停止:./run.sh stop"
;;
+34
View File
@@ -8,6 +8,7 @@
//! - `static_dir` = `<project_dir>/src/frontend/dist`,**不存在则 None**(前端产物没编译出来时
//! 不该让后端去托管一个不存在的目录)。
use std::net::{IpAddr, Ipv4Addr};
use std::path::{Path, PathBuf};
/// 后端默认端口。
@@ -15,6 +16,13 @@ use std::path::{Path, PathBuf};
/// 🔴 本仓固定 `:30010`;兄弟项目 `tdc-rs` 占 `:30000`,两者**不共享**任何东西。
pub const DEFAULT_PORT: u16 = 30010;
/// 后端**默认监听地址** = `127.0.0.1`(**只监听本机**)。
///
/// 🔴 默认值朝**安全方向**:本仓的种子口令是 `admin/123456`、token 永不过期
/// ⇒ 若默认监听所有网卡,局域网内可直接连上后端 ⇒ 必须默认只绑本机。
/// 要在容器 / 反代里对外暴露 ⇒ 显式设 `BIND_ADDR=0.0.0.0`。
pub const DEFAULT_BIND_ADDR: IpAddr = IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1));
/// `PGLITE_DIR` 设成该值 ⇒ 用**临时库**(进程退出即销毁)。
///
/// pglite-rs 0.2.7 **没有** 真内存模式(`memory://` 不是它的协议),
@@ -26,6 +34,11 @@ pub const TEMP_DIR_MARKER: &str = "memory://";
pub struct Config {
/// HTTP 监听端口(env `PORT`,缺省或非法 ⇒ `30010`)。
pub port: u16,
/// HTTP 监听地址(env `BIND_ADDR`,缺省或非法 ⇒ `127.0.0.1`)。
///
/// 🔴 **只接受字面 IP**(`127.0.0.1` / `0.0.0.0` / `::1`)⇒ **不解析主机名**
/// (`localhost` 会被判非法 ⇒ 回落 `127.0.0.1`,即朝安全方向回落)。
pub bind_addr: IpAddr,
/// pglite 数据目录(env `PGLITE_DIR`;值为 `memory://` ⇒ 临时库)。
pub pg_dir: PathBuf,
/// 项目根目录。
@@ -38,6 +51,8 @@ impl Config {
/// 从环境变量 + 传入的 `project_dir` 组装配置。
///
/// - `PORT`:非法值**不 panic**,回落 `30010`(配置写错不该让服务起不来)。
/// - `BIND_ADDR`:非法值**不 panic**,回落 `127.0.0.1`(**朝安全方向**回落,
/// 与 `PORT` 非法回落 `30010` 同一政策);**只接受字面 IP**,不解析主机名。
/// - `PGLITE_DIR`:空串按「未设置」处理 ⇒ 用默认数据目录。
pub fn from_env(project_dir: PathBuf) -> Config {
let port = std::env::var("PORT")
@@ -45,6 +60,11 @@ impl Config {
.and_then(|v| v.trim().parse::<u16>().ok())
.unwrap_or(DEFAULT_PORT);
let bind_addr = std::env::var("BIND_ADDR")
.ok()
.and_then(|v| v.trim().parse::<IpAddr>().ok())
.unwrap_or(DEFAULT_BIND_ADDR);
let pg_dir = match std::env::var("PGLITE_DIR") {
Ok(v) if !v.trim().is_empty() => PathBuf::from(v.trim()),
_ => project_dir.join("src/backend/data/lite.pg"),
@@ -55,6 +75,7 @@ impl Config {
Config {
port,
bind_addr,
pg_dir,
project_dir,
static_dir,
@@ -88,6 +109,19 @@ mod tests {
assert!(cfg.static_dir.is_none());
}
#[test]
fn bind_addr_defaults_to_loopback() {
// 外部若已设置 BIND_ADDR,本断言的前提不成立 ⇒ 跳过(不改动进程环境)。
if std::env::var("BIND_ADDR").is_ok() {
return;
}
// 未设 BIND_ADDR ⇒ 只监听本机(朝安全方向回落;与 PORT 非法回落 30010 同一政策)。
assert_eq!(DEFAULT_BIND_ADDR, IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)));
let cfg = Config::from_env(PathBuf::from("/tmp/does-not-exist-project"));
assert_eq!(cfg.bind_addr, DEFAULT_BIND_ADDR);
assert!(cfg.bind_addr.is_loopback());
}
#[test]
fn pg_is_temp_detects_marker() {
let mut cfg = Config::from_env(PathBuf::from("/tmp/x"));
+9
View File
@@ -165,6 +165,15 @@ impl Db {
self.scalar_text_inner(sql).await
}
/// 优雅关闭底层 pglite 后端(SIGTERM / SIGINT 停机路径用)。
///
/// 🔴 以前后端**忽略 SIGTERM** ⇒ 每次停机都是 `SIGKILL` 掉嵌入式 PostgreSQL
/// ⇒ 下次启动要 crash recovery,数据目录里还留 `postmaster.pid`。
/// 现在停机路径会先让 HTTP 服务收完在途请求,再调这里正常关库。
pub async fn shutdown(&self) -> Result<(), pglite::Error> {
self.pg.shutdown().await
}
// ---- 以下为**持锁调用**的内部实现(调用方已持有 `self.lock`)----
async fn query_json_inner(
+88 -5
View File
@@ -12,6 +12,9 @@
//! → `with_state(state)`(**链尾**));
//! 7. `TcpListener::bind` ⇒ 绑定失败**打印人话 + `exit 1`**(**不 panic**)。
//!
//! 🔴 **优雅停机**:`SIGTERM` / `SIGINT` ⇒ `with_graceful_shutdown` 收完在途请求 ⇒
//! 优雅关闭嵌入式 PostgreSQL(不再被 `SIGKILL` 打断 ⇒ 数据目录不留 `postmaster.pid`)。
//!
//! 🔴 本仓**刻意不同**于 react 版(那里是 try/catch + `logger.warn` 后**继续跑**):
//! 本仓是单二进制,启动期不变量破了就立刻退出 —— 服务要么正常起来,要么根本不起来。
@@ -139,6 +142,7 @@ fn print_usage() {
println!();
println!("环境变量:");
println!(" PORT 监听端口(缺省 30010)");
println!(" BIND_ADDR 监听地址(缺省 127.0.0.1 = 只监听本机;要对外暴露设 0.0.0.0)");
println!(" PGLITE_DIR pglite 数据目录;设成 memory:// 用临时库(进程退出即销毁)");
}
@@ -174,6 +178,8 @@ async fn run() -> Result<(), String> {
db: Arc::new(db),
sessions: Arc::new(SessionStore::new()),
};
// 🔴 保留一个 `Db` 句柄用于**停机时优雅关闭**嵌入式 PG(`state` 会被 `build_app` 吃掉)。
let db_for_shutdown = state.db.clone();
// ---- 第 6 步:路由装配 + 三层兜底 ----
// 🔴 装配链**只有一份**:`routes::build_app` —— S25 的顺序(`.fallback()` 在两个
@@ -182,21 +188,98 @@ async fn run() -> Result<(), String> {
let app = routes::build_app(state);
// ---- 第 7 步:绑定端口 ----
let addr = format!("0.0.0.0:{}", config.port);
let listener = tokio::net::TcpListener::bind(&addr)
// 🔴 **默认只监听 127.0.0.1**(`BIND_ADDR` 可覆盖)⇒ 与「文档写的就是 127.0.0.1」一致,
// 也避免「弱口令 + token 永不过期」的后端被局域网直接连上。
let addr = std::net::SocketAddr::new(config.bind_addr, config.port);
let listener = tokio::net::TcpListener::bind(addr)
.await
.map_err(|e| format!("绑定 {addr} 失败: {e}"))?;
println!(
"tds-lite-rs {} 已启动:http://127.0.0.1:{}(数据目录 {})",
"tds-lite-rs {} 已启动:http://{addr}(数据目录 {})",
env!("CARGO_PKG_VERSION"),
config.port,
config.pg_dir.display()
);
// 🔴 **优雅停机**:收到 SIGTERM / SIGINT ⇒ 先让 HTTP 服务收完在途请求,再关嵌入式 PG。
// (以前 SIGTERM 被忽略 ⇒ 每次停机都是 SIGKILL 掉嵌入式 PostgreSQL ⇒ 下次启动要
// crash recovery,数据目录里还留 `postmaster.pid`。)
axum::serve(listener, app)
.with_graceful_shutdown(shutdown_signal())
.await
.map_err(|e| format!("HTTP 服务异常退出: {e}"))
.map_err(|e| format!("HTTP 服务异常退出: {e}"))?;
// ---- 停机:优雅关闭嵌入式 PostgreSQL ----
// 🔴 **不 await** pglite 的关闭 future:pglite-rs 0.2.7 的 `PGlite::shutdown()` 给嵌入式 PG
// 发完 Terminate 之后**不会返回** —— PG 的 postmaster 会进入「拉起后端 → 后端读不到
// 完整协议 → FATAL → 再拉起」的循环(实测一次停机刷 30 多万行日志),收尾线程卡死在那儿。
// ⇒ 另起任务去发 Terminate,同时**盯住 `postmaster.pid` 何时消失**
// (PG 干净关库的**权威信号**)⇒ 一旦消失就立刻结束进程
// (顺带把 pglite 那段日志噪声压到最小)。
let shutdown_db = db_for_shutdown.clone();
tokio::spawn(async move {
if let Err(e) = shutdown_db.shutdown().await {
eprintln!("[停机] 关闭嵌入式 PostgreSQL 失败: {e}");
}
});
let pid_file = config.pg_dir.join("postmaster.pid");
let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(3);
if pid_file.exists() {
// 数据目录已知 ⇒ 等 `postmaster.pid` 消失(= PG 已干净关库)。
while pid_file.exists() && tokio::time::Instant::now() < deadline {
tokio::time::sleep(std::time::Duration::from_millis(5)).await;
}
} else {
// 临时库(`PGLITE_DIR=memory://`)⇒ 数据目录路径不可知 ⇒ 退化成「固定等 200ms」
//(实测嵌入式 PG 的干净关库只要几毫秒)。
tokio::time::sleep(std::time::Duration::from_millis(200)).await;
}
if pid_file.exists() {
eprintln!("[停机] ⚠️ 嵌入式 PostgreSQL 未在 3 秒内干净关库(`postmaster.pid` 仍在)");
} else {
println!("tds-lite-rs 已停止(嵌入式 PostgreSQL 已优雅关闭)。");
}
// 🔴 明确结束进程:pglite 的收尾线程可能卡死 ⇒ 不能让它吊住整个进程。
std::process::exit(0);
}
/// 等待**停机信号**(SIGTERM / SIGINT)—— 任一到来即返回。
///
/// 🔴 **只影响关停**,不改变任何请求处理路径的行为(契约一字不改)。
/// 🔴 tokio 的 `signal` feature 已在 workspace 的 `features = ["full"]` 里 ⇒ **不新增依赖**。
async fn shutdown_signal() {
#[cfg(unix)]
{
use tokio::signal::unix::{signal, SignalKind};
let mut term = match signal(SignalKind::terminate()) {
Ok(s) => s,
Err(e) => {
eprintln!("[停机] 注册 SIGTERM 失败(回落 Ctrl-C):{e}");
let _ = tokio::signal::ctrl_c().await;
return;
}
};
let mut intr = match signal(SignalKind::interrupt()) {
Ok(s) => s,
Err(e) => {
eprintln!("[停机] 注册 SIGINT 失败(只等 SIGTERM):{e}");
term.recv().await;
return;
}
};
tokio::select! {
_ = term.recv() => {}
_ = intr.recv() => {}
}
}
#[cfg(not(unix))]
{
let _ = tokio::signal::ctrl_c().await;
}
}
/// 从可执行文件向上找项目根(**与 cwd 解耦**)。
+98 -19
View File
@@ -1,4 +1,4 @@
//! routes —— 路由装配 + 三层兜底(404 / 405 / catch-all)。
//! routes —— 路由装配 + 三层兜底(404 / 405 / 413 改写 / catch-all)。
//!
//! 契约:`docs/contract.md` §9(`routes.rs` 接口)、§6.5(兜底三条)、§R1.2(业务失败恒 HTTP 200)。
//!
@@ -7,12 +7,12 @@
//! build_app(state) // ← 生产(main.rs)与单测都调它
//! build_router(state.clone())
//! .fallback(not_found_handler) // 404 兜底
//! .layer(m405_rewrite()) // 405 改写中间件
//! .layer(m_status_rewrite()) // 405 / 413 改写中间件
//! .layer(catch_all()) // panic 捕获中间件
//! .with_state(state) // ← 链尾(唯一一次把类型落成 Router<()>)
//! ```
//! `Router::layer` 是**后进先出** ⇒ 最后挂的最外层 ⇒ 请求**先**撞 `catch_all`,
//! **再**撞 `m405_rewrite`,**最后**才进 handler / 404 兜底。
//! **再**撞 `m_status_rewrite`,**最后**才进 handler / 404 兜底。
//!
//! 🔴 `.fallback(...)` 必须写在两个 `.layer(...)` **之前** —— axum 官方文档原话:
//! 「the middleware is only applied to existing routes. So you have to first add your
@@ -138,7 +138,7 @@ pub fn build_router(state: AppState) -> axum::Router<AppState> {
pub fn build_app(state: AppState) -> axum::Router {
build_router(state.clone())
.fallback(not_found_handler)
.layer(m405_rewrite())
.layer(m_status_rewrite())
.layer(catch_all())
.with_state(state)
}
@@ -174,7 +174,7 @@ pub async fn not_found_handler() -> (StatusCode, Json<ActionResult>) {
(StatusCode::NOT_FOUND, Json(envelope::fail(404, "接口不存在").0))
}
// ---------------------------------------------------------------- 405 改写中间件
// ---------------------------------------------------------------- 405 / 413 改写中间件
/// 中间件 future 的统一类型(boxed ⇒ 可命名 ⇒ 工厂函数的返回类型能写死)。
type MwFuture = Pin<Box<dyn Future<Output = Response> + Send>>;
@@ -182,36 +182,42 @@ type MwFuture = Pin<Box<dyn Future<Output = Response> + Send>>;
/// 中间件函数指针类型(fn 指针可命名 ⇒ 工厂函数的返回类型能写死)。
type MwFn = fn(Request, Next) -> MwFuture;
/// 405 改写中间件(挂在链尾的响应改写层)。
/// 405 / 413 改写中间件(挂在链尾的响应改写层)。
///
/// - **任何 405 都改写**成信封 body(契约 §6.5:405 ⇒ HTTP 405 +
/// `{code:405,msg:"方法不被允许",data:null}`)—— 🔴 **不看 body 是否为空**:
/// 「万一有 body 的 405 漏出非信封 body」是唯一的破口,不能留;
/// - **任何 413 都改写**成信封 body(传输状态码**保留** HTTP 413,body 换成
/// `{code:413,msg:"请求体过大",data:null}`)—— 改写前 axum 默认吐的是
/// `text/plain` 的 `Failed to buffer the request body: length limit exceeded`
/// ⇒ 服务端会冒出**第三种 body 形状**(契约 §2「没有第三种形状」的破口);
/// - **保留 `parts.headers`**(保住 `Allow` 头);
/// - 改写 `Content-Length`,body 换成 `{code:405,msg:"方法不被允许",data:null}`。
/// - 改写 `Content-Type` / `Content-Length`,body 换成对应信封。
///
/// 🔴 **非 405 响应原样放行**(不改写)。
/// 🔴 **非 405 / 非 413 的响应原样放行**(不改写)。
/// 🔴 **不要**用 axum 的 `method_not_allowed_fallback` —— 它只对「调用那一刻已注册的路由」
/// 生效,且**丢 `Allow` 头**。
pub fn m405_rewrite() -> axum::middleware::FromFnLayer<MwFn, (), (Request,)> {
axum::middleware::from_fn::<_, (Request,)>(m405_rewrite_fn)
pub fn m_status_rewrite() -> axum::middleware::FromFnLayer<MwFn, (), (Request,)> {
axum::middleware::from_fn::<_, (Request,)>(m_status_rewrite_fn)
}
fn m405_rewrite_fn(req: Request, next: Next) -> MwFuture {
Box::pin(m405_rewrite_inner(req, next))
fn m_status_rewrite_fn(req: Request, next: Next) -> MwFuture {
Box::pin(m_status_rewrite_inner(req, next))
}
async fn m405_rewrite_inner(req: Request, next: Next) -> Response {
async fn m_status_rewrite_inner(req: Request, next: Next) -> Response {
let res = next.run(req).await;
// 只处理 405(非 405 原样放行)。
if res.status() != StatusCode::METHOD_NOT_ALLOWED {
return res;
}
// 🔴 **任何 405 都改写**(不看 body 是否为空)—— 契约 §6.5 要求 405 恒是信封 body。
// 只处理 405 / 413(其它状态码原样放行)。
let (code, msg) = match res.status() {
StatusCode::METHOD_NOT_ALLOWED => (405, "方法不被允许"),
StatusCode::PAYLOAD_TOO_LARGE => (413, "请求体过大"),
_ => return res,
};
// 🔴 **任何 405 / 413 都改写**(不看 body 是否为空)—— 契约要求这两类恒是信封 body。
// 🔴 `serde_json::to_vec` 对本结构体恒成功;真失败 ⇒ 保留原响应(不冒险改坏)。
let Ok(bytes) = serde_json::to_vec(&envelope::fail(405, "方法不被允许").0) else {
let Ok(bytes) = serde_json::to_vec(&envelope::fail(code, msg).0) else {
return res;
};
@@ -355,6 +361,38 @@ mod tests {
String::from_utf8_lossy(&buf).to_string()
}
/// 发一个**超大 body** 的 POST,返回完整原始响应(头 + 体)。
///
/// 🔴 写 / 读的错误**必须容忍**:服务端判定 body 超限后会**立刻回 413**,
/// 并且**不再继续读**请求体 ⇒ 若客户端多写了,socket 上有未读数据 ⇒
/// 服务端只能 RST(这正是真实客户端 curl 会看到的形态)。
/// ⇒ 这里把 body 控制在「**刚好超过上限 1 字节**」,
/// 让服务端把 body 全部读走 ⇒ 干净 FIN ⇒ 响应能完整读到。
async fn raw_oversized(port: u16, request: &str) -> String {
let mut stream = tokio::net::TcpStream::connect(("127.0.0.1", port))
.await
.expect("连接失败");
let _ = stream.write_all(request.as_bytes()).await;
let _ = stream.flush().await;
let mut buf = Vec::new();
let mut tmp = [0u8; 16 * 1024];
// 收尾读:容忍 `ECONNRESET`(服务端 RST)—— 已读到的字节照样能用。
loop {
match tokio::time::timeout(
std::time::Duration::from_secs(2),
stream.read(&mut tmp),
)
.await
{
Ok(Ok(0)) => break,
Ok(Ok(n)) => buf.extend_from_slice(&tmp[..n]),
Ok(Err(_)) => break,
Err(_) => break,
}
}
String::from_utf8_lossy(&buf).to_string()
}
fn get(path: &str) -> String {
format!("GET {path} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n")
}
@@ -402,6 +440,47 @@ mod tests {
assert_eq!(body["data"], Value::Null);
}
/// 🔴 **超大 body ⇒ HTTP 413 + 信封**(契约 §2「没有第三种形状」)。
///
/// axum 的默认 body 上限是 2MB ⇒ 这里发**刚好超过 1 字节**的 JSON。
/// 改写前服务端会吐 `text/plain` 的 `Failed to buffer the request body: length limit exceeded`
/// ⇒ 那就是**第三种 body 形状** ⇒ 必须被归一成信封。
#[tokio::test]
async fn oversized_body_returns_http_413_with_envelope() {
let port = serve(new_state(db().await)).await;
// axum 默认 body 上限 = 2MB(2*1024*1024 字节)⇒ 这里发**刚好超过 1 字节**的 JSON。
// 🔴 刻意不做「远远超过」:多写的字节服务端不会读 ⇒ socket 残留未读数据 ⇒ RST ⇒ 响应读不全。
const LIMIT: usize = 2 * 1024 * 1024;
let prefix = "{\"account\":\"big_user\",\"password\":\"x\",\"realName\":\"";
let suffix = "\"}";
let padding = "a".repeat(LIMIT + 1 - prefix.len() - suffix.len());
let payload = format!("{prefix}{padding}{suffix}");
assert_eq!(payload.len(), LIMIT + 1);
let req = format!(
"POST /api/ssw/sys/User/Save HTTP/1.1\r\nHost: localhost\r\n\
Content-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
payload.len(),
payload
);
let raw = raw_oversized(port, &req).await;
assert!(
raw.starts_with("HTTP/1.1 413 Payload Too Large"),
"超大 body 必须是 HTTP 413,实际: {}",
&raw[..raw.len().min(400)]
);
let (head, body) = raw.split_once("\r\n\r\n").expect("响应必须有头体分隔");
assert!(
head.to_ascii_lowercase()
.contains("content-type: application/json"),
"413 必须是 JSON 信封,实际头: {head}"
);
let body: Value = serde_json::from_str(body).expect("响应体必须是合法 JSON");
assert_eq!(body["code"], 413);
assert_eq!(body["msg"], "请求体过大");
assert_eq!(body["data"], Value::Null);
}
/// 🔴 **路由表钉子测试** —— 27 条路径一条都不许少、一条都不许拼错。
///
/// 用「错方法 ⇒ 405」当作「这条路径确实注册了」的探针(比逐条调真接口便宜,