yunrui_asset/docs/docker-deployment-plan.md

Docker 化部署方案

讨论时间: 2026-06-12

一、架构设计

3 个容器

容器	角色	说明
Nginx（含前端）	Web 服务器 + 前端静态文件	serve 前端构建产物，反向代理 /api 到后端
Backend	Node.js 后端服务	Express API 服务
MySQL	数据库	MySQL 8.0

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Nginx 容器   │     │  Backend 容器 │     │  MySQL 容器   │
│              │     │              │     │              │
│  / ──────▶    │     │  Node.js     │     │  数据库       │
│  前端静态文件  │     │  :8000       │     │  :3306       │
│              │────▶│              │────▶│              │
│  /api ────▶   │     │              │     │              │
│  反向代理     │     │              │     │              │
│  :80         │     │              │     │              │
└──────────────┘     └──────────────┘     └──────────────┘

注意：前端不单独占一个容器。前端代码构建成静态文件后，直接打包进 Nginx 镜像中。

---

二、主机需要映射的目录

路径	说明	必要性
backend/.env	核心配置（数据库、JWT、日志等）	必选
backend/uploads/	用户上传文件持久化	必选
backend/logs/	运行日志持久化	必选
backend/backups/	数据库备份文件持久化	必选
backend/temp/	临时文件	可选
mysql_data/	MySQL 数据库文件持久化（Docker 数据卷）	必选

---

三、构建与部署方案

3.1 CI/CD 自动化流程

开发 → git push
         │
         ▼
    GitHub Actions
         │
         ├── 构建 yunrui_asset-backend:latest 镜像
         ├── 构建 yunrui_asset-frontend:latest 镜像（Nginx + 前端静态文件）
         ├── 推送到镜像仓库（Docker Hub / 阿里云 / GitHub Container Registry）
         │
         ▼
    生产服务器
    docker compose pull      # 拉取最新镜像
    docker compose up -d     # 重启容器

3.2 环境区分

环境	docker-compose 文件	镜像来源
开发环境	docker-compose.dev.yml（含 build: 指令）	本地构建
生产环境	docker-compose.prod.yml（用 image: 指令）	从镜像仓库拉取

生产环境的 docker-compose.yml 不写 build:，直接拉取远程镜像：

services:
  backend:
    image: yourname/yunrui_asset-backend:latest
    # 没有 build 指令，直接从仓库拉取

  frontend:
    image: yourname/yunrui_asset-frontend:latest
    # 同上，服务器不需要装 Node.js

  mysql:
    image: mysql:8.0

版本回滚

构建时打版本标签，支持快速回滚：

# 部署新版本
docker compose pull && docker compose up -d

# 回滚到旧版本
BACKEND_VERSION=v1.2.0 FRONTEND_VERSION=v1.2.0 docker compose up -d

---

四、后端关键配置变化

配置项	开发环境（远程 MySQL）	Docker 生产环境
MYSQL_HOST	1p.debian.zhaoyi520.tk	mysql（Docker 服务名）
MYSQL_PORT	33060	3306
JWT_SECRET	自动生成	部署前必须手动配置

注意点

1. JWT_SECRET：生产环境必须在 .env 中预先配置好，因为容器内无法写回只读挂载的 .env
2. 数据库初始化：MySQL 容器首次启动时，后端 sequelize.sync() 会自动建表，无需手动初始化
3. Nginx 反向代理：Nginx 容器内配置 proxy_pass http://backend:8000，用 Docker 服务名通信

已创建的文件（2026-06-12）

文件	说明
backend/Dockerfile	后端镜像构建（Node.js 20 Alpine）
backend/.dockerignore	后端构建忽略配置
frontend/Dockerfile	前端镜像构建（多阶段构建：先 npm build，再 Nginx）
frontend/nginx.conf	Nginx 配置（serve 静态文件 + 反向代理 /api）
frontend/.dockerignore	前端构建忽略配置
docker-compose.dev.yml	开发环境 Compose（含 build: 指令，本地构建）
docker-compose.prod.yml	生产环境 Compose（用 image:，从仓库拉取）

待实现

• .github/workflows/deploy.yml — CI/CD 自动构建推送 ✅ 已完成

五、CI/CD 配置

5.1 镜像仓库：阿里云容器镜像服务

阿里云控制台开通容器镜像服务后：

1. 创建命名空间（如 yunrui-asset）
2. 创建镜像仓库：yunrui_asset-backend、yunrui_asset-frontend
3. 设置访问凭证（用户名 + 密码）

5.2 GitHub Secrets 配置

在 GitHub 仓库 Settings → Secrets and variables → Actions 中配置：

Secret 名称	说明
ALIYUN_USERNAME	阿里云 Docker Registry 用户名
ALIYUN_PASSWORD	阿里云 Docker Registry 密码
ALIYUN_NAMESPACE	阿里云命名空间

5.3 触发条件

• 推送到 master 分支 → 构建 latest 镜像
• 创建 v* 标签（如 v1.0.0）→ 构建对应版本镜像
• 手动触发（Actions 页面 Run workflow）

5.4 镜像标签策略

每次构建会同时打两个标签：

• latest（或 tag 名称）：最新版本
• <commit-sha>：精确回溯到某次提交

5.5 部署流程

开发者：git push origin master
            ↓
   GitHub Actions 自动构建
            ↓
   推送镜像到阿里云仓库
            ↓
   管理员 SSH 到生产服务器
            ↓
   cd /opt/yunrui_assetet
   docker compose -f docker-compose.prod.yml pull
   docker compose -f docker-compose.prod.yml up -d

5.6 已创建文件

• .github/workflows/docker-build.yml — CI/CD 工作流定义
• .env.example — 生产环境 docker-compose 环境变量示例