yms-daemon/AGENTS_CHANGELOG.md

AGENTS Changelog

多 agent 并行时的共享变更记录。开工前先读本文，避免重复实现或与已变更的接口冲突。 条目按时间倒序排列；破坏性变更（接口签名、协议字段等）会明确标注。

---

2026-08-22 对账结果可见性 + 容器镜像 tag 展示

诊断与对账输出

• ymsctl status/doctor/reconcile 的状态展示区分 HEALTHY、REPAIRABLE、DRIFT。
• ymsctl reconcile --service backend 明确标记为只读修复计划，并提示追加 --apply。
• ymsctl reconcile --service backend --apply 成功后输出 APPLIED、对账事务 ID 和重新核对结果。
• daemonapi.Diagnosis 新增 RepairApplied、RepairTransactionID 字段；自动修复完成后由服务端填充。
• 对账修复仍通过 SQLite 事务与 coordinator 执行，未改变只读命令的行为。

容器镜像显示与校验

• 容器更新创建容器时使用用户提供的 tag 引用，使 docker ps / docker inspect .Config.Image 显示可读 tag。
• backendexecutor.Request 新增 DisplayImageReference，仅用于容器显示引用。
• 实际镜像仍使用不可变 digest 引用拉取、校验和事务记录；容器创建阶段继续校验镜像 ID，提交阶段同时接受 digest 引用或对应 tag 引用。
• 现有已创建容器不会被改写；下一次更新对应槽位后显示 tag。

验证与产物

• go test ./...、go vet ./...、git diff --check 通过。
• 生成 x86_64 RPM：dist/yms-daemon-0.1.0-20260822072334.f536987a.x86_64.rpm。
• RPM SHA256：a3df708e54a95dadbf67487b4cd25dfa7599557237241638d00f38d390cf581e。

---

2026-08-17 容器停止超时配置化 + 示例配置支持 native/container 快速切换

新增配置项

• deploymentconfig.Backend 新增 stop_grace_seconds *int（[backend] 下，可省略）。
  • 容器后端停止旧容器时，SIGTERM 后到强制终止前的等待秒数；省略时默认 30。
  • 配置值覆盖容器创建时的 9000 秒 StopTimeout；原生后端忽略该字段。
  • validateExactDocumentKeys 的 backend 允许键新增 stop_grace_seconds；Validate 要求其为正整数。
• backendupdate.Updater 新增 containerStopGraceSeconds，由 NewContainer 从配置读取（缺省 30）。
• containerStopOperation 新增 stopGraceSeconds 字段，switchAndCommitContainer 与 rollbackContainer 传 u.containerStopGraceSeconds。

示例配置

• 重写 packaging/etc/yms-daemon/yms-daemon.toml：同时展示 native（默认启用）与 container（整体注释）两套 [backend] 块，顶部注释说明快速切换步骤与约束（type 必须与现场一致、native↔container 需走迁移事务）。

测试

deploymentconfig/config_test.go 新增：stop_grace_seconds 合法值接受、非正整数拒绝。全量 build/vet/test 通过。

---

2026-08-17 修复旧容器停不掉与启动日志跟随

破坏性变更

containerengine.Engine.StopContainer 签名由 StopContainer(context.Context, string) error 改为 StopContainer(context.Context, string, int) error（新增超时秒数参数）。

修复旧容器「kill 不掉」

• 根因：MobyEngine.StopContainer 用 ContainerStopOptions{}（不传超时），Docker 沿用容器创建时设置的 StopTimeout=9000 秒，Spring Boot 优雅停机长期不退时旧容器无法停止。
• internal/containerengine/engine.go / moby.go：StopContainer 增加 timeoutSeconds，ContainerStop 显式传 Timeout。
• internal/backendupdate/container.go：新增常量 containerStopGraceSeconds = 30，containerStopOperation.Apply 传入 30 秒，超时后 Docker 强制 SIGKILL。

修复启动日志跟随

• 根因：ContainerLogs 用 Follow:false 一次性读快照（读于容器刚启动时，Spring Boot 尚未输出），且 RestartContainer 的 StartLog 为 false。
• internal/containerengine/moby.go：ContainerLogs 改为 Follow:true + io.Pipe 持续流式返回。
• internal/backendexecutor/executor.go：startAndCheck 改为后台 goroutine 跟随读日志（streamContainerLogs），健康检查结束后取消跟随。
• internal/backendupdate/container.go：RestartContainer 的 StartLog 改为 true。

测试

三个测试 fake 的 StopContainer 签名同步更新。全量 build/vet/test 通过。

---

2026-08-17 实现 container 后端 restart

ymsctl restart --service backend 的 container 后端此前直接返回「restart is not implemented for container backend」，本次补齐。

变更文件

• internal/backendexecutor/executor.go：新增 ImageAcquisitionPresent = "present" 模式——镜像已在本地，跳过 pull/load，仅在 prepare 核对本地镜像 digest + platform。
• internal/backendupdate/container.go：新增 RestartContainer；新增 inputTypeContainerRestart 常量；runContainerUpdate 按 InputType 区分 present/pull；提取 validateContainerInputs 复用前置校验。
• internal/backendupdate/restart.go：Restart 按 backend.type 分派，container → RestartContainer，native 走原逻辑。

语义（对齐 native restart 决策 50）

• 复用本地镜像，不重新 pull，不依赖 registry。
• 每次调用执行一次真实槽位轮转，幂等键用随机 restart: 前缀，不复用历史 update 的内容幂等键。
• 无部署记录、gateway 活动端口漂移、活动容器身份不一致时拒绝。
• 未完成 restart 事务由同一命令恢复；复用 runContainerUpdate + switchAndCommitContainer。

测试

container_test.go 新增：正常 restart（轮转 + 不 pull + 提交部署记录）、无部署记录拒绝、gateway 漂移拒绝。全量 build/vet/test 通过。

---

2026-08-17 实现 status / doctor / reconcile

依据 CLI_NAMING_AND_OPERATIONS_PLAN.md（已并入 PLAN.md 附录）第 3.3 / 4 / 5 节，实现三个诊断与对账子命令。

破坏性变更

1. daemonserver.New 签名：由 New(socketPath, updater, logger) 改为 New(socketPath, updater, diagnoser, logger)。
2. daemonapi.Request 新增 Apply bool（json:"apply"），仅 OperationReconcile 使用。
3. daemonapi.Response 新增 Diagnosis *Diagnosis（json:"diagnosis,omitempty"）。
4. daemonapi 新增操作常量 OperationStatus/OperationDoctor/OperationReconcile，及诊断级别常量 DiagnosisLevelOK/Fixable/Drift。
5. hostnginx.NewController 已是 2 参数（configPath, nginxExecutable），重载走 nginx -s reload（并行期间他人改动，本轮按现状接入）。

新增 / 修改文件

• 新增 internal/backendstatus/：diagnoser.go、container.go、native.go、reconcile.go、container_test.go。
• 修改 daemonapi/protocol.go、daemonserver/server.go、daemonclient/client.go、main.go、main_test.go、daemonserver/server_test.go。

诊断模型

• 级别：ok（一致）/ fixable（可自动修复）/ drift（需人工）。
• Healthy = true 当且仅当无 drift 项。
• 展示过滤：status 只展示 drift/fixable，doctor 展示全部，reconcile 只展示 fixable。
• container 诊断以 backend_container_deployment 记录为事实来源；native 只读诊断（无自动修复）。

待办

• native 自动修复未实现（JAR 链接漂移修复需 filestore identity + release 校验）。
• coverage.out 未重新生成（不含新包）。