fix(ci): simplify server provision pipeline

2026-06-05 16:14:30 +08:00
parent e5592304a5
commit 524ad430ab
7 changed files with 183 additions and 263 deletions
--- a/.hermes/shared-memory/decision-log.md
+++ b/.hermes/shared-memory/decision-log.md
@@ -16,6 +16,14 @@

 ---

+## 2026-06-05 Server-Provision 全程在目标部署 agent 执行且不安装构建链
+
+- 背景：`Genarrative-Server-Provision` 的 `DEPLOY_TARGET=development` 语义是部署到 dev 服务器，不是构建机 dry-run。旧流水线把 development 映射到 `linux && genarrative-build`，还先在 build 节点准备 `provision-tools/` 再 stash 给后续阶段，导致真实 dev 初始化可能跑到 Jenkins controller / build 节点；脚本还安装 clang / lld / pkg-config / OpenSSL headers / sccache 等构建链依赖，超出了服务器初始化职责。
+- 决策：Server-Provision 只做服务器初始化，全程运行在目标部署 agent：development 使用 `linux && genarrative-dev-deploy`，release 使用 `linux && genarrative-release-deploy`。`Prepare Provision Tools` 与 `Provision Server` 在同一个目标 agent workspace 顺序执行，不再切到 `linux && genarrative-build`，不再 `stash/unstash` 工具包。`scripts/jenkins-server-provision.sh` 不再安装 clang / lld / pkg-config / libssl-dev / sccache；非 dry-run 仍要求目标 dev / release agent 具备 root 权限，因为 provision 会写 systemd、Nginx、`/etc` 和系统用户。Job 的 `Pipeline script from SCM` 与 Jenkinsfile 参数 `SOURCE_GIT_REMOTE_URL` 都必须使用本机路径或目标 agent 可访问的内网 Git 源，不允许公网 Git fallback。
+- 影响范围：`jenkins/Jenkinsfile.production-server-provision`、`scripts/jenkins-server-provision.sh`、生产运维文档、Server-Provision 排障口径。
+- 验证方式：Jenkins 日志中 Server-Provision 的 `Prepare`、`Checkout Provision Files`、`Prepare Provision Tools` 和 `Provision Server` 都在目标 dev / release agent 上执行；日志不出现 `Running on Jenkins`、`linux && genarrative-build`、`stash 'server-provision-tools'`、`Git 主地址拉取失败...改用备用地址`、`https://git.genarrative.world/GenarrativeAI/Genarrative.git` 或构建依赖 / sccache 安装步骤；`bash -n scripts/jenkins-server-provision.sh` 和编码检查通过。
+- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 2026-06-05 api-server 重启先摘流再排空并持久化 outbox

 - 背景：生产部署重启 api-server 时，如果只用 `/healthz` 判断存活并直接停止进程，运行中的 HTTP 请求和本地 tracking outbox active 文件都可能被中断，容易造成用户请求失败或内存/本地缓冲数据延迟丢失。
@@ -459,7 +467,7 @@

 ## 2026-05-19 生产 provision 改为 Windows 下载包后由目标机本地安装

- 后续更新：该口径已被 `2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost` 取代；当前 `Genarrative-Server-Provision` 不再走 Windows 下载阶段，而是在 Linux build 节点直接准备 `provision-tools/`。
+- 后续更新：该口径先被 2026-06-01 Linux 优先方案取代，又在 2026-06-05 被 Server-Provision 专用口径覆盖；当前 `Genarrative-Server-Provision` 不走 Windows 下载阶段，也不在 Linux build 节点中转工具包，而是在目标 dev / release agent 内准备 `provision-tools/`。
 - 背景：当前 `development` provision 目标实际就是 Linux agent `genarrative-build-01`，之前把 `Prepare Provision Tools` 放在 `linux && genarrative-build` 会让目标机自己连 GitHub 和 `install.spacetimedb.com`，违背“Windows 本机先下载再传到目标机”的运维要求。
 - 决策：`Genarrative-Server-Provision` 拆成 Windows 下载阶段和 Linux 目标机安装阶段。Windows 节点的 `Download Provision Tool Archives` 只下载 `spacetime-x86_64-unknown-linux-gnu.tar.gz` 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz`，通过 `stash/unstash` 传到目标 Linux 节点；目标机执行 `scripts/prepare-server-provision-tools.sh` 时设置 `PROVISION_REQUIRE_LOCAL_DOWNLOADS=true`，只消费已下载件生成 `provision-tools/`，缺包直接失败，不回退外网下载。
 - 追加决策：Server-Provision 的 Windows helper 不再对 Jenkins `writeFile` 刚写出的 `.ps1` 做原地 UTF-8 BOM 重写，而是由显式 `powershell.exe` 按 UTF-8 读入脚本文本，并用 `ScriptBlock::Create(...)` 在内存中执行；这样既保留中文脚本内容，又避免同一个 workspace 脚本被立即重写时触发 `拒绝访问`。
@@ -1117,6 +1125,7 @@

 ## 2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost

+- 后续更新：该条仍适用于常规构建 / 发布流水线；`Genarrative-Server-Provision` 已在 2026-06-05 改为目标部署 agent 全程执行，并禁止公网 Git fallback 与 build 节点工具包中转。
 - 背景：生产流水线长期混用 Windows、Linux 和公网 Git 入口，导致构建 / 发布 / provision 的 checkout 口径分叉；同时 `Genarrative-Server-Provision` 还残留过 Windows 下载 helper，和当前 Linux 构建 / 发布部署路径不一致。
 - 决策：生产 Jenkins 流水线统一把执行节点收口到 Linux label，`Pipeline script from SCM` 仍保留公网域名，但所有生产流水线首次 `GitSCM checkout` 先尝试 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后再回退到 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；`Genarrative-Stdb-Module-Build`、`Genarrative-Server-Provision`、`Genarrative-Notify-Email` 也都切到 Linux 节点。`Genarrative-Server-Provision` 的工具准备不再依赖 Windows helper，而是在 Linux build 节点直接生成 `provision-tools/` 后交给后续 Linux 发布阶段。
 - 影响范围：`jenkins/Jenkinsfile.production-*`、`scripts/jenkins-checkout-source.sh`、`scripts/prepare-server-provision-tools.sh`、生产运维文档。
--- a/.hermes/shared-memory/pitfalls.md
+++ b/.hermes/shared-memory/pitfalls.md
@@ -1187,6 +1187,7 @@

 ## Jenkins 生产流水线拉 Git 先本机再域名备用

+- 后续更新：该条仍适用于常规构建 / 发布流水线；`Genarrative-Server-Provision` 已在 2026-06-05 改为服务器初始化专用口径，不允许公网 Git fallback，Job 的 `Pipeline script from SCM` 和 Jenkinsfile 内部 checkout 都必须使用本机路径或目标 agent 可访问的内网 Git 源。
 - 现象：生产发布、数据库导入导出、服务器配置、构建或 `Genarrative-Full-Build-And-Deploy` 流水线执行 `GitSCM checkout` 时，如果 Jenkins 生成的 fetch 是 `+refs/heads/*:refs/remotes/origin/*`，公网 Git 链路可能在收包阶段以 `git-remote-https died of signal 15`、`curl 56 GnuTLS recv error (-9)`、`early EOF`、`invalid index-pack output` 失败；发布类流水线还可能先遇到 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git` 不可达。
 - 原因：`127.0.0.1` 只代表当前执行阶段的 agent 自身；当 release agent 与 Git 服务不在同一台机器，或本机 Git/Web 服务临时不可用时，固定写死 localhost 会阻断 Jenkinsfile 内部源码/脚本 checkout。即使只使用域名 Git，如果 `GitSCM` 没有显式 refspec 并开启 `CloneOption honorRefspec=true`，Jenkins Git 插件也会拉取所有分支。
 - 处理：Jenkins Job 的 `Pipeline script from SCM` 由 Windows controller 执行，SCM URL 使用公网域名 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行于 `linux && genarrative-build` 的 `Genarrative-Full-Build-And-Deploy` 源码解析阶段、`Genarrative-Web-Build` checkout 阶段，以及部署/发布类 Linux agent 的 Jenkinsfile 首次 `checkout([$class: 'GitSCM', ...])` 层先尝试 `GIT_REMOTE_URL=http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后直接尝试 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不再配置内网 IP fallback；这些首次 checkout 都必须使用目标分支 refspec、`CloneOption shallow=true depth=1 noTags=true honorRefspec=true`。后续统一走 `scripts/jenkins-checkout-source.sh`，该脚本也按主地址、域名备用地址顺序重新 fetch 并把 `origin` 切到实际可用地址；`COMMIT_HASH` 为空时继续 `--depth=1 --no-tags`，只有指定 commit 时才允许加深历史做分支归属校验。
@@ -1209,12 +1210,12 @@
 - 验证：运行 `git ls-files --stage scripts/prepare-server-provision-tools.sh`，确认 mode 为 `100755`；重新跑 `Genarrative-Server-Provision` 时应进入工具下载/打包日志，而不是停在 `Permission denied`。
 - 关联：`jenkins/Jenkinsfile.production-server-provision`、`scripts/prepare-server-provision-tools.sh`、`scripts/jenkins-checkout-source.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

-## Server-Provision 工具准备只在 Linux build 节点做一次
+## Server-Provision 工具准备只在目标部署 agent 内做一次

- 现象：`Genarrative-Server-Provision` 在后续目标发布节点重复执行 `scripts/prepare-server-provision-tools.sh`，或日志里出现目标节点继续访问 GitHub release / `install.spacetimedb.com`。
- 原因：当前流水线已经改成 Linux build 节点一次性准备 `provision-tools/` 并 stash 给目标发布阶段；如果目标发布阶段又重新准备工具包，就会重复下载并把目标节点暴露到外网依赖。
- 处理：只允许 `Prepare Provision Tools` 阶段在 `linux && genarrative-build` 节点生成 `provision-tools/`；后续 `Provision Server` 阶段只 `unstash 'server-provision-tools'` 并安装其中的 `spacetime` 与 `otelcol-contrib`，不要再运行 `prepare-server-provision-tools.sh`。
- 验证：Jenkins 日志应先在 Linux build 节点出现 `[prepare-provision-tools] 工具包已准备`，后续目标发布节点只出现安装 / systemd / Nginx provision 日志；目标节点不应出现 `下载 otelcol-contrib:` 或 `下载 SpacetimeDB 官方安装器脚本:`。
+- 现象：`Genarrative-Server-Provision` 选择 `DEPLOY_TARGET=development` 时如果阶段跑在 `Running on Jenkins` 或 `linux && genarrative-build`，真实 provision 会落到构建机 / controller，而不是 dev 服务器。
+- 原因：Server-Provision 是服务器初始化流水线，dev / release 都是目标服务器，不应把 development 当成 build 节点预览目标，也不应通过 build 节点 stash 工具包再切回目标机；同时公网 Git fallback 会让目标 agent 内网源不可达时悄悄改从公网拉源码，掩盖服务器路由问题。
+- 处理：Server-Provision 全程运行在目标部署 agent：development 使用 `linux && genarrative-dev-deploy`，release 使用 `linux && genarrative-release-deploy`。`Prepare Provision Tools` 和 `Provision Server` 在同一个目标 agent workspace 内顺序执行，不再使用 `linux && genarrative-build`，也不再 `stash/unstash` 工具包。Job 的 `Pipeline script from SCM` 与参数 `SOURCE_GIT_REMOTE_URL` 都必须指向本机路径或内网 Git 源，不允许 `https://git.genarrative.world/...` 公网地址。
+- 验证：Jenkins 日志中 `Provision Target` 下的 `Prepare`、`Checkout Provision Files`、`Prepare Provision Tools` 和 `Provision Server` 都应运行在目标 dev / release agent；日志不应出现 `stash 'server-provision-tools'`、目标阶段 `unstash`、`Git 主地址拉取失败...改用备用地址` 或 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。
 - 关联：`jenkins/Jenkinsfile.production-server-provision`、`scripts/prepare-server-provision-tools.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

 ## 个人任务 scope 不得扩成 work/site/module
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -244,18 +244,18 @@ Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分

 `Genarrative-Web-Build` 打包 `web.tar.gz` 前、`Genarrative-Web-Deploy` 解包后都会把 Web 静态目录规范为目录 `755`、文件 `644`。如果前端页面能打开但 public 图片、字体或音频返回 `403 Forbidden`，优先检查当前 `/srv/genarrative/web` 指向的 release 中对应文件权限是否被异常归档为 `600`，临时恢复可对该 release 的 `web` 目录执行目录 `755`、文件 `644` 的权限修正。

-生产 Jenkins 的 `Pipeline script from SCM` 仍由 Jenkins controller 读取 Jenkinsfile，SCM URL 继续使用 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。现在所有生产流水线 job 的首次 checkout 都先走 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后回退到 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；两层 checkout 都必须保留单分支 refspec、`shallow=true`、`depth=1`、`noTags=true` 与 `honorRefspec=true`，后续二次源码确认继续走 `scripts/jenkins-checkout-source.sh`。
+生产 Jenkins 的 `Pipeline script from SCM` 由 Jenkins controller 读取 Jenkinsfile。`Genarrative-Server-Provision` 是服务器初始化流水线，Job 配置里的 SCM URL 必须使用 controller 本机可访问的仓库路径或内网 Gitea 地址，不能使用 `https://git.genarrative.world/...`；否则日志一开始的 `Checking out git ... to read jenkins/Jenkinsfile.production-server-provision` 就会先从公网拉 Jenkinsfile。其它构建 / 发布流水线仍按各自 Jenkinsfile 的 checkout 口径执行；所有 `GitSCM checkout` 都必须保留单分支 refspec、`shallow=true`、`depth=1`、`noTags=true` 与 `honorRefspec=true`。


 `Genarrative-Stdb-Module-Publish` 在 `Pipeline script from SCM` 阶段如果一开始就报 `No such DSL method 'pipeline'`，优先检查 `jenkins/Jenkinsfile.production-stdb-module-publish` 是否带 UTF-8 BOM。Jenkins Declarative Pipeline 的首个 token 必须是纯 `pipeline`；仓库中的 Jenkinsfile 应保存为 UTF-8 without BOM，只有临时写给 Windows PowerShell 5.1 `-File` 执行的 `.ps1` 才需要按对应 helper 转成带 BOM。验证时可检查文件前三字节不再是 `EF BB BF`，并运行 `validateDeclarativePipeline` 或重放该流水线。

 `Genarrative-Stdb-Module-Build` 或 SpacetimeDB module 构建失败若出现 Rust `E0425 cannot find function migrate_*`，优先排查 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs` 等同文件内默认种子迁移 helper 是否在分支合并时只保留了调用、漏掉了函数定义。`Genarrative-Stdb-Module-Build` 现在运行在 `linux && genarrative-build` 节点上，Checkout 与 Build 都走 bash + cargo + sccache，不再依赖 Windows PowerShell 或 Git Bash。修复时不要直接删除迁移调用；应恢复只纠偏历史默认种子且不覆盖后台手动配置的 helper，并用 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 复现 Jenkins module 编译路径。

-`Genarrative-Server-Provision` 现在也运行在 `linux && genarrative-build` / `linux && genarrative-release-deploy` 节点上，`Prepare Provision Tools` 会在 Linux build 节点直接准备 SpacetimeDB 与 `otelcol-contrib` 交付件，再 stash 给后续发布阶段；旧 Windows 下载 helper 已退役。`Genarrative-Stdb-Module-Build`、`Genarrative-Server-Provision` 和 `Genarrative-Notify-Email` 都不再需要单独的 Windows 节点口径。
+`Genarrative-Server-Provision` 只做服务器初始化，不再承担构建职责。流水线全程运行在目标服务器 agent：`DEPLOY_TARGET=development` 使用 `linux && genarrative-dev-deploy`，`DEPLOY_TARGET=release` 使用 `linux && genarrative-release-deploy`；`Prepare Provision Tools` 也在同一个目标 agent 工作区内准备 SpacetimeDB 与 `otelcol-contrib` 交付件，不再切到 `linux && genarrative-build`，也不再 stash 给后续阶段。`SOURCE_GIT_REMOTE_URL` 必须显式填写为目标 agent 可访问的本机路径、`file:///` 地址、localhost / 127.0.0.1、RFC1918 内网 HTTP Git 地址、单标签内网主机名或 `.local` / `.lan` / `.internal` 地址；这条流水线不配置公网 Git 备用地址，目标 agent 拉不到内网源就应直接失败。真实初始化会写入 `/etc` / systemd / Nginx、创建系统用户并修改服务，目标 dev / release agent 非 dry-run 时都必须具备 root 权限。

 生产环境变量模板：`deploy/env/api-server.env.example`。真实密钥只放服务器，不提交 Git，不写入文档示例。

-`Genarrative-Server-Provision` 会安装基础构建依赖、systemd 模板和 Nginx 站点模板。Ubuntu / apt 目标机会额外安装 `libnginx-mod-http-brotli-filter` 与 `libnginx-mod-http-brotli-static`，随后由 `scripts/jenkins-server-provision.sh` 通过临时 `nginx -t` 配置探测 Brotli 指令是否可用；该临时配置必须先 `include /etc/nginx/modules-enabled/*.conf`，因为 apt 安装的 Brotli 是动态模块，不会出现在普通 `nginx -V` 编译参数里。探测成功才在渲染后的 `deploy/nginx/genarrative.conf` / `genarrative-dev-http.conf` 中启用 Brotli，避免未安装模块的机器直接写入无效配置。Provision 写入 Genarrative Nginx 站点时会把 `/etc/nginx/sites-enabled/default*` 移到 `/etc/nginx/sites-disabled/`，避免 Debian / Certbot 默认站点继续占用 `genarrative.world` / `www.genarrative.world` 并在 `nginx -T` 中出现 `conflicting server name ... ignored`。如果 `nginx -t` 失败，脚本会恢复写入前的 Genarrative 配置和被移动的默认站点。
+`Genarrative-Server-Provision` 会安装 systemd 模板和 Nginx 站点模板，不再安装 clang / lld / pkg-config / OpenSSL headers / sccache 等构建链依赖。Ubuntu / apt 目标机会额外安装 `libnginx-mod-http-brotli-filter` 与 `libnginx-mod-http-brotli-static`，随后由 `scripts/jenkins-server-provision.sh` 通过临时 `nginx -t` 配置探测 Brotli 指令是否可用；该临时配置必须先 `include /etc/nginx/modules-enabled/*.conf`，因为 apt 安装的 Brotli 是动态模块，不会出现在普通 `nginx -V` 编译参数里。探测成功才在渲染后的 `deploy/nginx/genarrative.conf` / `genarrative-dev-http.conf` 中启用 Brotli，避免未安装模块的机器直接写入无效配置。Provision 写入 Genarrative Nginx 站点时会把 `/etc/nginx/sites-enabled/default*` 移到 `/etc/nginx/sites-disabled/`，避免 Debian / Certbot 默认站点继续占用 `genarrative.world` / `www.genarrative.world` 并在 `nginx -T` 中出现 `conflicting server name ... ignored`。如果 `nginx -t` 失败，脚本会恢复写入前的 Genarrative 配置和被移动的默认站点。

 50 HTTP req/s 首版压测优化口径：

@@ -263,8 +263,8 @@ Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
 - `GENARRATIVE_API_MAX_CONCURRENT_REQUESTS=512` 开启应用内 HTTP 并发背压；`GENARRATIVE_API_GALLERY_MAX_CONCURRENT_REQUESTS=320`、`GENARRATIVE_API_DETAIL_MAX_CONCURRENT_REQUESTS=64`、`GENARRATIVE_API_ADMIN_MAX_CONCURRENT_REQUESTS=16` 分别限制公开列表、公开详情和后台 API 热路径。超过许可时直接返回 `429 Too Many Requests` 和 `Retry-After: 1`，`/healthz` 与 `/readyz` 不受该限制。这些值不是 RPS 限速；如果压测中 429 上升但内存和 p95 收敛，说明背压正在保护进程。直连 `api-server` 的极高 RPS 压测若出现 `connection refused`，通常已经打到 TCP 监听 / accept 层，应同时检查 backlog、Nginx upstream keepalive 和前置限流。
 - `api-server` 正常运行时 `/healthz` 返回进程存活状态，`/readyz` 返回是否仍接收新流量；收到 `SIGINT` / `SIGTERM` 后会先把 readiness 标记为不可用，再让 Axum 停止接新连接并等待已有 HTTP 请求排空。systemd 仍以 `KillSignal=SIGINT` 停服务，`TimeoutStopSec=90` 作为长请求排空上限。
 - `genarrative-api.service` 设置 `LimitNOFILE=65535`、`TasksMax=2048`；上线后用 `systemctl show genarrative-api.service -p LimitNOFILE -p TasksMax -p TimeoutStopUSec` 和 `cat /proc/$(pidof api-server)/limits` 核对。
- Server provision 不再通过 Windows helper 下载。`Genarrative-Server-Provision` 的 `Prepare Provision Tools` 在 Linux build 节点直接准备 `spacetime-x86_64-unknown-linux-gnu.tar.gz` 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz`，再 stash `provision-tools/` 给后续发布阶段；如果 build 节点需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置 Linux 侧可访问的 HTTP 代理。后续 Linux 目标节点只消费 `provision-tools/`，不再回退到外网下载。
- `Genarrative-Stdb-Module-Build`、`Genarrative-Web-Build`、`Genarrative-Api-Build`、`Genarrative-*Deploy`、`Genarrative-Database-Import/Export`、`Genarrative-Full-Build-And-Deploy` 和 `Genarrative-Notify-Email` 的生产流水线现都以 Linux agent 为主，统一走 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git` 优先、`https://git.genarrative.world/GenarrativeAI/Genarrative.git` 备用的 checkout 口径。
+- Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转工具包。`Prepare Provision Tools` 在目标 dev / release agent 工作区内准备 `spacetime-x86_64-unknown-linux-gnu.tar.gz` 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz` 并生成 `provision-tools/`；如果目标服务器下载需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
+- 除 `Genarrative-Server-Provision` 外，`Genarrative-Stdb-Module-Build`、`Genarrative-Web-Build`、`Genarrative-Api-Build`、`Genarrative-*Deploy`、`Genarrative-Database-Import/Export`、`Genarrative-Full-Build-And-Deploy` 和 `Genarrative-Notify-Email` 的生产流水线现都以 Linux agent 为主，仍按各自 Jenkinsfile 的 checkout 口径执行。Server provision 不使用公网备用 Git 源。
 - `otelcol-contrib.service` 作为可选系统服务加入 provision，默认监听 `127.0.0.1:4317/4318` 并使用 `deploy/otelcol/genarrative-debug.yaml`。api-server 是否发送 OTLP 仍由 `GENARRATIVE_OTEL_ENABLED` 控制，服务 unit 见 `deploy/systemd/otelcol-contrib.service`。
 - Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；`limit_conn` 负责连接 / 并发保护，`limit_req` 负责入口 RPS 快拒绝。当前模板把公开 gallery list 单独放到 `genarrative_gallery_rps`，默认 `rate=5000r/s`、`burst=4096`、`limit_conn=320`；公开详情和普通 API 放到 `genarrative_api_rps`，后台 API 放到 `genarrative_admin_rps`。通用 `/api` location 设置 `client_max_body_size 64m` 是反代兜底，防止拼图入口页 / 新增关卡本地参考图 Data URL 或旧兼容请求在到达 `api-server` 前被默认 1 MiB 上限拦截；拼图本地参考图前后端统一限制 6MB，历史图片仍提交 `referenceImageAssetObjectId(s)`。若线上出现 `413 Request Entity Too Large` 且 access log 中 `request_time=0.000`、`upstream_status=-`，说明请求在 Nginx 层被拦截，先用 `nginx -T | grep client_max_body_size` 检查 release 模板是否已渲染并 reload，同时检查前端是否超出 6MB 或错误提交了未压缩大图。`limit_conn_status 429` 和 `limit_req_status 429` 必须在 HTTP 与 HTTPS server 中同时生效；若线上压测看到 `limiting connections by zone "genarrative_api_conn"` 却返回 503，优先检查 `nginx -T` 里 HTTPS server 是否缺少这些状态码，以及 `/api/runtime/puzzle/gallery` 是否误落到通用 `location ~ ^/api` 的 `limit_conn=64`。压测时看 `/var/log/nginx/genarrative.access.log` 中的 `request_time`、`upstream_connect_time`、`upstream_header_time`、`upstream_response_time`、`upstream_status`、`request_id`。
 - 作品列表 K6 脚本一次 iteration 默认请求两个公开接口，因此约 50 HTTP req/s 的目标命令使用 `SCENARIO=spike START_RPS=5 PEAK_RPS=25 HOLD=60s END_RPS=5 DETAIL_RATIO=0 npm run loadtest:k6:works`。
@@ -282,7 +282,7 @@ npm run container:k6
 npm run container:down
 ```

-容器方案默认暴露 `http://127.0.0.1:18080`，`api-server` 在容器内监听 `0.0.0.0:8082`，Nginx 通过 `api-server:8082` upstream 反代 `/api/` 和 `/admin/api/`。SpacetimeDB 也纳入 compose，容器内由 `spacetimedb:3101` 提供服务，宿主机通过 `http://127.0.0.1:13101` 进行模块发布；Collector 镜像使用 `otel/opentelemetry-collector-contrib:0.151.0`。生产 provision 侧现在由 Linux build 节点直接准备 `provision-tools/otelcol-contrib`，再交给后续 Linux 发布阶段安装本机 `otelcol-contrib.service`，真实库名、token 和外部服务密钥只写本地 `deploy/container/api-server.env`，不提交 Git。完整拓扑、端口、k6 参数和 OTLP debug exporter 使用方法见 `deploy/container/README.md`。
+容器方案默认暴露 `http://127.0.0.1:18080`，`api-server` 在容器内监听 `0.0.0.0:8082`，Nginx 通过 `api-server:8082` upstream 反代 `/api/` 和 `/admin/api/`。SpacetimeDB 也纳入 compose，容器内由 `spacetimedb:3101` 提供服务，宿主机通过 `http://127.0.0.1:13101` 进行模块发布；Collector 镜像使用 `otel/opentelemetry-collector-contrib:0.151.0`。生产 provision 侧现在由目标 dev / release agent 自己准备 `provision-tools/otelcol-contrib`，并安装本机 `otelcol-contrib.service`，真实库名、token 和外部服务密钥只写本地 `deploy/container/api-server.env`，不提交 Git。完整拓扑、端口、k6 参数和 OTLP debug exporter 使用方法见 `deploy/container/README.md`。
 `npm run container:config` 默认只做 quiet 校验，避免把本地 env 中的 token 展开到终端；确需排查完整 compose 时再传 `-- --print`。

 OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日志与 Nginx 文件日志仍保留：
--- a/jenkins/Jenkinsfile.production-api-build
+++ b/jenkins/Jenkinsfile.production-api-build
@@ -88,7 +88,7 @@ pipeline {
            chmod +x scripts/jenkins-prepare-cargo-env.sh
            source scripts/jenkins-prepare-cargo-env.sh
            if ! command -v clang >/dev/null 2>&1 || ! command -v lld >/dev/null 2>&1; then
-              echo "[api-build] 缺少 clang/lld。请先运行 Genarrative-Server-Provision 安装 Linux 构建依赖。" >&2
+              echo "[api-build] 缺少 clang/lld。请在 genarrative-build 节点预先安装 Linux 构建依赖。" >&2
              exit 1
            fi
            if ! command -v sccache >/dev/null 2>&1; then
--- a/jenkins/Jenkinsfile.production-server-provision
+++ b/jenkins/Jenkinsfile.production-server-provision
@@ -7,25 +7,21 @@ pipeline {
    buildDiscarder(logRotator(numToKeepStr: '20', artifactNumToKeepStr: '20'))
  }

-  environment {
-    GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
-    GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
-  }
-
  parameters {
-    choice(name: 'DEPLOY_TARGET', choices: ['development', 'release'], description: '逻辑部署目标；development 使用当前 Linux 开发/构建/开发部署 agent')
+    choice(name: 'DEPLOY_TARGET', choices: ['development', 'release'], description: '逻辑部署目标；development 使用 dev 服务器部署 agent，release 使用正式服务器部署 agent')
    booleanParam(name: 'CONFIRM_RELEASE_DEPLOY_AGENT', defaultValue: false, description: '确认 release 目标已有独立 release 部署 agent')
    string(name: 'NOTIFICATION_EMAILS', defaultValue: '', description: '本次运行追加通知邮箱；会与 Jenkins Secret Text 凭据 genarrative-notification-emails 合并发送')
    booleanParam(name: 'CONFIRM_PROVISION', defaultValue: false, description: '确认执行服务器初始化；未勾选时只允许 dry-run')
    booleanParam(name: 'DRY_RUN', defaultValue: true, description: '只打印将执行的服务器初始化命令，不写入系统配置')
+    string(name: 'SOURCE_GIT_REMOTE_URL', defaultValue: '', description: '部署脚本 Git 来源；必须是目标 agent 可访问的内网/本机 Gitea 地址，不配置公网备用')
    string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '部署脚本来源分支')
    string(name: 'COMMIT_HASH', defaultValue: '', description: '部署脚本来源 commit')
    string(name: 'SERVER_NAME', defaultValue: 'genarrative.example.com', description: '证书主域名；也作为 Nginx server_name 的第一个域名')
    string(name: 'SERVER_ALIASES', defaultValue: '', description: '可选，额外 Nginx server_name，多个用空格或逗号分隔，例如 www.genarrative.world')
-    string(name: 'PROVISION_DOWNLOADS_DIR', defaultValue: 'provision-tool-downloads', description: 'Linux 预下载阶段暂存 SpacetimeDB/otelcol 安装包的工作区相对目录')
+    string(name: 'PROVISION_DOWNLOADS_DIR', defaultValue: 'provision-tool-downloads', description: '目标服务器工作区内暂存 SpacetimeDB/otelcol 安装包的相对目录')
    string(name: 'PROVISION_TOOLS_DIR', defaultValue: 'provision-tools', description: '目标机工作区内由已下载安装包生成的工具包目录')
-    string(name: 'PROVISION_DOWNLOAD_PROXY', defaultValue: '', description: '可选，Linux 预下载阶段下载 SpacetimeDB 和 otelcol-contrib 时使用的代理地址，例如 http://127.0.0.1:7890；留空不设置代理')
-    string(name: 'SPACETIME_DOWNLOAD_ROOT', defaultValue: 'https://github.com/clockworklabs/SpacetimeDB/releases/latest/download', description: 'Linux 预下载阶段使用的 SpacetimeDB Linux release tarball 根地址')
+    string(name: 'PROVISION_DOWNLOAD_PROXY', defaultValue: '', description: '可选，目标服务器下载 SpacetimeDB 和 otelcol-contrib 时使用的代理地址，例如 http://127.0.0.1:7890；留空不设置代理')
+    string(name: 'SPACETIME_DOWNLOAD_ROOT', defaultValue: 'https://github.com/clockworklabs/SpacetimeDB/releases/latest/download', description: '目标服务器使用的 SpacetimeDB Linux release tarball 根地址')
    string(name: 'SPACETIME_TARGET_HOST', defaultValue: 'x86_64-unknown-linux-gnu', description: 'SpacetimeDB 预编译包 host triple，development/release Linux amd64 使用默认值')
    string(name: 'SPACETIME_ROOT', defaultValue: '/stdb', description: 'SpacetimeDB root-dir')
    string(name: 'RELEASE_ROOT', defaultValue: '/opt/genarrative/releases', description: 'release 根目录')
@@ -40,205 +36,160 @@ pipeline {
  }

  stages {
-    stage('Prepare') {
+    stage('Provision Target') {
      agent {
-        label 'linux && genarrative-build'
+        label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-dev-deploy' : 'linux && genarrative-release-deploy'}"
      }
-      steps {
-        script {
-          if (params.DEPLOY_TARGET == 'release' && !params.CONFIRM_RELEASE_DEPLOY_AGENT) {
-            error('release provision 需要先配置独立 release 部署 agent，并勾选 CONFIRM_RELEASE_DEPLOY_AGENT。')
-          }
-          if (!params.DRY_RUN && !params.CONFIRM_PROVISION) {
-            error('执行服务器初始化前必须勾选 CONFIRM_PROVISION；否则请保持 DRY_RUN=true。')
-          }
-          if (!params.SERVER_NAME?.trim()) {
-            error('SERVER_NAME 不能为空。')
-          }
-          if (!(params.SERVER_NAME.trim() ==~ /^[A-Za-z0-9][A-Za-z0-9.-]*$/)) {
-            error("SERVER_NAME 只能填写单个域名或 IP，不能包含空格、路径或协议: ${params.SERVER_NAME}")
-          }
-          def serverAliases = params.SERVER_ALIASES?.trim()
-          if (serverAliases) {
-            serverAliases.split(/[,\s]+/).findAll { it }.each { aliasName ->
-              if (!(aliasName ==~ /^[A-Za-z0-9][A-Za-z0-9.-]*$/)) {
-                error("SERVER_ALIASES 只能填写域名或 IP，多个用空格或逗号分隔: ${aliasName}")
+      stages {
+        stage('Prepare') {
+          steps {
+            script {
+              if (params.DEPLOY_TARGET == 'release' && !params.CONFIRM_RELEASE_DEPLOY_AGENT) {
+                error('release provision 需要先配置独立 release 部署 agent，并勾选 CONFIRM_RELEASE_DEPLOY_AGENT。')
+              }
+              if (!params.DRY_RUN && !params.CONFIRM_PROVISION) {
+                error('执行服务器初始化前必须勾选 CONFIRM_PROVISION；否则请保持 DRY_RUN=true。')
+              }
+              if (!params.SERVER_NAME?.trim()) {
+                error('SERVER_NAME 不能为空。')
+              }
+              def sourceGitRemoteUrl = params.SOURCE_GIT_REMOTE_URL?.trim()
+              if (!sourceGitRemoteUrl) {
+                error('SOURCE_GIT_REMOTE_URL 不能为空。')
+              }
+              def isLocalGitPath = sourceGitRemoteUrl ==~ /^\/[0-9A-Za-z._\/-]+$/
+              def isLocalGitFileUrl = sourceGitRemoteUrl ==~ /^file:\/\/\/\S+$/
+              def isPrivateHttpGitUrl = sourceGitRemoteUrl ==~ /^https?:\/\/(localhost|127(?:\.[0-9]{1,3}){3}|10(?:\.[0-9]{1,3}){3}|192\.168(?:\.[0-9]{1,3}){2}|172\.(?:1[6-9]|2[0-9]|3[0-1])(?:\.[0-9]{1,3}){2}|[A-Za-z0-9-]+|[A-Za-z0-9.-]+\.(?:local|lan|internal))(?::[0-9]+)?\/\S+$/
+              if (!isLocalGitPath && !isLocalGitFileUrl && !isPrivateHttpGitUrl) {
+                error('Genarrative-Server-Provision 不允许使用公网 Git 仓库；SOURCE_GIT_REMOTE_URL 只能是目标 agent 可访问的本机路径、file:/// 地址、localhost/127.0.0.1、RFC1918 内网 HTTP 地址、单标签内网主机名或 .local/.lan/.internal 地址。')
+              }
+              env.EFFECTIVE_GIT_REMOTE_URL = sourceGitRemoteUrl
+              if (!(params.SERVER_NAME.trim() ==~ /^[A-Za-z0-9][A-Za-z0-9.-]*$/)) {
+                error("SERVER_NAME 只能填写单个域名或 IP，不能包含空格、路径或协议: ${params.SERVER_NAME}")
+              }
+              def serverAliases = params.SERVER_ALIASES?.trim()
+              if (serverAliases) {
+                serverAliases.split(/[,\s]+/).findAll { it }.each { aliasName ->
+                  if (!(aliasName ==~ /^[A-Za-z0-9][A-Za-z0-9.-]*$/)) {
+                    error("SERVER_ALIASES 只能填写域名或 IP，多个用空格或逗号分隔: ${aliasName}")
+                  }
+                }
+              }
+              if (!params.PROVISION_TOOLS_DIR?.trim()) {
+                error('PROVISION_TOOLS_DIR 不能为空。')
+              }
+              if (!(params.PROVISION_TOOLS_DIR.trim() ==~ /^[0-9A-Za-z._\/-]+$/) || params.PROVISION_TOOLS_DIR.startsWith('/') || params.PROVISION_TOOLS_DIR.contains('..') || params.PROVISION_TOOLS_DIR.trim() == '.') {
+                error("PROVISION_TOOLS_DIR 只能是工作区内的相对目录，不能包含绝对路径或连续点号: ${params.PROVISION_TOOLS_DIR}")
+              }
+              if (!params.PROVISION_DOWNLOADS_DIR?.trim()) {
+                error('PROVISION_DOWNLOADS_DIR 不能为空。')
+              }
+              if (!(params.PROVISION_DOWNLOADS_DIR.trim() ==~ /^[0-9A-Za-z._\/-]+$/) || params.PROVISION_DOWNLOADS_DIR.startsWith('/') || params.PROVISION_DOWNLOADS_DIR.contains('..') || params.PROVISION_DOWNLOADS_DIR.trim() == '.') {
+                error("PROVISION_DOWNLOADS_DIR 只能是工作区内的相对目录，不能包含绝对路径或连续点号: ${params.PROVISION_DOWNLOADS_DIR}")
+              }
+              def provisionToolsDir = params.PROVISION_TOOLS_DIR.trim()
+              def provisionDownloadsDir = params.PROVISION_DOWNLOADS_DIR.trim()
+              if (provisionToolsDir == provisionDownloadsDir || provisionDownloadsDir.startsWith("${provisionToolsDir}/")) {
+                error("PROVISION_DOWNLOADS_DIR 不能等于或位于 PROVISION_TOOLS_DIR 内，否则目标机生成工具包时会删除下载缓存: ${provisionDownloadsDir}")
+              }
+              def provisionDownloadProxy = params.PROVISION_DOWNLOAD_PROXY?.trim()
+              if (provisionDownloadProxy && !(provisionDownloadProxy ==~ /^https?:\/\/\S+$/)) {
+                error("PROVISION_DOWNLOAD_PROXY 只能填写 http:// 或 https:// 开头的代理地址，当前值: ${params.PROVISION_DOWNLOAD_PROXY}")
+              }
+              if (!(params.OTELCOL_VERSION?.trim() ==~ /^[0-9]+\.[0-9]+\.[0-9]+$/)) {
+                error("OTELCOL_VERSION 格式应为 x.y.z: ${params.OTELCOL_VERSION}")
+              }
+              if (!(params.SPACETIME_DOWNLOAD_ROOT?.trim() ==~ /^https?:\/\/\S+$/)) {
+                error('SPACETIME_DOWNLOAD_ROOT 不能为空。')
+              }
+              if (!(params.SPACETIME_TARGET_HOST?.trim() ==~ /^[0-9A-Za-z._-]+$/)) {
+                error("SPACETIME_TARGET_HOST 只能包含字母、数字、点号、下划线和短横线: ${params.SPACETIME_TARGET_HOST}")
+              }
+              def nginxMode = params.NGINX_CONFIG_MODE?.trim()
+              if (!(nginxMode in ['none', 'production-https', 'development-http'])) {
+                error("NGINX_CONFIG_MODE 只能是 none、production-https 或 development-http，当前值: ${params.NGINX_CONFIG_MODE}")
+              }
+              if (params.DEPLOY_TARGET == 'release' && nginxMode == 'development-http') {
+                error('release 目标禁止安装 development-http Nginx 配置；无证书初始化请使用 NGINX_CONFIG_MODE=none。')
+              }
+              if (!params.DRY_RUN && nginxMode == 'production-https' && params.SERVER_NAME?.trim() == 'genarrative.example.com') {
+                error('真实初始化安装 Nginx 配置时必须把 SERVER_NAME 改成真实域名，不能使用 genarrative.example.com 占位值。证书未准备好时请先保持 NGINX_CONFIG_MODE=none。')
              }
            }
          }
-          if (!params.PROVISION_TOOLS_DIR?.trim()) {
-            error('PROVISION_TOOLS_DIR 不能为空。')
-          }
-          if (!(params.PROVISION_TOOLS_DIR.trim() ==~ /^[0-9A-Za-z._\/-]+$/) || params.PROVISION_TOOLS_DIR.startsWith('/') || params.PROVISION_TOOLS_DIR.contains('..') || params.PROVISION_TOOLS_DIR.trim() == '.') {
-            error("PROVISION_TOOLS_DIR 只能是工作区内的相对目录，不能包含绝对路径或连续点号: ${params.PROVISION_TOOLS_DIR}")
-          }
-          if (!params.PROVISION_DOWNLOADS_DIR?.trim()) {
-            error('PROVISION_DOWNLOADS_DIR 不能为空。')
-          }
-          if (!(params.PROVISION_DOWNLOADS_DIR.trim() ==~ /^[0-9A-Za-z._\/-]+$/) || params.PROVISION_DOWNLOADS_DIR.startsWith('/') || params.PROVISION_DOWNLOADS_DIR.contains('..') || params.PROVISION_DOWNLOADS_DIR.trim() == '.') {
-            error("PROVISION_DOWNLOADS_DIR 只能是工作区内的相对目录，不能包含绝对路径或连续点号: ${params.PROVISION_DOWNLOADS_DIR}")
-          }
-          def provisionToolsDir = params.PROVISION_TOOLS_DIR.trim()
-          def provisionDownloadsDir = params.PROVISION_DOWNLOADS_DIR.trim()
-          if (provisionToolsDir == provisionDownloadsDir || provisionDownloadsDir.startsWith("${provisionToolsDir}/")) {
-            error("PROVISION_DOWNLOADS_DIR 不能等于或位于 PROVISION_TOOLS_DIR 内，否则目标机生成工具包时会删除下载缓存: ${provisionDownloadsDir}")
-          }
-          def provisionDownloadProxy = params.PROVISION_DOWNLOAD_PROXY?.trim()
-          if (provisionDownloadProxy && !(provisionDownloadProxy ==~ /^https?:\/\/\S+$/)) {
-            error("PROVISION_DOWNLOAD_PROXY 只能填写 http:// 或 https:// 开头的代理地址，当前值: ${params.PROVISION_DOWNLOAD_PROXY}")
-          }
-          if (!(params.OTELCOL_VERSION?.trim() ==~ /^[0-9]+\.[0-9]+\.[0-9]+$/)) {
-            error("OTELCOL_VERSION 格式应为 x.y.z: ${params.OTELCOL_VERSION}")
-          }
-          if (!(params.SPACETIME_DOWNLOAD_ROOT?.trim() ==~ /^https?:\/\/\S+$/)) {
-            error('SPACETIME_DOWNLOAD_ROOT 不能为空。')
-          }
-          if (!(params.SPACETIME_TARGET_HOST?.trim() ==~ /^[0-9A-Za-z._-]+$/)) {
-            error("SPACETIME_TARGET_HOST 只能包含字母、数字、点号、下划线和短横线: ${params.SPACETIME_TARGET_HOST}")
-          }
-          def nginxMode = params.NGINX_CONFIG_MODE?.trim()
-          if (!(nginxMode in ['none', 'production-https', 'development-http'])) {
-            error("NGINX_CONFIG_MODE 只能是 none、production-https 或 development-http，当前值: ${params.NGINX_CONFIG_MODE}")
-          }
-          if (params.DEPLOY_TARGET == 'release' && nginxMode == 'development-http') {
-            error('release 目标禁止安装 development-http Nginx 配置；无证书初始化请使用 NGINX_CONFIG_MODE=none。')
-          }
-          if (!params.DRY_RUN && nginxMode == 'production-https' && params.SERVER_NAME?.trim() == 'genarrative.example.com') {
-            error('真实初始化安装 Nginx 配置时必须把 SERVER_NAME 改成真实域名，不能使用 genarrative.example.com 占位值。证书未准备好时请先保持 NGINX_CONFIG_MODE=none。')
-          }
        }
-      }
-    }

-    stage('Prepare Provision Tools') {
-      agent {
-        label 'linux && genarrative-build'
-      }
-      steps {
-        script {
-          def checkoutFromRemote = { String remoteUrl ->
-            checkout([
-              $class: 'GitSCM',
-              branches: [[name: "*/${params.SOURCE_BRANCH}"]],
-              doGenerateSubmoduleConfigurations: false,
-              extensions: [
-                [$class: 'CleanBeforeCheckout'],
-                [$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
-              ],
-              userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
-            ])
-          }
-          try {
-            checkoutFromRemote(env.GIT_REMOTE_URL)
-            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
-          } catch (error) {
-            echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
-            checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
-            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
-          }
-        }
-        sh '''
-          bash <<'BASH'
-            set -euo pipefail
-            chmod +x scripts/jenkins-checkout-source.sh
-            SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
-            COMMIT_HASH="${COMMIT_HASH:-}" \
-            GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
-            GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
-            SOURCE_COMMIT_FILE=".jenkins-source-commit" \
-            scripts/jenkins-checkout-source.sh
+        stage('Checkout Provision Files') {
+          steps {
+            script {
+              checkout([
+                $class: 'GitSCM',
+                branches: [[name: "*/${params.SOURCE_BRANCH}"]],
+                doGenerateSubmoduleConfigurations: false,
+                extensions: [
+                  [$class: 'CleanBeforeCheckout'],
+                  [$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
+                ],
+                userRemoteConfigs: [[url: env.EFFECTIVE_GIT_REMOTE_URL, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
+              ])
+            }
+            sh '''
+              bash <<'BASH'
+                set -euo pipefail
+                chmod +x scripts/jenkins-checkout-source.sh
+                SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
+                COMMIT_HASH="${COMMIT_HASH:-${SOURCE_COMMIT:-}}" \
+                GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL}" \
+                SOURCE_COMMIT_FILE=".jenkins-source-commit" \
+                scripts/jenkins-checkout-source.sh
 BASH
-        '''
-        sh '''
-          bash -lc '
-            set -euo pipefail
-            chmod +x scripts/prepare-server-provision-tools.sh
-            PROVISION_TOOLS_DIR="${PROVISION_TOOLS_DIR:-provision-tools}" \
-            PROVISION_DOWNLOADS_DIR="${PROVISION_DOWNLOADS_DIR:-provision-tool-downloads}" \
-            OTELCOL_VERSION="${OTELCOL_VERSION:-0.151.0}" \
-            PREPARE_OTELCOL="${ENABLE_OTELCOL:-true}" \
-            PROVISION_DOWNLOAD_PROXY="${PROVISION_DOWNLOAD_PROXY:-}" \
-            SPACETIME_DOWNLOAD_ROOT="${SPACETIME_DOWNLOAD_ROOT:-https://github.com/clockworklabs/SpacetimeDB/releases/latest/download}" \
-            SPACETIME_TARGET_HOST="${SPACETIME_TARGET_HOST:-x86_64-unknown-linux-gnu}" \
-            scripts/prepare-server-provision-tools.sh
-          '
-        '''
-        script {
-          env.SOURCE_COMMIT = readFile('.jenkins-source-commit').trim()
-          echo "Provision 工具包源码 commit=${env.SOURCE_COMMIT}"
+            '''
+            script {
+              env.SOURCE_COMMIT = readFile('.jenkins-source-commit').trim()
+              echo "Provision 源码 commit=${env.SOURCE_COMMIT}"
+            }
+          }
        }
-        stash name: 'server-provision-tools', includes: "${params.PROVISION_TOOLS_DIR}/**", useDefaultExcludes: false
-      }
-    }

-    stage('Checkout Provision Files') {
-      agent {
-        label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-build' : 'linux && genarrative-release-deploy'}"
-      }
-      steps {
-        script {
-          def checkoutFromRemote = { String remoteUrl ->
-            checkout([
-              $class: 'GitSCM',
-              branches: [[name: "*/${params.SOURCE_BRANCH}"]],
-              doGenerateSubmoduleConfigurations: false,
-              extensions: [
-                [$class: 'CleanBeforeCheckout'],
-                [$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
-              ],
-              userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
-            ])
-          }
-          try {
-            checkoutFromRemote(env.GIT_REMOTE_URL)
-            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
-          } catch (error) {
-            echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
-            checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
-            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
+        stage('Prepare Provision Tools') {
+          steps {
+            sh '''
+              bash -lc '
+                set -euo pipefail
+                chmod +x scripts/prepare-server-provision-tools.sh
+                PROVISION_TOOLS_DIR="${PROVISION_TOOLS_DIR:-provision-tools}" \
+                PROVISION_DOWNLOADS_DIR="${PROVISION_DOWNLOADS_DIR:-provision-tool-downloads}" \
+                OTELCOL_VERSION="${OTELCOL_VERSION:-0.151.0}" \
+                PREPARE_OTELCOL="${ENABLE_OTELCOL:-true}" \
+                PROVISION_DOWNLOAD_PROXY="${PROVISION_DOWNLOAD_PROXY:-}" \
+                SPACETIME_DOWNLOAD_ROOT="${SPACETIME_DOWNLOAD_ROOT:-https://github.com/clockworklabs/SpacetimeDB/releases/latest/download}" \
+                SPACETIME_TARGET_HOST="${SPACETIME_TARGET_HOST:-x86_64-unknown-linux-gnu}" \
+                scripts/prepare-server-provision-tools.sh
+              '
+            '''
          }
        }
-        sh '''
-          bash <<'BASH'
-            set -euo pipefail
-            chmod +x scripts/jenkins-checkout-source.sh
-            SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
-            COMMIT_HASH="${COMMIT_HASH:-${SOURCE_COMMIT:-}}" \
-            GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
-            GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
-            SOURCE_COMMIT_FILE=".jenkins-source-commit" \
-            scripts/jenkins-checkout-source.sh
-BASH
-        '''
-        script {
-          env.SOURCE_COMMIT = readFile('.jenkins-source-commit').trim()
-          echo "Provision 源码 commit=${env.SOURCE_COMMIT}"
-        }
-      }
-    }

-    stage('Provision Server') {
-      agent {
-        label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-build' : 'linux && genarrative-release-deploy'}"
-      }
-      steps {
-        unstash 'server-provision-tools'
-        sh '''
-          bash <<'BASH'
-            set -euo pipefail
-            if [[ "${ENABLE_OTELCOL:-true}" == "true" ]]; then
-              chmod +x "${PROVISION_TOOLS_DIR:-provision-tools}/otelcol-contrib"
-            fi
-            chmod +x "${PROVISION_TOOLS_DIR:-provision-tools}/spacetime/spacetime" \
-              "${PROVISION_TOOLS_DIR:-provision-tools}/spacetime/bin/current/spacetimedb-cli" \
-              "${PROVISION_TOOLS_DIR:-provision-tools}/spacetime/bin/current/spacetimedb-standalone"
-            chmod +x scripts/jenkins-server-provision.sh
-            PROVISION_TOOLS_DIR="${PROVISION_TOOLS_DIR:-provision-tools}" \
-            SPACETIME_BIN_SOURCE="${PROVISION_TOOLS_DIR:-provision-tools}/spacetime/spacetime" \
-            OTELCOL_BIN_SOURCE="${PROVISION_TOOLS_DIR:-provision-tools}/otelcol-contrib" \
-            scripts/jenkins-server-provision.sh
+        stage('Provision Server') {
+          steps {
+            sh '''
+              bash <<'BASH'
+                set -euo pipefail
+                if [[ "${ENABLE_OTELCOL:-true}" == "true" ]]; then
+                  chmod +x "${PROVISION_TOOLS_DIR:-provision-tools}/otelcol-contrib"
+                fi
+                chmod +x "${PROVISION_TOOLS_DIR:-provision-tools}/spacetime/spacetime" \
+                  "${PROVISION_TOOLS_DIR:-provision-tools}/spacetime/bin/current/spacetimedb-cli" \
+                  "${PROVISION_TOOLS_DIR:-provision-tools}/spacetime/bin/current/spacetimedb-standalone"
+                chmod +x scripts/jenkins-server-provision.sh
+                PROVISION_TOOLS_DIR="${PROVISION_TOOLS_DIR:-provision-tools}" \
+                SPACETIME_BIN_SOURCE="${PROVISION_TOOLS_DIR:-provision-tools}/spacetime/spacetime" \
+                OTELCOL_BIN_SOURCE="${PROVISION_TOOLS_DIR:-provision-tools}/otelcol-contrib" \
+                scripts/jenkins-server-provision.sh
 BASH
-        '''
+            '''
+          }
+        }
      }
    }
  }
@@ -253,9 +204,7 @@ BASH
          string(name: 'SOURCE_RESULT', value: currentBuild.currentResult ?: 'UNKNOWN'),
          string(name: 'SOURCE_BRANCH', value: params.SOURCE_BRANCH ?: ''),
          string(name: 'SOURCE_COMMIT', value: env.SOURCE_COMMIT ?: (params.COMMIT_HASH ?: '')),
-          string(name: 'BUILD_VERSION', value: env.EFFECTIVE_BUILD_VERSION ?: (params.BUILD_VERSION ?: '')),
          string(name: 'DEPLOY_TARGET', value: params.DEPLOY_TARGET ?: ''),
-          string(name: 'DATABASE', value: params.DATABASE ?: ''),
          string(name: 'SUMMARY', value: '服务器初始化流水线结束'),
        ]
        def notificationRecipients = params.NOTIFICATION_EMAILS?.trim()
--- a/scripts/jenkins-prepare-cargo-env.sh
+++ b/scripts/jenkins-prepare-cargo-env.sh
@@ -28,7 +28,7 @@ if [[ -z "${RUSTUP_HOME:-}" && -n "${ORIGINAL_HOME}" && -d "${ORIGINAL_HOME}/.ru
 fi

 # HOME 会在下面切到组件级缓存目录，因此这里先把真实用户的 Rust 工具链目录补进 PATH。
-# Server-Provision 通过 cargo install 安装的 sccache 通常会落在 /root/.cargo/bin。
+# Jenkins 构建节点预装的 Rust 工具和 sccache 通常会落在 /root/.cargo/bin。
 for tool_dir in "${ORIGINAL_HOME}/.cargo/bin" /root/.cargo/bin /usr/local/cargo/bin; do
  if [[ -d "${tool_dir}" && ":${PATH}:" != *":${tool_dir}:"* ]]; then
    export PATH="${tool_dir}:${PATH}"
--- a/scripts/jenkins-server-provision.sh
+++ b/scripts/jenkins-server-provision.sh
@@ -56,6 +56,18 @@ run_cmd() {
  fi
 }

+require_root_for_real_provision() {
+  if [[ "${DRY_RUN}" == "true" ]]; then
+    return
+  fi
+
+  if [[ "$(id -u)" != "0" ]]; then
+    echo "[server-provision] 非 dry-run 会安装系统包、写入 systemd/Nginx 和创建系统用户，必须在 root agent 上执行。" >&2
+    echo "[server-provision] 当前用户: $(id -un) uid=$(id -u)。请确认 DEPLOY_TARGET=${DEPLOY_TARGET:-} 对应的目标服务器 agent 以 root 运行，或保持 DRY_RUN=true。" >&2
+    exit 1
+  fi
+}
+
 install_file() {
  local source="$1"
  local target="$2"
@@ -66,21 +78,6 @@ install_file() {
  fi
 }

-install_build_dependencies() {
-  echo "[server-provision] 安装 Linux 构建依赖: clang, lld, pkg-config, OpenSSL headers"
-  if command -v apt-get >/dev/null 2>&1; then
-    run_cmd apt-get update
-    run_cmd apt-get install -y clang lld pkg-config libssl-dev ca-certificates
-  elif command -v dnf >/dev/null 2>&1; then
-    run_cmd dnf install -y clang lld pkgconf-pkg-config openssl-devel ca-certificates
-  elif command -v yum >/dev/null 2>&1; then
-    run_cmd yum install -y clang lld pkgconf-pkg-config openssl-devel ca-certificates
-  else
-    echo "[server-provision] 未找到 apt-get/dnf/yum，无法自动安装 clang/lld。请手动安装后重跑构建。" >&2
-    exit 1
-  fi
-}
-
 install_nginx_brotli_modules() {
  echo "[server-provision] 安装 Nginx Brotli 动态模块依赖"
  if command -v apt-get >/dev/null 2>&1; then
@@ -90,41 +87,6 @@ install_nginx_brotli_modules() {
  fi
 }

-install_sccache() {
-  for tool_dir in "${HOME:-}/.cargo/bin" /root/.cargo/bin /usr/local/cargo/bin; do
-    if [[ -d "${tool_dir}" && ":${PATH}:" != *":${tool_dir}:"* ]]; then
-      export PATH="${tool_dir}:${PATH}"
-    fi
-  done
-
-  if command -v sccache >/dev/null 2>&1; then
-    echo "[server-provision] sccache 已存在: $(command -v sccache)"
-    return
-  fi
-
-  if [[ -x /root/.cargo/bin/sccache ]]; then
-    echo "[server-provision] sccache 已存在: /root/.cargo/bin/sccache"
-    return
-  fi
-
-  echo "[server-provision] 未找到 sccache，准备通过 cargo install sccache 安装。"
-  if [[ "${DRY_RUN}" == "true" ]]; then
-    echo "+ cargo install sccache --locked"
-    return
-  fi
-
-  if ! command -v cargo >/dev/null 2>&1; then
-    echo "[server-provision] 未找到 cargo，无法自动安装 sccache。请先安装 Rust 工具链后重跑 Server-Provision。" >&2
-    exit 1
-  fi
-
-  cargo install sccache --locked
-  if ! command -v sccache >/dev/null 2>&1 && [[ ! -x /root/.cargo/bin/sccache ]]; then
-    echo "[server-provision] sccache 安装后仍不可用，请检查 cargo bin 目录是否在 PATH 中。" >&2
-    exit 1
-  fi
-}
-
 sync_otelcol_install() {
  local target_bin="/usr/local/bin/otelcol-contrib"
  local source_bin="${OTELCOL_BIN_SOURCE}"
@@ -142,7 +104,7 @@ sync_otelcol_install() {

  if [[ ! -x "${resolved_source}" ]]; then
    echo "[server-provision] otelcol-contrib 不存在或不可执行: ${source_bin}" >&2
-    echo "[server-provision] 请先在构建机准备好 otelcol-contrib ${version}，再通过 provision-tools 上传到目标机。" >&2
+    echo "[server-provision] 请确认 Prepare Provision Tools 已在目标 agent 生成 otelcol-contrib ${version}: ${source_bin}" >&2
    exit 1
  fi

@@ -671,9 +633,8 @@ require_non_root_relative_path "PROVISION_TOOLS_DIR" "${PROVISION_TOOLS_DIR}"
 echo "[server-provision] target=${DEPLOY_TARGET}, dry_run=${DRY_RUN}, nginx_config_mode=${NGINX_CONFIG_MODE}, source_commit=$(cat .jenkins-source-commit)"

 run_cmd id
-install_build_dependencies
+require_root_for_real_provision
 install_nginx_brotli_modules
-install_sccache
 run_cmd mkdir -p "${SPACETIME_ROOT}" "${RELEASE_ROOT}" "$(dirname "${CURRENT_LINK}")" "$(dirname "${WEB_LINK}")" /etc/genarrative /var/lib/genarrative/maintenance /var/lib/genarrative/auth /var/lib/genarrative/tracking-outbox /var/lib/genarrative/database-backups

 if ! id spacetimedb >/dev/null 2>&1; then