> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/practices/production-checklist · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 上线检查清单

从单机试跑走向生产前，按本清单逐项过一遍。每项给出「为什么」与「在哪配」，可勾选。

## 镜像版本

- [ ] 钉**不可变版本 tag** `vX.Y.Z`，**不要用 `latest`**——浮动 tag 会让重启/扩容拉到不同版本，故障时无法复现、也无法确定回滚目标。
- [ ] 需要绝对不可变时进一步钉到 `@sha256:<digest>`。
- [ ] 记录当前部署的版本号，便于对照 Release notes、排障与回滚。

> 官方镜像是 multi-arch（`linux/amd64` + `linux/arm64`），自动按宿主架构解析。tag 语义、架构支持与钉法详见 [镜像 tag 与架构](/zh-CN/reference/image-tags-and-arch.md)。

## 启动与探针

- [ ] `/health` 返回 200 即存活。
- [ ] 外部负载均衡器健康检查指向 `/ready`（数据库不可达、网关排空或入口落盘卷挂死时返回 503，用于灰度下线/零停机重启/挂死卷自动摘除）。
- [ ] `HOST` 设为 `0.0.0.0` 才能在容器里被端口映射访问（`127.0.0.1` 只本机）。

## 凭证与加密密钥

- [ ] 内置管理员账号 `protoflux` 的初始密码已改（控制台 → 控制台用户）。
- [ ] `ENCRYPTION_KEY` 从环境变量注入，**未**硬编码到镜像或 compose 明文。
- [ ] **已备份** `ENCRYPTION_KEY`：丢失 = 已加密数据（访问密钥、上游 API key）永久不可读。
- [ ] 多实例时所有实例用**同一把** `ENCRYPTION_KEY`。

::: danger ENCRYPTION_KEY 丢失不可逆
没有这把密钥，数据库里的访问密钥、上游 API key 都无法解密。务必单独备份，不要只存在部署环境里。
:::

## 控制台暴露面

- [ ] `CONSOLE_ALLOW_REMOTE` 默认 `true`（镜像默认允许远程访问控制台）。需要收紧时设 `false` 并**配合反向代理 + 访问控制**（防火墙 / IP 白名单 / VPN），不要裸暴露。
- [ ] 登录防爆破已生效（默认 20 次失败封 300 秒）。
- [ ] SSO 企业登录（如需）已配，见 [配置 SSO 企业登录](/zh-CN/howto/configure-sso.md)。

## 存储与多实例

- [ ] 单机用 SQLite，文件路径用绝对路径（如 `/var/lib/protoflux/stats.sqlite`），挂载到持久卷。
- [ ] 多实例用 PostgreSQL（共享统计与配置，30s 跨实例同步）+ Redis（共享会话/限流/IP 封禁/日志广播）。字段见 [环境变量配置参考](/zh-CN/reference/configuration.md)。
- [ ] PostgreSQL 版本 **17+**：日志表（`request_logs` / `openai_message_store`）按天 RANGE 分区、主键为 `IDENTITY` 列，分区表上的 IDENTITY 列仅 PG17 起支持（更早版本建表即失败）。
- [ ] 多实例**务必配 Redis**，否则会话/限流/IP 封禁退化为每实例独立，封禁阈值形同虚设。见 [做到高可用](/zh-CN/usecases/high-availability.md#multi-instance-shared-state)。

## 日志与磁盘

- [ ] `LOG_RETENTION_DAYS` 按合规需求设（如 30/90 天）。
- [ ] body 捕获跟随准入上限（ADR-005）：请求体按 `MAX_REQUEST_SIZE_MB`、响应体按 `MAX_RESPONSE_BODY_MB`。
- [ ] `LOG_STREAM_BODY_MAX_DISK_MB` 控制流式 body 磁盘占用。
- [ ] 多实例时 Live 日志 SSE 流汇聚所有实例日志，见 [日志查看器](/zh-CN/console/logs-viewer.md)。

## 限流与封禁

- [ ] 每密钥的 RPM/TPM（`rate_limit`）与并发上限在控制台设置（密钥/组字段 + 全局默认 `/settings/rate-limit`）；每 IP（`IP_RATE_LIMIT_RPM`）与每上游/每模型上限按需设置。字段见 [审计与安全配置](/zh-CN/reference/audit-and-security-config.md)。
- [ ] 多实例时限流走 Redis 共享，否则每实例独立、阈值被分散。

## 备份与恢复

- [ ] 数据库（SQLite 文件 / PostgreSQL）定期备份。
- [ ] `ENCRYPTION_KEY` 单独备份（见上）。
- [ ] 容器的环境变量清单（compose / task definition）纳入版本控制。
- [ ] 验证过一次恢复流程（光备份不验证等于没备份）。

## 常见问题

**Q：单机能直接上生产吗？**
小规模可以，但失去高可用与水平扩展。规模上去或要求高可用就上多实例 + PostgreSQL + Redis。

**Q：忘记管理员密码怎么办？**
设 `RESET_ADMIN=<新密码>` 后重启即重置（**仅生效一次**）。需再次重置：重新设 `RESET_ADMIN` 为新值再重启。重置成功后去掉该环境变量再重启，可避免每次重启告警。见 [Docker 单机跑通](/zh-CN/quickstart/docker-single-node.md) 的常见问题。

**下一步**：[做到高可用](/zh-CN/usecases/high-availability.md) 看容灾；[审计与安全配置](/zh-CN/reference/audit-and-security-config.md) 看安全字段；[满足合规与审计要求](/zh-CN/usecases/compliance-audit.md) 看合规。