started / 部署指南 - WlAdmin 文档

WlAdmin

正在加载文档...

文档内容较大，正在处理中，请稍候

1. 构建项目

1. 构建前准备

1.1 检查环境

确保本地开发环境已正确配置：

# 检查 Node.js 版本
node --version
# 应该 >= 20.19.0

# 检查 PNPM 版本
pnpm --version
# 应该 >= 10.24.0

# 检查 Docker（后端构建需要）
docker --version
docker info

1.2 确保代码已提交

# 检查 Git 状态
git status

# 提交代码（可选，但推荐）
git add .
git commit -m "准备部署 v1.0.0"

2. 执行构建

2.1 使用构建脚本（推荐）

项目提供了统一的构建脚本 scripts/build-for-deploy.sh：

# 进入项目根目录
cd /Volumes/Work/Template/project_root

# 构建指定版本
./scripts/build-for-deploy.sh v1.0.0

# 或使用默认版本号（时间戳格式：vYYYYMMDD-HHMMSS）
./scripts/build-for-deploy.sh

2.2 构建脚本功能

构建脚本会自动执行以下操作：

检查依赖：验证 Node.js、PNPM、Docker 是否安装
准备构建目录：在 build-history/日期/时间/ 创建构建目录
构建前端：
- 安装前端依赖
- 生成版本信息文件
- 执行生产构建（pnpm run build）
- 输出到 dist/ 目录
构建后端 Docker 镜像：
- 复制后端源码（排除 node_modules、dist、.git 等）
- 创建 Dockerfile
- 构建 Docker 镜像
- 导出镜像为 .tar 文件
生成版本信息：创建 version-info.txt 和 docker-info.txt
打包文件：创建传输包（不包含 Docker 镜像）

2.3 构建产物说明

构建完成后，会在 build-history/日期/时间/ 目录生成以下文件：

build-history/20241223/143000/
├── backend/                                    # 后端目录
│   ├── project-root-backend-v1.0.0.tar        # Docker镜像文件（约250MB）
│   ├── Dockerfile                              # Docker构建配置
│   ├── package.json                           # 依赖配置
│   ├── index.js                               # 入口文件
│   ├── src/                                   # 源代码目录
│   └── ...                                    # 其他后端文件
├── frontend/                                   # 前端静态文件
│   ├── index.html                             # 入口文件
│   ├── js/                                    # JavaScript文件
│   │   └── [hash]/                            # 带hash的文件名
│   ├── css/                                   # 样式文件
│   │   └── [hash]/                            # 带hash的文件名
│   ├── static/                                # 静态资源
│   ├── assets/                                # 资源文件
│   └── version.json                           # 版本信息文件
├── version-info.txt                            # 版本信息
├── docker-info.txt                            # Docker信息
└── project-root-docker-v1.0.0.tar.gz          # 传输包（前端+配置，不包含Docker镜像）

文件说明：

backend/project-root-backend-v1.0.0.tar：Docker 镜像文件，需要上传到服务器并加载
frontend/：前端静态文件目录，需要上传到服务器
version-info.txt：包含版本号、构建时间、Git 信息等
docker-info.txt：包含 Docker 镜像信息
project-root-docker-v1.0.0.tar.gz：传输包，包含前端文件和配置（不包含 Docker 镜像）

3. 验证构建结果

# 查看构建目录
ls -la build-history/$(date +%Y%m%d)/

# 查看最新构建
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)
echo "最新构建目录: $LATEST_BUILD"

# 查看版本信息
cat "$LATEST_BUILD/version-info.txt"

# 查看 Docker 信息
cat "$LATEST_BUILD/docker-info.txt"

# 验证 Docker 镜像文件
file "$LATEST_BUILD/backend/project-root-backend-v1.0.0.tar"

# 验证前端文件
ls -la "$LATEST_BUILD/frontend/"

4. 构建输出示例

构建成功后会显示：

[2024-12-23 14:30:00] 🎉 构建完成！

版本: v1.0.0

构建产物:
1. 后端镜像: project-root-backend:v1.0.0 ✓
2. 镜像文件: build-history/20241223/143000/backend/project-root-backend-v1.0.0.tar
3. 前端文件: build-history/20241223/143000/frontend/
4. 传输包: build-history/20241223/143000/project-root-docker-v1.0.0.tar.gz

传输命令:
scp build-history/20241223/143000/backend/project-root-backend-v1.0.0.tar root@server:/tmp/
scp -r build-history/20241223/143000/frontend/ root@server:/opt/docker_project/frontend/
scp build-history/20241223/143000/project-root-docker-v1.0.0.tar.gz root@server:/tmp/

历史版本: build-history/20241223/143000/

5. 服务器目录结构

服务器部署目录为 docker_project（上传到服务器后），实际结构如下：

docker_project/                        # 服务器部署主目录
├── docker-compose.yml                 # 统一配置（MySQL + Redis + Backend）
├── nginx.conf                         # Nginx反向代理配置
├── .env                               # 环境变量配置（需要创建）
├── .env.example                       # 环境变量模板
├── docker-compose/                   # 数据目录（MySQL + Redis）
│   ├── db-data/                      # MySQL数据目录
│   │   ├── conf/                     # MySQL配置
│   │   ├── data/                     # MySQL数据文件
│   │   └── logs/                     # MySQL日志
│   └── redis-data/                   # Redis数据目录
│       ├── conf/redis.conf           # Redis配置
│       └── data/                     # Redis数据文件
│
├── frontend/                          # 前端静态文件（版本管理）
│   ├── versions/                     # 版本存储目录
│   │   ├── v1.0.0/                  # 版本v1.0.0
│   │   │   ├── index.html           # 入口文件
│   │   │   ├── js/                  # JavaScript文件
│   │   │   ├── css/                 # 样式文件
│   │   │   ├── static/              # 静态资源
│   │   │   └── assets/              # 资源文件
│   │   ├── v1.0.1/                  # 其他版本...
│   │   └── v1.0.2/                  # 其他版本...
│   ├── backups/                      # 前端备份目录
│   │   ├── v1.0.0/                  # 备份版本
│   │   └── v1.0.1/                  # 备份版本...
│   ├── current -> versions/v1.0.2   # 当前版本软链接
│   └── protect/                      # 受保护目录（SSL证书等）
│       ├── ssl/                      # SSL证书
│       └── auth/                     # 认证文件

├── backup/                           # 部署备份文件目录
│   ├── 20251208/                     # 日期目录
│   │   ├── 153826/                  # 时间目录
│   │   │   ├── backend/             # 后端构建产物
│   │   │   │   └── *.tar             # Docker镜像文件
│   │   │   ├── frontend/            # 前端构建产物
│   │   │   └── version-info.txt     # 版本信息
│   │   └── 201530/                  # 其他时间目录...
│   └── 20251209/                     # 其他日期目录...
│
├── uploads/                           # 上传文件目录（挂载自容器）
│   ├── avatars/                      # 头像
│   ├── chunks/                       # 分片上传
│   ├── files/                        # 普通文件
│   └── sourcemaps/                   # Source Map 文件
│
├── logs/                             # 应用日志目录（挂载自容器）
├── scripts/                          # 部署和维护脚本
│   ├── auto-deploy.sh                # 主要自动化部署脚本（支持完整部署和仅前端部署）
│   ├── manage-frontend-versions.sh   # 前端版本管理脚本（已弃用）
│   ├── backup.sh                     # 系统备份脚本
│   ├── init-git.sh                   # Git 初始化脚本
│   └── manage-webhook.sh             # Webhook管理脚本
│
├── webhook/                          # Gitee Webhook 自动部署服务
│   ├── webhook-server.js             # Webhook 服务器
│   └── package.json                  # Node.js 依赖
│
└── webhook/                          # Gitee Webhook 自动部署服务
    ├── webhook-server.js             # Webhook 服务器
    ├── package.json                  # Node.js 依赖
    └── webhook-ecosystem.config.cjs  # PM2配置

2. 手动部署

1. 服务器环境准备

1.1 系统要求

操作系统：Ubuntu 20.04+ / CentOS 8+ / Debian 11+
内存：2GB+（推荐 4GB+）
磁盘空间：20GB+（推荐 50GB+）
网络：开放 80、22、8888、3306、6379 端口

1.2 安装 Docker 和 Docker Compose

# 安装 Docker
curl -fsSL https://get.docker.com | sh
systemctl start docker
systemctl enable docker

# 安装 Docker Compose
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# 验证安装
docker --version
docker compose --version

1.3 创建项目目录

# 创建项目主目录
mkdir -p /opt/docker_project
cd /opt/docker_project

# 创建必要的子目录
mkdir -p {frontend/{versions,backups},uploads,logs,backup,scripts}

1.4 上传部署文件

将本地 docker_project/ 目录上传到服务器：

# 在本地执行
cd /Volumes/Work/Template/project_root

# 上传部署配置文件
scp docker_project/docker-compose.yml root@your-server:/opt/docker_project/
scp docker_project/nginx.conf root@your-server:/opt/docker_project/ 2>/dev/null || true

# 上传数据目录（如果已存在数据，需要保留）
# 注意：统一配置后，docker-compose/ 目录仅用于存储数据，不再包含 docker-compose.yml
scp -r docker_project/docker-compose/ root@your-server:/opt/docker_project/ 2>/dev/null || true

# 上传部署脚本
scp -r docker_project/scripts/ root@your-server:/opt/docker_project/
chmod +x /opt/docker_project/scripts/*.sh

2. 配置环境变量

2.1 创建环境变量文件

# 登录服务器
ssh root@your-server

# 进入项目目录
cd /opt/docker_project

# 创建 .env 文件（如果不存在）
touch .env

2.2 配置环境变量

编辑 .env 文件，配置以下变量：

# ==================== 项目配置 ====================
PROJECT_NAME=project-root
BACKEND_VERSION=v1.0.0

# ==================== 应用配置 ====================
PORT=8888
NODE_ENV=production

# ==================== 数据库配置（生产环境）====================
DB_PRO_HOST=mysql-8
DB_PRO_PORT=3306
DB_PRO_USER=root
DB_PRO_PASSWORD=your_secure_mysql_password
DB_PRO_NAME=wladmin

# ==================== Redis 配置（生产环境）====================
PRO_REDIS_HOST=redis-7
PRO_REDIS_PORT=6379
PRO_REDIS_PASSWORD=your_secure_redis_password
PRO_REDIS_DB=0
PRO_CACHE_KEY_PREFIX=wladmin:
PRO_CACHE_KEY_SUFFIX=:cache

# ==================== JWT 配置 ====================
PRO_JWT_SECRET=your_32_character_jwt_secret_key
PRO_REFRESH_SECRET=your_32_character_refresh_secret_key
PRO_SESSION_SECRET=your_32_character_session_secret_key

# ==================== 其他配置 ====================
PRO_BASE_URL=https://your-domain.com
CACHE_TYPE=redis
LOG_LEVEL=info
ENABLE_SOURCEMAP_DEBUG=false
IS_SUPER_ADMIN_EDIT=false
SINGLE_LOGIN=on

# ==================== MySQL 基础设施配置 ====================
MYSQL_ROOT_PASSWORD=your_secure_mysql_password
MYSQL_DATABASE=wladmin
MYSQL_USER=wladmin_user
MYSQL_PASSWORD=your_mysql_user_password
MYSQL_TCP_PORT=3306

⚠️ 安全提示：

所有密码请使用强密码（至少 12 位，包含大小写字母、数字和特殊字符）
JWT 密钥建议使用 32 位以上随机字符串
不要使用默认密码
生产环境建议使用密码管理工具生成和管理密钥

3. 启动所有服务（统一配置）

⚠️ 重要：项目已使用统一配置，所有服务（MySQL、Redis、Backend）在一个 docker-compose.yml 文件中。

统一配置的优势：

✅ 简化部署：只需一个命令启动所有服务
✅ 自动启动顺序：使用 depends_on 确保 MySQL 和 Redis 先启动
✅ 网络自动管理：Docker Compose 自动创建和管理网络
✅ 配置更稳定：数据库和 Redis 主机已硬编码为容器名称，避免 IP 变化问题

# 进入项目目录
cd /opt/docker_project

# 启动所有服务（MySQL + Redis + Backend）
docker compose up -d

# 等待服务启动（约60秒，因为需要等待 MySQL 和 Redis 健康检查通过）
sleep 60

# 检查服务状态
docker compose ps

# 应该看到三个服务都在运行：
# NAME                    STATUS          PORTS
# project-root-backend    Up X seconds    0.0.0.0:8888->8888/tcp
# mysql-8                 Up X minutes    0.0.0.0:3306->3306/tcp
# redis-7                 Up X minutes    0.0.0.0:6379->6379/tcp

# 查看服务日志
docker compose logs -f

服务启动顺序：

MySQL 和 Redis 先启动（基础设施服务）
等待 MySQL 和 Redis 健康检查通过
后端服务自动启动（依赖 MySQL 和 Redis）

4. 初始化数据库（首次部署）

# 确保数据库初始化脚本已上传到服务器
# 脚本位置：sql/sqlinit/

# 进入项目目录
cd /opt/docker_project

# 执行数据库初始化（按顺序）
docker compose exec -T mysql-8 mysql -u root -p"${MYSQL_ROOT_PASSWORD:-${DB_PRO_PASSWORD}}" "${MYSQL_DATABASE:-${DB_PRO_NAME}}" < /path/to/建表.sql
docker compose exec -T mysql-8 mysql -u root -p"${MYSQL_ROOT_PASSWORD:-${DB_PRO_PASSWORD}}" "${MYSQL_DATABASE:-${DB_PRO_NAME}}" < /path/to/监控数据相关表.sql
docker compose exec -T mysql-8 mysql -u root -p"${MYSQL_ROOT_PASSWORD:-${DB_PRO_PASSWORD}}" "${MYSQL_DATABASE:-${DB_PRO_NAME}}" < /path/to/省市区数据.sql
docker compose exec -T mysql-8 mysql -u root -p"${MYSQL_ROOT_PASSWORD:-${DB_PRO_PASSWORD}}" "${MYSQL_DATABASE:-${DB_PRO_NAME}}" < /path/to/预制数据.sql

# 验证数据库初始化
docker compose exec mysql-8 mysql -u root -p"${MYSQL_ROOT_PASSWORD:-${DB_PRO_PASSWORD}}" "${MYSQL_DATABASE:-${DB_PRO_NAME}}" -e "SHOW TABLES;"

6. 上传构建产物

6.1 上传后端 Docker 镜像

# 在本地执行
cd /Volumes/Work/Template/project_root

# 找到最新构建目录
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)

# 上传 Docker 镜像文件
scp "$LATEST_BUILD/backend/project-root-backend-v1.0.0.tar" root@your-server:/tmp/

6.2 上传前端文件

# 上传前端静态文件到 backup 目录（用于自动部署脚本识别）
scp -r "$LATEST_BUILD/frontend" root@your-server:/opt/docker_project/backup/

# 或上传到指定时间目录（推荐）
scp -r "$LATEST_BUILD" root@your-server:/opt/docker_project/backup/

上传后的目录结构：

/opt/docker_project/backup/
├── 20241223/                              # 日期目录
│   └── 143000/                           # 时间目录
│       ├── backend/                      # 后端构建产物
│       │   └── project-root-backend-v1.0.0.tar
│       ├── frontend/                     # 前端静态文件
│       │   ├── index.html
│       │   ├── js/
│       │   ├── css/
│       │   └── ...
│       └── version-info.txt              # 版本信息

7. 部署后端服务

7.1 加载 Docker 镜像

# 登录服务器
ssh root@your-server

# 加载 Docker 镜像
docker load -i /tmp/project-root-backend-v1.0.0.tar

# 验证镜像加载成功
docker images | grep project-root-backend

# 应该能看到：
# project-root-backend   v1.0.0    xxx    xxx    xxx
# project-root-backend   latest    xxx    xxx    xxx

7.2 更新环境变量版本号

# 进入项目目录
cd /opt/docker_project

# 备份当前 .env 文件
cp .env .env.backup.$(date +%Y%m%d_%H%M%S)

# 更新 BACKEND_VERSION
sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=v1.0.0/" .env

# 或手动编辑
vim .env
# 修改 BACKEND_VERSION=v1.0.0

# 验证版本更新
grep "BACKEND_VERSION" .env

7.3 启动后端服务

# 启动应用服务
docker compose up -d

# 检查服务状态
docker compose ps

# 查看服务日志
docker compose logs -f backend

# 等待服务启动（约30秒）
sleep 30

# 检查服务健康状态
curl -f http://localhost:8888/health

8. 部署前端文件

8.1 部署前端到版本目录

# 进入项目目录
cd /opt/docker_project

# 找到最新的前端构建目录
LATEST_FRONTEND=$(find backup -type d -name "frontend" | head -1)
echo "找到前端目录: $LATEST_FRONTEND"

# 从 version-info.txt 读取版本号（如果存在）
VERSION=$(grep "^版本:" backup/*/version-info.txt 2>/dev/null | head -1 | sed 's/版本: //' | tr -d '[:space:]' || echo "v1.0.0")
echo "版本号: $VERSION"

# 创建版本目录
VERSION_DIR="/opt/docker_project/frontend/versions/$VERSION"
mkdir -p "$VERSION_DIR"

# 复制前端文件到版本目录
cp -r "$LATEST_FRONTEND"/* "$VERSION_DIR/"

# 同步受保护目录内容（SSL证书、认证文件等，如果存在）
if [ -d "/opt/docker_project/frontend/protect" ] && [ "$(ls -A /opt/docker_project/frontend/protect)" ]; then
    rsync -av /opt/docker_project/frontend/protect/ "$VERSION_DIR/" 2>/dev/null
fi

# 验证前端文件复制成功
ls -la "$VERSION_DIR/"

8.2 更新前端软链接

# 进入前端目录
cd /opt/docker_project/frontend

# 备份当前版本（如果存在）
if [ -L current ]; then
    CURRENT_VERSION=$(readlink current)
    BACKUP_DIR="/opt/docker_project/frontend/backups/$(basename $CURRENT_VERSION)_backup_$(date +%Y%m%d_%H%M%S)"
    mkdir -p /opt/docker_project/frontend/backups
    if [ -d "$CURRENT_VERSION" ]; then
        cp -r "$CURRENT_VERSION" "$BACKUP_DIR"
        echo "当前版本已备份: $BACKUP_DIR"
    fi
fi

# 删除现有软链接
rm -f current

# 创建新的软链接指向新版本
ln -s "versions/$VERSION" current

# 验证软链接创建成功
ls -la current
readlink current

8.3 配置 Nginx（如果使用）

# 检查 Nginx 配置
nginx -t

# 如果使用 Nginx，确保配置指向前端目录
# 编辑 Nginx 配置
vim /etc/nginx/sites-available/default

# 确保 root 指向：
# root /opt/docker_project/frontend/current;

# 重启 Nginx
systemctl restart nginx

# 检查 Nginx 状态
systemctl status nginx

9. 设置文件权限

# 设置上传目录权限（重要）
chown -R 1000:1000 /opt/docker_project/uploads
chmod -R 755 /opt/docker_project/uploads

# 设置日志目录权限
chown -R 1000:1000 /opt/docker_project/logs
chmod -R 755 /opt/docker_project/logs

# 设置前端目录权限
chown -R www-data:www-data /opt/docker_project/frontend 2>/dev/null || true
chmod -R 755 /opt/docker_project/frontend

# 验证权限设置
ls -la /opt/docker_project/uploads/
ls -la /opt/docker_project/frontend/

3. 自动部署

项目提供了完整的自动部署方案，支持从本地构建到服务器部署的一键自动化流程。

1. 自动部署概述

自动部署方案包含两个脚本：

本地脚本（scripts/auto-deploy.sh）：本地构建 + 上传到服务器
服务器脚本（docker_project/scripts/auto-deploy.sh）：服务器端自动部署

自动部署流程：

本地开发环境
    │
    ├── 1. 执行构建脚本
    │   └── ./scripts/build-for-deploy.sh v1.0.0
    │
    ├── 2. 上传构建产物到服务器
    │   └── scp build-history/.../ root@server:/opt/docker_project/backup/
    │
    └── 3. 执行服务器自动部署
        └── ssh root@server "./scripts/auto-deploy.sh deploy v1.0.0"
                │
                ├── 自动检测 backup 目录中的最新构建
                ├── 加载 Docker 镜像
                ├── 部署前端文件（版本管理）
                ├── 更新环境变量
                ├── 重启服务
                └── 健康检查

2. 服务器端自动部署

2.1 自动部署脚本功能

服务器端自动部署脚本位于 /opt/docker_project/scripts/auto-deploy.sh，支持以下功能：

✅ 自动检测构建文件：从 backup/ 目录自动检测最新构建
✅ Docker 镜像管理：自动加载、清理旧镜像
✅ 前端版本管理：自动备份、部署、软链接切换
✅ 服务管理：自动重启 Docker 服务
✅ 健康检查：自动验证部署结果
✅ 版本回滚：支持快速回滚到历史版本
✅ 日志记录：完整的部署日志记录

2.2 自动部署命令

完整部署（前端 + 后端）：

# 登录服务器
ssh root@your-server

# 进入项目目录
cd /opt/docker_project

# 完整部署（自动检测版本号）
./scripts/auto-deploy.sh deploy

# 部署指定版本
./scripts/auto-deploy.sh deploy v1.0.0

仅前端部署：

# 仅部署前端（自动检测版本号）
./scripts/auto-deploy.sh deploy-frontend

# 部署指定版本的前端
./scripts/auto-deploy.sh deploy-frontend v1.0.1

查看部署状态：

# 查看完整的部署状态
./scripts/auto-deploy.sh status

# 输出包括：
# - 最后后端镜像
# - 最后前端版本
# - 当前前端版本信息
# - backup 目录状态
# - 服务状态
# - API 健康状态
# - 前端访问状态

版本回滚：

# 回滚到上一个版本（从备份中恢复）
./scripts/auto-deploy.sh rollback

# 回滚到指定版本
./scripts/auto-deploy.sh rollback v1.0.0

# 查看可用的备份版本
ls -la /opt/docker_project/frontend/backups/

清理旧版本：

# 清理旧版本（保留最近 5 个）
./scripts/auto-deploy.sh cleanup

# 清理旧版本并清空 backup 目录
./scripts/auto-deploy.sh cleanup --cleanup-backup

健康检查：

# 执行健康检查
./scripts/auto-deploy.sh health

# 检查项目：
# - 后端 API 健康状态
# - 前端访问状态
# - Docker 容器状态

查看部署日志：

# 实时查看部署日志
./scripts/auto-deploy.sh logs

# 或直接查看日志文件
tail -f /opt/docker_project/logs/deploy.log

查看帮助：

# 查看完整的命令帮助
./scripts/auto-deploy.sh help

2.3 自动部署脚本命令列表

命令	说明	使用示例
`deploy [版本]`	完整部署（前端+后端）	`./scripts/auto-deploy.sh deploy v1.0.0`
`deploy-frontend [版本]`	仅部署前端	`./scripts/auto-deploy.sh deploy-frontend v1.0.1`
`status`	查看部署状态	`./scripts/auto-deploy.sh status`
`rollback [版本]`	回滚到指定版本	`./scripts/auto-deploy.sh rollback v1.0.0`
`cleanup`	清理旧版本	`./scripts/auto-deploy.sh cleanup`
`cleanup --cleanup-backup`	清理并清空 backup 目录	`./scripts/auto-deploy.sh cleanup --cleanup-backup`
`health`	执行健康检查	`./scripts/auto-deploy.sh health`
`logs`	查看部署日志	`./scripts/auto-deploy.sh logs`
`help`	显示帮助信息	`./scripts/auto-deploy.sh help`

2.4 自动部署流程说明

完整部署流程（deploy）：

检查工具：验证 Docker 和 Docker Compose 是否安装
检查 backup 目录：自动检测最新构建文件
备份当前前端版本：自动备份到 frontend/backups/
加载 Docker 镜像：从 backup/backend/*.tar 加载镜像
部署前端文件：
- 从 version-info.txt 读取版本号
- 复制前端文件到 frontend/versions/版本号/
- 更新 current 软链接
- 同步受保护目录内容（SSL 证书等）
部署后端服务：
- 更新 .env 文件中的 BACKEND_VERSION
- 停止旧服务
- 启动新服务
健康检查：验证 API 和前端访问
清理旧版本：自动清理旧的前端版本（保留最近 5 个）

仅前端部署流程（deploy-frontend）：

检查 backup 目录：检测前端构建文件
备份当前前端版本：自动备份
部署前端文件：复制文件、更新软链接
重启 Nginx：自动重启 Nginx 服务使配置生效
跳过后端部署：不加载 Docker 镜像，不重启后端服务

3. 本地到服务器自动部署

3.1 本地自动部署脚本

项目根目录提供了本地自动部署脚本 scripts/auto-deploy.sh，支持从本地构建到服务器部署的完整流程。

基本使用：

# 进入项目根目录
cd /Volumes/Work/Template/project_root

# 自动构建 + 部署到服务器（使用默认服务器）
./scripts/auto-deploy.sh v1.0.0

# 部署到指定服务器
./scripts/auto-deploy.sh -s root@192.168.1.100 v1.0.1

# 仅构建不上传
./scripts/auto-deploy.sh -b v1.0.2

# 本地模式（不部署到服务器）
./scripts/auto-deploy.sh -l v1.0.0

脚本功能：

本地构建：自动调用 build-for-deploy.sh 构建项目
上传文件：自动上传构建产物到服务器
执行部署：自动在服务器执行部署脚本
版本管理：自动管理版本号和部署历史

3.2 完整自动部署流程

步骤 1：本地构建

# 在项目根目录执行
cd /Volumes/Work/Template/project_root

# 构建指定版本
./scripts/build-for-deploy.sh v1.0.0

步骤 2：上传构建产物

# 找到最新构建目录
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)

# 上传到服务器 backup 目录
scp -r "$LATEST_BUILD" root@your-server:/opt/docker_project/backup/

步骤 3：执行自动部署

# 登录服务器
ssh root@your-server

# 进入项目目录
cd /opt/docker_project

# 执行自动部署
./scripts/auto-deploy.sh deploy v1.0.0

3.3 一键自动部署（推荐）

方式一：使用本地脚本（自动构建 + 上传 + 部署）

# 在项目根目录执行
cd /Volumes/Work/Template/project_root

# 自动构建 + 上传 + 部署（需要配置服务器地址）
./scripts/auto-deploy.sh -s root@your-server v1.0.0

方式二：手动上传 + 自动部署

# 1. 本地构建
./scripts/build-for-deploy.sh v1.0.0

# 2. 上传构建产物
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)
scp -r "$LATEST_BUILD" root@your-server:/opt/docker_project/backup/

# 3. 执行服务器自动部署
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh deploy v1.0.0"

4. 自动部署特性

4.1 智能版本检测

自动部署脚本支持多种版本号获取方式（按优先级）：

命令行指定版本号：./scripts/auto-deploy.sh deploy v1.0.0
version-info.txt 文件：从构建产物中的 version-info.txt 读取
package.json 版本：从 package.json 读取 version 字段
时间戳版本：如果以上都不可用，使用时间戳作为版本号

4.2 自动备份机制

前端版本自动备份：部署新版本前自动备份当前版本
备份位置：frontend/backups/版本号/
备份用途：支持快速回滚到历史版本

4.3 零停机部署

前端零停机：通过软链接切换实现零停机部署
后端平滑重启：先停止旧服务，再启动新服务
健康检查：部署后自动验证服务健康状态

4.4 自动清理机制

保留最近 5 个版本：自动清理旧的前端版本
清理旧镜像：自动清理未使用的 Docker 镜像
可选清理 backup：支持清理 backup/ 目录释放空间

5. 自动部署最佳实践

5.1 部署前检查清单

# 1. 检查服务器连接
ssh root@your-server "echo '连接成功'"

# 2. 检查服务器磁盘空间
ssh root@your-server "df -h"

# 3. 检查 Docker 服务状态
ssh root@your-server "docker ps"

# 4. 检查 backup 目录
ssh root@your-server "ls -la /opt/docker_project/backup/"

5.2 部署流程建议

# 1. 本地构建并验证
./scripts/build-for-deploy.sh v1.0.0

# 2. 查看构建产物
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)
ls -la "$LATEST_BUILD/"

# 3. 上传到服务器
scp -r "$LATEST_BUILD" root@your-server:/opt/docker_project/backup/

# 4. 查看服务器状态
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh status"

# 5. 执行部署
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh deploy v1.0.0"

# 6. 验证部署结果
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh health"

5.3 回滚流程

# 如果部署出现问题，快速回滚

# 1. 查看可用备份版本
ssh root@your-server "ls -la /opt/docker_project/frontend/backups/"

# 2. 回滚到指定版本
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh rollback v1.0.0"

# 3. 验证回滚结果
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh status"

5.4 定期维护

# 定期清理旧版本（建议每周执行一次）
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh cleanup"

# 清理并清空 backup 目录（释放空间）
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh cleanup --cleanup-backup"

6. 自动部署与手动部署对比

特性	自动部署	手动部署
部署速度	快速（一键完成）	较慢（需要多步操作）
错误率	低（自动化减少人为错误）	较高（手动操作易出错）
版本管理	自动备份和回滚	需要手动管理
日志记录	完整的部署日志	需要手动记录
适用场景	生产环境、频繁部署	首次部署、特殊配置
灵活性	标准化流程	高度灵活

建议：

✅ 生产环境：使用自动部署，提高效率和可靠性
✅ 开发/测试环境：可以使用手动部署，便于调试
✅ 首次部署：建议先手动部署一次，熟悉流程后再使用自动部署

4. 部署验证

1. 检查服务状态

# 检查 Docker 容器状态
docker compose ps

# 应该看到：
# NAME                    STATUS          PORTS
# project-root-backend    Up X seconds    0.0.0.0:8888->8888/tcp
# mysql-8                 Up X minutes    0.0.0.0:3306->3306/tcp
# redis-7                 Up X minutes    0.0.0.0:6379->6379/tcp

# 检查服务日志
docker compose logs backend
docker compose logs mysql
docker compose logs redis

2. 检查服务健康

# 检查后端 API 健康状态
curl -f http://localhost:8888/health

# 应该返回：
# {"status":"ok"}

# 检查前端访问
curl -I http://localhost/

# 应该返回：
# HTTP/1.1 200 OK

3. 检查端口监听

# 检查端口监听状态
netstat -tlnp | grep :80      # 前端（Nginx）
netstat -tlnp | grep :8888    # 后端 API
netstat -tlnp | grep :3306    # MySQL
netstat -tlnp | grep :6379    # Redis

4. 检查前端版本

# 查看当前前端版本
ls -la /opt/docker_project/frontend/current

# 查看版本信息文件（如果存在）
cat /opt/docker_project/frontend/current/version.json 2>/dev/null || echo "版本文件不存在"

5. 访问应用

部署成功后，可以通过以下地址访问：

🌐 前端：http://your-server-ip 或 https://your-domain.com
🚀 后端 API：http://your-server-ip:8888
📖 API 文档：http://your-server-ip:8888/api/docs/（如果配置了 Swagger）

5. 常见问题

Q1: Docker 镜像加载失败

错误信息：open /tmp/project-root-backend-v1.0.0.tar: no such file or directory

解决：

# 检查文件是否存在
ls -lh /tmp/project-root-backend-v1.0.0.tar

# 检查磁盘空间
df -h

# 重新上传文件
scp build-history/.../backend/project-root-backend-v1.0.0.tar root@server:/tmp/

Q2: 后端服务启动失败

错误信息：Cannot connect to the Docker daemon

解决：

# 检查 Docker 服务状态
systemctl status docker

# 启动 Docker 服务
systemctl start docker

# 检查 Docker 网络
docker network ls
docker network create docker_project_app-network

Q3: 数据库连接失败（生产环境）

错误信息：connect EHOSTUNREACH 172.29.0.2:3306 或 ECONNREFUSED

问题现象：

应用无法连接到数据库，错误信息：

connect EHOSTUNREACH 172.29.0.2:3306
code: EHOSTUNREACH
errno: -113

原因分析：

EHOSTUNREACH 表示目标主机不可达，常见原因：

数据库配置使用了错误的 IP 地址（最常见）⭐
- 配置中使用了 172.29.0.2，但实际数据库 IP 是 172.29.0.3
- Docker 容器重启后 IP 地址可能变化
数据库容器未启动
Docker 网络配置问题（容器不在同一网络）
防火墙或安全组阻止连接
数据库配置错误（主机地址、端口、用户名、密码）

📋 项目架构说明：

本项目使用统一配置的 docker-compose.yml：

docker-compose.yml（根目录）- 统一配置所有服务
- MySQL 容器名：mysql-8
- Redis 容器名：redis-7
- 后端容器名：project-root-backend
- 网络：docker_project_app-network（自动创建和管理）

统一配置的优势：

✅ 简化部署：只需一个命令启动所有服务
✅ 自动启动顺序：使用 depends_on 确保 MySQL 和 Redis 先启动并健康检查通过
✅ 网络自动管理：Docker Compose 自动创建和管理网络，无需手动创建
✅ 配置更稳定：数据库和 Redis 主机已硬编码为容器名称（mysql-8、redis-7），避免 IP 变化问题
✅ 统一管理：所有服务在一个文件中，便于维护和版本控制

重要：

所有服务在同一个 docker-compose.yml 文件中
它们共享同一个 Docker 网络，可以通过容器名称互相访问
修改 .env 文件后，需要重启所有服务（docker compose down && docker compose up -d）
数据库和 Redis 主机配置已硬编码为容器名称，.env 文件中的 DB_PRO_HOST 和 PRO_REDIS_HOST 会被忽略

⚠️ 重要提示：

Docker 容器 IP 地址会变化！

❌ 不要使用 IP 地址：172.29.0.2、172.29.0.3 等
✅ 使用容器名称：mysql、mysql-8 等（Docker 会自动解析）

原因：

Docker 容器重启后，IP 地址可能变化
使用容器名称，Docker DNS 会自动解析到正确的 IP
更稳定、更可靠

排查步骤：

1. 检查数据库容器状态

# 查看所有容器状态
docker ps -a

# 查看数据库容器状态（根据你的容器名称）
docker ps -a | grep mysql
# 或
docker ps -a | grep mariadb
# 或
docker ps -a | grep db

# 应该看到数据库容器状态为 "Up"
# 如果状态为 "Exited"，说明容器已停止

# 如果容器未运行，启动所有服务（统一配置）
cd /opt/docker_project
docker compose up -d

2. 检查 Docker 网络

# 查看所有 Docker 网络
docker network ls

# 查看应用容器使用的网络
docker inspect project-root-backend | grep -A 20 "Networks"

# 查看数据库容器使用的网络
docker inspect mysql-8 | grep -A 20 "Networks"

# 确保两个容器在同一个网络中
docker network inspect docker_project_app-network

3. 检查数据库容器 IP

# 查看数据库容器的 IP 地址
docker inspect mysql-8 | grep IPAddress

# 或者查看网络详情
docker network inspect docker_project_app-network

# 如果 IP 地址不是配置中的 IP，说明配置中的 IP 地址错误

4. 测试网络连通性

# 从应用容器 ping 数据库容器
docker exec project-root-backend ping -c 3 mysql-8

# 测试端口连通性
docker exec project-root-backend nc -zv mysql-8 3306
# 或使用 telnet
docker exec project-root-backend telnet mysql-8 3306

5. 检查数据库配置

# 查看应用的环境变量（数据库配置）
docker exec project-root-backend env | grep -i db
docker exec project-root-backend env | grep -i mysql

# 检查配置文件
cd /opt/docker_project
cat .env | grep -E "DB_PRO_"

# ⚠️ 重要：统一配置中，DB_PRO_HOST 和 PRO_REDIS_HOST 已硬编码为容器名称
# 在 docker-compose.yml 中：
#   DB_PRO_HOST: mysql-8  # ✅ 已硬编码，无需在 .env 中配置
#   PRO_REDIS_HOST: redis-7  # ✅ 已硬编码，无需在 .env 中配置
#
# .env 文件中的 DB_PRO_HOST 和 PRO_REDIS_HOST 会被忽略

解决方案：

方案一：使用容器名称而不是 IP（推荐）

问题： Docker 容器重启后 IP 地址可能变化，使用 IP 地址不稳定。

解决： 使用容器名称作为数据库主机。

# 1. 查看数据库容器名称
docker ps | grep mysql

# 2. 修改数据库配置
cd /opt/docker_project

# 备份当前 .env 文件
cp .env .env.backup.$(date +%Y%m%d_%H%M%S)

# 将数据库主机从 IP 地址改为容器名称
sed -i 's/DB_PRO_HOST=.*/DB_PRO_HOST=mysql-8/' .env

# 3. 验证修改
cat .env | grep DB_PRO_HOST
# 应该显示：DB_PRO_HOST=mysql-8

# 4. ⚠️ 重要：完全重启后端容器使环境变量生效
# ⚠️ 注意：docker restart 不会重新读取 .env 文件！
cd /opt/docker_project
docker compose down
docker compose up -d

# 5. 等待容器启动
sleep 10

# 6. 验证容器内的环境变量（重启后）
docker exec project-root-backend env | grep -E "DB_PRO_HOST"
# 应该显示：DB_PRO_HOST=mysql-8
# ✅ 如果还是显示 IP 地址，说明重启失败，需要检查 docker-compose.yml

# 7. 验证容器名称解析
docker exec project-root-backend ping -c 3 mysql-8
# 应该能 ping 通

# 8. 查看日志（等待几秒后）
docker logs project-root-backend --tail 50
# 应该不再有连接错误

配置说明：

统一配置中，数据库和 Redis 主机已硬编码为容器名称：

# docker-compose.yml 中已硬编码：
environment:
  DB_PRO_HOST: mysql-8  # ✅ 已硬编码，无需在 .env 中配置
  PRO_REDIS_HOST: redis-7  # ✅ 已硬编码，无需在 .env 中配置

.env 文件中的 DB_PRO_HOST 和 PRO_REDIS_HOST 会被忽略，因为 docker-compose.yml 中已硬编码。

如果需要修改数据库或 Redis 主机，需要修改 docker-compose.yml 文件，而不是 .env 文件。

方案二：检查网络配置（统一配置）

统一配置中，网络由 Docker Compose 自动创建和管理：

# 1. 查看 docker-compose.yml 中的网络配置
cd /opt/docker_project
cat docker-compose.yml | grep -A 10 networks

# 2. 检查网络是否存在
docker network ls | grep docker_project_app-network

# 3. 如果网络不存在，Docker Compose 会自动创建
# 只需执行：docker compose up -d

# 4. 查看网络中的容器
docker network inspect docker_project_app-network

方案三：重启所有服务（统一配置）

# 进入项目目录
cd /opt/docker_project

# 完全重启所有服务（统一配置）
docker compose down
docker compose up -d

# 等待服务启动（约60秒）
sleep 60

# 检查服务状态
docker compose ps

方案四：快速修复命令

# 1. 检查数据库容器状态和 IP
docker ps -a | grep -E "mysql|mariadb|db"
docker inspect mysql-8 | grep IPAddress
# 应该看到：IPAddress: 172.29.0.3（或其他 IP）

# 2. 检查应用容器配置的数据库 IP
docker exec project-root-backend env | grep -i db
# 或查看环境变量文件
cd /opt/docker_project
cat .env | grep DB_PRO_HOST

# 3. 修改 .env 文件（使用容器名称而不是 IP）
cd /opt/docker_project
# 备份
cp .env .env.backup.$(date +%Y%m%d_%H%M%S)
# 修改为容器名称
sed -i 's/DB_PRO_HOST=.*/DB_PRO_HOST=mysql-8/' .env

# 4. 验证修改
cat .env | grep DB_PRO_HOST
# 应该显示：DB_PRO_HOST=mysql-8

# 5. 验证容器名称解析（从应用容器测试）
docker exec project-root-backend ping -c 3 mysql-8
# 应该能 ping 通，显示：PING mysql-8 (172.29.0.3)

# 6. 重启应用容器使配置生效
cd /opt/docker_project
docker compose down
docker compose up -d

# 7. 查看应用日志确认连接成功
docker logs project-root-backend --tail 50
# 应该不再看到 EHOSTUNREACH 错误

⚠️ 重要提示：

修改 .env 文件后，必须重启容器才能使环境变量生效！

✅ 使用 docker compose down && docker compose up -d（推荐）
✅ 或使用 docker restart project-root-backend
❌ 仅修改 .env 文件不会自动生效

Redis 连接失败排查：

如果 Redis 连接也失败，使用相同的方法：

# 1. 查看 Redis 容器信息
docker ps -a | grep redis
docker inspect redis-7 | grep -A 5 "Networks"

# 2. 修改 Redis 配置为容器名称
cd /opt/docker_project
sed -i 's/PRO_REDIS_HOST=.*/PRO_REDIS_HOST=redis-7/' .env

# 3. 验证修改
cat .env | grep PRO_REDIS_HOST
# 应该显示：PRO_REDIS_HOST=redis-7

# 4. 重启应用容器
docker compose down
docker compose up -d

# 5. 验证连接
docker logs project-root-backend --tail 30 | grep -i redis

Q4: 前端文件无法访问

解决：

# 检查前端文件是否存在
ls -la /opt/docker_project/frontend/current/

# 检查软链接
ls -la /opt/docker_project/frontend/current
readlink /opt/docker_project/frontend/current

# 手动修复软链接
cd /opt/docker_project/frontend
rm -f current
ln -s versions/v1.0.0 current

# 检查 Nginx 配置
nginx -t
systemctl restart nginx

Q5: 文件上传权限错误

错误信息：EACCES: permission denied, open '/app/data/uploads/...'

解决：

# 设置上传目录权限
chown -R 1000:1000 /opt/docker_project/uploads
chmod -R 755 /opt/docker_project/uploads

# 重启后端服务
docker compose restart backend

Q6: 端口被占用（生产环境）

错误信息：EADDRINUSE: address already in use

原因：服务器端口已被其他进程占用。

解决：

1. 查找占用端口的进程

# 查找占用端口的进程
lsof -i :8888  # 后端 API 端口
lsof -i :3306  # MySQL 端口
lsof -i :6379  # Redis 端口
lsof -i :80    # Nginx 端口

# 或使用 netstat
netstat -tlnp | grep :8888
netstat -tlnp | grep :3306
netstat -tlnp | grep :6379

2. 停止占用端口的服务

# 停止占用端口的进程（替换 <PID> 为实际进程 ID）
kill -9 <PID>

# 如果是 Docker 容器占用，停止容器
docker ps | grep :8888
docker stop <container_id>

3. 修改端口配置

如果无法停止占用端口的进程，可以修改应用端口：

# 修改后端端口（.env 文件）
cd /opt/docker_project
vim .env
# 修改：PORT=8889

# 修改后重启服务
docker compose down
docker compose up -d

4. 检查 Docker 端口映射

# 检查 Docker 容器的端口映射
docker ps --format "table {{.Names}}\t{{.Ports}}"

# 如果端口冲突，修改 docker-compose.yml 中的端口映射

部署完成！ 🎉

1. 构建项目

1. 构建前准备

1.1 检查环境

确保本地开发环境已正确配置：

# 检查 Node.js 版本
node --version
# 应该 >= 20.19.0

# 检查 PNPM 版本
pnpm --version
# 应该 >= 10.24.0

# 检查 Docker（后端构建需要）
docker --version
docker info

1.2 确保代码已提交

# 检查 Git 状态
git status

# 提交代码（可选，但推荐）
git add .
git commit -m "准备部署 v1.0.0"

2. 执行构建

2.1 使用构建脚本（推荐）

项目提供了统一的构建脚本 scripts/build-for-deploy.sh：

# 进入项目根目录
cd /Volumes/Work/Template/project_root

# 构建指定版本
./scripts/build-for-deploy.sh v1.0.0

# 或使用默认版本号（时间戳格式：vYYYYMMDD-HHMMSS）
./scripts/build-for-deploy.sh

2.2 构建脚本功能

构建脚本会自动执行以下操作：

检查依赖：验证 Node.js、PNPM、Docker 是否安装
准备构建目录：在 build-history/日期/时间/ 创建构建目录
构建前端：
- 安装前端依赖
- 生成版本信息文件
- 执行生产构建（pnpm run build）
- 输出到 dist/ 目录
构建后端 Docker 镜像：
- 复制后端源码（排除 node_modules、dist、.git 等）
- 创建 Dockerfile
- 构建 Docker 镜像
- 导出镜像为 .tar 文件
生成版本信息：创建 version-info.txt 和 docker-info.txt
打包文件：创建传输包（不包含 Docker 镜像）

2.3 构建产物说明

构建完成后，会在 build-history/日期/时间/ 目录生成以下文件：

build-history/20241223/143000/
├── backend/                                    # 后端目录
│   ├── project-root-backend-v1.0.0.tar        # Docker镜像文件（约250MB）
│   ├── Dockerfile                              # Docker构建配置
│   ├── package.json                           # 依赖配置
│   ├── index.js                               # 入口文件
│   ├── src/                                   # 源代码目录
│   └── ...                                    # 其他后端文件
├── frontend/                                   # 前端静态文件
│   ├── index.html                             # 入口文件
│   ├── js/                                    # JavaScript文件
│   │   └── [hash]/                            # 带hash的文件名
│   ├── css/                                   # 样式文件
│   │   └── [hash]/                            # 带hash的文件名
│   ├── static/                                # 静态资源
│   ├── assets/                                # 资源文件
│   └── version.json                           # 版本信息文件
├── version-info.txt                            # 版本信息
├── docker-info.txt                            # Docker信息
└── project-root-docker-v1.0.0.tar.gz          # 传输包（前端+配置，不包含Docker镜像）

文件说明：

backend/project-root-backend-v1.0.0.tar：Docker 镜像文件，需要上传到服务器并加载
frontend/：前端静态文件目录，需要上传到服务器
version-info.txt：包含版本号、构建时间、Git 信息等
docker-info.txt：包含 Docker 镜像信息
project-root-docker-v1.0.0.tar.gz：传输包，包含前端文件和配置（不包含 Docker 镜像）

3. 验证构建结果

# 查看构建目录
ls -la build-history/$(date +%Y%m%d)/

# 查看最新构建
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)
echo "最新构建目录: $LATEST_BUILD"

# 查看版本信息
cat "$LATEST_BUILD/version-info.txt"

# 查看 Docker 信息
cat "$LATEST_BUILD/docker-info.txt"

# 验证 Docker 镜像文件
file "$LATEST_BUILD/backend/project-root-backend-v1.0.0.tar"

# 验证前端文件
ls -la "$LATEST_BUILD/frontend/"

4. 构建输出示例

构建成功后会显示：

[2024-12-23 14:30:00] 🎉 构建完成！

版本: v1.0.0

构建产物:
1. 后端镜像: project-root-backend:v1.0.0 ✓
2. 镜像文件: build-history/20241223/143000/backend/project-root-backend-v1.0.0.tar
3. 前端文件: build-history/20241223/143000/frontend/
4. 传输包: build-history/20241223/143000/project-root-docker-v1.0.0.tar.gz

传输命令:
scp build-history/20241223/143000/backend/project-root-backend-v1.0.0.tar root@server:/tmp/
scp -r build-history/20241223/143000/frontend/ root@server:/opt/docker_project/frontend/
scp build-history/20241223/143000/project-root-docker-v1.0.0.tar.gz root@server:/tmp/

历史版本: build-history/20241223/143000/

5. 服务器目录结构

服务器部署目录为 docker_project（上传到服务器后），实际结构如下：

docker_project/                        # 服务器部署主目录
├── docker-compose.yml                 # 统一配置（MySQL + Redis + Backend）
├── nginx.conf                         # Nginx反向代理配置
├── .env                               # 环境变量配置（需要创建）
├── .env.example                       # 环境变量模板
├── docker-compose/                   # 数据目录（MySQL + Redis）
│   ├── db-data/                      # MySQL数据目录
│   │   ├── conf/                     # MySQL配置
│   │   ├── data/                     # MySQL数据文件
│   │   └── logs/                     # MySQL日志
│   └── redis-data/                   # Redis数据目录
│       ├── conf/redis.conf           # Redis配置
│       └── data/                     # Redis数据文件
│
├── frontend/                          # 前端静态文件（版本管理）
│   ├── versions/                     # 版本存储目录
│   │   ├── v1.0.0/                  # 版本v1.0.0
│   │   │   ├── index.html           # 入口文件
│   │   │   ├── js/                  # JavaScript文件
│   │   │   ├── css/                 # 样式文件
│   │   │   ├── static/              # 静态资源
│   │   │   └── assets/              # 资源文件
│   │   ├── v1.0.1/                  # 其他版本...
│   │   └── v1.0.2/                  # 其他版本...
│   ├── backups/                      # 前端备份目录
│   │   ├── v1.0.0/                  # 备份版本
│   │   └── v1.0.1/                  # 备份版本...
│   ├── current -> versions/v1.0.2   # 当前版本软链接
│   └── protect/                      # 受保护目录（SSL证书等）
│       ├── ssl/                      # SSL证书
│       └── auth/                     # 认证文件

├── backup/                           # 部署备份文件目录
│   ├── 20251208/                     # 日期目录
│   │   ├── 153826/                  # 时间目录
│   │   │   ├── backend/             # 后端构建产物
│   │   │   │   └── *.tar             # Docker镜像文件
│   │   │   ├── frontend/            # 前端构建产物
│   │   │   └── version-info.txt     # 版本信息
│   │   └── 201530/                  # 其他时间目录...
│   └── 20251209/                     # 其他日期目录...
│
├── uploads/                           # 上传文件目录（挂载自容器）
│   ├── avatars/                      # 头像
│   ├── chunks/                       # 分片上传
│   ├── files/                        # 普通文件
│   └── sourcemaps/                   # Source Map 文件
│
├── logs/                             # 应用日志目录（挂载自容器）
├── scripts/                          # 部署和维护脚本
│   ├── auto-deploy.sh                # 主要自动化部署脚本（支持完整部署和仅前端部署）
│   ├── manage-frontend-versions.sh   # 前端版本管理脚本（已弃用）
│   ├── backup.sh                     # 系统备份脚本
│   ├── init-git.sh                   # Git 初始化脚本
│   └── manage-webhook.sh             # Webhook管理脚本
│
├── webhook/                          # Gitee Webhook 自动部署服务
│   ├── webhook-server.js             # Webhook 服务器
│   └── package.json                  # Node.js 依赖
│
└── webhook/                          # Gitee Webhook 自动部署服务
    ├── webhook-server.js             # Webhook 服务器
    ├── package.json                  # Node.js 依赖
    └── webhook-ecosystem.config.cjs  # PM2配置

2. 手动部署

1. 服务器环境准备

1.1 系统要求

操作系统：Ubuntu 20.04+ / CentOS 8+ / Debian 11+
内存：2GB+（推荐 4GB+）
磁盘空间：20GB+（推荐 50GB+）
网络：开放 80、22、8888、3306、6379 端口

1.2 安装 Docker 和 Docker Compose

# 安装 Docker
curl -fsSL https://get.docker.com | sh
systemctl start docker
systemctl enable docker

# 安装 Docker Compose
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# 验证安装
docker --version
docker compose --version

1.3 创建项目目录

# 创建项目主目录
mkdir -p /opt/docker_project
cd /opt/docker_project

# 创建必要的子目录
mkdir -p {frontend/{versions,backups},uploads,logs,backup,scripts}

1.4 上传部署文件

将本地 docker_project/ 目录上传到服务器：

# 在本地执行
cd /Volumes/Work/Template/project_root

# 上传部署配置文件
scp docker_project/docker-compose.yml root@your-server:/opt/docker_project/
scp docker_project/nginx.conf root@your-server:/opt/docker_project/ 2>/dev/null || true

# 上传数据目录（如果已存在数据，需要保留）
# 注意：统一配置后，docker-compose/ 目录仅用于存储数据，不再包含 docker-compose.yml
scp -r docker_project/docker-compose/ root@your-server:/opt/docker_project/ 2>/dev/null || true

# 上传部署脚本
scp -r docker_project/scripts/ root@your-server:/opt/docker_project/
chmod +x /opt/docker_project/scripts/*.sh

2. 配置环境变量

2.1 创建环境变量文件

# 登录服务器
ssh root@your-server

# 进入项目目录
cd /opt/docker_project

# 创建 .env 文件（如果不存在）
touch .env

2.2 配置环境变量

编辑 .env 文件，配置以下变量：

# ==================== 项目配置 ====================
PROJECT_NAME=project-root
BACKEND_VERSION=v1.0.0

# ==================== 应用配置 ====================
PORT=8888
NODE_ENV=production

# ==================== 数据库配置（生产环境）====================
DB_PRO_HOST=mysql-8
DB_PRO_PORT=3306
DB_PRO_USER=root
DB_PRO_PASSWORD=your_secure_mysql_password
DB_PRO_NAME=wladmin

# ==================== Redis 配置（生产环境）====================
PRO_REDIS_HOST=redis-7
PRO_REDIS_PORT=6379
PRO_REDIS_PASSWORD=your_secure_redis_password
PRO_REDIS_DB=0
PRO_CACHE_KEY_PREFIX=wladmin:
PRO_CACHE_KEY_SUFFIX=:cache

# ==================== JWT 配置 ====================
PRO_JWT_SECRET=your_32_character_jwt_secret_key
PRO_REFRESH_SECRET=your_32_character_refresh_secret_key
PRO_SESSION_SECRET=your_32_character_session_secret_key

# ==================== 其他配置 ====================
PRO_BASE_URL=https://your-domain.com
CACHE_TYPE=redis
LOG_LEVEL=info
ENABLE_SOURCEMAP_DEBUG=false
IS_SUPER_ADMIN_EDIT=false
SINGLE_LOGIN=on

# ==================== MySQL 基础设施配置 ====================
MYSQL_ROOT_PASSWORD=your_secure_mysql_password
MYSQL_DATABASE=wladmin
MYSQL_USER=wladmin_user
MYSQL_PASSWORD=your_mysql_user_password
MYSQL_TCP_PORT=3306

⚠️ 安全提示：

所有密码请使用强密码（至少 12 位，包含大小写字母、数字和特殊字符）
JWT 密钥建议使用 32 位以上随机字符串
不要使用默认密码
生产环境建议使用密码管理工具生成和管理密钥

3. 启动所有服务（统一配置）

⚠️ 重要：项目已使用统一配置，所有服务（MySQL、Redis、Backend）在一个 docker-compose.yml 文件中。

统一配置的优势：

✅ 简化部署：只需一个命令启动所有服务
✅ 自动启动顺序：使用 depends_on 确保 MySQL 和 Redis 先启动
✅ 网络自动管理：Docker Compose 自动创建和管理网络
✅ 配置更稳定：数据库和 Redis 主机已硬编码为容器名称，避免 IP 变化问题

# 进入项目目录
cd /opt/docker_project

# 启动所有服务（MySQL + Redis + Backend）
docker compose up -d

# 等待服务启动（约60秒，因为需要等待 MySQL 和 Redis 健康检查通过）
sleep 60

# 检查服务状态
docker compose ps

# 应该看到三个服务都在运行：
# NAME                    STATUS          PORTS
# project-root-backend    Up X seconds    0.0.0.0:8888->8888/tcp
# mysql-8                 Up X minutes    0.0.0.0:3306->3306/tcp
# redis-7                 Up X minutes    0.0.0.0:6379->6379/tcp

# 查看服务日志
docker compose logs -f

服务启动顺序：

MySQL 和 Redis 先启动（基础设施服务）
等待 MySQL 和 Redis 健康检查通过
后端服务自动启动（依赖 MySQL 和 Redis）

4. 初始化数据库（首次部署）

# 确保数据库初始化脚本已上传到服务器
# 脚本位置：sql/sqlinit/

# 进入项目目录
cd /opt/docker_project

# 执行数据库初始化（按顺序）
docker compose exec -T mysql-8 mysql -u root -p"${MYSQL_ROOT_PASSWORD:-${DB_PRO_PASSWORD}}" "${MYSQL_DATABASE:-${DB_PRO_NAME}}" < /path/to/建表.sql
docker compose exec -T mysql-8 mysql -u root -p"${MYSQL_ROOT_PASSWORD:-${DB_PRO_PASSWORD}}" "${MYSQL_DATABASE:-${DB_PRO_NAME}}" < /path/to/监控数据相关表.sql
docker compose exec -T mysql-8 mysql -u root -p"${MYSQL_ROOT_PASSWORD:-${DB_PRO_PASSWORD}}" "${MYSQL_DATABASE:-${DB_PRO_NAME}}" < /path/to/省市区数据.sql
docker compose exec -T mysql-8 mysql -u root -p"${MYSQL_ROOT_PASSWORD:-${DB_PRO_PASSWORD}}" "${MYSQL_DATABASE:-${DB_PRO_NAME}}" < /path/to/预制数据.sql

# 验证数据库初始化
docker compose exec mysql-8 mysql -u root -p"${MYSQL_ROOT_PASSWORD:-${DB_PRO_PASSWORD}}" "${MYSQL_DATABASE:-${DB_PRO_NAME}}" -e "SHOW TABLES;"

6. 上传构建产物

6.1 上传后端 Docker 镜像

# 在本地执行
cd /Volumes/Work/Template/project_root

# 找到最新构建目录
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)

# 上传 Docker 镜像文件
scp "$LATEST_BUILD/backend/project-root-backend-v1.0.0.tar" root@your-server:/tmp/

6.2 上传前端文件

# 上传前端静态文件到 backup 目录（用于自动部署脚本识别）
scp -r "$LATEST_BUILD/frontend" root@your-server:/opt/docker_project/backup/

# 或上传到指定时间目录（推荐）
scp -r "$LATEST_BUILD" root@your-server:/opt/docker_project/backup/

上传后的目录结构：

/opt/docker_project/backup/
├── 20241223/                              # 日期目录
│   └── 143000/                           # 时间目录
│       ├── backend/                      # 后端构建产物
│       │   └── project-root-backend-v1.0.0.tar
│       ├── frontend/                     # 前端静态文件
│       │   ├── index.html
│       │   ├── js/
│       │   ├── css/
│       │   └── ...
│       └── version-info.txt              # 版本信息

7. 部署后端服务

7.1 加载 Docker 镜像

# 登录服务器
ssh root@your-server

# 加载 Docker 镜像
docker load -i /tmp/project-root-backend-v1.0.0.tar

# 验证镜像加载成功
docker images | grep project-root-backend

# 应该能看到：
# project-root-backend   v1.0.0    xxx    xxx    xxx
# project-root-backend   latest    xxx    xxx    xxx

7.2 更新环境变量版本号

# 进入项目目录
cd /opt/docker_project

# 备份当前 .env 文件
cp .env .env.backup.$(date +%Y%m%d_%H%M%S)

# 更新 BACKEND_VERSION
sed -i "s/^BACKEND_VERSION=.*/BACKEND_VERSION=v1.0.0/" .env

# 或手动编辑
vim .env
# 修改 BACKEND_VERSION=v1.0.0

# 验证版本更新
grep "BACKEND_VERSION" .env

7.3 启动后端服务

# 启动应用服务
docker compose up -d

# 检查服务状态
docker compose ps

# 查看服务日志
docker compose logs -f backend

# 等待服务启动（约30秒）
sleep 30

# 检查服务健康状态
curl -f http://localhost:8888/health

8. 部署前端文件

8.1 部署前端到版本目录

# 进入项目目录
cd /opt/docker_project

# 找到最新的前端构建目录
LATEST_FRONTEND=$(find backup -type d -name "frontend" | head -1)
echo "找到前端目录: $LATEST_FRONTEND"

# 从 version-info.txt 读取版本号（如果存在）
VERSION=$(grep "^版本:" backup/*/version-info.txt 2>/dev/null | head -1 | sed 's/版本: //' | tr -d '[:space:]' || echo "v1.0.0")
echo "版本号: $VERSION"

# 创建版本目录
VERSION_DIR="/opt/docker_project/frontend/versions/$VERSION"
mkdir -p "$VERSION_DIR"

# 复制前端文件到版本目录
cp -r "$LATEST_FRONTEND"/* "$VERSION_DIR/"

# 同步受保护目录内容（SSL证书、认证文件等，如果存在）
if [ -d "/opt/docker_project/frontend/protect" ] && [ "$(ls -A /opt/docker_project/frontend/protect)" ]; then
    rsync -av /opt/docker_project/frontend/protect/ "$VERSION_DIR/" 2>/dev/null
fi

# 验证前端文件复制成功
ls -la "$VERSION_DIR/"

8.2 更新前端软链接

# 进入前端目录
cd /opt/docker_project/frontend

# 备份当前版本（如果存在）
if [ -L current ]; then
    CURRENT_VERSION=$(readlink current)
    BACKUP_DIR="/opt/docker_project/frontend/backups/$(basename $CURRENT_VERSION)_backup_$(date +%Y%m%d_%H%M%S)"
    mkdir -p /opt/docker_project/frontend/backups
    if [ -d "$CURRENT_VERSION" ]; then
        cp -r "$CURRENT_VERSION" "$BACKUP_DIR"
        echo "当前版本已备份: $BACKUP_DIR"
    fi
fi

# 删除现有软链接
rm -f current

# 创建新的软链接指向新版本
ln -s "versions/$VERSION" current

# 验证软链接创建成功
ls -la current
readlink current

8.3 配置 Nginx（如果使用）

# 检查 Nginx 配置
nginx -t

# 如果使用 Nginx，确保配置指向前端目录
# 编辑 Nginx 配置
vim /etc/nginx/sites-available/default

# 确保 root 指向：
# root /opt/docker_project/frontend/current;

# 重启 Nginx
systemctl restart nginx

# 检查 Nginx 状态
systemctl status nginx

9. 设置文件权限

# 设置上传目录权限（重要）
chown -R 1000:1000 /opt/docker_project/uploads
chmod -R 755 /opt/docker_project/uploads

# 设置日志目录权限
chown -R 1000:1000 /opt/docker_project/logs
chmod -R 755 /opt/docker_project/logs

# 设置前端目录权限
chown -R www-data:www-data /opt/docker_project/frontend 2>/dev/null || true
chmod -R 755 /opt/docker_project/frontend

# 验证权限设置
ls -la /opt/docker_project/uploads/
ls -la /opt/docker_project/frontend/

3. 自动部署

项目提供了完整的自动部署方案，支持从本地构建到服务器部署的一键自动化流程。

1. 自动部署概述

自动部署方案包含两个脚本：

本地脚本（scripts/auto-deploy.sh）：本地构建 + 上传到服务器
服务器脚本（docker_project/scripts/auto-deploy.sh）：服务器端自动部署

自动部署流程：

本地开发环境
    │
    ├── 1. 执行构建脚本
    │   └── ./scripts/build-for-deploy.sh v1.0.0
    │
    ├── 2. 上传构建产物到服务器
    │   └── scp build-history/.../ root@server:/opt/docker_project/backup/
    │
    └── 3. 执行服务器自动部署
        └── ssh root@server "./scripts/auto-deploy.sh deploy v1.0.0"
                │
                ├── 自动检测 backup 目录中的最新构建
                ├── 加载 Docker 镜像
                ├── 部署前端文件（版本管理）
                ├── 更新环境变量
                ├── 重启服务
                └── 健康检查

2. 服务器端自动部署

2.1 自动部署脚本功能

服务器端自动部署脚本位于 /opt/docker_project/scripts/auto-deploy.sh，支持以下功能：

✅ 自动检测构建文件：从 backup/ 目录自动检测最新构建
✅ Docker 镜像管理：自动加载、清理旧镜像
✅ 前端版本管理：自动备份、部署、软链接切换
✅ 服务管理：自动重启 Docker 服务
✅ 健康检查：自动验证部署结果
✅ 版本回滚：支持快速回滚到历史版本
✅ 日志记录：完整的部署日志记录

2.2 自动部署命令

完整部署（前端 + 后端）：

# 登录服务器
ssh root@your-server

# 进入项目目录
cd /opt/docker_project

# 完整部署（自动检测版本号）
./scripts/auto-deploy.sh deploy

# 部署指定版本
./scripts/auto-deploy.sh deploy v1.0.0

仅前端部署：

# 仅部署前端（自动检测版本号）
./scripts/auto-deploy.sh deploy-frontend

# 部署指定版本的前端
./scripts/auto-deploy.sh deploy-frontend v1.0.1

查看部署状态：

# 查看完整的部署状态
./scripts/auto-deploy.sh status

# 输出包括：
# - 最后后端镜像
# - 最后前端版本
# - 当前前端版本信息
# - backup 目录状态
# - 服务状态
# - API 健康状态
# - 前端访问状态

版本回滚：

# 回滚到上一个版本（从备份中恢复）
./scripts/auto-deploy.sh rollback

# 回滚到指定版本
./scripts/auto-deploy.sh rollback v1.0.0

# 查看可用的备份版本
ls -la /opt/docker_project/frontend/backups/

清理旧版本：

# 清理旧版本（保留最近 5 个）
./scripts/auto-deploy.sh cleanup

# 清理旧版本并清空 backup 目录
./scripts/auto-deploy.sh cleanup --cleanup-backup

健康检查：

# 执行健康检查
./scripts/auto-deploy.sh health

# 检查项目：
# - 后端 API 健康状态
# - 前端访问状态
# - Docker 容器状态

查看部署日志：

# 实时查看部署日志
./scripts/auto-deploy.sh logs

# 或直接查看日志文件
tail -f /opt/docker_project/logs/deploy.log

查看帮助：

# 查看完整的命令帮助
./scripts/auto-deploy.sh help

2.3 自动部署脚本命令列表

命令	说明	使用示例
`deploy [版本]`	完整部署（前端+后端）	`./scripts/auto-deploy.sh deploy v1.0.0`
`deploy-frontend [版本]`	仅部署前端	`./scripts/auto-deploy.sh deploy-frontend v1.0.1`
`status`	查看部署状态	`./scripts/auto-deploy.sh status`
`rollback [版本]`	回滚到指定版本	`./scripts/auto-deploy.sh rollback v1.0.0`
`cleanup`	清理旧版本	`./scripts/auto-deploy.sh cleanup`
`cleanup --cleanup-backup`	清理并清空 backup 目录	`./scripts/auto-deploy.sh cleanup --cleanup-backup`
`health`	执行健康检查	`./scripts/auto-deploy.sh health`
`logs`	查看部署日志	`./scripts/auto-deploy.sh logs`
`help`	显示帮助信息	`./scripts/auto-deploy.sh help`

2.4 自动部署流程说明

完整部署流程（deploy）：

检查工具：验证 Docker 和 Docker Compose 是否安装
检查 backup 目录：自动检测最新构建文件
备份当前前端版本：自动备份到 frontend/backups/
加载 Docker 镜像：从 backup/backend/*.tar 加载镜像
部署前端文件：
- 从 version-info.txt 读取版本号
- 复制前端文件到 frontend/versions/版本号/
- 更新 current 软链接
- 同步受保护目录内容（SSL 证书等）
部署后端服务：
- 更新 .env 文件中的 BACKEND_VERSION
- 停止旧服务
- 启动新服务
健康检查：验证 API 和前端访问
清理旧版本：自动清理旧的前端版本（保留最近 5 个）

仅前端部署流程（deploy-frontend）：

检查 backup 目录：检测前端构建文件
备份当前前端版本：自动备份
部署前端文件：复制文件、更新软链接
重启 Nginx：自动重启 Nginx 服务使配置生效
跳过后端部署：不加载 Docker 镜像，不重启后端服务

3. 本地到服务器自动部署

3.1 本地自动部署脚本

项目根目录提供了本地自动部署脚本 scripts/auto-deploy.sh，支持从本地构建到服务器部署的完整流程。

基本使用：

# 进入项目根目录
cd /Volumes/Work/Template/project_root

# 自动构建 + 部署到服务器（使用默认服务器）
./scripts/auto-deploy.sh v1.0.0

# 部署到指定服务器
./scripts/auto-deploy.sh -s root@192.168.1.100 v1.0.1

# 仅构建不上传
./scripts/auto-deploy.sh -b v1.0.2

# 本地模式（不部署到服务器）
./scripts/auto-deploy.sh -l v1.0.0

脚本功能：

本地构建：自动调用 build-for-deploy.sh 构建项目
上传文件：自动上传构建产物到服务器
执行部署：自动在服务器执行部署脚本
版本管理：自动管理版本号和部署历史

3.2 完整自动部署流程

步骤 1：本地构建

# 在项目根目录执行
cd /Volumes/Work/Template/project_root

# 构建指定版本
./scripts/build-for-deploy.sh v1.0.0

步骤 2：上传构建产物

# 找到最新构建目录
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)

# 上传到服务器 backup 目录
scp -r "$LATEST_BUILD" root@your-server:/opt/docker_project/backup/

步骤 3：执行自动部署

# 登录服务器
ssh root@your-server

# 进入项目目录
cd /opt/docker_project

# 执行自动部署
./scripts/auto-deploy.sh deploy v1.0.0

3.3 一键自动部署（推荐）

方式一：使用本地脚本（自动构建 + 上传 + 部署）

# 在项目根目录执行
cd /Volumes/Work/Template/project_root

# 自动构建 + 上传 + 部署（需要配置服务器地址）
./scripts/auto-deploy.sh -s root@your-server v1.0.0

方式二：手动上传 + 自动部署

# 1. 本地构建
./scripts/build-for-deploy.sh v1.0.0

# 2. 上传构建产物
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)
scp -r "$LATEST_BUILD" root@your-server:/opt/docker_project/backup/

# 3. 执行服务器自动部署
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh deploy v1.0.0"

4. 自动部署特性

4.1 智能版本检测

自动部署脚本支持多种版本号获取方式（按优先级）：

命令行指定版本号：./scripts/auto-deploy.sh deploy v1.0.0
version-info.txt 文件：从构建产物中的 version-info.txt 读取
package.json 版本：从 package.json 读取 version 字段
时间戳版本：如果以上都不可用，使用时间戳作为版本号

4.2 自动备份机制

前端版本自动备份：部署新版本前自动备份当前版本
备份位置：frontend/backups/版本号/
备份用途：支持快速回滚到历史版本

4.3 零停机部署

前端零停机：通过软链接切换实现零停机部署
后端平滑重启：先停止旧服务，再启动新服务
健康检查：部署后自动验证服务健康状态

4.4 自动清理机制

保留最近 5 个版本：自动清理旧的前端版本
清理旧镜像：自动清理未使用的 Docker 镜像
可选清理 backup：支持清理 backup/ 目录释放空间

5. 自动部署最佳实践

5.1 部署前检查清单

# 1. 检查服务器连接
ssh root@your-server "echo '连接成功'"

# 2. 检查服务器磁盘空间
ssh root@your-server "df -h"

# 3. 检查 Docker 服务状态
ssh root@your-server "docker ps"

# 4. 检查 backup 目录
ssh root@your-server "ls -la /opt/docker_project/backup/"

5.2 部署流程建议

# 1. 本地构建并验证
./scripts/build-for-deploy.sh v1.0.0

# 2. 查看构建产物
LATEST_BUILD=$(find build-history -name "version-info.txt" -exec dirname {} \; | sort | tail -1)
ls -la "$LATEST_BUILD/"

# 3. 上传到服务器
scp -r "$LATEST_BUILD" root@your-server:/opt/docker_project/backup/

# 4. 查看服务器状态
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh status"

# 5. 执行部署
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh deploy v1.0.0"

# 6. 验证部署结果
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh health"

5.3 回滚流程

# 如果部署出现问题，快速回滚

# 1. 查看可用备份版本
ssh root@your-server "ls -la /opt/docker_project/frontend/backups/"

# 2. 回滚到指定版本
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh rollback v1.0.0"

# 3. 验证回滚结果
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh status"

5.4 定期维护

# 定期清理旧版本（建议每周执行一次）
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh cleanup"

# 清理并清空 backup 目录（释放空间）
ssh root@your-server "cd /opt/docker_project && ./scripts/auto-deploy.sh cleanup --cleanup-backup"

6. 自动部署与手动部署对比

特性	自动部署	手动部署
部署速度	快速（一键完成）	较慢（需要多步操作）
错误率	低（自动化减少人为错误）	较高（手动操作易出错）
版本管理	自动备份和回滚	需要手动管理
日志记录	完整的部署日志	需要手动记录
适用场景	生产环境、频繁部署	首次部署、特殊配置
灵活性	标准化流程	高度灵活

建议：

✅ 生产环境：使用自动部署，提高效率和可靠性
✅ 开发/测试环境：可以使用手动部署，便于调试
✅ 首次部署：建议先手动部署一次，熟悉流程后再使用自动部署

4. 部署验证

1. 检查服务状态

# 检查 Docker 容器状态
docker compose ps

# 应该看到：
# NAME                    STATUS          PORTS
# project-root-backend    Up X seconds    0.0.0.0:8888->8888/tcp
# mysql-8                 Up X minutes    0.0.0.0:3306->3306/tcp
# redis-7                 Up X minutes    0.0.0.0:6379->6379/tcp

# 检查服务日志
docker compose logs backend
docker compose logs mysql
docker compose logs redis

2. 检查服务健康

# 检查后端 API 健康状态
curl -f http://localhost:8888/health

# 应该返回：
# {"status":"ok"}

# 检查前端访问
curl -I http://localhost/

# 应该返回：
# HTTP/1.1 200 OK

3. 检查端口监听

# 检查端口监听状态
netstat -tlnp | grep :80      # 前端（Nginx）
netstat -tlnp | grep :8888    # 后端 API
netstat -tlnp | grep :3306    # MySQL
netstat -tlnp | grep :6379    # Redis

4. 检查前端版本

# 查看当前前端版本
ls -la /opt/docker_project/frontend/current

# 查看版本信息文件（如果存在）
cat /opt/docker_project/frontend/current/version.json 2>/dev/null || echo "版本文件不存在"

5. 访问应用

部署成功后，可以通过以下地址访问：

🌐 前端：http://your-server-ip 或 https://your-domain.com
🚀 后端 API：http://your-server-ip:8888
📖 API 文档：http://your-server-ip:8888/api/docs/（如果配置了 Swagger）

5. 常见问题

Q1: Docker 镜像加载失败

错误信息：open /tmp/project-root-backend-v1.0.0.tar: no such file or directory

解决：

# 检查文件是否存在
ls -lh /tmp/project-root-backend-v1.0.0.tar

# 检查磁盘空间
df -h

# 重新上传文件
scp build-history/.../backend/project-root-backend-v1.0.0.tar root@server:/tmp/

Q2: 后端服务启动失败

错误信息：Cannot connect to the Docker daemon

解决：

# 检查 Docker 服务状态
systemctl status docker

# 启动 Docker 服务
systemctl start docker

# 检查 Docker 网络
docker network ls
docker network create docker_project_app-network

Q3: 数据库连接失败（生产环境）

错误信息：connect EHOSTUNREACH 172.29.0.2:3306 或 ECONNREFUSED

问题现象：

应用无法连接到数据库，错误信息：

connect EHOSTUNREACH 172.29.0.2:3306
code: EHOSTUNREACH
errno: -113

原因分析：

EHOSTUNREACH 表示目标主机不可达，常见原因：

数据库配置使用了错误的 IP 地址（最常见）⭐
- 配置中使用了 172.29.0.2，但实际数据库 IP 是 172.29.0.3
- Docker 容器重启后 IP 地址可能变化
数据库容器未启动
Docker 网络配置问题（容器不在同一网络）
防火墙或安全组阻止连接
数据库配置错误（主机地址、端口、用户名、密码）

📋 项目架构说明：

本项目使用统一配置的 docker-compose.yml：

docker-compose.yml（根目录）- 统一配置所有服务
- MySQL 容器名：mysql-8
- Redis 容器名：redis-7
- 后端容器名：project-root-backend
- 网络：docker_project_app-network（自动创建和管理）

统一配置的优势：

✅ 简化部署：只需一个命令启动所有服务
✅ 自动启动顺序：使用 depends_on 确保 MySQL 和 Redis 先启动并健康检查通过
✅ 网络自动管理：Docker Compose 自动创建和管理网络，无需手动创建
✅ 配置更稳定：数据库和 Redis 主机已硬编码为容器名称（mysql-8、redis-7），避免 IP 变化问题
✅ 统一管理：所有服务在一个文件中，便于维护和版本控制

重要：

所有服务在同一个 docker-compose.yml 文件中
它们共享同一个 Docker 网络，可以通过容器名称互相访问
修改 .env 文件后，需要重启所有服务（docker compose down && docker compose up -d）
数据库和 Redis 主机配置已硬编码为容器名称，.env 文件中的 DB_PRO_HOST 和 PRO_REDIS_HOST 会被忽略

⚠️ 重要提示：

Docker 容器 IP 地址会变化！

❌ 不要使用 IP 地址：172.29.0.2、172.29.0.3 等
✅ 使用容器名称：mysql、mysql-8 等（Docker 会自动解析）

原因：

Docker 容器重启后，IP 地址可能变化
使用容器名称，Docker DNS 会自动解析到正确的 IP
更稳定、更可靠

排查步骤：

1. 检查数据库容器状态

# 查看所有容器状态
docker ps -a

# 查看数据库容器状态（根据你的容器名称）
docker ps -a | grep mysql
# 或
docker ps -a | grep mariadb
# 或
docker ps -a | grep db

# 应该看到数据库容器状态为 "Up"
# 如果状态为 "Exited"，说明容器已停止

# 如果容器未运行，启动所有服务（统一配置）
cd /opt/docker_project
docker compose up -d

2. 检查 Docker 网络

# 查看所有 Docker 网络
docker network ls

# 查看应用容器使用的网络
docker inspect project-root-backend | grep -A 20 "Networks"

# 查看数据库容器使用的网络
docker inspect mysql-8 | grep -A 20 "Networks"

# 确保两个容器在同一个网络中
docker network inspect docker_project_app-network

3. 检查数据库容器 IP

# 查看数据库容器的 IP 地址
docker inspect mysql-8 | grep IPAddress

# 或者查看网络详情
docker network inspect docker_project_app-network

# 如果 IP 地址不是配置中的 IP，说明配置中的 IP 地址错误

4. 测试网络连通性

# 从应用容器 ping 数据库容器
docker exec project-root-backend ping -c 3 mysql-8

# 测试端口连通性
docker exec project-root-backend nc -zv mysql-8 3306
# 或使用 telnet
docker exec project-root-backend telnet mysql-8 3306

5. 检查数据库配置

# 查看应用的环境变量（数据库配置）
docker exec project-root-backend env | grep -i db
docker exec project-root-backend env | grep -i mysql

# 检查配置文件
cd /opt/docker_project
cat .env | grep -E "DB_PRO_"

# ⚠️ 重要：统一配置中，DB_PRO_HOST 和 PRO_REDIS_HOST 已硬编码为容器名称
# 在 docker-compose.yml 中：
#   DB_PRO_HOST: mysql-8  # ✅ 已硬编码，无需在 .env 中配置
#   PRO_REDIS_HOST: redis-7  # ✅ 已硬编码，无需在 .env 中配置
#
# .env 文件中的 DB_PRO_HOST 和 PRO_REDIS_HOST 会被忽略

解决方案：

方案一：使用容器名称而不是 IP（推荐）

问题： Docker 容器重启后 IP 地址可能变化，使用 IP 地址不稳定。

解决： 使用容器名称作为数据库主机。

# 1. 查看数据库容器名称
docker ps | grep mysql

# 2. 修改数据库配置
cd /opt/docker_project

# 备份当前 .env 文件
cp .env .env.backup.$(date +%Y%m%d_%H%M%S)

# 将数据库主机从 IP 地址改为容器名称
sed -i 's/DB_PRO_HOST=.*/DB_PRO_HOST=mysql-8/' .env

# 3. 验证修改
cat .env | grep DB_PRO_HOST
# 应该显示：DB_PRO_HOST=mysql-8

# 4. ⚠️ 重要：完全重启后端容器使环境变量生效
# ⚠️ 注意：docker restart 不会重新读取 .env 文件！
cd /opt/docker_project
docker compose down
docker compose up -d

# 5. 等待容器启动
sleep 10

# 6. 验证容器内的环境变量（重启后）
docker exec project-root-backend env | grep -E "DB_PRO_HOST"
# 应该显示：DB_PRO_HOST=mysql-8
# ✅ 如果还是显示 IP 地址，说明重启失败，需要检查 docker-compose.yml

# 7. 验证容器名称解析
docker exec project-root-backend ping -c 3 mysql-8
# 应该能 ping 通

# 8. 查看日志（等待几秒后）
docker logs project-root-backend --tail 50
# 应该不再有连接错误

配置说明：

统一配置中，数据库和 Redis 主机已硬编码为容器名称：

# docker-compose.yml 中已硬编码：
environment:
  DB_PRO_HOST: mysql-8  # ✅ 已硬编码，无需在 .env 中配置
  PRO_REDIS_HOST: redis-7  # ✅ 已硬编码，无需在 .env 中配置

.env 文件中的 DB_PRO_HOST 和 PRO_REDIS_HOST 会被忽略，因为 docker-compose.yml 中已硬编码。

如果需要修改数据库或 Redis 主机，需要修改 docker-compose.yml 文件，而不是 .env 文件。

方案二：检查网络配置（统一配置）

统一配置中，网络由 Docker Compose 自动创建和管理：

# 1. 查看 docker-compose.yml 中的网络配置
cd /opt/docker_project
cat docker-compose.yml | grep -A 10 networks

# 2. 检查网络是否存在
docker network ls | grep docker_project_app-network

# 3. 如果网络不存在，Docker Compose 会自动创建
# 只需执行：docker compose up -d

# 4. 查看网络中的容器
docker network inspect docker_project_app-network

方案三：重启所有服务（统一配置）

# 进入项目目录
cd /opt/docker_project

# 完全重启所有服务（统一配置）
docker compose down
docker compose up -d

# 等待服务启动（约60秒）
sleep 60

# 检查服务状态
docker compose ps

方案四：快速修复命令

# 1. 检查数据库容器状态和 IP
docker ps -a | grep -E "mysql|mariadb|db"
docker inspect mysql-8 | grep IPAddress
# 应该看到：IPAddress: 172.29.0.3（或其他 IP）

# 2. 检查应用容器配置的数据库 IP
docker exec project-root-backend env | grep -i db
# 或查看环境变量文件
cd /opt/docker_project
cat .env | grep DB_PRO_HOST

# 3. 修改 .env 文件（使用容器名称而不是 IP）
cd /opt/docker_project
# 备份
cp .env .env.backup.$(date +%Y%m%d_%H%M%S)
# 修改为容器名称
sed -i 's/DB_PRO_HOST=.*/DB_PRO_HOST=mysql-8/' .env

# 4. 验证修改
cat .env | grep DB_PRO_HOST
# 应该显示：DB_PRO_HOST=mysql-8

# 5. 验证容器名称解析（从应用容器测试）
docker exec project-root-backend ping -c 3 mysql-8
# 应该能 ping 通，显示：PING mysql-8 (172.29.0.3)

# 6. 重启应用容器使配置生效
cd /opt/docker_project
docker compose down
docker compose up -d

# 7. 查看应用日志确认连接成功
docker logs project-root-backend --tail 50
# 应该不再看到 EHOSTUNREACH 错误

⚠️ 重要提示：

修改 .env 文件后，必须重启容器才能使环境变量生效！

✅ 使用 docker compose down && docker compose up -d（推荐）
✅ 或使用 docker restart project-root-backend
❌ 仅修改 .env 文件不会自动生效

Redis 连接失败排查：

如果 Redis 连接也失败，使用相同的方法：

# 1. 查看 Redis 容器信息
docker ps -a | grep redis
docker inspect redis-7 | grep -A 5 "Networks"

# 2. 修改 Redis 配置为容器名称
cd /opt/docker_project
sed -i 's/PRO_REDIS_HOST=.*/PRO_REDIS_HOST=redis-7/' .env

# 3. 验证修改
cat .env | grep PRO_REDIS_HOST
# 应该显示：PRO_REDIS_HOST=redis-7

# 4. 重启应用容器
docker compose down
docker compose up -d

# 5. 验证连接
docker logs project-root-backend --tail 30 | grep -i redis

Q4: 前端文件无法访问

解决：

# 检查前端文件是否存在
ls -la /opt/docker_project/frontend/current/

# 检查软链接
ls -la /opt/docker_project/frontend/current
readlink /opt/docker_project/frontend/current

# 手动修复软链接
cd /opt/docker_project/frontend
rm -f current
ln -s versions/v1.0.0 current

# 检查 Nginx 配置
nginx -t
systemctl restart nginx

Q5: 文件上传权限错误

错误信息：EACCES: permission denied, open '/app/data/uploads/...'

解决：

# 设置上传目录权限
chown -R 1000:1000 /opt/docker_project/uploads
chmod -R 755 /opt/docker_project/uploads

# 重启后端服务
docker compose restart backend

Q6: 端口被占用（生产环境）

错误信息：EADDRINUSE: address already in use

原因：服务器端口已被其他进程占用。

解决：

1. 查找占用端口的进程

# 查找占用端口的进程
lsof -i :8888  # 后端 API 端口
lsof -i :3306  # MySQL 端口
lsof -i :6379  # Redis 端口
lsof -i :80    # Nginx 端口

# 或使用 netstat
netstat -tlnp | grep :8888
netstat -tlnp | grep :3306
netstat -tlnp | grep :6379

2. 停止占用端口的服务

# 停止占用端口的进程（替换 <PID> 为实际进程 ID）
kill -9 <PID>

# 如果是 Docker 容器占用，停止容器
docker ps | grep :8888
docker stop <container_id>

3. 修改端口配置

如果无法停止占用端口的进程，可以修改应用端口：

# 修改后端端口（.env 文件）
cd /opt/docker_project
vim .env
# 修改：PORT=8889

# 修改后重启服务
docker compose down
docker compose up -d

4. 检查 Docker 端口映射

# 检查 Docker 容器的端口映射
docker ps --format "table {{.Names}}\t{{.Ports}}"

# 如果端口冲突，修改 docker-compose.yml 中的端口映射

部署完成！ 🎉

1. 构建项目#

1. 构建前准备#

1.1 检查环境#

1.2 确保代码已提交#

2. 执行构建#

2.1 使用构建脚本（推荐）#

2.2 构建脚本功能#

2.3 构建产物说明#

3. 验证构建结果#

4. 构建输出示例#

5. 服务器目录结构#

2. 手动部署#

1. 服务器环境准备#

1.1 系统要求#

1.2 安装 Docker 和 Docker Compose#

1.3 创建项目目录#

1.4 上传部署文件#

2. 配置环境变量#

2.1 创建环境变量文件#

2.2 配置环境变量#

3. 启动所有服务（统一配置）#

4. 初始化数据库（首次部署）#

6. 上传构建产物#

6.1 上传后端 Docker 镜像#

6.2 上传前端文件#

7. 部署后端服务#

7.1 加载 Docker 镜像#

7.2 更新环境变量版本号#

7.3 启动后端服务#

8. 部署前端文件#

8.1 部署前端到版本目录#

8.2 更新前端软链接#

8.3 配置 Nginx（如果使用）#

9. 设置文件权限#

3. 自动部署#

1. 自动部署概述#

2. 服务器端自动部署#

2.1 自动部署脚本功能#

2.2 自动部署命令#

2.3 自动部署脚本命令列表#

2.4 自动部署流程说明#

3. 本地到服务器自动部署#

3.1 本地自动部署脚本#

3.2 完整自动部署流程#

3.3 一键自动部署（推荐）#

4. 自动部署特性#

4.1 智能版本检测#

4.2 自动备份机制#

4.3 零停机部署#

4.4 自动清理机制#

5. 自动部署最佳实践#

5.1 部署前检查清单#

5.2 部署流程建议#

5.3 回滚流程#

5.4 定期维护#

6. 自动部署与手动部署对比#

4. 部署验证#

1. 检查服务状态#

2. 检查服务健康#

3. 检查端口监听#

4. 检查前端版本#

5. 访问应用#

5. 常见问题#

Q1: Docker 镜像加载失败#

Q2: 后端服务启动失败#

Q3: 数据库连接失败（生产环境）#

1. 检查数据库容器状态#

2. 检查 Docker 网络#

3. 检查数据库容器 IP#

4. 测试网络连通性#

5. 检查数据库配置#

方案一：使用容器名称而不是 IP（推荐）#

方案二：检查网络配置（统一配置）#

方案三：重启所有服务（统一配置）#

方案四：快速修复命令#

Q4: 前端文件无法访问#

Q5: 文件上传权限错误#

Q6: 端口被占用（生产环境）#

1. 查找占用端口的进程#

2. 停止占用端口的服务#

1. 构建项目

1. 构建前准备

1.1 检查环境

1.2 确保代码已提交

2. 执行构建

2.1 使用构建脚本（推荐）

2.2 构建脚本功能

2.3 构建产物说明

3. 验证构建结果

4. 构建输出示例

5. 服务器目录结构

2. 手动部署

1. 服务器环境准备

1.1 系统要求

1.2 安装 Docker 和 Docker Compose

1.3 创建项目目录

1.4 上传部署文件

2. 配置环境变量

2.1 创建环境变量文件

2.2 配置环境变量

3. 启动所有服务（统一配置）

4. 初始化数据库（首次部署）

6. 上传构建产物

6.1 上传后端 Docker 镜像

6.2 上传前端文件

7. 部署后端服务

7.1 加载 Docker 镜像

7.2 更新环境变量版本号

7.3 启动后端服务

8. 部署前端文件

8.1 部署前端到版本目录

8.2 更新前端软链接

8.3 配置 Nginx（如果使用）

9. 设置文件权限

3. 自动部署

1. 自动部署概述

2. 服务器端自动部署

2.1 自动部署脚本功能

2.2 自动部署命令

2.3 自动部署脚本命令列表

2.4 自动部署流程说明

3. 本地到服务器自动部署

3.1 本地自动部署脚本

3.2 完整自动部署流程

3.3 一键自动部署（推荐）

4. 自动部署特性

4.1 智能版本检测

4.2 自动备份机制

4.3 零停机部署

4.4 自动清理机制

5. 自动部署最佳实践

5.1 部署前检查清单

5.2 部署流程建议

5.3 回滚流程

5.4 定期维护

6. 自动部署与手动部署对比

4. 部署验证

1. 检查服务状态

2. 检查服务健康

3. 检查端口监听

4. 检查前端版本

5. 访问应用

5. 常见问题

Q1: Docker 镜像加载失败

Q2: 后端服务启动失败

Q3: 数据库连接失败（生产环境）

1. 检查数据库容器状态

2. 检查 Docker 网络

3. 检查数据库容器 IP

4. 测试网络连通性

5. 检查数据库配置

方案一：使用容器名称而不是 IP（推荐）

方案二：检查网络配置（统一配置）

方案三：重启所有服务（统一配置）

方案四：快速修复命令

Q4: 前端文件无法访问

Q5: 文件上传权限错误

Q6: 端口被占用（生产环境）

1. 查找占用端口的进程

2. 停止占用端口的服务