6.5 KiB
Native backend 首次试运行
本文只适用于已经安装 yms-backend@.service、使用宿主机 Nginx managed upstream、当前由旧 yms.service 或 ymsback.service 接流的开发环境。
1. 构建 RPM
ARM64：
./packaging/rpm/build-rpm.sh --goarch arm64
x86-64：
./packaging/rpm/build-rpm.sh --goarch amd64
RPM 输出到 dist/。需要指定包版本和发布序号时使用：
./packaging/rpm/build-rpm.sh \
--goarch arm64 \
--version 0.1.0 \
--release 20260816010000
安装或升级：
rpm -Uvh dist/<完整RPM文件名>.rpm
systemctl enable --now yms-daemon.service
RPM 不会自动启动或重启 yms-daemon.service，避免安装恰好发生在更新事务执行期间。首次安装执行 systemctl enable --now；升级后由交付人员在确认没有更新事务执行时运行：
systemctl restart yms-daemon.service
/etc/yms-daemon/yms-daemon.toml 使用 noreplace 语义，升级不会覆盖现场配置。RPM 会安装 /usr/bin/ymsd 和 /usr/bin/ymsctl、两个 systemd unit、tmpfiles 配置，并创建 /home/yms/dump。
RPM 示例配置使用客户环境值：
[daemon]
environment = "prod"
开发机必须明确改为：
[daemon]
environment = "dev"
从不包含 [daemon] 的旧配置升级时，必须先加入上述完整 table，再重启 yms-daemon.service。environment 只选择未来 container 更新使用 Registry pull 还是 repack ZIP load，不改变当前 native backend 行为。
2. 直接构建 ARM64 二进制
在 yms-daemon 源码目录执行：
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -o yms-daemon .
3. 手工安装文件
把构建结果和 packaging 目录传到服务器后，以 root 执行：
install -m 0755 ymsd /usr/bin/ymsd
install -m 0755 ymsctl /usr/bin/ymsctl
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. 更新前检查
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 模式：
ymsctl update --service backend -f /home/yms/tmp/<完整包名>.zip
ZIP 根目录必须包含：
artifact-selection.json
<artifact-selection.json 中 backendArtifacts.fileName 精确声明的 JAR>
daemon 只接受 backendArtifacts 中唯一满足以下精确值的条目：
artifactKind = BACKEND
type = native
selectedType = native
开发环境不需要打 ZIP。Jenkins 或交付人员先把完整 JAR 复制到 /home/yms/tmp，再执行：
ymsctl update --service backend --native-jar /home/yms/tmp/<完整JAR文件名>.jar
-f 与 --native-jar 必须且只能提供一个。daemon 不根据文件扩展名选择更新模式。直传 JAR 会被完整校验并计算 SHA-256，然后保存到：
/home/yms/lib/releases/direct/<SHA-256前12位>/<原始JAR文件名>
目录名精确取完整 SHA-256 小写十六进制字符串的前 12 位。事务幂等身份和文件内容校验仍使用完整 SHA-256；12 位目录发生内容冲突时拒绝覆盖。
普通模式会持续输出更新过程，例如：
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：
ymsctl update --service backend --native-jar /home/yms/tmp/<完整JAR文件名>.jar --quite
--quite 不写正常过程和成功结果；失败信息仍写入 stderr，并返回非零退出码。
最终成功结果为：
transaction=<事务ID> state=COMMITTED
另一个终端可以查看全过程：
journalctl -u yms-daemon.service -f
6. 零停机重启 backend
修改 /home/yms/bin/env/yms.env 等 backend 启动配置后，执行：
ymsctl restart --service backend
daemon 读取 /home/yms/lib/glory-soft-yms.jar 当前指向的精确 release，创建独立 restart 事务，将同一 JAR 绑定到非活动槽位，启动并完成 Actuator 健康检查后切流，等待 drain，再停止旧槽。当前 JAR 已经位于 release 目录时直接复用；兼容入口仍是普通文件时，先按内容身份导入 release 目录。restart 不重新上传 JAR，也不以历史 update 的内容幂等键阻止本次轮转。
静默执行：
ymsctl restart --service backend --quite
restart 进行中如果 daemon 重启，再次执行同一命令会恢复唯一未完成的 backend restart 事务。存在其他未完成 update 事务时，restart 拒绝创建新事务并返回该活动事务 ID。
7. 更新或重启后检查
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。