手册：官网平台部署与上线检查

上线不是「容器起来了」。上线是：站点配置完整、内容已发布、转化链路可走通、资料助手在没有来源时会停答。下面按部署形态、检查清单、日常运维、故障处置和禁止操作排列，可直接勾核。

1. 部署形态

一台服务器、一个 Compose 项目，包含：Nginx、前端、FastAPI API、Celery worker、Celery beat、PostgreSQL、Valkey、SeaweedFS。

• 生产应用镜像通过必填 digest 环境键注入，由已安装的 sitectl 执行；生产 compose 不现场 build。
• 迁移、存储维护与首建管理员各自使用明确的独立进程，不由 API 进程代劳。
• API 进程不启动 scheduler 或 worker；后台任务全部由静态注册的 Celery task 执行。

2. 上线前检查清单

2.1 配置与密钥

• [ ] 数据库 URL、缓存 URL 文件、Celery 连接、签名密钥、Sentry、S3 运行凭据按进程分别提供
• [ ] S3 维护凭据只挂载给存储维护进程
• [ ] 缺少必填配置时进程启动失败（这是预期行为，不是故障）
• [ ] 证书联系人邮箱已配置；证书签发不复用发件邮箱

2.2 存储与媒体

• [ ] SeaweedFS 桶为 product-assets
• [ ] 仅 media/ 前缀可匿名读；下载资料不得使用该前缀
• [ ] Nginx 反代 /product-assets/{file_key}，请求体上限与后端一致（50 MiB）
• [ ] 已验证一张图片与一份 PDF 的上传与读取

2.3 站点配置

• [ ] GET /api/v1/config/site 返回正常（缺 theme 或必需媒体会返回 503）
• [ ] 品牌 Logo、og 图、Hero 图已上传且可解析为公开 URL
• [ ] 中文主语言下 theme.font.sans 覆盖 CJK
• [ ] 首页首段为可见 hero
• [ ] 三个资源目录位于页头一级

2.4 内容与 SEO

• [ ] 产品、知识文档、FAQ 已导入并发布
• [ ] 每页 meta_title 30–60 字符、meta_description 120–160 字符
• [ ] 图片均有 alt
• [ ] /robots.txt、/sitemap.xml、/feed.xml 可访问
• [ ] 结构化数据（Organization、WebSite、SoftwareApplication、FAQPage）已注入

2.5 转化链路

• [ ] 五类咨询表单可提交，隐私同意与提交键齐全
• [ ] 公开下载与留资下载两条链路各自跑通
• [ ] 资料助手对无来源问题停答而非编造
• [ ] 归因字段正常落库

3. 日常运维

事项	说明
内容发布	后台按草稿→待审→已发布流转，支持定时发布与下线
内容批量更新	用导入接口，先 dry_run 再 apply，按 external_key 幂等
配置变更	GET 取 revision → validate → diff → PUT 带 expected_revision
备份	数据库定期备份；对象存储按保留策略清理
监控	结构化日志、错误监控、本机指标

4. 故障处置口径

现象	排查顺序
公开页 503	站点配置完整性 → theme → 必需媒体是否可解析
图片不显示	对象是否存在 → 前缀是否匿名读 → Nginx 反代
下载链接失效	资产状态 → 签名有效期 → file_key 与对象是否一致
导入被拒	先 dry_run 看 rejected 原因 → 校验闭集与长度 → 修正后重跑
搜索无结果	实体是否已发布 → 索引是否重建

5. 禁止的操作

• 直接在生产 compose 中现场 build 镜像
• 把下载资料放到 media/ 前缀（会变成匿名公开）
• 手写跨层响应类型或生成类型别名（应重新生成 OpenAPI 生成物）
• 为兼容旧行为保留别名、双字段或影子入口