部署运维

两个项目共用同一套 FastAPI 后端和运维模型，差别只在 Web 管理端分别使用 Vue 3 与 Vue 2。选择任一前端都不会改变 数据库迁移、Redis、Leader、日志、密钥和插件发布流程。

本模块按生产工作的真实顺序组织：先确定拓扑和流量入口，再准备配置与密钥，然后执行有回退条件的发布，最后建立监控、 备份和故障恢复。仓库内的 Compose 用于本地体验和联调，不是生产模板。

本模块不会替项目提供基础设施

RuoYi-FastAPI 内置的是应用配置、运维 CLI、数据库/Redis 访问、调度协调、日志和本地文件能力。负载均衡、TLS、通用 Readiness、集中监控、Secret Manager、数据库 PITR 和自动滚动发布都依赖用户选择的外部平台；文档中的相关步骤是接入 要求，不代表仓库已经包含这些设施。

先选择部署路径

场景	推荐入口	数据库	主要目的
本地快速体验	Compose + MySQL	MySQL 8.0	最少步骤启动前端、后端、数据库和 Redis
PostgreSQL 兼容验证	Compose + PostgreSQL	PostgreSQL 14	验证 SQL、代码生成和插件 Migration 的双库兼容
单机或小规模生产	Nginx + 1 个后端实例 + 1 个 Worker	MySQL / PostgreSQL	结构简单，先把持久化、备份和密钥治理做完整
多实例生产	自建负载均衡 + 多后端实例 + 共享 DB/Redis/文件存储	MySQL / PostgreSQL	在外部部署系统支持下滚动发布、扩容和故障切换

这里的“实例”是一个独立启动的后端服务副本，例如一台主机上的一个容器。大多数中小型部署只有 1 个实例、1 个 Worker；只有在单实例吞吐或可用性不能满足要求时，才增加 Worker 或实例。扩容前先阅读 生产拓扑与容量规划，因为每个 Worker 都会创建自己的数据库连接池。

运维内容地图

阶段	要回答的问题	对应文档
部署与流量	服务放在哪里、暴露哪些端口、API 前缀怎样转发	生产拓扑、Nginx
配置与安全	哪些值可以公开、哪些密钥必须稳定、如何轮换	环境变量与密钥、加密密钥轮换
发布与变更	数据库、插件和多 Worker 怎样按顺序上线	数据库迁移、插件升级、调度安全
监控与恢复	怎样确认服务正常、怎样保留数据、故障时先查哪里	Redis 运维、日志与健康、备份恢复、故障排查

一次标准生产发布

1. 固定发布输入。 记录代码 commit 或镜像 digest，将同一个值注入 APP_RELEASE_ID；固定 Python、Node、Nginx 和基础镜像版本，保留前后端构建日志与制品校验值。

2. 校验生产配置。 确认使用 .env.prod 或等价的部署平台配置，生产 JWT、数据库、Redis 和 RSA 密钥已经注入， APP_RELOAD=false、DB_ECHO=false，Swagger / ReDoc 的开放状态符合安全策略。

   脚本运行目录 · ruoyi-fastapi-backend

   bash

   1ruoyi app env --env=prod --output=json2ruoyi app config --env=prod --output=json3ruoyi app doctor --env=prod --output=json

3. 记录依赖与数据版本。 ops health 只验证数据库和 Redis 连接；还要分别记录 Alembic head、当前数据库版本、 插件状态和待执行计划。

   脚本运行目录 · ruoyi-fastapi-backend

   bash

   1ruoyi ops health --env=prod --output=json2ruoyi db heads --env=prod --output=json3ruoyi db current --env=prod --output=json4ruoyi plugin check --env=prod --output=json

4. 生成可恢复备份。 数据库备份必须在隔离环境完成恢复验证；上传目录、插件制品、部署配置和必要 Redis 状态使用 同一恢复点标识。记录备份时间、业务写入边界和恢复负责人。

5. 预演高风险变更。 对数据库和插件使用与正式执行完全相同的环境、目标版本和插件 ID。审查预演结果后再批准 正式变更，不能只因为命令支持 --dry-run 就跳过备份。

6. 按兼容顺序发布。 有数据库变更时采用“旧代码可读新结构”的扩展阶段，再发布兼容代码，最后清理旧字段； 单实例部署在维护窗口停写。项目没有通用 HTTP /ready 路由，多实例部署必须先在外部部署系统中实现就绪判断、摘流 和连接排空，才能逐批发布和恢复流量。

7. 执行分层验证。 依次验证进程存活、HTTP 入口、数据库和 Redis、登录与权限、文件上传下载、定时任务、插件健康 和关键业务写入。不能用首页能打开或 ops health 返回成功代替完整验收。

8. 观察后关闭回退窗口。 至少观察错误率、延迟、数据库连接/锁、Redis 内存与 Stream、Leader 稳定性、磁盘和任务 失败。确认无需回退后再撤销旧密钥、删除旧制品或执行破坏性数据库清理。

上线门禁

门禁	通过标准
配置	目标环境正确；JWT 不为空且跨实例一致；示例 RSA 私钥和默认密码已替换
流量	HTTPS、API 前缀、APP_ROOT_PATH、proxy_pass 和可信代理配置相互一致
数据	备份已恢复验证；current 与目标 Revision 一致；迁移耗时与锁影响可接受
容量	数据库连接预算覆盖全部实例、Worker、Scheduler 同步引擎和运维命令余量
运行	数据库、Redis、上传存储和日志目录均持久化；磁盘、连接和延迟告警已启用
业务	登录、菜单权限、核心查询/写入、上传下载、任务和启用插件完成冒烟测试
回退	明确代码、数据库、插件、配置和密钥分别回退到什么版本，以及何时停止自动回退

不要直接把仓库 Compose 用于生产

当前 Compose 使用固定数据库密码、无密码 Redis、未声明可复用的数据库/Redis 数据卷、宿主机端口直出，并使用未固定的 redis:latest 和 nginx:latest。它还没有 TLS、备份、资源限制和高可用。删除或重建容器可能导致数据丢失。

日常值班入口

• 变更前：先看数据库迁移、备份与回退和插件发布与升级。
• 性能或容量异常：先看生产拓扑与容量规划、Redis 运维和 日志与健康检查。
• 502、启动失败、登录异常或任务重复：直接进入生产故障排查，先保留证据再操作。
• 灾难恢复：按数据与文件备份恢复从空环境演练，不在故障主机上直接覆盖原数据。