---
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`）