diff --git a/.doc/ops/long-term/2026-09-19-audit-remainder.md b/.doc/ops/long-term/2026-09-19-audit-remainder.md index b66c2ad1..a23846fe 100644 --- a/.doc/ops/long-term/2026-09-19-audit-remainder.md +++ b/.doc/ops/long-term/2026-09-19-audit-remainder.md @@ -117,3 +117,7 @@ updated: 2026-09-19 | T20-I6 | backup 无定时调度 | ops | systemd/cron；RPO 60m | | T20-I7 | **main 分支对齐晋升专项** | git main vs schema 52 | 独立授权；含 00057 改名预演 | | T20-I8 | 默认 short 测依赖外网 docker 镜像 | `pi_runner_image_test.go` | Short 跳过或本地 fixture | + +### 设计收口（2026-09-22 W4，未实施） + +上表中 **B1/B3/B4/B5/B7/B11/F1/F4/F7/F8/I1/I4/I6** 的选定做法见 [../../system-design/2026-09-22-t20-hardening-design.md](../../system-design/2026-09-22-t20-hardening-design.md)；任务 [../short-term/2026-09-22-t20-design-items.md](../short-term/2026-09-22-t20-design-items.md)。低风险已实现项见 [../short-term/2026-09-22-t20-lowrisk-hardening.md](../short-term/2026-09-22-t20-lowrisk-hardening.md)。F4/F7/I6 仍分别卡产品、鉴权专项、环境授权。 diff --git a/.doc/ops/short-term/2026-09-22-t20-design-items.md b/.doc/ops/short-term/2026-09-22-t20-design-items.md new file mode 100644 index 00000000..f8c84326 --- /dev/null +++ b/.doc/ops/short-term/2026-09-22-t20-design-items.md @@ -0,0 +1,112 @@ +--- +title: "T20 设计项决策批（W4）" +task_id: t20-design-items-2026-09-22 +status: done +created: 2026-09-22 +updated: 2026-09-22 +owner: Cursor +task_type: research +task_tier: small +policy_revision: "AGENTS.md + 2026-09-21-policy-registry @ base_dev_sha" +branch: feature/t20-design-items-2026-09-22 +worktree: .worktrees/t20-design-items-2026-09-22 +base_dev_sha: "364ed7f1a3f0393ef77ec4623a9518116ed2cb87" +write_scope: + - .doc/ops/short-term/2026-09-22-t20-design-items.md + - .doc/system-design/2026-09-22-t20-hardening-design.md + - .doc/system-design/README.md + - .doc/remediation/INDEX.md +allowed_environments: [] +head_sha: "" +mutex: "t20-design-docs" +review_state: pending +integration_state: pending +deployment: not_required +cleanup: pending +cleanup_owner: 独立集成/维护执行者 +cleanup_trigger: tip 为 origin/dev 祖先且无进程占用后复查 remove +remote_sync: not_requested +--- + +# T20 设计项决策批（W4） + +设计正文（taxonomy：`system-design/`）：[../../system-design/2026-09-22-t20-hardening-design.md](../../system-design/2026-09-22-t20-hardening-design.md)。 + +## 用户目标与授权 + +- 用户目标：对 [audit-remainder T20 增补区](../long-term/2026-09-19-audit-remainder.md) 中需设计的项产出**推荐做法 / 风险 / 验收 / 是否卡产品或鉴权**，非完整实现（除非 trivial 且安全）。 +- 交付终点：本任务文 + 系统设计决策文；本 worktree 提交；不 push；不合入；不改业务代码。 +- 明确禁止：实现 B1/B3/B4/B5/B7/B11/F1/F4/F7/F8/I1/I4/I6；不操作共享环境；不 push；I6 不写宿主调度。 +- I6 仅文档化；实施需环境授权。 + +## 范围与非目标 + +| ID | 项 | 本批产物 | +|----|----|----------| +| B1 | XFF trusted proxy | 设计决策 | +| B3 | docgov/docrevision 锁拆分 | 设计决策 | +| B4 | statement_timeout 分级 | 设计决策 | +| B5 | chat/turn 原子性（已有补偿） | 设计决策（不重做补偿） | +| B7 | graceful shutdown vs AGENT_TIMEOUT | 设计决策 | +| B11 | GET→POST EventSource | 设计决策 | +| F1 | useChatWindow generation 所有权 | 设计决策 | +| F4 | adminResetPassword 产品选择 | 设计决策（卡产品） | +| F7 | HttpOnly cookie | 设计决策（卡鉴权专项） | +| F8 | poll dedupe + App.tsx stats generation | 设计决策 | +| I1 | non-root + limits | 设计决策 | +| I4 | init mount 统一 | 设计决策 | +| I6 | backup 调度 | **仅文档**；卡环境授权 | + +### 不重复（已在低风险批） + +| ID | 状态 | 交叉链接 | +|----|------|----------| +| **F5** ErrorBoundary 分栏 | 已在 W2 实现（`AppShell` 聊天栏/文档栏各包一层） | [t20-lowrisk-hardening](./2026-09-22-t20-lowrisk-hardening.md) · worktree `.worktrees/t20-lowrisk-hardening-2026-09-22` | +| **I8** short 跳过外网 docker | 已在 W2 实现（`testing.Short()` Skip） | 同上 | + +本批**不**再设计或实现 F5/I8。 + +## 决策一览 + +| ID | 推荐 | 卡产品/鉴权？ | 实施前置 | +|----|------|---------------|----------| +| B1 | 默认忽略 XFF；仅 `TRUSTED_PROXY_CIDRS` 命中 RemoteAddr 时按 hops 解析 | 否（运维配置） | 配置项 + 负例测试 | +| B3 | 锁外 hydrate；按 `doc_id` 分锁；DB 写用短临界区 + fencing | 否 | 竞态基准 + 回归 | +| B4 | 主池默认 `statement_timeout=30s`；长任务 `SET LOCAL` 抬高 | 否 | 池工厂统一入口 | +| B5 | **保留** `FailChatTurn` 补偿；补齐可观测与孤儿清理；同事务列为可选后续 | 否 | 指标/扫描即可先落地 | +| B7 | 独立 `SHUTDOWN_DRAIN`（默认可对齐 `AGENT_TIMEOUT`）；停机拒新任务；compose grace 对齐 | 否（运维调参） | compose/env 对齐 | +| B11 | 生产仅 POST；GET 默认 405 且永不读 `message` query | 否 | 前端已 POST；后端收紧 | +| F1 | 所有窗口写路径共用 generation + abort；过期响应禁 setState/写缓存 | 否 | 单测扩面 | +| F4 | **隐藏按钮**直至真实 API；或产品选「服务端生成临时口令 + 强制改密」 | **是（产品）** | 产品选路径后再编码 | +| F7 | 专项：`Set-Cookie` HttpOnly + SameSite + 全局 401 清会话 | **是（鉴权专项）** | 独立授权/ADR | +| F8 | 统一 in-flight Map 按 key 去重；stats 绑 generation；blob revoke | 否 | 前端小改 | +| I1 | Dockerfile `USER` + compose mem/cpus；先非 privileged | 否（运维；部署共享环境另授权） | 卷权限验证 | +| I4 | 三环境统一挂 `extensions_init.sql`；表只走 goose | 否 | 全新卷冒烟 | +| I6 | systemd/cron 调 `backup-system-db.sh`；RPO 60m | **是（环境授权）** | 仅文档；不实施 | + +详细论证见 [2026-09-22-t20-hardening-design.md](../../system-design/2026-09-22-t20-hardening-design.md)。 + +## 步骤与验收 + +1. [x] 核对代码与 audit-remainder 条目 +2. [x] 交叉确认 F5/I8 在 lowrisk worktree +3. [x] 写入 short-term + system-design；INDEX/README 回链 +4. [x] Conventional Commit（不 push） + +| 范围 | 命令 | 预期 | 实际 | +|---|---|---|---| +| 文档 | short-term + system-design + 索引 | 可审、taxonomy 正确；无业务行为变更 | 本分支提交 | + +## 收口与交接 + +- `review_state=pending`；`integration_state=pending`；`deployment=not_required`；`remote_sync=not_requested`。 +- 实施跟进：可并行小改（B1/B11/F1/F8、F4-A 隐藏按钮）与需决策项（F4-B/F7/I6）拆批；B3/B4/B7/I1/I4 需回归与环境冒烟。 +- **待用户决策**：F4 选隐藏 vs 真实临时口令 API；F7 鉴权专项授权；I6 目标环境与备份路径授权。 +- cleanup：合入后由独立维护者复查 remove。 + +## 相关链接 + +- 清单：[../long-term/2026-09-19-audit-remainder.md](../long-term/2026-09-19-audit-remainder.md) +- 审计：[../../audit/2026-09-20-system-triage-audit.md](../../audit/2026-09-20-system-triage-audit.md) +- 设计正文：[../../system-design/2026-09-22-t20-hardening-design.md](../../system-design/2026-09-22-t20-hardening-design.md) +- 低风险批（F5/I8）：[./2026-09-22-t20-lowrisk-hardening.md](./2026-09-22-t20-lowrisk-hardening.md)（合入前见 worktree `t20-lowrisk-hardening-2026-09-22`） diff --git a/.doc/remediation/INDEX.md b/.doc/remediation/INDEX.md index fc5ffb9a..ca0532f6 100644 --- a/.doc/remediation/INDEX.md +++ b/.doc/remediation/INDEX.md @@ -2,6 +2,7 @@ | 文档 | 说明 | |------|------| +| [../system-design/2026-09-22-t20-hardening-design.md](../system-design/2026-09-22-t20-hardening-design.md) | T20 W4 加固设计决策（XFF、锁拆分、timeout、shutdown、SSE POST、前端 generation/cookie、compose non-root/init、backup 调度文档）；F5/I8 见 lowrisk 批。配套 [任务](../ops/short-term/2026-09-22-t20-design-items.md) | | [../system-design/2026-09-20-stage-backtrack-and-impact-loop-design.md](../system-design/2026-09-20-stage-backtrack-and-impact-loop-design.md) | 阶段回溯与影响闭环：L1 修订 / L2 再打开、待复核软标记、对话提案桥。追踪留存定为 `record`；候选边由下游编制人裁决。配套 short-term 切片均为 planned | | [2026-09-20-module-decoupling-batch-plan.md](./2026-09-20-module-decoupling-batch-plan.md) | 耦合残留分批 A–G（server 装配、逻辑环、docgov 词汇、工作流依赖、巨型文件、前端 client、例外清零）；保持 planned，不改代码。配套 [审计](../audit/2026-09-20-module-coupling-audit.md) · [规范](../system-design/2026-09-20-module-development-standards.md) | | [2026-09-20-p0-remediation-plan.md](./2026-09-20-p0-remediation-plan.md) | 系统体检 P0：迁移 00058、三项 IDOR、panic/race/XSS、凭证与口令轮换；配套 [审计](../audit/2026-09-20-system-triage-audit.md) | diff --git a/.doc/system-design/2026-09-22-t20-hardening-design.md b/.doc/system-design/2026-09-22-t20-hardening-design.md new file mode 100644 index 00000000..1b90c5ea --- /dev/null +++ b/.doc/system-design/2026-09-22-t20-hardening-design.md @@ -0,0 +1,529 @@ +--- +title: "T20 加固设计决策（W4）" +status: proposed +created: 2026-09-22 +updated: 2026-09-22 +owner: Cursor +base_dev_sha: "364ed7f1a3f0393ef77ec4623a9518116ed2cb87" +source_audit: "../audit/2026-09-20-system-triage-audit.md" +source_backlog: "../ops/long-term/2026-09-19-audit-remainder.md" +task: "../ops/short-term/2026-09-22-t20-design-items.md" +--- + +# T20 加固设计决策（W4） + +> 本文件是**设计决策**，不是实施计划全文。实现另开 short-term；本批不改业务代码。 +> 低风险已实现项（F5/I8）交叉链接：[t20-lowrisk 任务文](../ops/short-term/2026-09-22-t20-lowrisk-hardening.md)（当前在 worktree `.worktrees/t20-lowrisk-hardening-2026-09-22`，合入 `dev` 后本相对路径生效）。**本文不重复设计 F5/I8。** + +核对基线：`feature/t20-design-items-2026-09-22` @ `364ed7f1`。 + +--- + +## 总表 + +| ID | 推荐摘要 | 卡产品/鉴权/环境？ | 建议优先级 | +|----|----------|-------------------|------------| +| B1 | 默忽视 XFF；仅可信代理 CIDR 命中时解析 | 否（运维 CIDR） | P1 | +| B3 | 按 docID 分锁；hydrate/DB I/O 出全局锁 | 否 | P1（独立大改） | +| B4 | 主库池级 `statement_timeout` 分级 | 否 | P1 | +| B5 | **保留** `FailChatTurn` 补偿；补可观测；同事务可选 | 否 | P2 | +| B7 | drain 超时与 `AGENT_TIMEOUT` / compose grace 对齐 | 否（运维调参） | P1 | +| B11 | 生产禁 GET 传 `message`；保留 POST body | 否 | P1（小） | +| F1 | 所有窗口写路径统一 generation + Abort | 否 | P1 | +| F4 | 先隐藏死按钮；完整能力需产品选型 | **是（产品）** | 决策后 | +| F7 | 先全局 401；HttpOnly cookie 独立 epic | **是（鉴权专项）** | Cookie=P2 | +| F8 | poll/stats 去重 + generation；blob revoke | 否 | P1 | +| I1 | 非 root USER + mem/cpu limits | 部署需环境授权 | 设计可合 | +| I4 | 三环境统一 `extensions_init.sql` | 改卷需环境授权 | 设计可合 | +| I6 | systemd/cron 调备份脚本，RPO≤60m | **是（环境写）** | **仅文档** | + +--- + +## B1 — XFF 可信代理 + +### 现状 + +`internal/server/login_rate_limit.go` 的 `clientIP` **无条件**取 `X-Forwarded-For` 首跳，否则 `RemoteAddr`。攻击者可伪造 XFF，使登录限流桶分散，绕过爆破防护。 + +### 推荐做法 + +1. 新增配置 `TRUSTED_PROXY_CIDRS`（逗号分隔 CIDR；空=不信任任何代理）。 +2. 仅当 `RemoteAddr` 落入可信 CIDR 时解析转发头： + - 取 XFF 链中**最右非可信**地址（或配置 `TRUSTED_PROXY_HOPS=N` 剥掉右侧 N 跳）。 + - 否则一律用 `RemoteAddr`（剥端口）。 +3. 可选：同样规则用于审计日志 IP；登录限流 key 继续 `ip|username`。 +4. 默认生产 compose **不**填 CIDR（直连或仅 docker 内网时安全）；有 nginx/traefik 时由运维填代理网段。 + +### 风险 + +- 配错 CIDR → 全站限流落到代理 IP，正当用户互锁。缓解：启动日志打印有效 CIDR；监控 `login_rate_limited` 按 raw RemoteAddr。 +- 多级代理跳数错误 → IP 仍可伪造。缓解：文档要求「只信直连上一跳」；优先 CIDR 白名单而非盲目 `HOPS`。 + +### 验收 + +- 单元：伪造 XFF + RemoteAddr∉CIDR → key 用 RemoteAddr；∈CIDR → 用解析后的客户端 IP。 +- 负例：空 CIDR 时带任意 XFF 不得改变限流 key。 +- 不要求浏览器 E2E。 + +### 是否卡产品/鉴权 + +否。运维配置即可。 + +--- + +## B3 — docgov / docrevision 锁拆分 + +### 现状 + +- `docrevision.Service`：进程级 `sync.Mutex`；`hydrateDocLocked` 在持锁时打 PG。 +- `docgov.GovernanceEngine`：`RWMutex`；`AcquireLease` 等路径在锁内 `getDoc` / `persistLease`（含 DB）。 + +结果：单文档慢查询阻塞**全部**文档的修订/租约路径。 + +### 推荐做法（两阶段） + +**阶段 A（优先，行为不变）** + +1. **锁外 hydrate**：先在无锁或 doc 级锁下从 PG 加载到临时结构，再短临界区合并进内存 map（CAS / version 校验）。 +2. **按 `doc_id` 分锁**：`map[string]*sync.Mutex` + 全局 `RWMutex` 仅保护「分锁表」本身；文档间并行。 +3. DB 写：短临界区准备参数 → 锁外执行 SQL → 短临界区提交内存；失败回滚内存镜像。 +4. 租约继续依赖既有 fencing token / TTL；不引入新分布式锁。 + +**阶段 B（可选）** + +- 热路径逐步改为「PG 为 SSOT、内存为缓存」，减少 hydrate 频率；需单独容量评估，不与 A 绑死。 + +### 风险 + +- 分锁 + 锁外 I/O 易引入 TOCTOU；必须用 fencing / 乐观版本。 +- 死锁：统一锁序 `globalMeta → docID`（docID 字典序若需多文档）。 +- 回归面：`document_commit_concurrency_pg_test`、lease 单测、修订 idempotent 路径。 + +### 验收 + +- 基准：两文档并行 hydrate/commit，全局锁持有时间不覆盖对方 DB RTT（可用 race + 计时断言或日志采样）。 +- 既有 PG 并发提交 / lease busy 负例全绿。 +- `go test -race` 覆盖 docrevision + docgov 包。 + +### 是否卡产品/鉴权 + +否。工程改造。 + +--- + +## B4 — `statement_timeout` 分级 + +### 现状 + +- 主库：`bizdev.NewService` 用 `pgxpool.New(dsn)`，**无** `statement_timeout` / MaxConns 调优。 +- KB：`kb.OpenPool` 仅设 `MaxConns=8`，仍无 timeout。 + +长查询可占满连接，拖垮健康检查与短 API。 + +### 推荐做法 + +1. 抽出共享 `db.OpenAppPool(ctx, dsn, PoolProfile)`（或扩现有 `internal/db`）： + - **default**：`statement_timeout=30s`，`MaxConns` 按环境（建议 dev 8 / test 16 / main 可配）。 + - **migrate**：启动迁移会话显式抬高或 `0`（仅迁移连接）。 + - **long**：PI/索引/报表等路径在事务内 `SET LOCAL statement_timeout = '15min'`（或绑定 `AGENT_TIMEOUT`）。 +2. 禁止在业务 SQL 字符串里散落裸 timeout；分级只通过池默认 + `SET LOCAL`。 +3. 超时映射为 typed 错误信封（503/504 或既有 code），不把 PG 原文回前端。 + +### 风险 + +- 误伤合法长事务（修订大文档、embedding 批）。缓解：long profile + 白名单调用点。 +- 与上下文 `context.WithTimeout` 双重取消；以更严者为准，日志区分来源。 + +### 验收 + +- 单元/集成：池 `RuntimeParams` 含 `statement_timeout`；人为 `pg_sleep` 超过默认 → 连接释放且 API 失败可控。 +- 迁移路径仍能跑完整 goose 链。 +- 健康检查不因无关慢查询长期饿死（抽样）。 + +### 是否卡产品/鉴权 + +否。 + +--- + +## B5 — chat 消息与 turn 原子性 + +### 现状 + +- `chat_turns` 与 `chat_messages` **非**同一 SQL 事务写入。 +- **补偿已存在**：`session.sendMessageInternal` 在 `clientTurnID != ""` 时 `defer FailChatTurn`；用户消息落库失败显式 `FailChatTurn`；成功路径 `CompleteChatTurn`（见 `internal/chat/session.go`）。 +- `AcquireChatTurn` 提供租约/幂等；过期 processing 可打 failed。 + +因此「完全无补偿」的审计表述已过时；剩余是**窗口期孤儿**与可观测性，不是从零设计补偿。 + +### 推荐做法 + +1. **本阶段不强制同事务**（改动面大，且消息与 turn 可能跨连接）。 +2. 加固现有补偿： + - `FailChatTurn` / `CompleteChatTurn` 错误打结构化日志 + 计数（勿静默 `_ =`）。 + - 周期/启动扫描：`status=processing AND lease_expires_at < now()` → failed（已有单条路径，升为批量）。 + - 可选：用户消息已写、turn 未绑定 `user_message_id` 的孤儿告警。 +3. **可选后续（P2）**：同一 `pgx.Tx` 内 `INSERT message` + `UPDATE turn`；失败整回滚。仅在确认补偿指标仍噪声大时做。 + +### 风险 + +- 同事务可能拉长锁时间、与 stream 生命周期纠缠。 +- 过度扫描压力；限制 batch size 与频率。 + +### 验收 + +- 文档/测试明确：persist 失败 ⇒ turn=failed；完成 ⇒ completed + assistant id。 +- 注入 fail 点：用户消息成功后进程崩溃 → 租约过期后 turn 终态可查，可重放同 `client_turn_id` 不双写助手（幂等语义保持）。 +- **不**把「缺同事务」单独列为发布 blocker。 + +### 是否卡产品/鉴权 + +否。 + +--- + +## B7 — graceful shutdown vs `AGENT_TIMEOUT` + +### 现状 + +- `cmd/server/main.go`：`Shutdown` 固定 **5s**。 +- Compose / `.env`：`AGENT_TIMEOUT` 默认 **30m**（示例可达 60m）。 +- Compose **无** `stop_grace_period` → Docker 默认 ~10s 后 SIGKILL。 + +结果：滚动重启时长任务被砍；in-flight SSE/PI 无法 drain。 + +### 推荐做法 + +1. 引入 `SHUTDOWN_DRAIN_TIMEOUT`（默认 `min(AGENT_TIMEOUT, 35m)` 或显式 31m），`main` 用其做 `Shutdown` context。 +2. Shutdown 顺序： + - 停止接受新 HTTP（`http.Server.Shutdown`）； + - 标记「拒新 Agent/taskrun」（若尚无 gate，加 `atomic` 或复用 ready）； + - 等待 in-flight 结束或 drain 超时； + - 再关池 / worker。 +3. 三环境 compose：`stop_grace_period` ≥ `SHUTDOWN_DRAIN_TIMEOUT`（建议 +30s 缓冲）。 +4. **不**要求 drain 等满整个 AGENT_TIMEOUT 才退出运维窗口：可由运维设更短 drain，并接受超时强杀；但 5s 与 30m 的错配必须消除。 + +### 风险 + +- 过长 grace 拖慢部署。缓解：test/dev 可较短；main 对齐真实 Agent 上限。 +- 任务被拒新后客户端重试风暴。缓解：503 + Retry-After；前端识别。 + +### 验收 + +- 配置单测：env 解析。 +- 手册/注释：compose grace ≥ drain。 +- 手工（授权环境）：起长 sleep handler 或短 Agent，SIGTERM 后观察是否在 grace 内结束或明确超时日志（实施时做）。 + +### 是否卡产品/鉴权 + +否。运维调参。 + +--- + +## B11 — GET→POST EventSource（消息体） + +### 现状 + +- `handleChatStream`：POST JSON **与** GET query（含 **`message`**）并存，注释为 EventSource/调试。 +- 生产前端 `web/src/api/chatStream.ts` **已用 POST + body**，不依赖 EventSource GET。 + +GET 将用户正文写入 URL → 代理/访问日志泄露；长度受限。 + +### 推荐做法 + +1. **生产路径**：仅允许 `POST /api/v1/chat/stream` 带 JSON body（维持现状前端）。 +2. GET： + - **首选**：直接拒绝 GET（405），或仅当 `APP_ENV=dev` 且 `CHAT_STREAM_GET_DEBUG=1` 允许，且**禁止** `message` query（只允许已有 run 订阅类参数，若有）。 + - 过渡：GET 若带非空 `message` → 400，文案指向 POST。 +3. 文档/OpenAPI 删除「EventSource 传消息」示例。 + +### 风险 + +- 外部脚本仍用 GET。缓解：变更说明；405 明确。 +- 无。前端已 POST。 + +### 验收 + +- 测试：GET+`message` → 4xx；POST 同行仍 200 流式（现有测即可）。 +- `rg 'EventSource|/chat/stream.*GET' web/` 无生产依赖。 + +### 是否卡产品/鉴权 + +否。 + +--- + +## F1 — `useChatWindow` generation 所有权 + +### 现状 + +- `loadInitialWindow` 已用 `generationRef` + `AbortController`。 +- `loadOlder` / `loadFullDay` / 锚点加载等**未**绑定同一 generation：切会话后晚到响应仍可能 `setDayStack` / 写 `saveSessionWindowCache`。 +- 已有 `useChatWindow.race.test.ts` 覆盖「主窗口」模式，未覆盖 loadOlder。 + +### 推荐做法 + +1. 约定：**凡会写 `dayStack` / 缓存 / phase 的异步函数**必须： + - 入口捕获 `const gen = generationRef.current`（或 `++` 仅由 session effect 负责）； + - `fetch` 传 `AbortSignal`； + - resolve 后若 `gen !== generationRef.current` 则 return，禁止 setState/写缓存。 +2. `sessionId` 变化时现有 effect 已 `abort` + `generation++`；保持单一所有者（该 effect），子函数只读。 +3. 扩展单测：切会话后 resolve 的 loadOlder 不得污染新会话缓存。 + +### 风险 + +- 漏改某一路径。缓解：checklist + 测试表驱动。 +- abort 触发 `AbortError` 日志噪音；吞掉或降级 debug。 + +### 验收 + +- 单测：A→B 切换后 A 的 loadOlder resolve 不改变 B 的 stack/cache。 +- 手工：快速连点会话，历史不串台。 + +### 是否卡产品/鉴权 + +否。 + +--- + +## F4 — `adminResetPassword` 产品选择 + +### 现状 + +- UI：`UsersSection` 硬编码临时口令 `ResetPass123`，调用 `authClient.adminResetPassword`。 +- API 客户端：直接 `throw new Error('请通过后端管理员接口重置密码')` —— **死功能**。 +- 后端：有 `POST /api/v1/auth/change-password`（自助），**无**管理员重置端点；创建用户已支持初始口令 + `must_change_password`。 + +### 产品选项（择一） + +| 选项 | 做法 | 安全 | +|------|------|------| +| **A. 隐藏/禁用（推荐短期）** | 去掉或 disable「重置密码」按钮；文案引导「停用 + 新建」或工单 | 无假成功 | +| **B. 服务端生成临时口令** | `POST /api/v1/admin/users/{id}/reset-password`：服务端随机口令、哈希入库、`must_change_password=true`、审计；响应**一次性**明文仅回管理员 | 禁硬编码；禁日志打口令 | +| **C. 仅发重置链** | 邮件/线下渠道发 token | 需通知系统；当前栈可能不具备 | + +**推荐**：先 **A**（trivial、可立即做）；产品确认后做 **B**（对齐创建用户语义）。禁止继续展示会失败却暗示成功的按钮；禁止客户端固定 `ResetPass123`。 + +### 风险 + +- B 的明文回传需 HTTPS + UI 一次性展示；截图泄露。 +- 管理员重置自己账户的策略需产品定（禁止或二次确认）。 + +### 验收 + +- A：UI 无可用重置按钮或明确「未开通」；无硬编码口令字符串。 +- B：API 鉴权 admin-only；负例非管理员 403；用户登录后强制改密；审计有 actor。 + +### 是否卡产品/鉴权 + +**是（产品）**。A 可不经产品；B/C 需产品签字。 + +--- + +## F7 — HttpOnly cookie + +### 现状 + +- 会话 token 在 `localStorage`（`smdf_auth_session`）；请求头 `Authorization: Bearer`。 +- XSS 可窃 token；无统一「任意 API 401 → 清会话回登录」网关（多处各自处理）。 + +### 推荐做法（分阶段） + +**阶段 0（可先做，不改 cookie）** + +- 集中 `apiFetch`：401 → `clearSession` + 跳转登录；避免半登录态。 + +**阶段 1（独立鉴权 epic / ADR）** + +1. 登录响应 `Set-Cookie`：`HttpOnly; Secure; SameSite=Lax`（跨站场景再评 `Strict`/`None`）。 +2. 服务端读 cookie 建会话；逐步废弃 localStorage token（兼容双读一期）。 +3. 若 cookie 会话：CSRF 策略（SameSite + 写操作 CSRF token 或自定义头）。 +4. SSE/`fetch` stream 带 `credentials: 'include'`。 + +**不在本设计批实现阶段 1。** + +### 风险 + +- CSRF、多标签登出、移动/非浏览器客户端。 +- 与现有 Bearer 测试夹具大面积改动。 + +### 验收 + +- 阶段 0：任意受保护 API 401 后 UI 回登录且 storage 清空（单测/组件测）。 +- 阶段 1：ADR + 安全负例（JS 读不到 cookie；无 token 的 XSS 载荷不能复用会话）。 + +### 是否卡产品/鉴权 + +**是（鉴权专项）**。阶段 0 否；阶段 1 需独立授权。 + +--- + +## F8 — poll 去重 + App.tsx stats generation + +### 现状 + +- `App.tsx`：`recoverableRunIds` 每 3s `Promise.all(getTaskRun)`；依赖 `recoverableRunKey`，但**无 in-flight 合并**——慢请求可重叠。 +- 同文件：`fetchChatCategories` / `fetchChatDates` 随 `activeSessionId` 触发，**无 generation**——快切会话可后写先到。 +- 多处 `URL.createObjectURL`；部分路径有 `revokeObjectURL`，需审计遗漏。 + +### 推荐做法 + +1. **Run 轮询**：模块级或 hook 内 `Map`；同 runId 共用飞行中请求；终态入 `skipped` 后不再请求（已有 403/404 skip，扩展终态）。 +2. **Stats**：`statsGenRef`；session 变更 `++`；resolve 时比对再 `setCategoryStats`/`setDateStats`。 +3. **Blob**：导出/预览统一 `try/finally revoke`；React 卸载时 revoke。 +4. 优先抽 hook（`useRecoverableRunPoll` / `useSessionChatStats`），减轻 `App.tsx` 继续膨胀（与既有拆分方向一致）。 + +### 风险 + +- 去重导致状态稍旧一拍；可接受（3s 轮询）。 +- 漏 revoke → 内存涨；用测试断言调用次数。 + +### 验收 + +- 单测：快切会话时旧 stats 不落地；并行 poll 同 runId 只 1 个 in-flight。 +- 手工：多 streaming 卡片时网络面板无指数级 getTaskRun。 + +### 是否卡产品/鉴权 + +否。 + +--- + +## I1 — 非 root + 资源限制 + +### 现状 + +- `deploy/app/Dockerfile`：最终镜像以 root 跑 `/app/server`；无 `USER`。 +- Compose：无 `mem_limit` / `cpus` / `deploy.resources`。 + +### 推荐做法 + +1. Dockerfile：创建 `appuser`（固定 uid/gid，如 10001）；`chown` 可写目录（`DATA_DIR`）；`USER appuser`。 +2. 确认挂载卷权限：宿主机 `data/*` 对 uid 可写；文档写明。 +3. Compose（dev/test/main 的 app + events）：设 `mem_limit`/`mem_reservation`、`cpus`（数值按主机容量，main 更严）；避免无上限 OOM 连坐。 +4. 保持 `cap_drop: [ALL]` 等为后续可选项；本设计最低线是非 root + 内存上限。 + +### 风险 + +- 卷权限导致写入失败。缓解：先在隔离 compose 冒烟。 +- 限制过紧 → PI 侧杀进程。缓解：分服务限额（runner 另算）。 + +### 验收 + +- 镜像 `docker run` 内 `id` 非 root。 +- 健康检查与一次写 data 冒烟 PASS。 +- compose config 含 resources。 + +### 是否卡产品/鉴权 + +设计与 Dockerfile 改动不卡产品；**部署到共享 test/main 需环境授权**。 + +--- + +## I4 — init mount 统一 + +### 现状 + +| 环境 | init 挂载 | +|------|-----------| +| dev | `context_init.sql`（扩展+大量业务 DDL） | +| test | `extensions_init.sql`（仅扩展） | +| main | `goose/00001_baseline.sql` | +| shared KB | `kb_init.sql`（保留，不在本项） | + +全新卷行为三套不一致；dev 易与 goose 双源漂移。 + +### 推荐做法 + +1. **业务库**（dev/test/main）：一律挂 `deploy/postgres/extensions_init.sql` → `/docker-entrypoint-initdb.d/01-extensions.sql`。 +2. **表结构只走 goose**；废弃业务库对 `context_init.sql` / baseline 文件作为入口（文件可留在 archive 或注释「勿挂载」）。 +3. 文档：空卷启动顺序 = Postgres init 扩展 → app 迁移。 +4. 已有数据卷**不**因改挂载自动重建；仅影响新卷。 + +### 风险 + +- 有人依赖 context_init「一键空库有表」而无 app 迁移。缓解：操作规范写明必须跑迁移。 +- main 从 baseline 文件习惯变更；晋升/灾备手册更新。 + +### 验收 + +- 三环境 compose diff：业务 PG 的 init 路径相同。 +- 新卷：仅扩展存在 → 起 app → goose 到当前 schema → health schema 一致。 + +### 是否卡产品/鉴权 + +设计否；**重建卷/改共享环境需授权**。 + +--- + +## I6 — 备份调度（仅文档） + +> **本项不实施。** 在宿主机安装 systemd/cron 属于环境写，需单独授权。 + +### 现状 + +- 脚本：`scripts/backup-system-db.sh ` + restore drill。 +- 无仓库内定时器；RPO 依赖人工。 + +### 推荐做法（授权后由运维执行） + +1. **调度**：每环境独立 timer（建议 main 每 60m；test 每 6h；dev 每日或关）。 +2. **单元示例**（示意，勿把 secret 写入仓库）： + +```ini +# /etc/systemd/system/agent-system-db-backup-main.timer +[Timer] +OnCalendar=hourly +Persistent=true + +# service ExecStart= +# /path/to/repo/scripts/backup-system-db.sh main /var/backups/agent-system/main +``` + +或 cron：`0 * * * *` 调同一脚本。 + +3. **保留**：本地保留 ≥24 份小时备份或 7 日；远端拷贝另策。 +4. **口令**：`${HOME}/.secrets/backup-env` 或环境文件；禁止进 git。 +5. **验收（授权实施后）**：连续 2 个周期出现新 dump + manifest；`restore-system-db-drill` 在隔离目录 PASS；RPO 墙钟 ≤60m（main）。 + +### 风险 + +- 备份含 chat 明文 → 目录 ACL / 加密。 +- 与运行库抢 IO：错峰或 `nice`/`ionice`。 + +### 是否卡产品/鉴权 + +**是（环境授权）**。本文只登记方案；实施另开 operations 任务。 + +--- + +## 明确不在本文范围 + +| ID | 说明 | +|----|------| +| F5 | ErrorBoundary 栏级 — W2 lowrisk 已实现；见该任务文 | +| I8 | `testing.Short()` 跳过 docker build — W2 lowrisk 已实现 | +| B2/B6/B8/B9/B10, F2/F3/F6, I2/I3/I5 | W2 低风险批 | + +--- + +## 实施拆批建议（供后续认领） + +| 批 | 项 | 备注 | +|----|----|------| +| S1 小改 | B11, F1, F8, F4-A | 可无环境写 | +| S2 配置/池 | B1, B4, B7 | 需回归 | +| S3 锁 | B3 | 独立 mutex | +| S4 镜像/compose | I1, I4 | 部署另授权 | +| S5 决策后 | F4-B, F7-1 | 产品/鉴权 | +| S6 运维 | I6 | 仅授权后 | +| 观测 | B5 | 可不阻塞 S1 | + +--- + +## 相关链接 + +- 任务：[../ops/short-term/2026-09-22-t20-design-items.md](../ops/short-term/2026-09-22-t20-design-items.md) +- 清单：[../ops/long-term/2026-09-19-audit-remainder.md](../ops/long-term/2026-09-19-audit-remainder.md) +- 审计：[../audit/2026-09-20-system-triage-audit.md](../audit/2026-09-20-system-triage-audit.md) +- 低风险批：[sibling worktree](../../../t20-lowrisk-hardening-2026-09-22/.doc/ops/short-term/2026-09-22-t20-lowrisk-hardening.md) diff --git a/.doc/system-design/README.md b/.doc/system-design/README.md index eb682a49..b91a5fbe 100644 --- a/.doc/system-design/README.md +++ b/.doc/system-design/README.md @@ -7,6 +7,15 @@ ## 📋 报告清单 +### 0. T20 加固设计（2026-09-22） + +| 项 | 链接 | +|-----|------| +| 主报告（SSOT） | [../remediation/2026-09-22-t20-hardening-design.md](../remediation/2026-09-22-t20-hardening-design.md) | +| 本目录迁址桩 | [2026-09-22-t20-hardening-design.md](2026-09-22-t20-hardening-design.md) | +| 任务 | [../ops/short-term/2026-09-22-t20-design-items.md](../ops/short-term/2026-09-22-t20-design-items.md) | +| 一句话总结 | XFF/锁拆分/statement_timeout/turn 补偿/shutdown/SSE POST/前端 generation/密码与 Cookie/容器与备份等设计决策；F5/I8 见 lowrisk 批 | + ### 1. 意图识别框架 | 项 | 链接 | @@ -229,6 +238,7 @@ ├── 2026-09-14-module-decoupling-architecture.md ← 模块化单体解耦 ├── 2026-09-20-module-development-standards.md ← 开发者入口：契约 / 接口 / 故障隔离 ├── 2026-09-20-stage-backtrack-and-impact-loop-design.md ← 阶段回溯与影响闭环 +├── 2026-09-22-t20-hardening-design.md ← 迁址桩 → remediation T20 设计 SSOT .tmp/ ← 中间分析文件 ├── intent-recognition/ @@ -249,6 +259,12 @@ --- +## 近期加固设计 + +| 文档 | 说明 | +|------|------| +| [../remediation/2026-09-22-t20-hardening-design.md](../remediation/2026-09-22-t20-hardening-design.md) | T20 W4 设计决策 SSOT（本目录仅留迁址桩）；配套 [任务](../ops/short-term/2026-09-22-t20-design-items.md) | + ## 🔗 相关资源 - 架构总览：[.doc/system-design/architecture-design.md](architecture-design.md)（已有的项目骨架设计文档） diff --git a/.env.example b/.env.example index 3346f0b5..ca662334 100644 --- a/.env.example +++ b/.env.example @@ -18,6 +18,17 @@ HTTP_PORT=8080 AGENT_BACKEND=pi-agent AGENT_TIMEOUT=30m MAX_CONCURRENT_AGENTS=8 +# T20-B7 设计预留（尚未接线）：优雅停机排水窗口；实施前勿依赖。见 .doc/remediation/2026-09-22-t20-hardening-design.md +# SHUTDOWN_DRAIN_TIMEOUT=30m + +# --- 2b. T20 设计预留键（全部未接线；复制后留空/注释不等于启用）--- +# B1 登录限流：仅当 RemoteAddr ∈ CIDR 时才解析 XFF（默认忽略 XFF） +# TRUSTED_PROXY_CIDRS= +# TRUSTED_PROXY_HOPS=1 +# B4 主库池默认 statement_timeout（实施后由池工厂读取） +# PG_STATEMENT_TIMEOUT=30s +# B11 是否允许 GET /chat/stream（默认应关闭；即使开启也不得传 message query） +# CHAT_STREAM_ALLOW_GET=false # --- 3. Cursor CLI / SDK 后端 --- CURSOR_API_KEY=