weichen/Agent-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(docgov): 登记共享 map 并发崩溃的问题、经验与竞态回归

Browse Source 
登录 500 来自进程被 concurrent map 打崩，不是登录逻辑。单测 -race 已通过，dev 重建仍待合入后复验。
This commit is contained in:
weichen
2026-09-28 09:06:06 +00:00
parent a90cce73b9
commit 792c216c96
6 changed files with 130 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.doc/audit/ISSUES.md
+2 -1
View File
@@ -2,10 +2,11 @@
维护规则：[问题记录与开发经验闭环](../ops/2026-09-23-issue-learning-workflow.md)。每个问题一个稳定 ID；主记录是事实与状态来源，本表为可检索投影。新发现及时登记，修复后保留记录；发布 blocker 仍见 [gap-matrix](../remediation/gap-matrix.md)。
更新：2026-09-28。只上传文档、无文字时对话 400 已在重载后的 dev 浏览器复验（resolved，`bin/agent-server` 10:22 +0800）。历史任务 run 事件流 HTTP/2 与 502 另记，未在本轮修。激活预览前端预检与管理台密钥 form 已在 dev 浏览器复验（resolved，dev `3e534bbb`，项目 6023）。非编制人触发小队账本提交被 `uow: permission denied` 拒绝（fixing，待 dev 重跑）。test 注册 INTERNAL：标准角色 role-guest 缺失导致 FK 23503，已补种并重启 test（goose 77，resolved）。重复用户名 400 在新代码单测通过；当前 rc 二进制仍返回 INTERNAL，随下次含本提交的 test 制品生效。管理台重置密码入口被 F4-A 误删（端点仍在），已恢复 UI（resolved）。2026-09-27。上传链路：登记并修复上传文档跨端不可访问（占位模板退化 + 元数据/正文不落服务端，fixing 待 dev 集成）。2026-09-26。docgov 批准链：登记并修复 review_snapshot_id 装载缺失与 uow 行锁自死锁（resolved）；memDocs 持久化失败缓存投毒（investigating）。历史 resolved 不表示本日产品回归通过。系统 code review P0/P1 批次修复落账（5 resolved + 1 deferred + 1 open，主记录见 [整改文档](2026-09-26-system-code-review-fixes.md)，来源 [审计](2026-09-26-system-code-review.md)）。
更新：2026-09-28。docgov 共享 map 并发读写曾在 06:38 UTC 打崩 dev 进程，登录等 API 在进程缺席期间 500（verifying，单测 `-race` 已过，dev 重建未做）。只上传文档、无文字时对话 400 已在重载后的 dev 浏览器复验（resolved，`bin/agent-server` 10:22 +0800）。历史任务 run 事件流 HTTP/2 与 502 另记，未在本轮修。激活预览前端预检与管理台密钥 form 已在 dev 浏览器复验（resolved，dev `3e534bbb`，项目 6023）。非编制人触发小队账本提交被 `uow: permission denied` 拒绝（fixing，待 dev 重跑）。test 注册 INTERNAL：标准角色 role-guest 缺失导致 FK 23503，已补种并重启 test（goose 77，resolved）。重复用户名 400 在新代码单测通过；当前 rc 二进制仍返回 INTERNAL，随下次含本提交的 test 制品生效。管理台重置密码入口被 F4-A 误删（端点仍在），已恢复 UI（resolved）。2026-09-27。上传链路：登记并修复上传文档跨端不可访问（占位模板退化 + 元数据/正文不落服务端，fixing 待 dev 集成）。2026-09-26。docgov 批准链：登记并修复 review_snapshot_id 装载缺失与 uow 行锁自死锁（resolved）；memDocs 持久化失败缓存投毒（investigating）。历史 resolved 不表示本日产品回归通过。系统 code review P0/P1 批次修复落账（5 resolved + 1 deferred + 1 open，主记录见 [整改文档](2026-09-26-system-code-review-fixes.md)，来源 [审计](2026-09-26-system-code-review.md)）。
| issue_id | 模块 / 检索词 | 问题 | 严重度 | issue_state | owner | 证据日期 / 范围 | 唯一主记录 | 经验 |
|---|---|---|---|---|---|---|---|---|
| ISSUE-20260928-docgov-map-race | docgov / memDocs / concurrent map / GetDocument / 登录 500 | per-doc 锁拆分后共享 map 无互斥，不同文档并发读写 fatal，进程退出期间全部 API 500 | critical | verifying | Cursor | 2026-09-28；`.tmp/launch/server.log` fatal + `web.log` ECONNREFUSED；`TestMemMapsNoRaceAcrossDocs` `-race` PASS（`a90cce73`）；dev 重建未做 | [主记录](../ops/short-term/2026-09-28-docgov-shared-map-race.md#issue-20260928-docgov-map-race) | [LESSON-20260928-docgov-shared-map-race](../ops/lessons/2026-09-28-docgov-shared-map-race.md) |
| ISSUE-20260928-quality-heading-drift | squad / quality_gate / 缺少必填章节 / State-of-the-Art / H3 | 调研报告章节在，只因 H3 和少空格被判缺章，受控文档不投影 | high | verifying | Cursor | 2026-09-28；dev `research_1790566833205199368` manifest score 85；单测已覆盖，dev 重跑未做 | [主记录](../ops/short-term/2026-09-28-quality-gate-heading-mismatch.md#issue-20260928-quality-heading-drift) | [LESSON-20260928-quality-heading-normalize](../ops/lessons/2026-09-28-quality-heading-normalize.md) |
| ISSUE-20260928-data-dir-doubled | workspace / data/dev/data/dev / DataDir | 出现双层 `data/dev/data/dev/workspaces` 且只有孤立 output.md，写入点未证实 | medium | open | — | 2026-09-28；`intake_1790565513115586191` 双路径对照 | [主记录](../ops/short-term/2026-09-28-quality-gate-heading-mismatch.md#issue-20260928-data-dir-doubled) | 本轮不修 |
| ISSUE-20260928-progress-query-trigger | intent / matchTriggerTask / QUERY_PROGRESS / 编写进度 | 询问调研报告编写进度时，写动词加任务名词被识别成启动新任务，进度回复不读真实 run | medium | verifying | Cursor | 2026-09-28；「调研报告编写进度怎么样了」单测为 QUERY_PROGRESS；「开始做调研报告」仍为 research。浏览器复验见测试报告 | [主记录](../ops/short-term/2026-09-28-refresh-task-state-recovery.md) | 疑问进度句必须让行查询；显式「开始/重新」仍启动任务 |
.doc/ops/CURRENT.md
+1
View File
@@ -18,6 +18,7 @@
| owner | task | branch | worktree | mutex | status |
|---|---|---|---|---|---|
| Cursor | docgov-shared-map-race-2026-09-28-r2 | fix/docgov-shared-map-race-2026-09-28 | .worktrees/docgov-shared-map-race-2026-09-28 | docgov-shared-map-race | in_progress |
| Cursor | promote-rc-beta6-closeout-2026-09-28 | feature/promote-rc-beta6-closeout-2026-09-28 | .worktrees/promote-rc-beta6-closeout-2026-09-28 | git:test+env:test | done |
| Cursor | quality-gate-heading-mismatch-2026-09-28-r3 | fix/quality-gate-heading-mismatch-2026-09-28 | .worktrees/quality-gate-heading-mismatch-2026-09-28 | quality-gate-heading | in_progress |
| Cursor | agent-reply-llm-narrative-2026-09-28 | feature/agent-reply-llm-narrative-2026-09-28 | .worktrees/agent-reply-llm-narrative-2026-09-28 | chat+coordinator | in_progress |
.doc/ops/lessons/2026-09-28-docgov-shared-map-race.md
+20
View File
@@ -0,0 +1,20 @@
---
lesson_id: LESSON-20260928-docgov-shared-map-race
lesson_state: candidate
owner: Cursor
reviewer: Cursor（自审）
last_reviewed: 2026-09-28
reviewed_revision: a90cce73
source_issues: [ISSUE-20260928-docgov-map-race]
keywords: [docgov, memDocs, memMu, per-doc lock, concurrent map, 登录 500]
---
# 拆细粒度锁后，共享 map 仍要单独互斥
- 触发条件：把全局锁拆成 per-id 锁，但多个 id 仍读写同一张 Go map（缓存、审计、批注、提案）。
- 机制与来源：docgov 的 per-doc 锁不保护 `memDocs` 等 map。不同文档并发时 `GetDocument` 与写入撞上，运行时 fatal，进程退出后所有 HTTP API（含登录）500。证据：2026-09-28 `.tmp/launch/server.log` 与 `web.log` 的 `ECONNREFUSED`。修复见 [任务](../short-term/2026-09-28-docgov-shared-map-race.md)。
- 开发检查：map 的读写、遍历、append 都走同一把锁。已持有外层锁的路径不能再锁同一把（Go 互斥锁不可重入）。锁序固定，禁止在 map 锁内再拿文档锁或外层锁。不要用「登录 500」去改登录代码。
- 验证方式：不同 docID 并发创建与读取，`go test -race` 覆盖 `TestMemMapsNoRaceAcrossDocs`。进程崩溃类问题还要看服务日志里的 fatal，而不是只看单个 API 状态码。
- 适用边界：适用于 docgov 这四张内存 map。文档结构体字段的数据竞争、以及持久化失败后的缓存投毒（`ISSUE-20260926-docgov-memdocs-poison`）不在本条范围内。
- 防护落实：`memMu` 与 `TestMemMapsNoRaceAcrossDocs`。没有新增静态检查，漏一个裸访问仍要靠 `-race` 和复查。
- 修订与失效：若这四张 map 改为分片或移除，本条对那个存储失效，保留历史。
.doc/ops/lessons/INDEX.md
+1
View File
@@ -4,6 +4,7 @@
| lesson_id | 触发条件 / 关键词 | 注意事项 | lesson_state | 主记录 / 最近复核 |
|---|---|---|---|---|
| LESSON-20260928-docgov-shared-map-race | docgov、memDocs、per-doc 锁、concurrent map、登录 500 | 拆锁后共享 map 仍要单独互斥；锁不可重入；全站 500 先看进程是否退出 | candidate | [共享 map 互斥](2026-09-28-docgov-shared-map-race.md)；2026-09-28 |
| LESSON-20260928-quality-heading-normalize | 缺少必填章节、State-of-the-Art、H3、质量门禁、AutoRepair | 标题比对去空白并跨 H2–H4；层级漂移不扣分；真实缺章仍失败 | candidate | [章节标题归一化](2026-09-28-quality-heading-normalize.md)；2026-09-28 |
| LESSON-20260928-task-write-verb-visible-refusal | 帮我定、制定、ClarificationQuestion、前置条件、quality_failed | 写动词覆盖制定与帮我定；拒绝和澄清进对话；质量失败不写宿主机路径 | candidate | [写动词与可见拒绝](2026-09-28-task-write-verb-visible-refusal.md)；2026-09-28 |
| LESSON-20260928-activation-preview-client-gate | activation-preview、NO_GOVERNED_DOCUMENT、clientDutyIssues、400 | 服务端激活门禁要有同等前端预检；live_edit 不套激活门禁 | validated | [激活预检对齐](2026-09-28-activation-preview-client-gate.md)；2026-09-28 |
.doc/ops/short-term/2026-09-28-docgov-shared-map-race.md
+59
View File
@@ -0,0 +1,59 @@
---
title: "docgov 共享 map 并发读写导致进程崩溃"
status: in_progress
created: 2026-09-28
owner: Cursor
task_id: docgov-shared-map-race-2026-09-28-r2
policy_revision: issue-learning-2026-09-23-r1 @ a3db288a
review_state: pending
integration_state: pending
deployment: pending
cleanup: pending
remote_sync: not_requested
updated: 2026-09-28
write_scope: internal/docgov .doc/ops/CURRENT.md .doc/ops/short-term/2026-09-28-docgov-shared-map-race.md .doc/test-reports/2026-09-28-docgov-shared-map-race-test-report.md .doc/audit/ISSUES.md .doc/ops/lessons/2026-09-28-docgov-shared-map-race.md .doc/ops/lessons/INDEX.md
mutex: docgov-shared-map-race
base_dev_sha: a3db288a7aa055ff5884e3aa4d91511959cff721
---
# docgov 共享 map 并发读写
## 范围与授权
用户报告 dev（`frp-mix.com:58880`）登录及多个 API 返回 500，并说明没有改登录代码。授权是查清原因并修复。允许写路径见 front matter。交付终点：共享 map 并发读写有回归测试，合入 local dev 后重建并复验 `/health` 与登录接口不再因进程死亡返回 500。不改登录协议，不晋升 test/main，不 push。
## 问题登记与经验检索
- issue_id: `ISSUE-20260928-docgov-map-race`
- 检索词：`docgov`、`memDocs`、`concurrent map`、`500`、`登录`
- 命中：`ISSUE-20260926-docgov-memdocs-poison`（同模块内存态与库分叉，机制不同，本轮不关）。无「per-doc 锁拆分后共享 map 无互斥」的既有经验。
- 采纳：修共用 map 互斥，不用登录特例。
## 现象
2026-09-28 06:38 UTC，dev `agent-server` 在 `GetDocument`（`internal/docgov/engine_read.go`）触发 `fatal error: concurrent map read and map write` 后退出。06:38–06:49 Vite 代理 `ECONNREFUSED 127.0.0.1:8080`，登录、`auth/me`、通知、维护状态等全部 500。06:49 进程被重新拉起后接口恢复。登录代码未改。
## 根因
`340342fa` 把 docgov 全局锁拆成 per-doc 锁。per-doc 锁只串行同一 `docID`。`memDocs`、`memAudits`、`memComms`、`memProps` 仍被不同文档并发读写。`e.mu` 不是可重入锁，且部分调用方已经持有它，所以新增 `memMu` 专门保护这四张 map。锁序：docLocks → `e.mu` → `memMu`。
## 修复
`a90cce73`。回归：`TestMemMapsNoRaceAcrossDocs`（`go test -race`）。
## 五态
| 字段 | 值 |
|---|---|
| review_state | pending |
| integration_state | pending |
| deployment | pending（合入后需重建 dev `agent-server`） |
| cleanup | pending |
| remote_sync | not_requested |
## ISSUE-20260928-docgov-map-race
- 预期：文档治理并发不杀死 HTTP 进程；登录等无关 API 保持可用。
- 实际：2026-09-28 06:38 UTC 进程 fatal，约 11 分钟内全部 API 500。
- 状态：verifying（单测已过；dev 重建复验尚未做）。
- 同类：所有裸读写上述四张 map 的路径，已收口到 `memMu` 辅助函数。`ISSUE-20260926-docgov-memdocs-poison` 仍是另一机制。
.doc/test-reports/2026-09-28-docgov-shared-map-race-test-report.md
+47
View File
@@ -0,0 +1,47 @@
# docgov 共享 map 并发读写 测试报告
## 一、 测试背景 (Background)
2026-09-28 06:38 UTC，dev 后端因 `internal/docgov` 共享 map 并发读写 fatal 退出。Vite 代理在后端缺席期间对登录等全部 API 返回 500。本报告记录修复后的工程回归。产品 PI 全链路不适用：变更是治理引擎内存锁，不改对话或文档业务规则。
## 二、 测试目标 (Test Objectives)
- 不同 docID 并发创建、读取、列审计/批注、写批注时，`-race` 不报告 data race，进程不 fatal。
- 并发结束后每个 docID 仍能读回。
## 三、 测试方案与环境 (Test Plan & Environment)
- OS：Linux；`go version go1.27.1 linux/amd64`
- 工作区：`.worktrees/docgov-shared-map-race-2026-09-28`，提交 `a90cce73`
- 层级：模块单元测试 + race detector。无数据库。产品 PI：NOT REQUIRED（非产品工作流变更；依据验证契约对纯工程锁修复的范围，以及本报告不把单测写成产品 PASS）。
- 用例：`TestMemMapsNoRaceAcrossDocs`
## 四、 预期结果 (Expected Results)
`go test -race` 该用例 PASS，且 48 个文档均可 `GetDocument`。
## 五、 实际测试结果与判定 (Actual Results & Evaluation)
- 测试输入 (Input)：`go test -race -count=1 -timeout 180s -v ./internal/docgov/ -run TestMemMapsNoRaceAcrossDocs`
- 实际输出 (Actual Output)：
```
=== RUN TestMemMapsNoRaceAcrossDocs
--- PASS: TestMemMapsNoRaceAcrossDocs (0.00s)
PASS
ok chat-agent-system/internal/docgov 1.012s
```
- 评价判定 (Evaluation / Verdict)：PASS
- 性能与耗时 (Duration & Latency)：包测试约 1.012s；用例本身 0.00s（race 插桩耗时在包级）
同一次会话里不带 `-run` 的 `go test -race -count=1 -timeout 180s ./internal/docgov/` 亦为 `ok`（1.012s）。dev 进程重建后的 `/health` 与登录复验在合入之后补记，本段不将其记为已完成。
## 六、 自动化测试套件汇总 (Test Suite Execution)
- `go test -race ./internal/docgov/`：PASS（含 `TestMemMapsNoRaceAcrossDocs`）
- 未跑产品 PI、未跑全仓 `go test`
## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
工程回归达到本修复的单测终点。合入 local dev 后需重建 `bin/agent-server` 并确认 `/health` 与空登录请求返回 401 而不是 500。`ISSUE-20260926-docgov-memdocs-poison` 仍开放。