GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity
Files
879a53bf8dc365f64a30d61a2544a0684c6d5d15
Genarrative/生产部署计划.md
kdletters 879a53bf8d docs: add production deployment plan
2026-05-02 02:58:14 +08:00

11 KiB
Raw Blame History

生产部署计划

更新时间：2026-05-02

目标

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

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

生产架构

  • Nginx 作为唯一公网入口，负责 HTTPS、静态站点、后台静态页面、维护页与 /admin/api/ 反向代理。
  • SpacetimeDB 作为系统服务运行，监听 127.0.0.1:3000，数据根目录为 /stdb。
  • Rust api-server 作为系统服务运行，监听 127.0.0.1:8082，只被 Nginx 的 /admin/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:3000
  • 对外暴露：默认不直接暴露公网端口。

该方案与 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。

Nginx 规则

只保留必要入口：

  • /：主站静态页面。
  • /admin/：后台前端静态页面，后台构建时使用 /admin/ 作为 base path。
  • /admin/api/：反向代理到 http://127.0.0.1:8082/admin/api/。
  • HTTP 到 HTTPS：只保留 301 重定向。
  • /maintenance.html：维护中页面。

移除这些公网反向代理：

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

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

维护模式

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

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

行为：

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

构建产物

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

build/<version>/
├─ web/
│  ├─ index.html
│  ├─ assets/
│  ├─ maintenance.html
│  └─ admin/
├─ api-server
├─ spacetime_module.wasm
├─ scripts/
│  ├─ spacetime-publish-prod.sh
│  ├─ database-export.sh
│  ├─ database-import.sh
│  ├─ maintenance-on.sh
│  ├─ maintenance-off.sh
│  └─ maintenance-status.sh
├─ deploy/
│  ├─ systemd/
│  │  ├─ spacetimedb.service
│  │  └─ genarrative-api.service
│  ├─ nginx/
│  │  ├─ genarrative.conf
│  │  └─ snippets/maintenance.conf
│  └─ env/api-server.env.example
└─ README.md

不再生成旧产物：

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

Jenkins 节点

Jenkins 可运行在 Windows 或其他机器上，但构建与发布动作使用 Linux agent。

开发/构建实例

  • 节点名：genarrative-dev
  • 标签：genarrative-linux dev build
  • 用途：拉代码、安装依赖、构建主站、构建后台、构建 api-server、构建 SpacetimeDB wasm、归档产物。

生产/发布实例

  • 节点名：genarrative-prod
  • 标签：genarrative-linux prod deploy
  • 用途：服务器配置、发布静态网站、发布 api-server、发布 SpacetimeDB 模块、数据库导入导出、维护模式切换。

SSH PEM 凭证

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

  • genarrative-dev-ssh-key：开发/构建实例 SSH 凭证。
  • genarrative-prod-ssh-key：生产/发布实例 SSH 凭证。

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

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

构建流水线运行在 build && dev，发布、导入导出和服务器配置流水线运行在 deploy && prod。

构建流水线支持参数 PUBLISH_AFTER_BUILD：

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

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

流水线职责

Genarrative-Server-Provision

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

  • 创建 spacetimedb、genarrative 等系统用户。
  • 创建 /stdb、/opt/genarrative、/srv/genarrative、/etc/genarrative、/var/lib/genarrative/maintenance。
  • 安装或更新 SpacetimeDB。
  • 安装 systemd unit。
  • 安装 Nginx 配置和维护模式 snippet。
  • 执行 nginx -t。
  • 启用并启动 spacetimedb.service 与 genarrative-api.service。

该流水线属于高风险操作，默认要求人工确认后执行。

Web Build / Deploy

构建：

  • 构建主站静态文件。
  • 构建后台前端，base path 为 /admin/。
  • 生成或复制 maintenance.html。
  • 归档 web/ 产物。

发布：

  • 解包到 /opt/genarrative/releases/<version>/web。
  • 更新 /opt/genarrative/current 与 /srv/genarrative/web 指向。
  • 执行 Nginx 配置测试和静态页面 smoke test。
  • 不进入维护模式。

Api Build / Deploy

构建：

  • 编译 Rust api-server。
  • 归档单一可执行文件和必要运行说明。

发布：

  • 进入维护模式。
  • 解包到 /opt/genarrative/releases/<version>/api-server。
  • 更新 /opt/genarrative/current。
  • 重启 genarrative-api.service。
  • 检查本机 /healthz。
  • 成功后解除维护模式。
  • 失败时保留维护模式并发邮件。

Stdb Module Build / Publish

构建：

  • 使用 spacetime build 构建 spacetime_module.wasm。
  • 归档 wasm 与发布脚本。

发布：

  • 进入维护模式。
  • 将 wasm 上传到生产实例。
  • 在生产实例本机执行 spacetime publish -s local --bin-path spacetime_module.wasm <database-name>。
  • 成功后执行必要 smoke test。
  • 成功后解除维护模式。
  • 失败时保留维护模式并发邮件。

数据库导出与导入

导出

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

  • 运行在 deploy && prod。
  • 进入维护模式，避免导出期间继续写入。
  • 从本机 SpacetimeDB 导出指定数据库数据。
  • 产物归档到 Jenkins，并可额外保存到服务器备份目录。
  • 成功后解除维护模式。
  • 失败时保留维护模式并邮件通知。

导入

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

  • 运行在 deploy && prod。
  • 必须要求人工确认目标数据库、导入文件和是否覆盖。
  • 进入维护模式。
  • 导入前先生成一次安全备份。
  • 执行导入。
  • 执行数据校验和服务 smoke test。
  • 成功后解除维护模式。
  • 失败时保留维护模式并邮件通知。

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

全量构建并发布

Genarrative-Full-Build-And-Deploy 顺序：

  1. 触发 Genarrative-Web-Build。
  2. 触发 Genarrative-Api-Build。
  3. 触发 Genarrative-Stdb-Module-Build。
  4. 触发 Genarrative-Stdb-Module-Publish。
  5. 触发 Genarrative-Api-Deploy。
  6. 触发 Genarrative-Web-Deploy。
  7. 执行生产 smoke test。

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

回滚

  • 网站回滚：将 /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/nginx/genarrative.conf
  • deploy/nginx/snippets/maintenance.conf
  • deploy/env/api-server.env.example
  • scripts/deploy/maintenance-on.sh
  • scripts/deploy/maintenance-off.sh
  • scripts/deploy/maintenance-status.sh
  • 新 Jenkinsfile 或 Job DSL，用于上述 10 条流水线。
  • 更新旧部署文档，标记旧一体化脚本为废弃或迁移对象。

参考

Reference in New Issue View Git Blame Copy Permalink