yms-daemon/CLI_NAMING_AND_OPERATIONS_PLAN.md

YMS 命令入口与操作查询方案

状态：方案确认，暂不进入代码实现

1. 命令职责

命令入口采用 daemon/client 分离，命名参考 chronyd / chronyc：

命令	职责	是否常驻
ymsd	更新助手服务端，监听 Unix Socket，执行事务和恢复	是
ymsctl	运维和交付 CLI，提交更新、查询状态、诊断和回滚	否
yms-gui	客户 PC 图形化中转助手，名称后续确定	否

ymsd 不承担交互式更新命令；更新请求由 ymsctl 通过 Unix Socket 提交。POC 阶段不对外提供 serve 子命令，systemd 的 ExecStart 直接启动 /usr/sbin/ymsd。

2. systemd 与安装

systemd unit 名称继续固定为：

yms-daemon.service

unit 的启动目标为：

/usr/sbin/ymsd

POC 阶段不保留 yms-daemon 命令兼容入口，直接采用新命名。更新命令统一使用：

ymsctl update ...
ymsctl restart ...

3. ymsctl 命令层级

3.1 更新与回滚

ymsctl update --service backend -f <repack.zip>
ymsctl update --service backend --native-jar <backend.jar>
ymsctl update --service backend --container-image <image:tag>
ymsctl restart --service backend
ymsctl rollback --service backend --transaction <transaction-id>

--native-jar 与 --container-image 互斥。rollback 必须指定明确的事务 ID 或已提交版本身份，不允许根据目录排序、文件修改时间或镜像 tag 猜测回滚目标。

3.2 历史操作查询

ymsctl list
ymsctl list --limit 50
ymsctl list --state FAILED
ymsctl list --service backend
ymsctl list --json

默认显示最近 20 次操作，按创建时间倒序。每条记录至少展示：

• 创建时间和结束时间；
• transaction ID；
• service；
• operation；
• 输入类型和版本或镜像 digest；
• 来源（CLI、PC client、Jenkins、server API）；
• 最终状态；
• 失败原因。

--json 输出稳定 JSON，供 Jenkins 和 PC client 使用。列表数据只读取 SQLite，不直接扫描 systemd、Docker 或 Nginx 生成历史记录。

3.3 当前状态与诊断

ymsctl status --service backend
ymsctl doctor --service backend
ymsctl reconcile --service backend
ymsctl reconcile --service backend --apply

• status：读取 SQLite 后校验当前 systemd、Docker、Nginx 和活动槽位状态；
• doctor：只读诊断，输出漂移项和建议动作；
• reconcile：只读生成修复计划；
• reconcile --apply：执行明确授权的修复动作，并创建可审计事务。

4. 状态漂移处理原则

SQLite 是事务事实来源，外部系统是待校验运行状态。发现不一致时默认拒绝更新，不自动覆盖现场。

只有以下类型允许自动修复：

1. SQLite 记录的活动容器存在、身份匹配且健康，Nginx 仅指向错误槽位；
2. 非活动槽位容器存在、已停止且没有提交记录；
3. native 活动 JAR 链接与已提交事务明确记录的 release 不一致，且目标文件身份校验通过；
4. 已完成事务的临时文件可以按照事务凭据清理。

以下情况必须进入 DRIFT_DETECTED，等待人工确认：

• SQLite 记录的活动容器已经不存在；
• 两个槽位同时运行且无法确定提交归属；
• SQLite 没有部署记录，但现场已经存在容器或运行中的 native 服务；
• Nginx 配置无法验证或存在非 daemon 管理的冲突；
• systemd unit、容器镜像 digest、JAR SHA-256 与事务记录不一致。

任何修复动作都必须先写入事务，再执行外部变更；修复失败时沿用现有回滚和恢复机制。

5. systemd 服务与 ymsd 的边界

ymsd 负责：

• 持有进程锁；
• 打开 SQLite；
• 恢复未完成事务；
• 调用 native/container 执行器；
• 通过 Unix Socket 提供请求和进度响应；
• 写入 stdout 和本地日志文件。

ymsctl 负责：

• 参数校验；
• 提交请求；
• 展示进度；
• 查询历史和当前状态；
• 发起显式诊断和修复。

ymsctl 不直接写 SQLite，不直接修改 Nginx，不直接调用 Docker 或 systemd。

6. 实施顺序

1. 增加 SQLite 最近操作查询接口；
2. 实现 ymsctl list 和 JSON 输出；
3. 拆分 ymsd 与 ymsctl 的编译入口；
4. 安装 ymsd、ymsctl 和兼容入口 yms-daemon；
5. 实现 status 只读一致性检查；
6. 实现 doctor 漂移报告；
7. 实现带事务审计的 reconcile --apply；
8. 最后确定 GUI 名称和 PC client 的调用协议。