Files

T

zhang1106 3d933ad6a0 chore: 更新镜像默认tag为latest并新增部署文档

1. 将.env.example和docker-compose.prod.yml中的后端、前端镜像默认tag从v2.1.0改为latest
2. 新增万字级Docker生产环境部署教程文档

2026-06-15 17:05:08 +08:00

11 KiB

Raw Blame History

IDC 设备管理系统 - Docker 部署教程

适用场景：新服务器上首次部署

架构：3 个容器（Nginx + 前端静态文件 | Backend | MySQL）

一、前置要求

1.1 所需条件

条件	说明
服务器	Linux 系统（推荐 Ubuntu 20.04+ / Debian 11+ / CentOS 7+）
Docker	20.10 及以上版本
Docker Compose	v2 及以上
Git	用于拉取项目代码
网络	服务器能访问阿里云容器镜像服务

1.2 架构说明

用户访问 http://服务器IP 时，请求流程如下：

用户浏览器 → Nginx 容器 :80
                ├── / 路径 → 返回前端静态页面（HTML/JS/CSS）
                └── /api 路径 → 反向代理 → Backend 容器 :8000 → MySQL 容器 :3306（或远程 MySQL）

二、服务器准备

2.1 安装 Docker

# Ubuntu / Debian
curl -fsSL https://get.docker.com | bash -s docker
sudo systemctl enable docker
sudo systemctl start docker

# 验证
docker --version
docker compose version

2.2 创建目录结构

# 在服务器上创建项目根目录
mkdir -p /opt/idc_assest
cd /opt/idc_assest

三、拉取项目与配置

3.1 克隆项目代码

注意：克隆代码是为了获取 docker-compose.prod.yml 和 .env 配置模板，不是用来构建镜像的（镜像已由CI/CD自动构建好）。

git clone https://github.com/gituib/idc_assest.git .

3.2 创建数据持久化目录

mkdir -p backend/uploads backend/logs backend/backups backend/temp

3.3 配置 .env 文件

复制后端配置模板，填入实际参数：

cp backend/.env.example backend/.env   # 如果有示例文件则用，否则手动创建
# 或直接编辑
nano backend/.env

完整的 .env 配置内容如下：

# ==============================================
# 服务器配置
# ==============================================
PORT=8000
NODE_ENV=production

# ==============================================
# 数据库配置
# ==============================================
# 方式一：使用 Docker 本地 MySQL 容器（推荐新部署）
DB_TYPE=mysql
MYSQL_HOST=mysql                      # Docker 服务名，不是 localhost
MYSQL_PORT=3306
MYSQL_USERNAME=idc_user
MYSQL_PASSWORD=这里改成MySQL容器密码
MYSQL_DATABASE=idc_management

# 方式二：使用远程 MySQL（已有数据库的情况）
# DB_TYPE=mysql
# MYSQL_HOST=远程MySQL地址
# MYSQL_PORT=3306
# MYSQL_USERNAME=数据库用户名
# MYSQL_PASSWORD=数据库密码
# MYSQL_DATABASE=数据库名

# ==============================================
# JWT 密钥（重要！必须手动设置）
# 生产环境不能留空，生成命令：
#   node -e "console.log(require('crypto').randomBytes(64).toString('base64'))"
# ==============================================
JWT_SECRET=这里填入生成的密钥，至少32位

# ==============================================
# 其他配置（保持默认即可）
# ==============================================
TOKEN_EXPIRY=24h
SALT_ROUNDS=12
MAX_LOGIN_ATTEMPTS=3
LOCK_TIME_MINUTES=15
PASSWORD_MIN_LENGTH=8
USERNAME_MIN_LENGTH=4
USERNAME_MAX_LENGTH=30
API_TIMEOUT=20000
DB_QUERY_TIMEOUT=15000
DEFAULT_PAGE_SIZE=20
MAX_PAGE_SIZE=500
MAX_FILE_SIZE_MB=30
MAX_AVATAR_SIZE_MB=2
MAX_RETRIES=5
RETRY_DELAY=2000
LOG_LEVEL=info
LOG_DIR=./logs
LOG_MAX_FILE_SIZE=20m
LOG_MAX_FILES=30d

四、生产环境配置

部署方式分两种，选择其中一种：

方式A：使用 Docker 本地 MySQL（推荐新部署）

MySQL 作为容器运行在 Docker 内部，数据卷持久化到主机。

步骤 1：编辑 .env，确认 MySQL 配置如下：

DB_TYPE=mysql
MYSQL_HOST=mysql
MYSQL_PORT=3306
MYSQL_USERNAME=idc_user
MYSQL_PASSWORD=你的密码
MYSQL_DATABASE=idc_management

步骤 2：修改 docker-compose.prod.yml，取消 MySQL 容器的注释：

使用以下命令编辑，把文件中 MySQL 相关部分（# mysql: 到 # retries: 5）的注释去掉：

nano docker-compose.prod.yml

去掉注释后，MySQL 部分应该是这样的（且 volumes: 和 mysql_data: 也要取消注释）：

  mysql:
    image: mysql:8.0
    container_name: idc-mysql
    volumes:
      - mysql_data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE:-idc_management}
      MYSQL_USER: ${MYSQL_USER:-idc_user}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    networks:
      - idc-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  idc-network:
    driver: bridge

volumes:
  mysql_data:

步骤 3：创建 .env 文件（项目根目录，非 backend 目录），写入 MySQL 密码：

# 在 /opt/idc_assest/ 下创建 .env 文件（与 docker-compose.prod.yml 同目录）
cat > .env << 'EOF'
MYSQL_ROOT_PASSWORD=root密码
MYSQL_USER=idc_user
MYSQL_PASSWORD=用户密码
MYSQL_DATABASE=idc_management
EOF

方式B：使用远程 MySQL（已有数据库）

保持现有的远程 MySQL 实例，不需要本地 MySQL 容器。

docker-compose.prod.yml 保持原样（MySQL 部分保持注释），.env 中配置远程数据库地址即可：

DB_TYPE=mysql
MYSQL_HOST=远程MySQL的IP或域名
MYSQL_PORT=3306
MYSQL_USERNAME=数据库用户名
MYSQL_PASSWORD=数据库密码
MYSQL_DATABASE=数据库名

五、启动容器

5.1 首次拉取镜像

cd /opt/idc_assest

# 方式A（本地 MySQL）
docker compose -f docker-compose.prod.yml pull

# 方式B（远程 MySQL）
docker compose -f docker-compose.prod.yml pull

5.2 启动服务

# 方式A（本地 MySQL）
docker compose -f docker-compose.prod.yml up -d

# 方式B（远程 MySQL）
docker compose -f docker-compose.prod.yml up -d

5.3 查看启动状态

# 查看所有容器状态
docker compose -f docker-compose.prod.yml ps

# 实时查看日志
docker compose -f docker-compose.prod.yml logs -f

# 单独查看某个容器的日志
docker logs idc-backend
docker logs idc-frontend
docker logs idc-mysql   # 仅方式A

5.4 等待初始化完成

首次启动后，后端会自动执行以下操作（约 10-30 秒）：

连接数据库
自动创建所有数据库表（sequelize.sync()）
初始化默认数据（设备字段、工单字段、故障分类、系统设置等）

可以通过日志查看初始化进度：

docker logs -f idc-backend

当日志出现以下内容时，说明启动完成：

所有初始化完成，服务器准备就绪
服务器运行在 http://localhost:8000

六、验证部署

6.1 检查容器状态

docker compose -f docker-compose.prod.yml ps

所有容器都应该是 Up 状态：

NAME            IMAGE                                          STATUS          PORTS
idc-frontend    .../idc-frontend:latest                        Up              :80->80/tcp
idc-backend     .../idc-backend:latest                         Up (healthy)    8000/tcp
idc-mysql       mysql:8.0                                      Up              3306/tcp

6.2 访问系统

在浏览器中访问：

http://服务器IP

应该能看到登录页面。

6.3 测试 API

curl http://服务器IP/api

返回 JSON 格式的 API 信息。

6.4 健康检查

curl http://服务器IP/health

七、日常运维

7.1 常用命令

# 查看状态
docker compose -f docker-compose.prod.yml ps

# 查看日志
docker compose -f docker-compose.prod.yml logs -f

# 重启服务
docker compose -f docker-compose.prod.yml restart

# 停止服务
docker compose -f docker-compose.prod.yml down

# 停止并删除数据卷（数据会丢失！慎用）
docker compose -f docker-compose.prod.yml down -v

7.2 备份数据库

# MySQL 本地容器方式
docker exec idc-mysql mysqldump -u root -p idc_management > backup_$(date +%Y%m%d).sql

# 如果开启了自动备份，后端自身也会定期备份到 backend/backups/ 目录

7.3 查看容器资源占用

docker stats idc-backend idc-frontend idc-mysql

7.4 更新服务配置

修改 .env 后，需要重启后端容器才能生效：

docker compose -f docker-compose.prod.yml restart backend

八、版本升级

场景：代码有更新，需要部署新版本

# 1. 拉取最新镜像
docker compose -f docker-compose.prod.yml pull

# 2. 重新创建容器
docker compose -f docker-compose.prod.yml up -d

# 3. 清理旧镜像（可选）
docker image prune -a

回滚到指定版本

# 用 v2.1.0 版本的镜像启动
BACKEND_IMAGE=crpi-c807itn6exy37e7d.cn-hangzhou.personal.cr.aliyuncs.com/idc-assest/idc-backend:v2.1.0 \
FRONTEND_IMAGE=crpi-c807itn6exy37e7d.cn-hangzhou.personal.cr.aliyuncs.com/idc-assest/idc-frontend:v2.1.0 \
docker compose -f docker-compose.prod.yml up -d

九、常见问题

9.1 容器启动后立即退出

原因： 配置错误或数据库连接失败。

排查：

# 查看退出容器的日志
docker logs idc-backend

# 常见错误：
# - JWT_SECRET 未配置 → 在 .env 中设置 JWT_SECRET
# - MySQL 连接被拒 → 检查 MYSQL_HOST / MYSQL_PASSWORD
# - 端口被占用 → 检查 80 端口是否已被其他程序占用

9.2 端口被占用

如果 80 端口被其他服务占用，可以修改 docker-compose.prod.yml 中的端口映射：

ports:
  - "8080:80"   # 改为 8080 端口，访问 http://ip:8080

9.3 拉取镜像失败

原因： 阿里云登录凭证问题或网络不通。