From 1539892d86e7c41d65697a6952ef72ca4e036f57 Mon Sep 17 00:00:00 2001 From: admin Date: Mon, 26 Oct 2026 05:22:57 +0800 Subject: [PATCH] =?UTF-8?q?fix(final):=20=E5=89=8D=E7=AB=AF=E5=B0=B1?= =?UTF-8?q?=E7=BB=AA=E6=A0=A1=E9=AA=8C=20+=20=E7=BB=91=20127.0.0.1=20+=204?= =?UTF-8?q?13=20=E4=BF=A1=E5=B0=81=E5=8C=96=20+=20=E4=BC=98=E9=9B=85?= =?UTF-8?q?=E5=81=9C=E6=9C=BA=20+=20=E6=96=87=E6=A1=A3=E4=BA=8B=E5=AE=9E?= =?UTF-8?q?=E4=BF=AE=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .env.example | 10 ++++ HANDOFF.md | 36 ++++++++---- README.md | 13 +++-- docs/runbook.md | 27 +++++++-- run.sh | 45 +++++++++++++-- src/backend/src/config.rs | 34 +++++++++++ src/backend/src/db.rs | 9 +++ src/backend/src/main.rs | 93 ++++++++++++++++++++++++++++-- src/backend/src/routes.rs | 117 +++++++++++++++++++++++++++++++------- 9 files changed, 337 insertions(+), 47 deletions(-) diff --git a/.env.example b/.env.example index a38e3d6..5df49ef 100644 --- a/.env.example +++ b/.env.example @@ -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` diff --git a/HANDOFF.md b/HANDOFF.md index 78b7055..63864ef 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -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` 遇**畸形百分号编码** ⇒ axum 默认返**纯文本 400(非信封)**(handler 签名由契约 §S17 定死,改它要动 `sys.rs`)。 +- **(l)** ~~`Path` 遇**畸形百分号编码** ⇒ 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` 的**行为口径**(不是缺陷,是刻意设计): diff --git a/README.md b/README.md index 21b0aa3..e97432c 100644 --- a/README.md +++ b/README.md @@ -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` 遇畸形百分号编码** ⇒ axum 默认返纯文本 400(**非信封**);handler 签名由契约定死。 +- **`Path` 遇畸形百分号编码** ⇒ **实测 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)。 diff --git a/docs/runbook.md b/docs/runbook.md index b59f337..41768d1 100644 --- a/docs/runbook.md +++ b/docs/runbook.md @@ -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` 对它是**原样使用** ⇒ 相对路径会相对**当前工作目录**解析 diff --git a/run.sh b/run.sh index baf7186..678c11b 100755 --- a/run.sh +++ b/run.sh @@ -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" ;; diff --git a/src/backend/src/config.rs b/src/backend/src/config.rs index 30d9d17..f3cf396 100644 --- a/src/backend/src/config.rs +++ b/src/backend/src/config.rs @@ -8,6 +8,7 @@ //! - `static_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::().ok()) .unwrap_or(DEFAULT_PORT); + let bind_addr = std::env::var("BIND_ADDR") + .ok() + .and_then(|v| v.trim().parse::().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")); diff --git a/src/backend/src/db.rs b/src/backend/src/db.rs index 5cc7fa9..57cd2bc 100644 --- a/src/backend/src/db.rs +++ b/src/backend/src/db.rs @@ -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( diff --git a/src/backend/src/main.rs b/src/backend/src/main.rs index 7ae6c40..2e01ab6 100644 --- a/src/backend/src/main.rs +++ b/src/backend/src/main.rs @@ -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 解耦**)。 diff --git a/src/backend/src/routes.rs b/src/backend/src/routes.rs index 24e3e35..3c84bc0 100644 --- a/src/backend/src/routes.rs +++ b/src/backend/src/routes.rs @@ -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 { 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) { (StatusCode::NOT_FOUND, Json(envelope::fail(404, "接口不存在").0)) } -// ---------------------------------------------------------------- 405 改写中间件 +// ---------------------------------------------------------------- 405 / 413 改写中间件 /// 中间件 future 的统一类型(boxed ⇒ 可命名 ⇒ 工厂函数的返回类型能写死)。 type MwFuture = Pin + Send>>; @@ -182,36 +182,42 @@ type MwFuture = Pin + 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 { - axum::middleware::from_fn::<_, (Request,)>(m405_rewrite_fn) +pub fn m_status_rewrite() -> axum::middleware::FromFnLayer { + 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」当作「这条路径确实注册了」的探针(比逐条调真接口便宜,