ReglowAdmin 小白生产环境部署指南

适用项目：coding/backend-python + coding/frontend-admin
适用平台：阿里云 ECS、腾讯云 CVM、华为云 ECS，以及其他普通 Linux 云服务器
推荐部署方式：Docker Compose 一机部署（前端 + 后端 + MySQL + Redis）
文档目标：让第一次部署生产环境的人，也能理解“为什么这样做”，并把开发代码安全、稳定地跑到公网。

1. 先用一句话理解部署

开发环境像“你家厨房”：你可以边做边尝、随手改配方。
生产环境像“正式餐厅”：要有后厨、仓库、收银、监控、消防、备用钥匙，不能靠临时发挥。

把 ReglowAdmin 部署到生产环境，本质上就是把下面这些角色安顿好：

2. 为什么推荐 Docker Compose 部署

小白最容易踩的坑是：本地能跑，服务器不能跑。

原因通常是：

• 本地 Python 版本和服务器 Python 版本不同；
• 本地 Node 版本和服务器 Node 版本不同；
• 本地有某些依赖，服务器没有；
• 本地连 SQLite，服务器要连 MySQL；
• 本地 Redis 没开，生产验证码/限流失效；
• 前端打包后接口路径不对；
• 数据库表没迁移；
• 文件上传目录没持久化。

Docker 的作用就像“打包好的标准厨房”：锅、灶、调料、摆放方式都固定。你把这套厨房搬到阿里云、腾讯云、华为云，做出来的菜基本一样。

Docker Compose 的作用就像“开店清单”：

先开 MySQL → 再开 Redis → 再开后端 → 最后开前端 Nginx

当前项目已经具备这些生产部署基础：

• 根目录有 docker-compose.yml；
• 后端有 coding/backend-python/Dockerfile；
• 后端启动时会执行 alembic upgrade head 自动迁移数据库；
• 前端有 coding/frontend-admin/Dockerfile；
• 前端有 coding/frontend-admin/nginx.conf，负责静态页面和接口反代；
• Compose 已包含 mysql、redis、backend、frontend 四个服务；
• 后端已有 /health、/health/live、/health/ready、/metrics。

3. 生产环境和开发环境最大的区别

3.1 开发环境追求“方便”

开发时常见做法：

• DEBUG=true；
• 用默认密码；
• 前后端分别启动；
• 数据库随便删了重建；
• 报错直接看控制台；
• 接口可以跨域乱连；
• 文件放本地目录。

这适合写代码，但不适合上线。

3.2 生产环境追求“稳定、安全、可恢复”

生产环境要遵守这些核心规律：

4. ReglowAdmin 当前生产部署架构

推荐的一机部署结构如下：

公网用户浏览器
    │
    │ 访问 http://你的域名 或 https://你的域名
    ▼
frontend 容器（Nginx，监听 80）
    ├─ 返回 Vue 后台静态页面
    ├─ /admin/api/*  → 转发到 backend:8000
    ├─ /api/*        → 转发到 backend:8000
    └─ /uploads/*    → 转发到 backend:8000

backend 容器（FastAPI + Uvicorn，监听 8000）
    ├─ 业务接口
    ├─ 权限认证/JWT
    ├─ Redis 验证码/限流/缓存
    ├─ Alembic 数据库迁移
    ├─ /health/ready 健康检查
    └─ /metrics 指标

mysql 容器
    └─ 保存业务数据

redis 容器
    └─ 保存验证码、限流计数、缓存

Docker volumes
    ├─ mysql_data       保存 MySQL 数据
    ├─ redis_data       保存 Redis 数据
    └─ backend_uploads  保存上传文件

这套结构的优点是：

• 小白容易部署；
• 各云厂商基本通用；
• 项目已有配置文件支持；
• 后续可平滑升级到更专业架构：云数据库、云 Redis、对象存储、负载均衡、CDN。

5. 云服务器怎么选

阿里云 ECS、腾讯云 CVM、华为云 ECS 名字不同，本质都是“一台远程 Linux 电脑”。

5.1 小型生产环境推荐配置

如果只是演示环境：2 核 4GB 可以跑。
如果是企业内部多人使用：建议 4 核 8GB 起步。
如果上传素材较多：磁盘要更大，后续建议接对象存储 OSS/COS/OBS。

5.2 安全组/防火墙开放端口

生产最小开放：

形象理解：

• 80/443 是“正门”；
• 22 是“员工通道”，最好只允许你自己的办公 IP；
• 3306/6379 是“账本房”和“便签柜”，不能开到大街上；
• 8000 是“厨房门”，正常让 Nginx 内部转交就行。

6. 阿里云、腾讯云、华为云部署前准备

三家云厂商操作名称略有不同，但步骤规律一样。

6.1 创建云服务器

阿里云

• 产品：ECS 云服务器；
• 网络：专有网络 VPC；
• 镜像：Ubuntu 22.04 LTS 或 Alibaba Cloud Linux 3；
• 安全组：开放 22、80、443；
• 绑定公网 IP；
• 推荐绑定弹性公网 IP，方便后续迁移。

腾讯云

• 产品：CVM 云服务器；
• 网络：私有网络 VPC；
• 镜像：Ubuntu 22.04 LTS；
• 安全组：开放 22、80、443；
• 分配公网 IP。

华为云

• 产品：ECS 弹性云服务器；
• 网络：VPC；
• 镜像：Ubuntu 22.04 LTS；
• 安全组：开放 22、80、443；
• 绑定弹性公网 IP。

6.2 绑定域名

如果有域名，去 DNS 控制台添加解析：

记录类型：A
主机记录：admin 或 @
记录值：你的服务器公网 IP

例如：

admin.example.com  →  你的服务器公网 IP

为什么要域名？

• HTTPS 证书通常需要域名；
• 用户更容易访问；
• 后续迁移服务器时，只改 DNS，不用通知所有人换地址。

7. 服务器初始化

下面以 Ubuntu 为例。先 SSH 登录服务器：

ssh root@你的服务器公网IP

如果不是 root 用户，用：

ssh ubuntu@你的服务器公网IP

7.1 更新系统

sudo apt update
sudo apt upgrade -y

为什么要更新？
就像新手机开机先升级系统，修补已知安全漏洞，避免用旧组件裸奔。

7.2 安装常用工具

sudo apt install -y git curl wget vim ca-certificates gnupg lsb-release

这些工具分别用于：

• git：拉代码；
• curl/wget：下载和测试接口；
• vim：编辑配置；
• ca-certificates/gnupg：安装软件源和证书。

7.3 安装 Docker

推荐使用 Docker 官方安装脚本：

curl -fsSL https://get.docker.com | sudo sh

启动 Docker：

sudo systemctl enable docker
sudo systemctl start docker

检查版本：

docker version

7.4 安装 Docker Compose

新版 Docker 通常自带 Compose 插件，检查：

docker compose version

如果能看到版本号，就可以继续。

8. 上传或拉取项目代码

推荐把项目放在 /opt/reglow_project：

sudo mkdir -p /opt
cd /opt

8.1 如果代码在 Git 仓库

git clone 你的仓库地址 reglow_project
cd reglow_project

8.2 如果是本地压缩包

在本地打包上传到服务器，例如上传到 /opt/reglow_project.zip，然后服务器上解压：

cd /opt
sudo apt install -y unzip
unzip reglow_project.zip -d reglow_project
cd reglow_project

确保目录结构类似：

/opt/reglow_project
├── docker-compose.yml
├── .env.docker.example
└── coding
    ├── backend-python
    │   ├── Dockerfile
    │   ├── docker-entrypoint.sh
    │   ├── alembic.ini
    │   ├── alembic/
    │   └── main.py
    └── frontend-admin
        ├── Dockerfile
        ├── nginx.conf
        └── package.json

9. 配置生产环境变量

项目根目录已有 .env.docker.example，先复制成 .env：

cd /opt/reglow_project
cp .env.docker.example .env
vim .env

示例：

MYSQL_ROOT_PASSWORD=请换成很长的Root密码
MYSQL_DATABASE=reglow_admin
MYSQL_USER=reglow
MYSQL_PASSWORD=请换成很长的数据库密码
JWT_SECRET=请换成至少32位以上随机字符串
CORS_ORIGINS=https://admin.example.com

9.1 每个变量是什么意思

9.2 JWT_SECRET 怎么生成

可以在服务器上生成：

openssl rand -hex 32

把输出填到 .env 的 JWT_SECRET。

为什么不能用默认值？
JWT_SECRET 就像银行印章。默认值人人都知道，别人就可能伪造登录凭证。

9.3 CORS_ORIGINS 怎么填

如果你用域名：

CORS_ORIGINS=https://admin.example.com

如果暂时没有 HTTPS，只用 IP 测试：

CORS_ORIGINS=http://你的服务器公网IP

不要在生产环境写：

CORS_ORIGINS=*

当前后端配置会在 DEBUG=false 时禁止 CORS 通配符，这是正确的安全设计。

10. 一条命令启动生产环境

在项目根目录执行：

cd /opt/reglow_project
docker compose up -d --build

这条命令会做几件事：

1. 拉取 MySQL 镜像；
2. 拉取 Redis 镜像；
3. 构建后端镜像；
4. 构建前端镜像；
5. 创建 Docker 网络；
6. 创建数据卷；
7. 启动 MySQL；
8. 启动 Redis；
9. 等 MySQL/Redis 健康后启动后端；
10. 后端入口脚本执行 alembic upgrade head；
11. 后端启动 Uvicorn；
12. 前端 Nginx 启动并对外监听 80。

查看服务状态：

docker compose ps

查看日志：

docker compose logs -f

只看后端日志：

docker compose logs -f backend

只看前端日志：

docker compose logs -f frontend

11. 验证部署是否成功

11.1 检查容器状态

docker compose ps

理想状态：

mysql      healthy
redis      healthy
backend    healthy
frontend   running

11.2 检查后端健康接口

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/health/ready

/health 说明后端进程活着。
/health/ready 说明后端能连 MySQL 和 Redis，更适合作为生产探活。

返回类似：

{
  "status": "ok",
  "checks": {
    "database": true,
    "redis": true
  }
}

如果是：

{
  "status": "degraded"
}

说明后端活着，但数据库或 Redis 有问题。

11.3 浏览器访问

打开：

http://你的服务器公网IP

或：

http://你的域名

如果页面能打开，说明前端 Nginx 正常。

如果登录接口正常，说明 Nginx → 后端 → MySQL/Redis 链路基本正常。

12. HTTPS 怎么配置

生产环境强烈建议上 HTTPS。HTTP 像“明信片”，路上谁都可能看到内容；HTTPS 像“加密信封”。

12.1 最省心做法：云厂商负载均衡 + 免费证书

阿里云、腾讯云、华为云都支持：

用户 HTTPS 访问
    ↓
云负载均衡/应用网关（挂 HTTPS 证书）
    ↓
服务器 80 端口 frontend 容器

优点：

• 证书由云平台管理；
• 续期更省心；
• 后续多台服务器扩容方便。

12.2 单机做法：服务器上加反向代理或改 Nginx

可以使用 Caddy、Nginx + Certbot 等方式。小白推荐 Caddy，因为自动签证书比较简单。

示意结构：

Caddy 监听 80/443
    ↓
转发到 frontend 容器 80

如果使用这种方式，Compose 里的 frontend 端口可以改成只绑定本机：

ports:
  - "127.0.0.1:8080:80"

然后 Caddy 转发到 127.0.0.1:8080。

注意：当前项目默认 Compose 直接把 frontend 暴露到 80:80，适合快速部署。上 HTTPS 后可以再做一层外部代理。

13. 数据库、Redis、上传文件为什么要用 volume

当前 docker-compose.yml 已经配置：

volumes:
  mysql_data:
  redis_data:
  backend_uploads:

这非常重要。

容器像“可替换的外卖盒”，坏了可以扔；数据像“账本”，不能跟盒子一起扔。

所以：

• 可以重建容器；
• 可以重建镜像；
• 但不要随便删 volume。

危险命令：

docker compose down -v

-v 会删除数据卷，小白生产环境不要用。

正确停止：

docker compose down

14. 备份和恢复

生产环境一定要备份。没有备份的系统，不叫上线，叫冒险。

14.1 备份 MySQL

cd /opt/reglow_project
mkdir -p backups

docker compose exec -T mysql mysqldump \
  -u$MYSQL_USER \
  -p$MYSQL_PASSWORD \
  $MYSQL_DATABASE > backups/reglow_admin_$(date +%F_%H%M%S).sql

如果 shell 没读到 .env，可以先：

set -a
source .env
set +a

再执行备份。

14.2 备份上传文件

docker run --rm \
  -v reglow_project_backend_uploads:/data \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/uploads_$(date +%F_%H%M%S).tar.gz -C /data .

14.3 恢复 MySQL

先确认你真的要恢复，因为会覆盖现有数据。

cat backups/你的备份.sql | docker compose exec -T mysql mysql \
  -u$MYSQL_USER \
  -p$MYSQL_PASSWORD \
  $MYSQL_DATABASE

14.4 备份规律

15. 日常运维常用命令

15.1 查看服务

docker compose ps

15.2 查看日志

docker compose logs -f backend

docker compose logs -f frontend

15.3 重启某个服务

docker compose restart backend

docker compose restart frontend

15.4 重启全部服务

docker compose restart

15.5 重新构建并启动

docker compose up -d --build

15.6 进入后端容器

docker compose exec backend sh

15.7 查看健康状态

curl http://127.0.0.1:8000/health/ready

15.8 查看指标

curl http://127.0.0.1:8000/metrics

16. 怎么从开发代码发布到生产

推荐流程：

本地开发 → 本地测试 → 提交代码 → 服务器拉代码 → 备份数据 → 构建镜像 → 启动服务 → 健康检查 → 浏览器验证

16.1 本地提交代码

git status
git add 需要提交的文件
git commit -m "你的提交说明"
git push

16.2 服务器拉取最新代码

cd /opt/reglow_project
git pull

如果不是 Git 部署，就重新上传压缩包并覆盖代码，但注意不要覆盖 .env 和数据目录。

16.3 发版前备份

mkdir -p backups
set -a
source .env
set +a

docker compose exec -T mysql mysqldump \
  -u$MYSQL_USER \
  -p$MYSQL_PASSWORD \
  $MYSQL_DATABASE > backups/before_release_$(date +%F_%H%M%S).sql

16.4 重新构建并启动

docker compose up -d --build

后端启动时会自动执行：

alembic upgrade head

这意味着数据库表结构会跟随代码升级。

16.5 发版后检查

docker compose ps
curl http://127.0.0.1:8000/health/ready

浏览器检查：

• 登录是否正常；
• 菜单是否正常；
• 员工/角色/菜单/素材等核心页面是否正常；
• 上传是否正常；
• 控制台是否有明显报错。

17. 回滚怎么做

上线失败不可怕，可怕的是没有回滚方案。

17.1 代码回滚

如果用 Git：

cd /opt/reglow_project
git log --oneline -5

找到上一个稳定版本的 commit，然后：

git checkout 上一个稳定commit
docker compose up -d --build

如果你不熟悉 Git 回滚，至少要保留上一个稳定压缩包。

17.2 数据库回滚

数据库回滚要非常谨慎。一般流程：

1. 停止服务；
2. 备份当前坏状态，防止二次事故；
3. 恢复发版前备份；
4. 启动旧代码；
5. 验证业务。

停止服务：

docker compose stop backend frontend

恢复备份后再启动：

docker compose start backend frontend

17.3 为什么数据库回滚更危险

代码像菜单，换回旧菜单比较容易。
数据库像账本，如果新版本已经写入新格式的数据，再强行换旧格式，可能对不上。

所以发版前备份数据库非常重要。

18. 常见故障排查

18.1 页面打不开

检查：

docker compose ps
docker compose logs -f frontend

可能原因：

• 云安全组没开 80；
• frontend 容器没启动；
• 服务器防火墙拦截；
• 域名 DNS 没解析到正确 IP。

18.2 页面打开了，但登录失败

检查后端：

docker compose logs -f backend
curl http://127.0.0.1:8000/health/ready

可能原因：

• backend 没启动；
• MySQL 没健康；
• Redis 没健康；
• .env 的 JWT_SECRET/CORS_ORIGINS 配置错误；
• Nginx 反代路径异常。

18.3 后端启动失败，提示 JWT_SECRET

如果看到类似：

生产环境必须通过环境变量注入 JWT_SECRET

说明你还在用默认密钥。编辑 .env：

vim .env

把 JWT_SECRET 改成随机长字符串，然后：

docker compose up -d --build

18.4 数据库连接失败

检查 MySQL：

docker compose ps mysql
docker compose logs -f mysql

常见原因：

• .env 数据库密码写错；
• 第一次启动 MySQL 初始化未完成；
• 数据卷中已有旧密码，改 .env 不会自动改老数据库密码。

如果是生产数据，不要轻易删 volume。

18.5 Redis 连接失败

检查：

docker compose ps redis
docker compose logs -f redis

Redis 主要影响：

• 验证码；
• 短信验证码；
• 登录/短信限流；
• 字典缓存。

当前代码有内存降级，但生产多实例不建议长期依赖降级。

18.6 上传文件丢了

检查 backend_uploads volume 是否还在：

docker volume ls

不要执行：

docker compose down -v

因为它会删除 volume。

19. 阿里云、腾讯云、华为云的进一步生产化建议

一机 Docker Compose 适合第一阶段上线。业务增长后，可以逐步升级。

19.1 数据库上云托管

为什么用云数据库？

• 自动备份；
• 高可用；
• 监控告警；
• 扩容更方便；
• 不怕你误删 MySQL 容器。

切换方式：

DB_HOST=你的云数据库内网地址
DB_PORT=3306
DB_USER=数据库用户
DB_PASSWORD=数据库密码
DB_NAME=reglow_admin

然后 Compose 可以去掉本地 mysql 服务，或保留但不用。

19.2 Redis 上云托管

修改：

REDIS_URL=redis://:密码@Redis内网地址:6379/0

19.3 上传文件放对象存储

为什么要对象存储？

本地 uploads 像把照片放在店里电脑硬盘。服务器坏了，照片可能没了。对象存储像专门的云相册，有高可靠、多副本、CDN 加速。

当前后端已有 S3 相关配置字段：

STORAGE_BACKEND=s3
S3_ENDPOINT=
S3_ACCESS_KEY=
S3_SECRET_KEY=
S3_BUCKET=
S3_REGION=
CDN_DOMAIN=

是否能直接启用，要以当前素材模块实现为准。上线初期可以先用本地 volume，业务增长后再迁移对象存储。

19.4 使用负载均衡

负载均衡像“门口排队分流员”：

• 可以挂 HTTPS 证书；
• 可以把流量转到多台服务器；
• 可以做健康检查；
• 某台服务器挂了自动摘掉。

初期一台服务器可以不用，访问量上来后再加。

19.5 使用 CDN

前端静态资源、图片素材多时，可以用：

CDN 像把常用文件提前放到离用户更近的小仓库，用户访问更快，也减轻服务器压力。

20. 生产安全清单

上线前逐项检查：

• 服务器安全组只开放 22、80、443；
• 22 端口最好限制自己的 IP；
• MySQL 3306 不开放公网；
• Redis 6379 不开放公网；
• 后端 8000 不直接开放公网，或至少仅限内网；
• .env 中 JWT_SECRET 已改为随机长字符串；
• DEBUG=false；
• CORS_ORIGINS 只填真实域名，不使用 *；
• 已配置 HTTPS；
• 已备份数据库；
• 已确认 uploads 文件有备份策略；
• 管理员默认密码已修改；
• 不把 .env 提交到 Git 仓库；
• 定期更新系统和镜像。

21. 生产运维核心规律总结

21.1 容器可以随便换，数据不能随便动

容器是“外卖盒”，数据是“账本”。
删容器通常没事，删 volume 可能就是事故。

21.2 配置要放环境变量，不要写进代码

代码是公开菜谱，配置是保险柜密码。
密码、密钥、数据库地址都应该通过 .env 管理。

21.3 所有服务都要有健康检查

服务不是“进程在”就等于“能用”。
后端活着但连不上 MySQL，也不能接客。
所以 /health/ready 比 /health 更适合生产探活。

21.4 上线前先备份，出事才能回头

没有备份的上线，就像不带降落伞跳伞。
发版前备份数据库，是最低成本的保险。

21.5 暴露得越少，越安全

公网只开必要入口：80/443。
数据库、Redis、后端内部端口不该直接暴露。

21.6 先简单稳定，再逐步专业化

第一阶段：Docker Compose 单机跑稳。
第二阶段：HTTPS、备份、监控补齐。
第三阶段：云数据库、云 Redis、对象存储、负载均衡、CDN。
第四阶段：CI/CD、多实例、灰度发布。

不要一开始就追求复杂架构。复杂不是高级，稳定才是高级。

22. 推荐上线步骤总清单

1. 购买云服务器
2. 配安全组：22、80、443
3. 绑定域名 DNS
4. SSH 登录服务器
5. 安装 Docker 和 Docker Compose
6. 上传或 git clone 项目代码
7. 复制 .env.docker.example 为 .env
8. 修改数据库密码、JWT_SECRET、CORS_ORIGINS
9. 执行 docker compose up -d --build
10. 查看 docker compose ps
11. 检查 /health/ready
12. 浏览器访问前端
13. 修改默认管理员密码
14. 配置 HTTPS
15. 配置数据库和上传文件备份
16. 记录运维命令和回滚方案

23. 当前项目相关文件索引

24. 最后给小白的一句话

部署不是“把代码丢到服务器上跑起来”这么简单。
真正的生产部署，是让系统在没人盯着的时候也能稳定工作；出了问题能看见、能定位、能恢复。

ReglowAdmin 现在已经具备较好的生产部署基础：Docker Compose、MySQL、Redis、Alembic、Nginx、健康检查、指标接口都已准备好。
你要做的是：把配置填对，把端口管住，把数据备份好，把上线流程固定下来。

做到这四点，小白也能稳稳地把项目上线。