造物矩阵模板

Appearance

AI 部署手册 ​

这份文档既给人看，也作为 AI 的执行协议。把源码目录和一台服务器交给 AI 前，先让它读取仓库根目录的 AGENTS.md 与 config/community-template-deployment.json。

如果只是查看和试用功能，请先走 本地 Mock 体验。本页从生产部署开始，需要真实域名、HTTPS 和 Provider 凭据，不应拿 Mock 配置直接上线。

1. 前置条件 ​

  • 一台由你控制的 Linux 服务器；建议至少 4 vCPU、8 GB 内存和 40 GB 可用磁盘。
  • Node.js 22+、pnpm 8.13.1、Docker Engine 和 Docker Compose v2。
  • 已解析到服务器的主站与 Auth 域名，以及可签发 HTTPS 证书的控制权。
  • PostgreSQL、Redis 使用 Compose 内建服务；生产数据必须落在命名卷中。
  • 根据启用功能准备 SMTP、七牛云、支付、视频或 AI Provider 凭据。
  • 默认的 PostgreSQL 定时备份使用七牛 S3 兼容端点；部署前必须准备独立备份前缀并完成一次可恢复性校验。

AI 可以检查环境和填写非敏感配置，但不得替你创建、猜测或在对话中回显云厂商 Secret、支付私钥和加密密钥。缺少凭据时应列出待办并停止相关模块，而不是使用示例值上线。

2. 建立生产环境文件 ​

从示例创建，不覆盖已经存在的文件：

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

至少完成以下设置：

  • 所有公网 URL 使用 https://，回调 URL 与云端控制台完全一致。
  • AUTH_NODE_ENV=production、AUTH_COOKIE_SECURE=true。
  • PostgreSQL、Redis、Cookie、CSRF、Session、机器令牌和各业务加密密钥使用独立高熵值。
  • 为 Auth 生成独立 RSA OIDC 私钥，保存到 OIDC_KEYS_DIR，并将容器路径填写为 /run/secrets/oidc/...。私钥不得进入镜像、Git 或部署报告。
  • SPACE_PAYMENT_MOCK_ENABLED=false、所有 OAuth Mock 和渠道 Mock 关闭。
  • 按 config/community-template.json 中启用的 Provider 填写真实配置。
  • 使用七牛公开存储时，必须显式填写头像、帖子图片、通用附件、工具库图片和最前线发布截图的真实 HTTPS CDN origin；不得保留 .env.example 中的 assets.example.com 占位值。
  • 启用数字商品交付时，在 qiniu 与 filesystem 中选择一种存储方式；文件系统方式必须使用 .secrets/software 一类非 Git 目录，并生成独立下载签名 Secret。
  • 启用推荐返利时，生成独立的 SPACE_REFERRAL_TOKEN_SECRET；不得复用邀请、活动、小铺或下载签名 Secret。

可以在服务器本地生成通用随机 Secret，例如：

bash
openssl rand -base64 48

OIDC 私钥必须写入未跟踪的 Secret 目录：

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

不要把生成结果写进命令历史、AI 回复、部署报告或 Git。支付和 OAuth 私钥按厂商流程创建并放入受限文件或 Secret 管理服务。

3. 选择功能与 Provider ​

修改 config/community-template.json，然后执行：

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

只使用 schema 已允许的 Provider。腾讯云 COS、阿里云 OSS 等尚未实现的 Provider 不能通过改字符串启用。

4. 运行安全预检 ​

bash
pnpm install --frozen-lockfile
pnpm ops:template:preflight

预检会依次验证运行时、功能配置、生产环境值、生产 Compose 加固配置、证书与视频回调条件。它不会打印 Secret 值。任何失败都必须先修复；不能删掉校验或改用开发 Compose 绕过。

5. 部署 ​

默认部署 Web 模板核心服务：

bash
pnpm ops:template:deploy

首次部署时 Nginx 会在证书尚未签发时保留 HTTP ACME 校验入口。确认 DNS 和 80/443 端口后执行：

bash
pnpm ops:template:certificate

命令会从 .env 安全读取三个公开域名与 ACME 邮箱，调用 Certbot，并在成功后重启 Nginx。不得用 source .env 或在对话中复制环境文件。若启用腾讯 VOD，必须先完成证书签发，再将 TENCENT_VOD_ENABLED 设为 true 并重新运行预检。

如只更新无状态服务，可以显式传入服务名：

bash
bash scripts/template-deploy.sh auth auth-web space-api space-web community-template-worker template-docs nginx

部署脚本会再次运行安全预检，使用 docker-compose.yml + docker-compose.production.yml 构建和启动，并在末尾输出服务状态。

6. 验证 ​

AI 必须完成并报告：

  1. docker compose ... ps 中核心容器为 running/healthy。
  2. Auth /healthz 返回成功。
  3. Space API /healthz 返回成功。
  4. 主站公网 URL 能通过 HTTPS 打开，注册/登录回调回到正确域名。
  5. /v1/app 中的模块和 Provider 与 community-template.json 一致，且不含 Secret。
  6. 一个被关闭的 Web 路由和对应 API 均返回 404。
  7. 数据库与 Redis 端口没有绑定公网地址。
  8. 启用数字商品时，验证无权益、有效下载、过期地址和 SHA-256 四条路径。
  9. 报告当前源码版本、启用模块、Provider 标识、健康结果和回滚方式。

不要在报告中粘贴 .env、请求签名、访问令牌、Cookie 或私有下载 URL。

7. 回滚 ​

回滚前先备份数据库。切换到上一个已验证的不可变发行包，复用同一份 .env、config/community-template.json 和命名卷，然后重新执行预检与部署。

禁止使用：

bash
docker compose down -v

它会删除持久卷。若新版本已经执行不可逆数据库迁移，AI 必须停止自动回滚并请求人工确认，不得自行清表、降级 schema 或恢复未知备份。

8. AI 的完成报告模板 ​

text
部署版本：
站点域名：
启用模块：
Provider：
容器健康状态：
公网验证：
被关闭模块验证：
备份位置（不含凭据）：
回滚版本与命令：
仍需人工处理：