Agent-System/.doc/ops/short-term/2026-09-28-docgov-shared-map-race.md

title, status, created, owner, task_id, policy_revision, review_state, integration_state, deployment, cleanup, remote_sync, updated, write_scope, mutex, base_dev_sha

title	status	created	owner	task_id	policy_revision	review_state	integration_state	deployment	cleanup	remote_sync	updated	write_scope	mutex	base_dev_sha
docgov 共享 map 并发读写导致进程崩溃	done	2026-09-28	Cursor	docgov-shared-map-race-2026-09-28-r2	issue-learning-2026-09-23-r1 @ a3db288a	accepted	merged_local_dev	loaded_local	pending	not_requested	2026-09-28	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	docgov-shared-map-race	a3db288a7a

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	accepted
integration_state	merged_local_dev（收口记录待第二次快进）
deployment	loaded_local（2026-09-28 09:10 UTC 重建并重启 :8080，health 200）
cleanup	pending
remote_sync	not_requested

ISSUE-20260928-docgov-map-race

• 预期：文档治理并发不杀死 HTTP 进程；登录等无关 API 保持可用。
• 实际：2026-09-28 06:38 UTC 进程 fatal，约 11 分钟内全部 API 500。
• 状态：resolved。go test -race PASS（a90cce73）。dev b9339cd2 重建 bin/agent-server 后，/health 200，空登录 POST 401（req_e28309cc8d615ed4），Vite :3100 的 public-config 200。
• 同类：所有裸读写上述四张 map 的路径，已收口到 memMu 辅助函数。ISSUE-20260926-docgov-memdocs-poison 仍是另一机制。