From 84eccfe8cb82ad024fbab878b8c11df418d4ff96 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Tue, 19 May 2026 18:49:20 +0800
Subject: [PATCH] fix(jenkins): run server provision downloads on windows

---
 .hermes/shared-memory/decision-log.md          |  3 ++-
 .hermes/shared-memory/pitfalls.md              |  8 ++++++++
 ...€å�‘è¿�维】本地开å�‘验è¯�与生产è¿�ç»´-2026-05-15.md |  2 +-
 .../Jenkinsfile.production-server-provision    | 18 +++++++++++++++---
 4 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/.hermes/shared-memory/decision-log.md b/.hermes/shared-memory/decision-log.md
index 9896b079..02a76a14 100644
--- a/.hermes/shared-memory/decision-log.md
+++ b/.hermes/shared-memory/decision-log.md
@@ -91,8 +91,9 @@
 
 - 背景：当� `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` �下载 SpacetimeDB 官方安装脚本�Linux update installer 和 `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 脚本被立��写时触� `拒�访问`。
 - 影�范围：`jenkins/Jenkinsfile.production-server-provision`�`scripts/prepare-server-provision-tools.sh`�`scripts/jenkins-server-provision.sh`�生产�维文档。
-- 验�方�：Jenkins 日志应先出现 Windows 节点的 `[prepare-provision-downloads]` 下载日志，�在 `genarrative-build-01` 上出现“使用已下载的 ...�日志；目标机�应出现直接访问 `install.spacetimedb.com` 或 OpenTelemetry GitHub release 下载地�的回退日志。
+- 验�方�：Jenkins 日志应先出现 Windows 节点的 `[jenkins-powershell] workspace:`�`[jenkins-powershell] loaded bytes:` 和 `[prepare-provision-downloads]` 下载日志，�在 `genarrative-build-01` 上出现“使用已下载的 ...�日志；目标机�应出现直接访问 `install.spacetimedb.com` 或 OpenTelemetry GitHub release 下载地�的回退日志。
 - 关�文档：`docs/�开��维】本地开�验�与生产�维-2026-05-15.md`。
 
 ## 2026-05-19 公开 gallery 入��布��以快拒��护�端
diff --git a/.hermes/shared-memory/pitfalls.md b/.hermes/shared-memory/pitfalls.md
index 46f4448f..cf2a4b9f 100644
--- a/.hermes/shared-memory/pitfalls.md
+++ b/.hermes/shared-memory/pitfalls.md
@@ -1032,6 +1032,14 @@
 - 验�：检查 Jenkins build log 中是�出现 `[jenkins-powershell] user:` 和 `[jenkins-powershell] exe:`，以� `[stdb-checkout] current HEAD:`。上游 Full Build 传下�的 `COMMIT_HASH` 若已等于当� GitSCM checkout，日志应显示 `requested commit already matches Jenkins GitSCM checkout` 并继续进入构建阶段；�时确认 `builds/<n>/log` ���在 `PipelineNodeTreeScanner... Cannot run program "powershell"` 或 Checkout 内部 exit code 5。
 - 关�：`jenkins/Jenkinsfile.production-stdb-module-build`�`docs/�开��维】本地开�验�与生产�维-2026-05-15.md`。
 
+## Server-Provision Windows 下载 helper ��原地�写临时 ps1
+
+- 现象：`Genarrative-Server-Provision` 的 Windows 下载阶段已�打�了 `[jenkins-powershell] user:` 和 `[jenkins-powershell] exe:`，但在 `.ps1` 原地 BOM �写���然返回 `exit code 5` / `拒�访问`，且下载目录还没创建。
+- 原因：Jenkins `writeFile` 生�的临时 `.ps1` 正被�一个 workspace 里的 PowerShell 进程马上�写� BOM 文件，这个原地改写在本地 Windows Jenkins 环境里比直接脚本执行更容易碰到 workspace �用或 ACL 拒�。对这��水线�说，BOM �是必须的执行�件。
+- 处�：`runWindowsPowerShell(...)` 改�先 `writeFile`，�由显� `powershell.exe` 读�脚本文本并用 `ScriptBlock::Create(...)` 直接在内存中执行，��对�一个 `.ps1` � BOM �写。Windows 下载脚本里先把 `PROVISION_DOWNLOADS_DIR` 归一到 workspace �对路径，并补 `Windows workspace` / `download dir` / `已创建下载目录` 三段日志，方便区分是路径问题还是下载问题。
+- 验�：Jenkins log 应先出现 `[jenkins-powershell] workspace:`�`[jenkins-powershell] loaded bytes:`，�出现 `[prepare-provision-downloads] Windows workspace:` 和 `[prepare-provision-downloads] 已创建下载目录:`；如果下载 URL 故�指到��达地�，应该�在 `curl 下载失败` 处结�，而�是�在 BOM �写�。
+- 关�：`jenkins/Jenkinsfile.production-server-provision`�`docs/�开��维】本地开�验�与生产�维-2026-05-15.md`。
+
 ## QQ �览器�现页推���全�显示先查 aspect-ratio 兜底
 
 - 现象：�现页的“推���频�作��标题�作者和数�正常，但所有��图�显示，常�于 QQ �览器 / X5 等旧移动内核。
diff --git a/docs/�开��维】本地开�验�与生产�维-2026-05-15.md b/docs/�开��维】本地开�验�与生产�维-2026-05-15.md
index be4285e1..8ed3324b 100644
--- a/docs/�开��维】本地开�验�与生产�维-2026-05-15.md
+++ b/docs/�开��维】本地开�验�与生产�维-2026-05-15.md
@@ -160,7 +160,7 @@ Windows Stdb module 构建�水线�行在 Jenkins `windows` 节点上。该
 - `api-server` 生产模�默认 `GENARRATIVE_API_LISTEN_BACKLOG=1024`�`GENARRATIVE_API_WORKER_THREADS=4`；本地未设置 worker threads 时继续使用 Tokio 默认值。
 - `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` ��该�制。这些值�是 RPS �速；如果压测中 429 上�但内存和 p95 收敛，说明背压正在�护进程。直连 `api-server` 的�高 RPS 压测若出现 `connection refused`，通常已�打到 TCP 监� / accept 层，应�时检查 backlog�Nginx upstream keepalive 和�置��。
 - `genarrative-api.service` 设置 `LimitNOFILE=65535`�`TasksMax=2048`；上线�用 `systemctl show genarrative-api.service -p LimitNOFILE -p TasksMax` 和 `cat /proc/$(pidof api-server)/limits` 核对。
-- Server provision �在目标机�网下载 SpacetimeDB 或 `otelcol-contrib`。`Genarrative-Server-Provision` 先在 Windows Jenkins 节点执行 `Download Provision Tool Archives`，把 `https://install.spacetimedb.com`�SpacetimeDB Linux update installer 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz` 先下载到工作区，�通过 `stash/unstash` 带到 `genarrative-build-01`；目标 Linux 节点上的 `scripts/prepare-server-provision-tools.sh` �消费这些本地下载件生� `provision-tools/`，�交给 `scripts/jenkins-server-provision.sh` 安装 `/stdb/spacetime`�`/stdb/bin/current/*` 和 `/usr/local/bin/otelcol-contrib`。注� `scripts/jenkins-checkout-source.sh` 会执行 `git reset --hard` / `git clean`，因此被直接执行的新增脚本必须以 Git `100755` 模��交，或在二次 checkout 之��补 `chmod +x`。
+- Server provision �在目标机�网下载 SpacetimeDB 或 `otelcol-contrib`。`Genarrative-Server-Provision` 先在 Windows Jenkins 节点执行 `Download Provision Tool Archives`，把 `https://install.spacetimedb.com`�SpacetimeDB Linux update installer 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz` 先下载到工作区，�通过 `stash/unstash` 带到 `genarrative-build-01`；目标 Linux 节点上的 `scripts/prepare-server-provision-tools.sh` �消费这些本地下载件生� `provision-tools/`，�交给 `scripts/jenkins-server-provision.sh` 安装 `/stdb/spacetime`�`/stdb/bin/current/*` 和 `/usr/local/bin/otelcol-contrib`。Windows 侧的 `runWindowsPowerShell(...)` 现在会先 `writeFile` 生� UTF-8 `.ps1`，�直接把脚本文本读入内存并通过 `ScriptBlock::Create(...)` 执行，��对�一个 workspace 脚本�原地 BOM �写；因此排查时除了看下载日志，还�看 `[jenkins-powershell] workspace:`�`[jenkins-powershell] script:` 和 `[jenkins-powershell] loaded bytes:`。注� `scripts/jenkins-checkout-source.sh` 会执行 `git reset --hard` / `git clean`，因此被直接执行的新增脚本必须以 Git `100755` 模��交，或在二次 checkout 之��补 `chmod +x`。
 - Windows 下载阶段如果走代�，在 `Genarrative-Server-Provision` �数 `PROVISION_DOWNLOAD_PROXY` 填写 Windows Jenkins 节点�访问的 HTTP 代�，例如 `http://127.0.0.1:7890`；��填写目标 release 机器视角的 `127.0.0.1`，除�代�确实�行在该 Windows 节点本机。Linux 目标机阶段会强制�求使用本地下载件，缺少文件直接失败，��回退到外网下载。
 - `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`。压测时看 `/var/log/nginx/genarrative.access.log` 中的 `request_time`�`upstream_connect_time`�`upstream_header_time`�`upstream_response_time`�`upstream_status`�`request_id`。
diff --git a/jenkins/Jenkinsfile.production-server-provision b/jenkins/Jenkinsfile.production-server-provision
index c324b3e0..e95ef581 100644
--- a/jenkins/Jenkinsfile.production-server-provision
+++ b/jenkins/Jenkinsfile.production-server-provision
@@ -11,10 +11,13 @@ if not exist "%GENARRATIVE_POWERSHELL%" (
 )
 echo [jenkins-powershell] user:
 whoami
+echo [jenkins-powershell] workspace: %CD%
 echo [jenkins-powershell] exe: %GENARRATIVE_POWERSHELL%
-"%GENARRATIVE_POWERSHELL%" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command "\$path = '%CD%\\${scriptPath}'; \$text = [System.IO.File]::ReadAllText(\$path, [System.Text.Encoding]::UTF8); \$utf8Bom = New-Object System.Text.UTF8Encoding(\$true); [System.IO.File]::WriteAllText(\$path, \$text, \$utf8Bom)"
-if errorlevel 1 exit /b %ERRORLEVEL%
-"%GENARRATIVE_POWERSHELL%" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "%CD%\\${scriptPath}"
+if not exist "%CD%\\${scriptPath}" (
+  echo [jenkins-powershell] script not found: %CD%\\${scriptPath}
+  exit /b 1
+)
+"%GENARRATIVE_POWERSHELL%" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command "try { \$path = Join-Path (Get-Location).ProviderPath '${scriptPath}'; Write-Host '[jenkins-powershell] script:' \$path; \$text = [System.IO.File]::ReadAllText(\$path, [System.Text.Encoding]::UTF8); Write-Host '[jenkins-powershell] loaded bytes:' ([System.IO.File]::ReadAllBytes(\$path).Length); \$scriptBlock = [ScriptBlock]::Create(\$text); & \$scriptBlock; if (\$LASTEXITCODE -is [int] -and \$LASTEXITCODE -ne 0) { exit \$LASTEXITCODE } } catch { Write-Host '[jenkins-powershell] failed:' \$_.Exception.Message; if (\$_.ScriptStackTrace) { Write-Host \$_.ScriptStackTrace }; exit 1 }"
 exit /b %ERRORLEVEL%
 """
 }
@@ -153,11 +156,20 @@ pipeline {
             $spacetimeDownloadRoot = if ($env:SPACETIME_DOWNLOAD_ROOT) { $env:SPACETIME_DOWNLOAD_ROOT.TrimEnd('/') } else { 'https://github.com/clockworklabs/SpacetimeDB/releases/latest/download' }
             $spacetimeTargetHost = if ($env:SPACETIME_TARGET_HOST) { $env:SPACETIME_TARGET_HOST } else { 'x86_64-unknown-linux-gnu' }
             $downloadProxy = if ($env:PROVISION_DOWNLOAD_PROXY) { $env:PROVISION_DOWNLOAD_PROXY } else { '' }
+            $workspace = (Get-Location).ProviderPath
+            if ([System.IO.Path]::IsPathRooted($downloadsDir)) {
+              throw "[prepare-provision-downloads] PROVISION_DOWNLOADS_DIR �能是工作区内相对路径: ${downloadsDir}"
+            }
+            $downloadsDir = Join-Path $workspace $downloadsDir
+            Write-Host "[prepare-provision-downloads] Windows workspace: ${workspace}"
+            Write-Host "[prepare-provision-downloads] download dir: ${downloadsDir}"
 
             if (Test-Path -LiteralPath $downloadsDir) {
+              Write-Host "[prepare-provision-downloads] 清�旧下载目录: ${downloadsDir}"
               Remove-Item -LiteralPath $downloadsDir -Recurse -Force
             }
             New-Item -ItemType Directory -Force -Path $downloadsDir | Out-Null
+            Write-Host "[prepare-provision-downloads] 已创建下载目录: ${downloadsDir}"
 
             if ($downloadProxy) {
               $env:HTTP_PROXY = $downloadProxy