造物矩阵模板

Appearance

人工部署手册 ​

本页适合希望自己逐项控制服务器配置的开发者。若希望由 AI 读取仓库协议并代为执行，请使用AI 部署手册。

1. 准备环境 ​

  • 由你控制的 Linux 服务器，建议至少 4 vCPU、8 GB 内存与 40 GB 可用磁盘。
  • Node.js 22+、pnpm 8.13.1、Docker Engine 与 Docker Compose v2。
  • 已解析到服务器的主站和 Auth 域名。
  • 具有签发 HTTPS 证书和配置第三方回调的权限。

资源需求会随内容量、并发、视频处理和启用模块变化。上线后应根据监控结果调整，而不是把建议配置当作永久容量承诺。

2. 解压并校验版本 ​

从商品页下载源码压缩包后，先比对下载页显示的 SHA-256：

bash
shasum -a 256 maker-community-template-*.zip

在新目录解压，不要覆盖正在运行的旧版本，也不要删除旧版本与备份。

3. 安装依赖 ​

bash
corepack enable
pnpm install --frozen-lockfile

先运行本地 Mock，确认压缩包与当前机器环境可用：

bash
pnpm dev:community-template

确认主站、接口和文档可以打开后停止本地服务，再继续生产配置。

4. 设置站点与模块 ​

编辑 config/community-template.json，填写站点身份并选择模块与 Provider，然后验证：

bash
pnpm --filter @zaowu/template-core validate:config -- config/community-template.json

不要通过删除页面或注释 API 注册来关闭功能。模块开关会同时控制导航、页面和接口。

5. 建立生产环境变量 ​

bash
test -f .env || cp .env.example .env
chmod 600 .env

在 .env 中完成公网 URL、数据库、Redis、Cookie、Session、CSRF、机器令牌和已启用 Provider 的配置。生产环境必须关闭 Mock 支付、Mock OAuth 与本地视频模式。

默认部署包含 PostgreSQL 定时备份。请同时填写 QINIU_ACCESS_KEY、QINIU_SECRET_KEY、QINIU_BUCKET、QINIU_REGION、QINIU_S3_ENDPOINT 和独立的 QINIU_BACKUP_PREFIX；预检会在启动前阻止缺少凭据、非 HTTPS 端点或越界对象前缀。首次上线后还必须实际执行并校验一次可恢复备份，不能只以定时容器处于运行状态作为通过标准。

为 OIDC 生成独立私钥，并只通过只读 Secret 挂载提供给 Auth：

bash
install -d -m 700 .secrets/oidc
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 \
  -out .secrets/oidc/community-auth.pem
chmod 600 .secrets/oidc/community-auth.pem

然后设置 OIDC_KEYS_DIR=./.secrets/oidc、AUTH_OIDC_PRIVATE_KEY_PATH=/run/secrets/oidc/community-auth.pem 和唯一的 AUTH_OIDC_KEY_ID。不要把私钥内容复制进 .env、Dockerfile 或代码。

若启用活动、小铺或数字商品，保持 COMMUNITY_COMMERCE_MAINTENANCE_ENABLED=true，并为 SPACE_MACHINE_TOKEN 设置独立高熵值。Worker 会定期关闭超时待支付记录，释放库存、活动名额和未核销代码。关闭这个维护开关会让预占状态无法自动回收，不应作为正常生产配置。

若启用 referrals，还要为 SPACE_REFERRAL_TOKEN_SECRET 生成独立的 32 位以上高熵值。它只用于签署短期推荐归因，不能与邀请、活动、小铺或下载签名 Secret 共用。生产预检会拒绝示例值和过短值。

Secret 只放在服务器上的 .env 或 Secret 管理服务中，不写进 Git、聊天记录、截图或部署报告。

如果启用 softwareDelivery，还要选择数字商品交付方式：

场景配置需要准备
七牛私有空间SPACE_SOFTWARE_STORAGE_PROVIDER=qiniu七牛 Access/Secret Key、私有空间和已绑定的 HTTPS 下载域名
服务器私有目录SPACE_SOFTWARE_STORAGE_PROVIDER=filesystem服务器私有目录、独立下载签名 Secret 和足够的磁盘/备份容量

文件系统方式默认把宿主机 ./.secrets/software 只读挂载到容器 /var/lib/zaowu/software。发行记录中的 artifactKey 是该目录下的相对路径，例如：

text
.secrets/software/software/my-product/releases/my-product-1.0.0.zip

同时设置 SPACE_SOFTWARE_DOWNLOAD_TOKEN_SECRET 为独立高熵值。文件不会由 Nginx 直接公开；用户通过权益检查后取得默认 300 秒有效的主站下载地址。七牛方式与文件系统方式只能二选一，切换时不需要修改商品和版本数据。

6. 运行预检并部署 ​

bash
pnpm ops:template:preflight
pnpm ops:template:deploy

部署命令使用生产 Compose 配置构建并启动核心服务。首次没有证书时，Nginx 会先以 HTTP 模式提供 ACME 校验路径。确认三个域名都已解析到服务器、80 和 443 端口可访问后，签发或续期同一张多域名证书：

bash
pnpm ops:template:certificate

该命令只读取 .env 中的站点域名和 ACME 邮箱，不会加载或打印 Secret；它会调用 Certbot，并在成功后重启 Nginx 切换到 HTTPS。若启用腾讯 VOD，应先完成证书签发，再打开 TENCENT_VOD_ENABLED 并重新运行预检。不要为了绕过预检改用开发 Compose。

7. 上线验证 ​

至少检查：

  1. 核心容器处于 running/healthy。
  2. Auth 与 Space API 的 /healthz 返回成功。
  3. 主站通过 HTTPS 打开，注册与登录回到正确域名。
  4. /v1/app 返回的模块与 Provider 和配置一致，且不含 Secret。
  5. 被关闭的 Web 页面与对应 API 均返回 404。
  6. 数据库与 Redis 端口未绑定公网地址。
  7. 上传、邮件、支付、视频与 AI 按实际启用范围验证成功和失败路径。
  8. 数字商品验证无权益拒绝、有效链接下载、过期链接拒绝与文件 SHA-256。
  9. 创建一笔测试用待支付订单或活动报名，确认 Worker 能在到期后关闭记录并释放库存、名额与代码预占。
  10. PostgreSQL、上传文件与数字商品发行文件完成一次可恢复备份。

8. 保存部署记录 ​

记录当前源码版本、启用模块、Provider、迁移输出、健康检查、备份位置、回滚版本和仍需人工处理的事项。记录中不要包含密钥、Cookie、访问令牌或私有下载 URL。