141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
# 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 名称继续固定为：
|
||
|
||
```text
|
||
yms-daemon.service
|
||
```
|
||
|
||
unit 的启动目标为：
|
||
|
||
```text
|
||
/usr/sbin/ymsd
|
||
```
|
||
|
||
POC 阶段不保留 `yms-daemon` 命令兼容入口，直接采用新命名。更新命令统一使用：
|
||
|
||
```bash
|
||
ymsctl update ...
|
||
ymsctl restart ...
|
||
```
|
||
|
||
## 3. ymsctl 命令层级
|
||
|
||
### 3.1 更新与回滚
|
||
|
||
```bash
|
||
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 历史操作查询
|
||
|
||
```bash
|
||
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 当前状态与诊断
|
||
|
||
```bash
|
||
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 的调用协议。
|