Agent-System-Documents/docs/guides/team-storage.md

团队存储运行手册（协作存储 U1）

适用范围：协作存储与分布式方案 U1/U2 （已批准，2026-10-11）落地后的 team 部署档 运维与验证。个人 local 档（SQLite） 用法不变，见 usage。本文是 U1 的固定部署清单、配置合同、迁移映射、 容量合同、隔离测试方案与 KTD14 副本保护合同的单一事实源；实施状态以各任务卡为准。

1. 目标实例与固定部署清单

项	值	说明
部署形态	svc.sh 管理的 runtime/<name> 实例	非容器；单机多实例按名隔离
当前团队候选	runtime/dev（8788，SQLite）→ 目标切 team 档 PG	切换窗口与回退按方案 §6，须另行授权
数据库（本机验证）	PostgreSQL 18.6 + pgvector 0.8.7（brew）	本机验证用；正式实例待指定
数据库（CI 门禁）	Ubuntu 24.04 apt：postgresql 16 + postgresql-16-pgvector	版本以 CI job 输出为准
缓存/限流	Redis 8.10.2（本机）；CI apt redis-server	只存可重建状态（KTD10）
应用制品	agent-system 单二进制（make build）	拷贝即运行；team 档需 --tier team

未知项（正式实例主机、pgvector 正式启用版本、对象存储选型）在正式切换授权前 必须补齐；本清单不把本机验证环境当作正式部署事实。

2. team 档配置合同（U2 已实施）

启动语义（KTD1 fail-closed）：

• tier=team：必须配置 dsn 且认证开启（auth=on；auth=auto 随 DSN 自动开）； 任一缺失拒绝启动。PG 打开失败拒绝就绪，绝不回落 SQLite。未配置执行隔离 （disableExecTools 或 execBackend）时启动警告（多用户开放前必须补齐）。
• tier=local：SQLite；配置 dsn 是配置错误，拒绝启动。
• tier 缺省（auto）：现状语义——dsn 非空走 PG，否则 SQLite。

配置键（四源合并：默认 → 文件 → 环境 → 显式 CLI，与 usage §启动一致）：

键	env	CLI	语义（team 档）
tier	AGENT_SYSTEM_TIER	--tier	local / team / 空=auto
dsn	AGENT_SYSTEM_DSN	--dsn	PG 连接串；team 必填
auth	AGENT_SYSTEM_AUTH	--auth	team 档要求最终为 on
instance	AGENT_SYSTEM_INSTANCE	--instance	空=主机名:监听地址（多实例必须互异）
pgMaxOpen	AGENT_SYSTEM_PG_MAX_OPEN	--pg-max-open	每进程最大连接（默认 16）
pgMaxIdle	AGENT_SYSTEM_PG_MAX_IDLE	--pg-max-idle	每进程空闲连接（默认 8）
pgConnMaxIdleSec	AGENT_SYSTEM_PG_CONN_MAX_IDLE_SEC	--pg-conn-max-idle-sec	空闲回收（默认 300s）
pgConnMaxLifetimeSec	AGENT_SYSTEM_PG_CONN_MAX_LIFETIME_SEC	--pg-conn-max-lifetime-sec	连接寿命（默认不限）
pgQueryTimeoutSec	AGENT_SYSTEM_PG_QUERY_TIMEOUT_SEC	--pg-query-timeout-sec	statement_timeout 秒（默认不限）

连接预算（KTD12）：预算覆盖全部 API/Worker/LISTEN/migrator/监控连接； 100 在线用户 ≠ 100 连接。agent-system config explain 输出脱敏有效值 （DSN 密码打码）。启动日志打印 storage tier: team (dialect=postgres pool=… schema=v…)。

迁移（KTD8，U2 已实施）：DDL 与版本登记同事务（中途失败整体回滚，不存在 「表已建、账本未记」中间态）；PG 并发迁移者按会话咨询锁串行化；SQLite 写事务 _txlock=immediate 跨进程排队。库内出现比二进制新的 schema 版本时拒绝启动。

3. 迁移映射（SQLite → PG，U4 工具消费）

SQLite 侧	PG 侧	备注
agent-system.db（WAL）	同名逻辑库	活跃 WAL 不能只拷 .db；一致性备份用 VACUUM INTO
INTEGER 0/1 布尔列	BOOLEAN	v9/v10/v11 起双方言已分型
INTEGER PRIMARY KEY AUTOINCREMENT	BIGSERIAL/SERIAL	events、command_audit、audit_events
FTS5 虚表 + 触发器	tsvector 生成列 + pg_trgm GIN	v4；中文子串走 trigram
vec BLOB	BYTEA	pgvector 类型切换在 U6，不在本映射
<data>/artifacts/ 工件对象	本期仍本地目录 + PG 清单	共享对象存储在 U5/U9

RDM 独立业务库与旧 Agent-System 治理库不在本映射内；迁移工具（U4）只处理 Backend 库，非空目标拒绝、同快照才可续传。

4. 容量合同（验收目标，非性能结论）

方案 §3 的量化指标（100 在线 / 300 SSE / 20 执行中 Agent / P95≤300ms 等）是 待验证合同。区分两个计数：接纳的 run 数（进入队列）与执行许可 （同时真正执行，含子代理、初始全局 20、每用户 2、索引 4）；等待子代理/HITL 的 父 run 让出执行许可、保留会话所有权。压测在 U7 执行并绑定组件 SHA 出证。

5. 隔离测试库/目录/端口方案

资源	约定	生命周期
本机 PG 实例	scripts/svc.sh db create collabtest --port 8897 --tag test	svc.sh 管理；用毕 svc.sh collabtest stop + rm --purge
测试库/扩展	库 agent_test；pg_trgm 预装 public	测试辅助幂等预装；CI 启动步显式预装
用例 schema	t_* / pgbus_* 前缀，随机名	每用例建、Cleanup 级联删
本机 Redis	redis-server --port 6399 --save '' --appendonly no	纯内存、用毕即停
CI	job test-pg：apt 安装 PG16+pgvector+Redis，端口 5432/6399	每次 PR 必跑；缺服务失败不跳过

本地跑真实库门禁：

export AGENT_PG_TEST_DSN="$(scripts/svc.sh db dsn collabtest --db agent_test --reveal | tail -1)"
export AGENT_REDIS_TEST_ADDR=127.0.0.1:6399
make test-backend-pg

禁止对共享/现役实例（如 runtime/dev 的库）跑测试；DSN 不入命令历史与任务卡。

6. KTD14 副本保护与保留合同

• 备份/导出/WAL/测试副本使用专用数据库角色（非应用角色），存放于受限目录 （0700，非工作区）；传输与静态备份加密，解密材料存独立受管秘密存储。
• 保留期限：迁移演练副本用毕即删，最长 7 天；正式备份保留 30 天滚动 + 每月 1 份年度副本（待正式实例指定后确认）。
• 日志/报告只留统计与哈希：不落 DSN、密钥、文档正文；测试一律用脱敏数据。
• 恢复演练：每次演练恢复到新目标并核对应用可用与权限/文件完整性； 「备份命令成功」不等于可恢复。
• 阻塞项：正式导出前，未知 owner 的数据、未定位的权威文件、缺失的保留期限 任一存在即阻塞（不静默继续）。

7. 暂态 Worker 文件分类

类	内容	处置
可重建	构建产物 bin/、node_modules/、测试数据目录、__pycache__	随时删除重建
必须迁移	SQLite 库、artifacts/ 工件、.agentx/checkpoints.jsonl、Squad FileStore/续跑标记	U4 迁移 + 联合备份；U5 前禁止跨机接管
只读参考	svc.env（600）、history.jsonl	保留在实例目录，不入副本外流

8. 已知边界（诚实清单）

• CLI 子命令（apikey/user 等）不校验 tier；team 档语义只在 serve 入口强制。
• 迁移仍随启动执行（已原子 + 锁化）；完全独立的 migrator 入口留待 U4 工具。
• 多实例安全未因此声明（R4/U5）；本档只交付单实例 team 档与真库门禁。
• pgvector 扩展已安装 ≠ 启用；向量检索仍是应用内扫描（U6）。