207 lines
6.5 KiB
Markdown
207 lines
6.5 KiB
Markdown
# 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/ymsd` 和 `/usr/bin/ymsctl`、两个 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 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. 更新前检查
|
||
|
||
```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
|
||
ymsctl 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
|
||
ymsctl 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
|
||
ymsctl 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
|
||
ymsctl restart --service backend
|
||
```
|
||
|
||
daemon 读取 `/home/yms/lib/glory-soft-yms.jar` 当前指向的精确 release，创建独立 restart 事务，将同一 JAR 绑定到非活动槽位，启动并完成 Actuator 健康检查后切流，等待 drain，再停止旧槽。当前 JAR 已经位于 release 目录时直接复用；兼容入口仍是普通文件时，先按内容身份导入 release 目录。restart 不重新上传 JAR，也不以历史 update 的内容幂等键阻止本次轮转。
|
||
|
||
静默执行：
|
||
|
||
```bash
|
||
ymsctl 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。
|