GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity
Files
5b96265c5029280c0db35b0289be3e2df73678d5
Genarrative/docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md

50 KiB
Raw Blame History

生产部署计划

更新时间：2026-05-02

当前落地进度

已落地生产基础设施骨架与首批生产 Jenkinsfile：

  • deploy/systemd/spacetimedb.service
  • deploy/systemd/genarrative-api.service
  • deploy/nginx/genarrative.conf
  • deploy/nginx/genarrative-dev-http.conf
  • deploy/nginx/snippets/genarrative-maintenance.conf
  • deploy/env/api-server.env.example
  • scripts/deploy/maintenance-on.sh
  • scripts/deploy/maintenance-off.sh
  • scripts/deploy/maintenance-status.sh
  • scripts/build-production-release.sh
  • scripts/jenkins-checkout-source.sh
  • scripts/jenkins-server-provision.sh
  • scripts/deploy/production-web-deploy.sh
  • scripts/deploy/production-api-deploy.sh
  • scripts/deploy/production-stdb-publish.sh
  • jenkins/Jenkinsfile.production-web-build
  • jenkins/Jenkinsfile.production-web-deploy
  • jenkins/Jenkinsfile.production-api-build
  • jenkins/Jenkinsfile.production-api-deploy
  • jenkins/Jenkinsfile.production-stdb-module-build
  • jenkins/Jenkinsfile.production-stdb-module-publish
  • jenkins/Jenkinsfile.production-full-build-and-deploy
  • jenkins/Jenkinsfile.production-server-provision
  • jenkins/Jenkinsfile.production-database-export
  • jenkins/Jenkinsfile.production-database-import
  • jenkins/Jenkinsfile.production-notify-email
  • npm run build:production-release

旧 Jenkins 一体化发布链对应的 Jenkinsfile 已从仓库移除，生产构建和发布入口统一切到 jenkins/Jenkinsfile.production-*。scripts/deploy-rust-remote.sh 等旧发布包脚本暂保留为历史迁移参考，不再作为生产 Jenkins Job 的入口。

目标

将当前部署方式调整为单机生产推荐方案：生产运行路径不使用 Docker，不再使用旧的一体化启动脚本，由 systemd 托管 SpacetimeDB 与 Rust api-server，由 Nginx 托管主站、后台前端与必要反向代理。

本计划用于重新创建 Jenkins 流水线、服务器环境配置、网站发布、api-server 发布、SpacetimeDB 模块发布，以及数据库人工导入导出流程。

生产架构

  • Nginx 作为唯一公网入口，负责 HTTPS、静态站点、后台静态页面、维护页、/admin/api/ 反向代理，以及临时兼容期的主站 /api/* 反向代理。
  • SpacetimeDB 作为系统服务运行，监听 127.0.0.1:3101，数据根目录为 /stdb。3000 保留给部署机本机 Git/Web 服务，禁止再让 SpacetimeDB 占用该端口。
  • Rust api-server 作为系统服务运行，监听 127.0.0.1:8082。当前临时兼容期仍允许 Nginx 将主站 /api/* 与 /admin/api/ 反向代理到该服务；前端完成 SpacetimeDB SDK / bindings 直连迁移后，再删除公网 /api/* 反代。
  • 主站与后台前端构建为静态文件，发布到服务器固定目录，不放入 Jenkins 目录，也不跟随 Docker 镜像。
  • 除网站静态发布外，api-server 发布、SpacetimeDB 模块发布、数据库导入、服务器配置变更都必须先进入维护模式。

服务器目录

  • /opt/genarrative/releases/<version>/：每次发布的完整版本目录。
  • /opt/genarrative/current：指向当前生效版本的软链接。
  • /srv/genarrative/web：指向 /opt/genarrative/current/web，供 Nginx 托管静态站点。
  • /etc/genarrative/api-server.env：api-server 生产环境变量文件。
  • /var/lib/genarrative/maintenance/enabled：维护模式开关文件。
  • /stdb：SpacetimeDB 程序、配置与数据根目录。

生产密钥

/etc/genarrative/api-server.env 中的生产密钥指所有只能存在于生产服务器、不能进入 Git、不能进入构建产物的敏感配置。典型内容包括：

  • LLM 或第三方服务 API Key。
  • 短信服务 Access Key 与 Secret。
  • 后台登录、会话、签名、加密相关密钥。
  • 生产 SpacetimeDB 地址与数据库名。
  • 只允许生产使用的回调地址、白名单或内部令牌。

该文件由服务器配置流水线或人工初始化创建，权限建议为 root:genarrative、0640。Jenkins 构建任务不能读取该文件；只有生产发布或服务启动需要读取。

systemd 服务

SpacetimeDB

  • 服务名：spacetimedb.service
  • 运行用户：spacetimedb
  • 工作目录：/stdb
  • 启动命令：/stdb/spacetime --root-dir=/stdb start --listen-addr=127.0.0.1:3101
  • 对外暴露：默认不直接暴露公网端口。

该方案与 SpacetimeDB 官方自托管文档一致：使用 Ubuntu、专用用户、/stdb 根目录、systemd 服务和 Nginx。

api-server

  • 服务名：genarrative-api.service
  • 运行用户：genarrative
  • 工作目录：/opt/genarrative/current
  • 可执行文件：/opt/genarrative/current/api-server
  • 环境文件：/etc/genarrative/api-server.env
  • 监听地址：127.0.0.1:8082

api-server 不放入 Docker，也不直接暴露公网端口。发布时替换版本目录并重启 genarrative-api.service。

全量发布流水线的 DATABASE 参数必须同时传给 Stdb 发布和 API 发布：Stdb 发布负责把 wasm 发布到目标数据库，API 发布必须在重启 genarrative-api.service 前把同一个库名写入 /etc/genarrative/api-server.env 的 GENARRATIVE_SPACETIME_DATABASE，并同步 GENARRATIVE_SPACETIME_SERVER_URL。否则 api-server 会继续读取环境文件中的旧库名，出现 wasm 已发布到新库但 HTTP facade 仍访问旧库的错位。

API 发布阶段只使用上游 API 构建产物，不应回退到上游源码 commit 执行部署脚本；部署脚本应始终取 SOURCE_BRANCH 最新提交。否则全量流水线在修复部署脚本后仍可能按旧 COMMIT_HASH checkout，继续执行不认识新参数的旧版 production-api-deploy.sh。

服务器配置流水线

Genarrative-Server-Provision 的 Jenkinsfile 只负责参数、节点路由与调用脚本；服务器配置主体逻辑放在 scripts/jenkins-server-provision.sh。不要再把数百行 Bash 内联进 Jenkins sh ''' ... ''' 或 bash -lc '...'，否则 Jenkins/Groovy/sh/bash 多层转义会把 \"、${...}、sed 表达式等内容二次改写，容易在运行时出现 syntax error near unexpected token '}' 这类难定位错误。

该脚本负责安装构建依赖、同步 SpacetimeDB current 目录、安装 systemd/Nginx 配置、创建或保留 /etc/genarrative/api-server.env、维护模式配置以及首次服务启动前的 SpacetimeDB client token 初始化。修改后应至少执行：

bash -n scripts/jenkins-server-provision.sh
git diff --check

Nginx 规则

生产正式入口只保留必要路由：

  • /：主站静态页面。
  • /admin/：后台前端静态页面，后台构建时使用 /admin/ 作为 base path。
  • /admin/api/：反向代理到 http://127.0.0.1:8082/admin/api/。
  • /api 与 /api/*：临时反向代理到 http://127.0.0.1:8082，保留原始请求 URI，用于兼容当前主站前端仍在使用的 HTTP facade。
  • HTTP 到 HTTPS：production-https 模式只保留 301 重定向。
  • /maintenance.html：维护中页面。

当前仍需移除这些公网反向代理：

  • /generated-*
  • 公网 /healthz
  • 其他旧的一体化 web server 代理入口。

/api/* 仅作为临时兼容债务保留，不代表生产长期 API 暴露策略。后续主站前端完成 SpacetimeDB SDK / bindings 接入后，必须从 Nginx 模板中删除 /api 与 /api/* 反代，并恢复其公网 404 行为。

SpacetimeDB 公网路由默认保持收敛，只按实际前端 SDK 需要暴露最小集合。禁止开放可远程发布数据库或管理实例的通用入口。

Nginx 配置文件分为两类：

  • deploy/nginx/genarrative.conf：生产正式域名 HTTPS 配置，genarrative.example.com 只是占位域名，安装时必须替换为真实 SERVER_NAME，并要求 /etc/letsencrypt/live/<SERVER_NAME>/fullchain.pem 与 privkey.pem 已存在。SERVER_NAME 只填证书主目录名对应的单个域名；www 等额外域名通过 SERVER_ALIASES 写入 Nginx server_name，不参与证书目录拼接。
  • deploy/nginx/genarrative-dev-http.conf：开发服无域名时的 HTTP-only 配置，只允许 DEPLOY_TARGET=development 使用。没有域名时，SERVER_NAME 填开发机 IP 或临时主机名；如有多个入口，额外域名或 IP 填 SERVER_ALIASES。它仍复用同一套静态目录、后台 API 反代、临时主站 /api/* 反代和 SpacetimeDB SDK 最小公网路由，不恢复旧 /generated-* 或公网 /healthz。

维护模式

维护模式由 /var/lib/genarrative/maintenance/enabled 控制：

  • 文件存在：进入维护模式。
  • 文件不存在：退出维护模式。

行为：

  • 网站静态资源发布不进入维护模式。
  • api-server 发布、SpacetimeDB 模块发布、数据库导入、服务器配置变更必须进入维护模式。
  • 普通页面在维护模式下展示 /maintenance.html。
  • /admin/api/* 在维护模式下返回 503。
  • /v1/database/<database>/subscribe 与 /v1/identity 在维护模式下返回 503，阻断已打开前端继续通过 SpacetimeDB SDK 访问运行时数据。
  • 静态资源仍允许访问，避免维护页样式和资源加载失败。
  • 发布成功后自动解除维护模式。
  • 发布失败时保持维护模式，并通过邮件通知人工处理。

构建产物

生产发布包构建入口：

npm run build:production-release -- --name <version>

每次构建产物按版本号归档：

build/<version>/
├─ web/
│  ├─ index.html
│  ├─ assets/
│  ├─ maintenance.html
│  └─ admin/
├─ web.tar.gz
├─ web.tar.gz.sha256
├─ api-server
├─ api-server.sha256
├─ spacetime_module.wasm
├─ spacetime_module.wasm.sha256
├─ release-manifest.json
├─ scripts/
│  ├─ database-export.mjs
│  ├─ database-import.mjs
│  ├─ spacetime-migration-common.mjs
│  ├─ maintenance-on.sh
│  ├─ maintenance-off.sh
│  └─ maintenance-status.sh
├─ deploy/
│  ├─ systemd/
│  │  ├─ spacetimedb.service
│  │  └─ genarrative-api.service
│  ├─ nginx/
│  │  ├─ genarrative.conf
│  │  ├─ genarrative-dev-http.conf
│  │  └─ snippets/genarrative-maintenance.conf
│  └─ env/api-server.env.example
└─ README.md

web/ 可以保留在构建目录中供本地 smoke test 与人工排查使用。Web Build 必须生成 web.tar.gz 与 web.tar.gz.sha256，但 web.tar.gz 不作为 Jenkins controller 默认归档对象，避免每次把约数百 MB 的 Web 大包从 Linux agent 拉回本地 controller。Web 大包保存在构建机稳定目录 /var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/，Jenkins 只归档 web.tar.gz.sha256、release-manifest.json 与 web-artifact-pointer.txt。api-server 和 spacetime_module.wasm 是单文件产物，默认直接归档单文件与对应 .sha256，不强制压缩。

不再生成旧产物：

  • web-server.mjs
  • 旧的一体化 start.sh
  • 旧的一体化 stop.sh

Jenkins 节点

Jenkins 可运行在 Windows 或其他机器上，本机 Windows 只作为人工触发入口；构建与发布动作只允许由 Jenkins 调度到 Linux agent 执行。当前已接入的 Linux agent 是开发/构建机，同时也是 development 环境部署机。

开发/构建/开发部署实例

  • Jenkins Job 参数不暴露真实节点名、IP 或带 IP 的标签。
  • 构建 Job 固定使用 label expression：linux && genarrative-build。
  • 当前开发/构建/开发部署 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 的开发环境部署。

生产/发布实例

  • Jenkins Job 参数不暴露真实节点名、IP 或带 IP 的标签。
  • 生产机已作为独立 Linux Jenkins agent 接入，节点名使用脱敏名称 genarrative-release-deploy-01，调度标签只使用 linux 与 genarrative-release-deploy。
  • 生产机 agent 启动方式统一改为 inbound agent + systemd 自守护，不再依赖 Jenkins controller 通过 SSH launcher 长期拉起。SSH 只作为首次登录和安装 systemd 服务的运维通道。
  • 生产机真实连接地址只允许保存在 Jenkins 节点连接配置或人工运维 SSH 配置中，不能写入节点名、调度标签、Job 参数默认值或文档推荐命令。
  • 发布 Job 通过 DEPLOY_TARGET 选择逻辑部署目标，再在 Jenkinsfile 内部映射到 Linux-only 脱敏调度表达式：development -> linux && genarrative-build，release -> linux && genarrative-release-deploy。
  • 用途：服务器配置、发布静态网站、发布 api-server、发布 SpacetimeDB 模块、数据库导入导出、维护模式切换。

Jenkins inbound agent 自恢复

构建 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-build-01.service、jenkins-agent@genarrative-release-deploy-01.service。
  • systemd 自身 WorkingDirectory 保持 /var/lib/jenkins/agent/<node-name>；Jenkins remoting -workDir 可按节点拆分，例如构建机使用 /root/jenkins-agent-build、发布机继续使用旧 SSH agent 的 /root/jenkins-agent，避免多 agent 共用 remoting 根目录，同时减少发布机迁移时 workspace 和缓存路径漂移。
  • inbound secret 只能放在目标机 /etc/jenkins-agent/<node-name>.secret 或等价 Secret Text 注入位置，不能提交到 Git，也不能写入 Jenkinsfile 默认参数。
  • systemd unit 使用 Restart=always 和 RestartSec=10；agent Java 进程退出、网络短断或机器重启后由 systemd 自动恢复，不需要人工盯着 Jenkins 页面手动重启。
  • 当前 Genarrative-Server-Provision 仍负责 systemd、Nginx、/opt/genarrative、/etc/genarrative 等特权写入，因此 inbound agent 默认仍按现有 root 执行口径迁移。若后续改为 jenkins 用户运行 agent，必须先把生产流水线需要的特权命令收敛为精确 NOPASSWD sudoers 白名单。

如果 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 <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 连接。

首次迁移示例：

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-build \
  --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 \
  --jenkins-url http://127.0.0.1:18080/ \
  --secret-file /etc/jenkins-agent/genarrative-release-deploy-01.secret \
  --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@*.service' -f

如果 Jenkins controller 暂时仍配置为 SSH launcher，只能作为过渡方案使用：需要把 SSH launch timeout 拉长、增加 retry 和 retry wait、固定 Java 路径，并确认 ssh user@host 'java -version' 稳定返回。最终仍要切到 inbound + systemd，避免 SSH 连接卡住时阻塞发布队列。

Git 仓库访问

Jenkins controller 与 Linux agent 看到的 Git 服务地址不同，必须拆成两层配置：

  • Jenkins Job 的 Pipeline script from SCM 由 controller 执行，SCM URL 使用 controller 可访问的公网域名：https://git.genarrative.world/GenarrativeAI/Genarrative.git。
  • Jenkinsfile 内部的源码、脚本 checkout 在 Linux agent 上执行，GIT_REMOTE_URL 优先使用 agent 本机可访问地址：http://127.0.0.1:3000/GenarrativeAI/Genarrative.git。
  • 若 127.0.0.1 Git 服务在当前 Linux agent 上不可达，发布、数据库和服务器配置类 Jenkinsfile 会用 GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git 重新 checkout。该首次 checkout 只拉 SOURCE_BRANCH 单分支、depth=1 且不拉 tags，避免 release agent 通过公网备用地址拉取全仓库历史时被 Jenkins Git checkout timeout 杀掉；scripts/jenkins-checkout-source.sh 后续 fetch 也会按主地址、域名备用地址顺序重试，并在日志中输出最终使用的远端。
  • 这里的 3000 是 Git/Web 服务端口，不是 SpacetimeDB 端口；生产 SpacetimeDB 固定使用 http://127.0.0.1:3101，避免流水线部署时与本机 Git 服务抢端口。

因此生产 Jenkinsfile 不使用 checkout scm 作为构建源码入口，而是显式 checkout([$class: 'GitSCM', userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/<SOURCE_BRANCH>:refs/remotes/origin/<SOURCE_BRANCH>"]], ...])。首次 checkout 先尝试 GIT_REMOTE_URL，失败后尝试 GIT_REMOTE_FALLBACK_URL，两次都必须保持单分支浅克隆和 noTags=true；后续 scripts/jenkins-checkout-source.sh 会继续把 origin 设置为实际可用远端，并按 SOURCE_BRANCH / COMMIT_HASH 拉取和校验目标提交。

127.0.0.1 只代表当前执行该阶段的 Linux agent 自身；如果 release agent 与 Git 服务不在同一台机器，GIT_REMOTE_FALLBACK_URL 统一使用 https://git.genarrative.world/GenarrativeAI/Genarrative.git，不要再配置内网 IP 备用地址。

SSH PEM 凭证

在 Jenkins 中使用 SSH Username with private key 类型添加 PEM 私钥：

  • genarrative-dev-ssh-key：开发/构建实例 SSH 凭证。
  • genarrative-prod-root-ssh：当前开发/构建实例已使用的 SSH 凭证；生产/发布实例复用同一个凭证。

推荐使用非 root 用户，例如 jenkins。该用户只通过 sudoers 获得必要命令权限，例如 systemctl restart genarrative-api、nginx -t、维护脚本、发布目录切换等。

Jenkins 流水线

生产 Jenkins 目标流水线：

  1. Genarrative-Server-Provision
  2. Genarrative-Web-Build
  3. Genarrative-Web-Deploy
  4. Genarrative-Api-Build
  5. Genarrative-Api-Deploy
  6. Genarrative-Stdb-Module-Build
  7. Genarrative-Stdb-Module-Publish
  8. Genarrative-Database-Export
  9. Genarrative-Database-Import
  10. Genarrative-Full-Build-And-Deploy
  11. Genarrative-Notify-Email

已落地的生产流水线脚本文件：

  • jenkins/Jenkinsfile.production-web-build
  • jenkins/Jenkinsfile.production-web-deploy
  • jenkins/Jenkinsfile.production-api-build
  • jenkins/Jenkinsfile.production-api-deploy
  • jenkins/Jenkinsfile.production-stdb-module-build
  • jenkins/Jenkinsfile.production-stdb-module-publish
  • jenkins/Jenkinsfile.production-full-build-and-deploy
  • jenkins/Jenkinsfile.production-server-provision
  • jenkins/Jenkinsfile.production-database-export
  • jenkins/Jenkinsfile.production-database-import
  • jenkins/Jenkinsfile.production-notify-email

Genarrative-Database-Export、Genarrative-Database-Import 的生产版 Jenkinsfile 已落地；旧的数据库导入导出 Jenkinsfile 已删除，避免继续沿用旧部署目录和旧一体化发布链假设。

构建流水线运行在当前 Linux agent 的脱敏 label expression linux && genarrative-build。发布、导入导出和服务器配置流水线通过 DEPLOY_TARGET 映射到 Linux-only 脱敏部署表达式；其中 development 映射到当前 Linux 开发/构建/开发部署 agent 的 linux && genarrative-build，release 映射到独立 Linux 生产部署 agent 的 linux && genarrative-release-deploy，不能复用当前开发/构建/开发部署 agent。真实机器名、IP 和带 IP 的 Jenkins label 只允许留在 Jenkins 节点连接配置中，不能暴露为 Job 参数默认值、调度标签或文档推荐值。

发布流水线通过 Jenkins copyArtifacts(...) 从对应构建 Job 获取归档产物，因此 Jenkins 需要安装并启用 Copy Artifact 插件。Web 大包例外：Genarrative-Web-Build 只把轻量元数据归档到 Jenkins controller，web.tar.gz 保留在 Linux 构建机稳定目录 /var/cache/genarrative-build/web-artifacts/，Genarrative-Web-Deploy 在部署目标机器上按构建 Job、构建号和版本号读取该目录。development 目标天然共享当前 Linux 开发/构建/开发部署机；release 目标若不是同一台机器，必须先把该目录通过共享存储、rsync 或其它内网同步方式提供给 release 部署 agent。数据库导入流水线的手动上传模式使用 stashedFile 文件参数，因此 Jenkins 还需要安装并启用 File Parameter 插件。所有生产 Pipeline 日志必须带时间戳以便审计，Jenkins 需要安装 Timestamper 插件，并在全局配置中启用 Enabled for all Pipeline builds。邮件通知流水线使用 Jenkins Pipeline mail step，Jenkins 需要安装/启用 Mailer 能力，并在系统配置中配置 SMTP。生产发布不能退回到读取构建 workspace 本地目录的旧模式。

邮件通知的持久收件人不写入 Git，由 Jenkins Secret text 凭据 genarrative-notification-emails 保存，凭据内容为逗号分隔邮箱。所有生产流水线仍提供 NOTIFICATION_EMAILS 参数作为本次运行的追加收件人；通知 Job 会把持久收件人凭据与本次 NOTIFICATION_EMAILS 合并去重后发送，参数留空时只发送给持久收件人。流水线结束时在 post { always { ... } } 中异步触发 Genarrative-Notify-Email，把来源 Job、构建号、构建 URL、结果、源码分支、源码 commit、发布版本、部署目标和数据库名传给通知 Job。通知 Job 失败不能反向改变业务流水线结果，只在来源流水线日志中记录触发失败。

持久收件人在 Jenkins controller 的 Manage Jenkins -> Credentials -> System -> Global credentials 中新增 Secret text 凭据，ID 固定为 genarrative-notification-emails，Secret 填 ops@example.com,dev@example.com 这类逗号分隔邮箱。SMTP 服务器在 Manage Jenkins -> System 的 E-mail Notification 区域配置。邮件地址属于 Jenkins 持久化配置，不作为仓库文件提交。

所有发布流水线必须提供 DEPLOY_TARGET 参数，用于选择逻辑部署目标：

  • 默认值：development，用于当前 Linux 开发/构建/开发部署 agent 上的开发环境部署，对应脱敏调度表达式 linux && genarrative-build。
  • 备选值：release，对应生产发布目标，由独立 Linux 生产部署 agent 执行。

发布流水线的 agent 必须使用 DEPLOY_TARGET 在 Jenkinsfile 内部映射到脱敏 label expression，并且表达式必须包含 linux，避免在参数页面暴露真实节点名、IP 或带 IP 的 Jenkins label，也避免非 Linux 节点执行构建或部署。release 目标还必须要求 CONFIRM_RELEASE_DEPLOY_AGENT=true。Genarrative-Full-Build-And-Deploy 也必须透传同一个 DEPLOY_TARGET，确保 Stdb publish、API deploy、Web deploy 三个部署动作落到同一类目标部署环境。

Rust 构建缓存与磁盘控制

Jenkins 在 agent 上执行构建时会为不同 Job 或不同构建创建独立 workspace；Rust 默认把编译产物写入仓库内 server-rs/target/，会导致每个 workspace 都保留一份完整 target 目录，占用大量磁盘。生产构建流水线必须把 Rust 缓存固定到 workspace 外的稳定目录。

如果构建 agent 使用 root 账户执行，缓存目录不应写死为 /var/lib/jenkins。推荐优先使用单独数据盘，例如 /data/jenkins-cache/genarrative/；如果没有数据盘，可使用 /var/cache/genarrative-build/：

mkdir -p /var/cache/genarrative-build/{api-server,stdb-module}
chmod 700 /var/cache/genarrative-build

API 构建流水线建议设置：

environment {
  CARGO_HOME = '/var/cache/genarrative-build/api-server/cargo-home'
  CARGO_TARGET_DIR = '/var/cache/genarrative-build/api-server/cargo-target/prod-release'
  CARGO_INCREMENTAL = '0'

  RUSTC_WRAPPER = 'sccache'
  SCCACHE_DIR = '/var/cache/genarrative-build/api-server/sccache'
  SCCACHE_CACHE_SIZE = '30G'
}

Stdb module 构建流水线建议设置：

environment {
  CARGO_HOME = '/var/cache/genarrative-build/stdb-module/cargo-home'
  CARGO_TARGET_DIR = '/var/cache/genarrative-build/stdb-module/cargo-target/prod-release'
  CARGO_INCREMENTAL = '0'

  RUSTC_WRAPPER = 'sccache'
  SCCACHE_DIR = '/var/cache/genarrative-build/stdb-module/sccache'
  SCCACHE_CACHE_SIZE = '30G'
}

如使用数据盘，则把上述路径替换为：

environment {
  CARGO_HOME = '/data/jenkins-cache/genarrative/<component>/cargo-home'
  CARGO_TARGET_DIR = '/data/jenkins-cache/genarrative/<component>/cargo-target/prod-release'
  CARGO_INCREMENTAL = '0'

  RUSTC_WRAPPER = 'sccache'
  SCCACHE_DIR = '/data/jenkins-cache/genarrative/<component>/sccache'
  SCCACHE_CACHE_SIZE = '30G'
}

其中 <component> 使用 api-server 或 stdb-module。API 与 Stdb module 并行构建时不能共享同一个 CARGO_HOME 或 CARGO_TARGET_DIR，否则容易在 Cargo package cache 或 target 目录上出现 Blocking waiting for file lock on package cache 等锁等待。

Rust 构建流水线还必须在真正执行 cargo 前 source scripts/jenkins-prepare-cargo-env.sh。该脚本会把 HOME 临时切到组件级缓存目录，显式导出组件级 CARGO_HOME、CARGO_TARGET_DIR、SCCACHE_DIR，并在 ${CARGO_HOME}/config.toml 写入可用的 Cargo sparse registry 配置。这样可以避免构建 agent 使用 root 账户时继续读取 /root/.cargo/config 中失效的全局镜像配置，例如错误的 replace-with = "tuna" 导致 config.json not found in registry。

server-rs/.cargo/config.toml 只保留 Linux release 目标的 linker/rustflags 等仓库级构建配置，不在仓库级 config.toml 里重定义 agent 全局镜像源。不要把这些约束写到单个 crate 的 Cargo.toml，因为 Cargo 不会从 crate manifest 的 [target.x86_64-unknown-linux-gnu] 读取构建器配置。

由于 server-rs/.cargo/config.toml 使用 clang 与 -fuse-ld=lld 构建 Linux release 目标，构建 agent 必须安装 clang 和 lld。Genarrative-Server-Provision 负责通过 apt-get、dnf 或 yum 安装 clang、lld、pkg-config/pkgconf-pkg-config、OpenSSL headers 与 CA 证书；同时负责在缺失时通过 cargo install sccache --locked 补齐 sccache，让 API/Stdb 构建流水线的 RUSTC_WRAPPER=sccache 真正生效。API/Stdb 构建流水线在执行 Cargo 前必须检查 clang 与 lld，缺失时直接失败并提示先运行 Server-Provision。

scripts/build-production-release.sh 必须尊重 CARGO_TARGET_DIR，不能硬编码从 server-rs/target/ 拷贝 Rust 产物。脚本中的产物路径应按以下口径计算：

CARGO_TARGET_DIR="${CARGO_TARGET_DIR:-${SERVER_RS_DIR}/target}"
API_BINARY_SOURCE="${CARGO_TARGET_DIR}/x86_64-unknown-linux-gnu/release/api-server"
WASM_SOURCE="${CARGO_TARGET_DIR}/wasm32-unknown-unknown/release/spacetime_module.wasm"

并发与清理规则：

  • 同一个 Rust 构建 Job 建议使用 disableConcurrentBuilds()，避免同一组件的多个 release 构建同时写入同一最终产物路径。
  • 如果 Linux/Windows agent 未安装 sccache，或 sccache --version 无法实际执行，应先补齐缓存工具；Rust 构建流水线仍必须自动取消 RUSTC_WRAPPER，回退到直接使用 rustc，不能因为缺少可选缓存工具阻断真实构建。
  • 生产发布流水线只能消费 build/<version>/ 或 Jenkins 归档产物，不允许从共享 cargo-target 目录直接发布。
  • SCCACHE_CACHE_SIZE 必须设置上限，避免编译缓存无限增长。
  • 对 /var/cache/genarrative-build/*/cargo-target 或数据盘对应目录配置定期清理，建议保留最近 14 到 30 天。
  • Jenkins Job 必须配置构建记录和归档产物保留策略，避免历史 release 包长期堆积。

统一源码版本参数

所有构建流水线、发布流水线和 Genarrative-Full-Build-And-Deploy 都必须支持以下参数：

  • SOURCE_BRANCH：源码分支，默认 master，代表 origin/master 最新提交。
  • COMMIT_HASH：可选 Git commit hash，留空时使用 origin/<SOURCE_BRANCH> 最新 commit；填写时必须是 7 到 40 位十六进制 hash，并且该 commit 必须属于 origin/<SOURCE_BRANCH>。
  • DEPLOY_TARGET：逻辑部署目标选择参数。发布流水线和 Genarrative-Full-Build-And-Deploy 必填；构建流水线仅在 PUBLISH_AFTER_BUILD=true 时用于触发下游发布。

执行规则：

  • 流水线先按 Jenkins SCM 配置 checkout 仓库，再执行单分支 git fetch --no-tags --prune origin "+refs/heads/<SOURCE_BRANCH>:refs/remotes/origin/<SOURCE_BRANCH>"；COMMIT_HASH 为空时追加 --depth=1。
  • 如果工作区是浅克隆，只有在 COMMIT_HASH 非空、需要验证指定提交属于目标分支时，流水线才尝试 git fetch --unshallow --no-tags。COMMIT_HASH 为空时只需要目标分支 HEAD，必须保持 --depth=1 --no-tags，避免普通发布或服务器配置任务拉取全仓库历史。
  • COMMIT_HASH 为空时，detached checkout 到 refs/remotes/origin/<SOURCE_BRANCH> 当前最新 commit。
  • COMMIT_HASH 非空时，先解析到完整 commit，再用 git merge-base --is-ancestor <commit> refs/remotes/origin/<SOURCE_BRANCH> 校验该提交属于指定分支，校验通过后 detached checkout。
  • 流水线日志必须输出最终 SOURCE_BRANCH 与实际 SOURCE_COMMIT。
  • 构建产物必须写入 release-manifest.json，至少包含 version、source_branch、source_commit、built_at 和组件类型，供发布、回滚和审计使用。
  • Windows 构建 Job 写入 .jenkins-source-commit 时必须使用 UTF-8 无 BOM；部署脚本在校验 COMMIT_HASH 前也会剥离 UTF-8 BOM 和 CRLF，避免上游 PowerShell 5.1 Set-Content -Encoding UTF8 产生的不可见 BOM 让下游发布误判 commit hash 非法。

构建流水线使用上述参数决定实际构建源码。发布流水线也暴露同名参数，但只用于选择本次发布使用的部署脚本、配置模板和 smoke test 逻辑；被发布的应用文件仍必须来自 Jenkins 归档产物或指定 release 包，不允许在发布流水线中重新构建。

当构建流水线以 PUBLISH_AFTER_BUILD=true 触发下游发布流水线时，必须把 SOURCE_BRANCH 和实际解析出的 SOURCE_COMMIT 作为下游 COMMIT_HASH 传递，确保部署逻辑和刚生成的产物可追溯到同一源码版本。

构建流水线支持参数 PUBLISH_AFTER_BUILD：

  • false：只构建并归档产物。
  • true：构建成功后触发对应发布流水线。

发布流水线必须从归档产物获取文件，不依赖构建 workspace 的本地状态。

流水线职责

Genarrative-Server-Provision

用于生产服务器一次性或低频配置：

  • 创建 spacetimedb、genarrative 等系统用户。
  • 创建 /stdb、/opt/genarrative、/srv/genarrative、/etc/genarrative、/var/lib/genarrative/maintenance。
  • 安装或更新 SpacetimeDB。
  • 安装 SpacetimeDB 时不能只复制 /usr/local/bin/spacetime wrapper，还必须把 spacetimedb-cli 与 spacetimedb-standalone 同步到 <SPACETIME_ROOT>/bin/current/。否则 spacetime --root-dir=<SPACETIME_ROOT> start 会回调缺失的 <SPACETIME_ROOT>/bin/current/spacetimedb-cli，导致 spacetimedb.service 循环重启但 provision 表面已经执行过 systemctl restart。
  • 安装 systemd unit。
  • 可选安装 Nginx 配置和维护模式 snippet。
  • 安装 Nginx 配置时执行 nginx -t，通过后必须执行 nginx -s reload，确保新配置对当前 Nginx master/worker 生效。
  • 启用并启动 spacetimedb.service 与 genarrative-api.service；重启 spacetimedb.service 后必须等待 http://127.0.0.1:3101/v1/ping 确认就绪，不能只依赖 systemctl restart 的返回码。<SPACETIME_ROOT> 下所有运行态文件必须归属 spacetimedb:spacetimedb。不要在 root 身份下对同一个 <SPACETIME_ROOT> 执行 spacetime --root-dir=<SPACETIME_ROOT> server ping，否则会生成 root-owned CLI 配置，导致 spacetimedb 服务用户后续启动时遇到权限错误。
  • 首次初始化时，如果 /etc/genarrative/api-server.env 里还没有 GENARRATIVE_SPACETIME_TOKEN，流水线会在 spacetimedb.service 就绪后调用本机 POST http://127.0.0.1:3101/v1/identity 生成 client identity/token，只把 token 写入环境文件，并只在日志里显示 identity 前缀。随后流水线会以 spacetimedb 用户执行 <SPACETIME_ROOT>/bin/current/spacetimedb-cli --root-dir <SPACETIME_ROOT> login --token [REDACTED]，确保后续首次 Stdb publish 使用同一个 client identity 创建数据库；这个 identity 才会成为后台读取 private 表所需的 owner。若环境文件已有 GENARRATIVE_SPACETIME_TOKEN，初始化必须保留该值，只同步 CLI 登录态，不重新生成或覆盖。

该流水线属于高风险操作，默认要求人工确认后执行。 已落地的 Jenkinsfile 为 jenkins/Jenkinsfile.production-server-provision。该流水线默认 DRY_RUN=true，只打印将执行的初始化动作；真正写入系统用户、目录、systemd、环境文件并启动服务时，必须设置 DRY_RUN=false 且勾选 CONFIRM_PROVISION。当 DEPLOY_TARGET=release 时，还必须勾选 CONFIRM_RELEASE_DEPLOY_AGENT，并通过 linux && genarrative-release-deploy 调度到独立 release 部署 agent。

首次真实初始化默认保持 NGINX_CONFIG_MODE=none，先完成系统用户、目录、SpacetimeDB、systemd unit 与 /etc/genarrative/api-server.env 落盘。开发服没有域名时，使用 DEPLOY_TARGET=development + NGINX_CONFIG_MODE=development-http 安装 deploy/nginx/genarrative-dev-http.conf，并把 SERVER_NAME 填为开发机 IP 或临时主机名。等正式域名确定，并且目标机已经存在 /etc/letsencrypt/live/<SERVER_NAME>/fullchain.pem 与 /etc/letsencrypt/live/<SERVER_NAME>/privkey.pem 后，再把 SERVER_NAME 改成证书主域名，并设置 NGINX_CONFIG_MODE=production-https 安装 Nginx HTTPS 配置。如果同一张证书同时覆盖根域名和 www 域名，SERVER_NAME 仍只填证书目录名，例如 genarrative.world，SERVER_ALIASES 填 www.genarrative.world。流水线会拒绝 release 目标安装 development-http，也会拒绝用占位域名或缺失证书安装 production-https。Nginx 配置写入后必须先 nginx -t，再 nginx -s reload，不能只验证配置而不重载当前进程。

若误用占位域名执行过真实初始化，失败通常发生在 nginx -t，错误表现为找不到 /etc/letsencrypt/live/genarrative.example.com/fullchain.pem 或 privkey.pem。新版初始化在 NGINX_CONFIG_MODE=none 时会检测并禁用上一轮留下的占位域名 Nginx 配置，避免它继续影响后续 nginx -t。

Web Build / Deploy

构建：

  • 先按 SOURCE_BRANCH / COMMIT_HASH 解析并 checkout 目标源码，默认构建 origin/master 最新 commit。
  • 默认执行 npm ci 安装前端依赖，确保 Jenkins 新 workspace 中存在 vite 等构建工具。
  • 构建主站静态文件。
  • 构建后台前端，base path 为 /admin/。
  • 生成或复制 maintenance.html。
  • 将 web/ 打包为 web.tar.gz，生成 web.tar.gz.sha256。
  • 将 web.tar.gz、web.tar.gz.sha256 和 release-manifest.json 复制到 /var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/；Jenkins 只归档 web.tar.gz.sha256、release-manifest.json 和 web-artifact-pointer.txt，不把 web.tar.gz 拉回 controller。

发布：

  • 先按 SOURCE_BRANCH / COMMIT_HASH 解析并 checkout 部署脚本源码，默认使用 origin/master 最新 commit；上游构建触发时使用上游传入的实际构建 commit。
  • 通过 Jenkins 归档获取 web.tar.gz.sha256、release-manifest.json 和 web-artifact-pointer.txt，再从 /var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/ 读取 web.tar.gz；先校验 checksum，再解压到 /opt/genarrative/releases/<version>/web。
  • 更新 /opt/genarrative/current 与 /srv/genarrative/web 指向。
  • 执行 Nginx 配置测试和静态页面 smoke test。
  • 不进入维护模式。

Api Build / Deploy

构建：

  • 先按 SOURCE_BRANCH / COMMIT_HASH 解析并 checkout 目标源码，默认构建 origin/master 最新 commit。
  • 编译 Rust api-server。
  • 归档单一可执行文件、必要运行说明和 release-manifest.json。

发布：

  • 先按 SOURCE_BRANCH / COMMIT_HASH 解析并 checkout 部署脚本源码，默认使用 origin/master 最新 commit；上游构建触发时使用上游传入的实际构建 commit。
  • 进入维护模式。
  • 解包到 /opt/genarrative/releases/<version>/api-server。
  • 更新 /opt/genarrative/current。
  • 重启 genarrative-api.service。
  • 检查本机 /healthz。
  • 导出产物归档成功后解除维护模式。
  • 失败时保留维护模式并发邮件。

Stdb Module Build / Publish

构建：

  • 先按 SOURCE_BRANCH / COMMIT_HASH 解析并 checkout 目标源码，默认构建 origin/master 最新 commit。
  • 构建 spacetime_module.wasm 前默认生成 32 字节随机 hex 迁移引导密钥，注入 GENARRATIVE_SPACETIME_MIGRATION_BOOTSTRAP_SECRET，并把同一份密钥写入 build/<version>/migration-bootstrap-secret.txt。构建日志只输出密钥来源和长度，不打印明文。
  • Genarrative-Stdb-Module-Build 提供 MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID 参数：留空时自动生成新密钥；填写 Jenkins Secret Text 凭据 ID 时，构建环境注入 GENARRATIVE_SPACETIME_MIGRATION_BOOTSTRAP_SECRET 并复用该值。仅在明确传 --no-migration-bootstrap-secret 时才构建不带引导密钥的 wasm。
  • 使用 Rust wasm target 构建 spacetime_module.wasm。
  • 归档 wasm、migration-bootstrap-secret.txt 和 release-manifest.json。migration-bootstrap-secret.txt 属于敏感产物，只用于创建首个迁移操作员或录入数据库导入/导出流水线的 BOOTSTRAP_SECRET_CREDENTIAL_ID 指向的 Jenkins Secret Text；授权完成后不要把明文留在公开归档或聊天记录中。

发布：

  • 先按 SOURCE_BRANCH / COMMIT_HASH 解析并 checkout 发布脚本源码，默认使用 origin/master 最新 commit；上游构建触发时使用上游传入的实际构建 commit。
  • 进入维护模式。
  • 将 wasm 上传到生产实例。
  • 在生产实例本机执行 spacetime --root-dir=/stdb publish <database-name> --server http://127.0.0.1:3101 --bin-path spacetime_module.wasm --yes --no-config。
  • 发布动作默认以 spacetimedb 服务用户执行，避免 root 默认 CLI 身份对自托管数据库验签失败，也避免 root 写入 /stdb/config 造成后续服务用户启动权限错误。
  • Stdb publish 固定追加 --no-config，只依赖显式传入的 --root-dir、--server、--bin-path 与数据库名，避免 agent 工作区、本机用户目录或仓库内 spacetime 配置干扰发布目标。
  • 首次迁移操作员授权时，使用本次 Stdb module 构建归档的 migration-bootstrap-secret.txt 创建 Jenkins Secret Text，然后在 Genarrative-Database-Export / Genarrative-Database-Import 的 BOOTSTRAP_SECRET_CREDENTIAL_ID 中填写该凭据 ID。后续已有迁移操作员时优先改用 TOKEN_CREDENTIAL_ID。
  • 成功后执行必要 smoke test。
  • 成功后解除维护模式。
  • 失败时保留维护模式并发邮件。

Full Build-And-Deploy

  • 先解析一次最终 SOURCE_COMMIT，所有下游构建和发布都使用同一个分支与 commit。
  • 并行执行 Web / API / Stdb 三条构建流水线。
  • 并行构建阶段必须开启 fail-fast：任一构建流水线失败时，立即中断其他仍在执行的并行构建分支，本次全量编排不再继续进入发布阶段。
  • 构建全部成功后，按顺序执行 Stdb publish、API deploy、Web deploy，并把同一个 DEPLOY_TARGET 透传给三条发布流水线。
  • Stdb publish 同时透传 SPACETIME_SERVER_URL、SPACETIME_ROOT_DIR 与 SPACETIME_RUN_AS_USER，默认分别为 http://127.0.0.1:3101、/stdb、spacetimedb。
  • 每条下游构建都只消费自己的归档产物，不直接复用别的 workspace。
  • 生产 Web 发布只处理 web.tar.gz 与 checksum，API 发布只处理 api-server 与 checksum，Stdb 发布只处理 spacetime_module.wasm 与 checksum。

数据库导出与导入

导出

Genarrative-Database-Export 用于人工导出生产数据：

  • 已落地 Jenkinsfile：jenkins/Jenkinsfile.production-database-export。
  • 通过 DEPLOY_TARGET 选择逻辑导出目标；development 映射到 linux && genarrative-build，release 映射到 linux && genarrative-release-deploy。
  • release 导出必须勾选 CONFIRM_RELEASE_DEPLOY_AGENT，避免当前开发/构建/开发部署 agent 冒充 release 部署机。
  • 进入维护模式，避免导出期间继续写入。
  • 从目标机器本机 SpacetimeDB 导出指定数据库数据，默认连接 SPACETIME_SERVER_URL=http://127.0.0.1:3101，自托管 root-dir 默认 /stdb。
  • 产物归档到 Jenkins，并可额外保存到 SERVER_BACKUP_DIRECTORY。
  • 敏感 token 与 bootstrap secret 只通过 Jenkins Secret Text 凭据 ID 注入，不作为明文 Job 参数。
  • 导出和导入流水线的 Bash 执行块启用 set -u；所有可选 Jenkins 参数必须先通过 ${VAR:-} 收敛成本地默认值，再传给 Node 迁移脚本，避免空参数没有导出时触发 unbound variable。
  • 成功后解除维护模式。
  • 失败时保留维护模式并邮件通知。

导入

Genarrative-Database-Import 用于人工导入或恢复数据：

  • 已落地 Jenkinsfile：jenkins/Jenkinsfile.production-database-import。
  • 通过 DEPLOY_TARGET 选择逻辑导入目标；development 映射到 linux && genarrative-build，release 映射到 linux && genarrative-release-deploy。
  • release 导入必须勾选 CONFIRM_RELEASE_DEPLOY_AGENT，避免当前开发/构建/开发部署 agent 冒充 release 部署机。
  • 通过 INPUT_SOURCE 选择数据源，pipeline_archive 从 Genarrative-Database-Export 归档复制 INPUT_FILE，manual_upload 使用本次构建上传的 MANUAL_INPUT_FILE；两种方式互斥，Prepare 阶段会直接拦截混填。
  • DRY_RUN 默认开启；真正写入数据时必须勾选 CONFIRM_IMPORT，并让 CONFIRM_DATABASE 与 CONFIRM_INPUT_FILE 分别完全匹配 DATABASE 与实际输入文件。
  • REPLACE_EXISTING=true 且 DRY_RUN=false 时必须额外勾选 CONFIRM_REPLACE_EXISTING。
  • 进入维护模式。
  • 导入前先生成一次安全备份。
  • 执行导入。
  • 执行数据校验和服务 smoke test。
  • 成功后解除维护模式。
  • 失败时保留维护模式并邮件通知。
  • pipeline_archive 模式默认使用导出流水线 Genarrative-Database-Export；只需要填写 EXPORT_BUILD_NUMBER_TO_IMPORT 时，归档输入路径自动解析为 database-exports/spacetime-migration-<导出构建号>.json。如果导出时覆盖过 WORKSPACE_EXPORT_DIRECTORY 或 EXPORT_NAME，再显式填写归档内相对路径 INPUT_FILE。
  • manual_upload 模式需要上传 MANUAL_INPUT_FILE，并在 CONFIRM_INPUT_FILE 中填写原始文件名；此模式不再填写 EXPORT_BUILD_NUMBER_TO_IMPORT 或 INPUT_FILE，EXPORT_JOB_NAME 的默认值会被忽略。
  • 敏感 token 与 bootstrap secret 只通过 Jenkins Secret Text 凭据 ID 注入，不作为明文 Job 参数。

数据库表结构变更必须同步检查并更新 migration.rs，不能只发布 wasm。

全量构建并发布

Genarrative-Full-Build-And-Deploy 编排：

  1. 按 SOURCE_BRANCH / COMMIT_HASH 解析一次最终 SOURCE_COMMIT，默认 origin/master 最新 commit。
  2. 并行触发 Genarrative-Web-Build、Genarrative-Api-Build、Genarrative-Stdb-Module-Build，三条构建都必须使用同一个 SOURCE_BRANCH 和 SOURCE_COMMIT；并行阶段开启 fail-fast，任一构建失败就中断其他仍在执行的构建分支。
  3. 三条构建全部成功后，按顺序触发 Genarrative-Stdb-Module-Publish、Genarrative-Api-Deploy、Genarrative-Web-Deploy，同样继续透传同一个 SOURCE_BRANCH、SOURCE_COMMIT 和 DEPLOY_TARGET。
  4. 最后执行生产 smoke test。

网站最后发布，避免后台或主站提前指向尚未完成发布的后端能力。

这种编排能够在不牺牲版本一致性的前提下缩短总耗时，同时避免 Web / API / Stdb 彼此等待构建资源。并行构建时仍要保证每条构建流水线独立归档自己的产物，发布阶段只能消费归档结果，不能回到构建 workspace 重新取文件。

Genarrative-Full-Build-And-Deploy 额外作为定时任务运行，Jenkins 在每天凌晨 4 点自动触发一次，默认按 SOURCE_BRANCH=master 解析最新提交，并以 DEPLOY_TARGET=development 把全量构建结果部署到开发机。该定时任务不改写手动触发参数语义，只是给主线全量发布补一个固定的夜间全量刷新入口。

回滚

  • 网站回滚：将 /srv/genarrative/web 或 /opt/genarrative/current 切回上一版本并 reload Nginx。
  • api-server 回滚：将 /opt/genarrative/current 切回上一版本并重启 genarrative-api.service。
  • SpacetimeDB 模块回滚：发布上一版本 spacetime_module.wasm。
  • 数据回滚：使用导入流水线恢复指定备份，必须进入维护模式。

待落地文件

后续工程落地时需要新增或改造：

  • deploy/systemd/spacetimedb.service
  • deploy/systemd/genarrative-api.service
  • deploy/systemd/jenkins-agent@.service
  • deploy/nginx/genarrative.conf
  • deploy/nginx/genarrative-dev-http.conf
  • deploy/nginx/snippets/genarrative-maintenance.conf
  • deploy/env/api-server.env.example
  • scripts/deploy/maintenance-on.sh
  • scripts/deploy/maintenance-off.sh
  • scripts/deploy/maintenance-status.sh
  • scripts/deploy/jenkins-local-controller-watchdog.ps1
  • scripts/deploy/jenkins-agent-reverse-tunnel.ps1
  • scripts/deploy/jenkins-inbound-agent-start.sh
  • scripts/deploy/install-jenkins-inbound-agent.sh
  • scripts/build-production-release.sh
  • scripts/jenkins-checkout-source.sh
  • scripts/deploy/production-web-deploy.sh
  • scripts/deploy/production-api-deploy.sh
  • scripts/deploy/production-stdb-publish.sh
  • jenkins/Jenkinsfile.production-web-build
  • jenkins/Jenkinsfile.production-web-deploy
  • jenkins/Jenkinsfile.production-api-build
  • jenkins/Jenkinsfile.production-api-deploy
  • jenkins/Jenkinsfile.production-stdb-module-build
  • jenkins/Jenkinsfile.production-stdb-module-publish
  • jenkins/Jenkinsfile.production-full-build-and-deploy
  • jenkins/Jenkinsfile.production-server-provision
  • 删除旧 Jenkinsfile：Jenkinsfile.build-and-deploy、Jenkinsfile.deploy、Jenkinsfile.database-export、Jenkinsfile.database-import
  • 更新旧部署文档，标记旧一体化脚本为废弃或迁移对象。
  • jenkins/Jenkinsfile.production-database-export
  • jenkins/Jenkinsfile.production-database-import
  • jenkins/Jenkinsfile.production-notify-email
  • 所有生产流水线通过 NOTIFICATION_EMAILS 参数在结束时触发 Genarrative-Notify-Email

参考

  • SpacetimeDB 官方自托管文档：https://spacetimedb.com/docs/how-to/deploy/self-hosting/
    • 该文档建议 Ubuntu 24.04、spacetimedb 专用用户、/stdb root-dir、systemd 托管，以及 Nginx/HTTPS。
    • 默认公网路由只开放 TypeScript SDK 必需的 /v1/identity 与 /v1/database/<database>/subscribe，其他发布、SQL、管理类入口保持本机可用。
Reference in New Issue View Git Blame Copy Permalink