docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md

@@ -195,7 +195,8 @@ Jenkins 可运行在 Windows 或其他机器上，本机 Windows 只作为人工
 
 - Jenkins Job 参数不暴露真实节点名、IP 或带 IP 的标签。
 - 构建 Job 固定使用 label expression：`linux && genarrative-build`。
-- 当前开发/构建/开发部署 agent 必须同时配置 `linux` 与 `genarrative-build` 两个标签；非 Linux 节点不能承担构建或部署。
+- 当前开发/构建/开发部署 agent 使用脱敏节点名 `genarrative-build-01`，必须同时配置 `linux` 与 `genarrative-build` 两个标签；非 Linux 节点不能承担构建或部署。
+- 构建机 agent 启动方式统一改为 inbound agent + systemd 自守护，不再依赖 Jenkins controller 通过 SSH launcher 长期拉起。SSH 只作为首次登录和安装 systemd 服务的运维通道。
 - 用途：拉代码、安装依赖、构建主站、构建后台、构建 `api-server`、构建 SpacetimeDB wasm、归档产物，并执行 `DEPLOY_TARGET=development` 的开发环境部署。
 
 ### 生产/发布实例
@@ -209,11 +210,11 @@ Jenkins 可运行在 Windows 或其他机器上，本机 Windows 只作为人工
 
 ### Jenkins inbound agent 自恢复
 
-发布 agent 必须由目标 Linux 机器主动连接 Jenkins controller，并由 systemd 托管：
+构建 agent 与发布 agent 都必须由目标 Linux 机器主动连接 Jenkins controller，并由 systemd 托管：
 
 - Jenkins 节点 Launch method 使用 inbound agent，优先启用 WebSocket。这样目标机只需要能访问 Jenkins Web 地址，不依赖 controller 每次 SSH 拉起 agent。
 - 目标机安装 `deploy/systemd/jenkins-agent@.service`、`scripts/deploy/jenkins-inbound-agent-start.sh` 与 `scripts/deploy/install-jenkins-inbound-agent.sh`。
-- systemd 服务名采用 `jenkins-agent@<node-name>.service`，例如 `jenkins-agent@genarrative-release-deploy-01.service`。
+- systemd 服务名采用 `jenkins-agent@<node-name>.service`，例如 `jenkins-agent@genarrative-build-01.service`、`jenkins-agent@genarrative-release-deploy-01.service`。
 - systemd 自身 `WorkingDirectory` 保持 `/var/lib/jenkins/agent/<node-name>`；Jenkins remoting `-workDir` 可继续使用旧 SSH agent 的 `/root/jenkins-agent`，避免迁移时 workspace 和缓存路径漂移。
 - inbound secret 只能放在目标机 `/etc/jenkins-agent/<node-name>.secret` 或等价 Secret Text 注入位置，不能提交到 Git，也不能写入 Jenkinsfile 默认参数。
 - systemd unit 使用 `Restart=always` 和 `RestartSec=10`；agent Java 进程退出、网络短断或机器重启后由 systemd 自动恢复，不需要人工盯着 Jenkins 页面手动重启。
@@ -221,13 +222,22 @@ Jenkins 可运行在 Windows 或其他机器上，本机 Windows 只作为人工
 
 如果 Jenkins controller 只运行在本地 Windows，不直接对目标机暴露公网地址，需要在本地控制机启动 `scripts/deploy/jenkins-agent-reverse-tunnel.ps1`。该脚本通过同一条 SSH 会话把远端 `127.0.0.1:18080` 转到本地 Jenkins Web `127.0.0.1:8080`，把远端 `127.0.0.1:50000` 转到本地 Jenkins inbound TCP agent port `127.0.0.1:50000`，并在隧道断开后自动重试。此时远端 agent 的 `JENKINS_URL` 固定写 `http://127.0.0.1:18080/`，不写本地 Windows 的 `127.0.0.1:8080`。
 
-本地反向隧道脚本不内置目标机地址；注册 Windows 计划任务时必须显式传入 `-RemoteHost <release-agent-host>`，真实 IP 或主机名只保存在本地计划任务配置中，不提交到 Git。
+本地反向隧道脚本不内置目标机地址；注册 Windows 计划任务时必须显式传入 `-RemoteHost <agent-host>`，真实 IP 或主机名只保存在本地计划任务配置中，不提交到 Git。同一台 Linux 机器上同时运行构建与发布 agent 时，两者共用这一条反向隧道，不为每个 Jenkins 节点重复注册本地隧道任务。
 
 当 Jenkins controller 以本地 Windows `java -jar jenkins.war` 方式运行时，使用 `scripts/deploy/jenkins-local-controller-watchdog.ps1` 作为本地守护脚本。该脚本只保存本机 Java、`jenkins.war`、`JENKINS_HOME` 和端口路径，不保存 Jenkins 账号、密码、token 或 agent secret；注册 Windows 计划任务后，脚本会在登录后检查 `8080` 是否已有 Jenkins 监听，若已有则监控现有 PID，若进程退出或端口空闲则重新启动 Jenkins，并固定 `--agentPort=50000` 供远端 inbound agent 连接。
 
 首次迁移示例：
 
 ```bash
+sudo install -m 0600 /tmp/genarrative-build-01.secret /etc/jenkins-agent/genarrative-build-01.secret
+sudo scripts/deploy/install-jenkins-inbound-agent.sh \
+  --agent-name genarrative-build-01 \
+  --jenkins-url http://127.0.0.1:18080/ \
+  --secret-file /etc/jenkins-agent/genarrative-build-01.secret \
+  --workdir /root/jenkins-agent \
+  --java-bin /usr/bin/java
+sudo systemctl status jenkins-agent@genarrative-build-01.service --no-pager -l
+
 sudo install -m 0600 /tmp/genarrative-release-deploy-01.secret /etc/jenkins-agent/genarrative-release-deploy-01.secret
 sudo scripts/deploy/install-jenkins-inbound-agent.sh \
   --agent-name genarrative-release-deploy-01 \
@@ -236,7 +246,7 @@ sudo scripts/deploy/install-jenkins-inbound-agent.sh \
   --workdir /root/jenkins-agent \
   --java-bin /usr/bin/java
 sudo systemctl status jenkins-agent@genarrative-release-deploy-01.service --no-pager -l
-journalctl -u jenkins-agent@genarrative-release-deploy-01.service -f
+journalctl -u 'jenkins-agent@*.service' -f
 ```
 
 如果 Jenkins controller 暂时仍配置为 SSH launcher，只能作为过渡方案使用：需要把 SSH launch timeout 拉长、增加 retry 和 retry wait、固定 Java 路径，并确认 `ssh user@host 'java -version'` 稳定返回。最终仍要切到 inbound + systemd，避免 SSH 连接卡住时阻塞发布队列。