Merge pull request 'Add the team-storage runbook for U1 and cross-link usage' (#61) from feature/collab-storage-pg-tier into main
This commit was merged in pull request #61.
This commit is contained in:
@@ -0,0 +1,120 @@
|
||||
# 团队存储运行手册（协作存储 U1）
|
||||
|
||||
适用范围：[协作存储与分布式方案](../proposals/2026-10-11-collaboration-storage-and-distribution.md) U1/U2
|
||||
（已批准，2026-10-11）落地后的 **team 部署档** 运维与验证。个人 `local` 档（SQLite）
|
||||
用法不变，见 [usage](usage.md)。本文是 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 必跑；缺服务失败不跳过 |
|
||||
|
||||
本地跑真实库门禁：
|
||||
|
||||
```bash
|
||||
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）。
|
||||
@@ -36,7 +36,7 @@ agent-system config explain [--config envs/prod.json] # 只读诊断：逐字
|
||||
agent-system version
|
||||
```
|
||||
|
||||
启动参数四源合并，优先级从低到高：**内置默认 → 配置文件（`--config`，显式 JSON，无自动发现）→ 环境变量（`AGENT_SYSTEM_ADDR/DATA/PLUGINS/DSN/ARTIFACTS/AUTH/MOCK`）→ 命令行**；未显式传入的命令行参数不参与覆盖，删除 override 恢复继承。字段：`addr`（监听）、`data`（工作区根目录）、`plugins`、`dsn`（空 = 嵌入式 SQLite 档，非空 = PostgreSQL 档）、`artifacts`、`auth`（auto/on/off）、`mock`；未知键与类型错误在启动时定位报错，不静默失效。
|
||||
启动参数四源合并，优先级从低到高：**内置默认 → 配置文件（`--config`，显式 JSON，无自动发现）→ 环境变量（`AGENT_SYSTEM_ADDR/DATA/PLUGINS/DSN/ARTIFACTS/AUTH/MOCK`）→ 命令行**；未显式传入的命令行参数不参与覆盖，删除 override 恢复继承。字段：`addr`（监听）、`data`（工作区根目录）、`plugins`、`dsn`（空 = 嵌入式 SQLite 档，非空 = PostgreSQL 档）、`artifacts`、`auth`（auto/on/off）、`mock`；未知键与类型错误在启动时定位报错，不静默失效。team 部署档（`tier`/连接预算键）与真实数据库门禁见[团队存储运行手册](team-storage.md)。
|
||||
|
||||
**多环境启动**——仓库自带隔离示例 `envs/{dev,test,prod}.json`（data 根与 DB 互不重叠）：
|
||||
|
||||
@@ -44,6 +44,7 @@ agent-system version
|
||||
agent-system serve --config envs/dev.json # mock 开、./data-dev
|
||||
agent-system serve --config envs/test.json # 127.0.0.1:8788、./data-test
|
||||
agent-system serve --config envs/prod.json # PostgreSQL 档、auth on、独立卷
|
||||
agent-system serve --tier team --dsn "$DSN" --auth on # team 档：缺 DSN/未认证拒绝启动，PG 故障拒绝就绪（见团队存储手册）
|
||||
AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve # 环境变量定位文件
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user