yms-daemon/RUNBOOK_NATIVE_BACKEND.md

# Native backend 首次试运行

本文只适用于已经安装 `yms-backend@.service`、使用宿主机 Nginx managed upstream、当前由旧 `yms.service` 或 `ymsback.service` 接流的开发环境。

## 1. 构建 RPM

ARM64：

```bash
./packaging/rpm/build-rpm.sh --goarch arm64
```

x86-64：

```bash
./packaging/rpm/build-rpm.sh --goarch amd64
```

RPM 输出到 `dist/`。需要指定包版本和发布序号时使用：

```bash
./packaging/rpm/build-rpm.sh \
  --goarch arm64 \
  --version 0.1.0 \
  --release 20260816010000
```

安装或升级：

```bash
rpm -Uvh dist/<完整RPM文件名>.rpm
systemctl enable --now yms-daemon.service
```

RPM 不会自动启动或重启 `yms-daemon.service`，避免安装恰好发生在更新事务执行期间。首次安装执行 `systemctl enable --now`；升级后由交付人员在确认没有更新事务执行时运行：

```bash
systemctl restart yms-daemon.service
```

`/etc/yms-daemon/yms-daemon.toml` 使用 `noreplace` 语义，升级不会覆盖现场配置。RPM 会安装 `/usr/bin/yms-daemon`、两个 systemd unit、tmpfiles 配置，并创建 `/home/yms/dump`。

RPM 示例配置使用客户环境值：

```toml
[daemon]
environment = "prod"
```

开发机必须明确改为：

```toml
[daemon]
environment = "dev"
```

从不包含 `[daemon]` 的旧配置升级时，必须先加入上述完整 table，再重启 `yms-daemon.service`。`environment` 只选择未来 container 更新使用 Registry pull 还是 repack ZIP load，不改变当前 native backend 行为。

## 2. 直接构建 ARM64 二进制

在 `yms-daemon` 源码目录执行：

```bash
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -o yms-daemon .
```

## 3. 手工安装文件

把构建结果和 `packaging` 目录传到服务器后，以 root 执行：

```bash
install -m 0755 yms-daemon /usr/bin/yms-daemon
install -d -m 0755 /etc/yms-daemon
install -m 0640 packaging/etc/yms-daemon/yms-daemon.toml /etc/yms-daemon/yms-daemon.toml
install -m 0644 packaging/systemd/yms-daemon.service /etc/systemd/system/yms-daemon.service
install -m 0644 packaging/systemd/yms-backend@.service /etc/systemd/system/yms-backend@.service
install -m 0644 packaging/tmpfiles.d/yms-daemon.conf /etc/tmpfiles.d/yms-daemon.conf
systemd-tmpfiles --create /etc/tmpfiles.d/yms-daemon.conf
systemctl daemon-reload
systemctl enable --now yms-daemon.service
```

## 4. 更新前检查

```bash
systemctl status yms-daemon.service --no-pager -l
/usr/sbin/nginx -t
curl -fsS http://127.0.0.1:8081/yms/actuator/health
```

确认健康响应顶层 `status` 为 `UP`。第一次更新前不要手工停止 `ymsback.service`；daemon 需要读取当前接流端口和旧 unit 状态完成受控迁移。

## 5. 执行更新

客户 repack ZIP 模式：

```bash
yms-daemon update --service backend -f /home/yms/tmp/<完整包名>.zip
```

ZIP 根目录必须包含：

```text
artifact-selection.json
<artifact-selection.json 中 backendArtifacts.fileName 精确声明的 JAR>
```

daemon 只接受 `backendArtifacts` 中唯一满足以下精确值的条目：

```text
artifactKind = BACKEND
type = native
selectedType = native
```

开发环境不需要打 ZIP。Jenkins 或交付人员先把完整 JAR 复制到 `/home/yms/tmp`，再执行：

```bash
yms-daemon update --service backend --native-jar /home/yms/tmp/<完整JAR文件名>.jar
```

`-f` 与 `--native-jar` 必须且只能提供一个。daemon 不根据文件扩展名选择更新模式。直传 JAR 会被完整校验并计算 SHA-256，然后保存到：

```text
/home/yms/lib/releases/direct/<SHA-256前12位>/<原始JAR文件名>
```

目录名精确取完整 SHA-256 小写十六进制字符串的前 12 位。事务幂等身份和文件内容校验仍使用完整 SHA-256；12 位目录发生内容冲突时拒绝覆盖。

普通模式会持续输出更新过程，例如：

```text
INFO           Validating direct native backend JAR and computing SHA-256
CREATED        Created update transaction <事务ID>
VALIDATING     Validating inactive native backend slot
PREPARED       Installing backend JAR and binding the inactive slot
STARTING       Starting native backend unit yms-backend@8080.service
STARTING       Waiting up to 2m0s for Actuator health: http://127.0.0.1:8080/yms/actuator/health
STARTING       Actuator health status is UP
SWITCHING      Switching host Nginx backend traffic to port 8080
VERIFYING      Updating the active compatibility JAR link
DRAINING       Draining previous backend unit for 5s
COMMITTED      Native backend update committed
transaction=<事务ID> state=COMMITTED
```

Jenkins 只需要退出码、不需要过程和成功结果时，使用精确参数 `--quite`：

```bash
yms-daemon update --service backend --native-jar /home/yms/tmp/<完整JAR文件名>.jar --quite
```

`--quite` 不写正常过程和成功结果；失败信息仍写入 stderr，并返回非零退出码。

最终成功结果为：

```text
transaction=<事务ID> state=COMMITTED
```

另一个终端可以查看全过程：

```bash
journalctl -u yms-daemon.service -f
```

## 6. 零停机重启 backend

修改 `/home/yms/bin/env/yms.env` 等 backend 启动配置后，执行：

```bash
yms-daemon restart --service backend
```

daemon 读取 `/home/yms/lib/glory-soft-yms.jar` 当前指向的精确 release，创建独立 restart 事务，将同一 JAR 绑定到非活动槽位，启动并完成 Actuator 健康检查后切流，等待 drain，再停止旧槽。当前 JAR 已经位于 release 目录时直接复用；兼容入口仍是普通文件时，先按内容身份导入 release 目录。restart 不重新上传 JAR，也不以历史 update 的内容幂等键阻止本次轮转。

静默执行：

```bash
yms-daemon restart --service backend --quite
```

restart 进行中如果 daemon 重启，再次执行同一命令会恢复唯一未完成的 backend restart 事务。存在其他未完成 update 事务时，restart 拒绝创建新事务并返回该活动事务 ID。

## 7. 更新或重启后检查

```bash
systemctl show --no-pager \
  --property=Id \
  --property=LoadState \
  --property=ActiveState \
  ymsback.service \
  yms-backend@8080.service \
  yms-backend@8081.service

readlink /home/yms/lib/glory-soft-yms.jar

sed -n \
  '/# yms-update managed upstream begin/,/# yms-update managed upstream end/p' \
  /etc/nginx/nginx.conf

curl -fsS http://127.0.0.1:8080/yms/actuator/health
```

第一次从当前现场状态更新成功后，预期 Nginx 接流 8080、`yms-backend@8080.service` 为 active、旧 `ymsback.service` 为 inactive，兼容入口指向 `/home/yms/lib/releases` 中的新 JAR。