diff --git a/PROJECT.md b/PROJECT.md index bffd1f23..e555079d 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -40,14 +40,15 @@ U2 起实施与部署分别评审。 - [服务重启与全量数据恢复方案 r2](modules/documents/docs/proposals/2026-10-12-service-restart-data-recovery.md): svc 启停、异常进程/主机退出后的依赖、配置/数据身份、任务/HITL/副作用、文件与组合备份恢复; - r1 经六角色自审、r2 吸收外部源码复核;2026-10-12 用户批准 r2(五阶段一并),实施、故障注入、部署与运行验收 NOT_RUN; + r1 经六角色自审、r2 吸收外部源码复核;2026-10-12 用户批准 r2(五阶段一并)。同日批准 r3 新增 + (R11/R12、KTD13–15、U8):SQLite 活动服务锁与耐久核验进入实施,故障注入、部署与运行验收仍 NOT_RUN; 衔接协作存储案;U2 首切片已由 svc-autorecover 合入 main(PR #396/#401);U1 实例身份已合入(Dev #415);余量另立增量。 - [svc 统一部署与一次性登录 Key 方案 r1](modules/documents/docs/proposals/2026-10-12-svc-unified-deploy-and-login-key.md): 二进制/源码统一部署、环境准备、无初始密码开户与账户恢复;一次性 Key 仅兑换设密受限会话; - 2026-10-12 已批准;U1/U4 实施启动中;规格见 `docs/svc-deploy/`。 + 2026-10-12 已批准;U1/U4 已合入。同日批准 r2 新增(R13–R15、KTD11–14、U7),账户事务与审计随后实施;规格见 `docs/svc-deploy/`。 -上述账户/恢复方案已有 U1/U4 与 recover/watchdog 基础源码。2026-10-12 的 dev 8788 续查形成账户 r2、恢复 r3 **候选草案**:帮助与能力发现、账户事务/审计/登录接线、SQLite 活动服务隔离及备份恢复增补。新增内容待人工评审;Documents 独立分支 `feature/svc-account-durability-plan` 仅本地保存,不推进本仓 gitlink;本入口原链接仍指固定版。候选交接与核查见[续审记录](docs/svc-deploy/2026-10-12-account-durability-plan-review.md)。 +上述账户/恢复方案已有 U1/U4 与 recover/watchdog 基础源码。2026-10-12 用户批准账户 r2 新增与恢复 r3 新增,并授权连续推进到 PR 可合入(合入仍由用户执行)。U8 规格见 `docs/recovery/u8-sqlite-instance-guard.md`。方案正文的确认状态由 Documents 收口更新;本入口原链接仍指当前固定版。候选交接与核查见[续审记录](docs/svc-deploy/2026-10-12-account-durability-plan-review.md)。 ## 验证 diff --git a/docs/svc.md b/docs/svc.md index ecf381fa..2dfd4657 100644 --- a/docs/svc.md +++ b/docs/svc.md @@ -811,9 +811,35 @@ scripts/svc.sh prod deploy --env .env.prod # 等价 ## 13. 故障排查 +SQLite 档的活动服务锁在打开数据库之前取得,锁文件是解析后的 +`agent-system.db.lock`(不删除)。同一数据文件只允许一个 `serve` 或 `migrate`。 +`svc.sh` 的 `.start.lock` 只串行化脚本,挡不住直接启动二进制。账户短事务命令不拿这把锁。 +显式迁移: + +```bash +agent-system migrate --data <数据目录> +agent-system migrate --dsn "$AGENT_SYSTEM_DSN" # PostgreSQL,不取文件锁 +``` + +数据库被替换,或守卫建立后锁文件被删掉重建,启动会拒绝。确认是同一次实例后: + +```bash +agent-system serve --data <数据目录> --adopt-instance-guard +agent-system migrate --data <数据目录> --adopt-instance-guard +``` + +硬链接别名不能用 adopt 绕过。PostgreSQL 档在应用连接上读到 `fsync`、 +`full_page_writes` 或 `synchronous_commit` 为 off 时拒绝启动。 + | 症状 | 处置 | |---|---| | `端口被占用(非本服务)` | 按提示的占用者处理,或换端口(`--port` / `set --port --apply`) | +| `instance guard: sqlite service already running` | 已有进程占用同一 SQLite 文件:停掉那个服务,或换独立数据目录。`migrate` 同样会被拒绝 | +| `instance guard: sqlite database replaced` | 库文件 inode 与锁记录不符:确认不是拿错目录后,用 `--adopt-instance-guard` | +| `instance guard: recorded sqlite database is missing` | 锁记录指向的库不在了:恢复该文件,或在确认后 adopt | +| `instance guard: lock file was rebuilt` | 守卫已建立后锁文件被重建:确认后 `--adopt-instance-guard` | +| `instance guard: sqlite database has a hardlink alias` | 去掉硬链接别名后再启动;adopt 不能放行 | +| `durability:` | SQLite 未保持 WAL + synchronous FULL,或 PostgreSQL 的 fsync / full_page_writes / synchronous_commit 为 off | | `进程启动后即退出` | `scripts/svc.sh logs 200` / postgres 看 `runtime//pg.log`;history 里有 fail 记录 | | `20s 健康检查未通过` | 进程活着但未响应:查日志与端口;agent 常见原因是 DSN 指向未启动的库 | | `该产物不支持部分启动参数` | 提示而非错误:旧版本制品自动省略了不支持的 flag;需要该能力请部署新提交 | diff --git a/modules/backend b/modules/backend index 8e509775..89acd16c 160000 --- a/modules/backend +++ b/modules/backend @@ -1 +1 @@ -Subproject commit 8e509775d39d1455b69be44803037faa7af844b4 +Subproject commit 89acd16ca5c46e4a2d2fc58f9e598dccf55be65c