xlcp/docs/DEPLOYMENT.md

# XL 监狱综合管理平台部署文档

## 1. 文档概述

本文档详细描述 XL 监狱综合管理平台在服务器 `root@192.168.10.150` 上的部署流程。该平台采用 Docker 容器化部署方式，包含 MySQL 数据库、Redis 缓存、Spring Boot 后端服务和 Nginx 前端服务。

### 1.1 系统架构

```
┌─────────────────────────────────────────────────────────────────────┐
│                         服务器 192.168.10.150                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                    Docker 网络 (xlcp-network)             │  │
│  │                                                              │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌────────────────────────┐ │  │
│  │  │   MySQL 8   │  │  Redis 6    │  │   后端服务 (Java)      │ │  │
│  │  │  端口:3306  │  │  端口:6379  │  │   端口:48080           │ │  │
│  │  │             │  │             │  │                        │ │  │
│  │  └──────┬──────┘  └──────┬──────┘  └───────────┬────────────┘ │  │
│  │         │                │                      │              │  │
│  │         └────────────────┼──────────────────────┘              │  │
│  │                          │                                     │  │
│  │                   ┌──────┴──────┐                              │  │
│  │                   │   Nginx     │                              │  │
│  │                   │   端口:8080 │                              │  │
│  │                   └──────┬──────┘                              │  │
│  │                          │                                     │  │
│  └──────────────────────────┼─────────────────────────────────────┘  │
│                             │                                        │
│                             ▼                                        │
│                    外部用户访问入口                                   │
│                  http://192.168.10.150:8080                          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### 1.2 端口分配

| 服务 | 端口 | 说明 |
|------|------|------|
| Nginx 前端 | 8080 | Web 访问入口 |
| Spring Boot 后端 | 48080 | API 服务端口 |
| MySQL | 3306 | 数据库服务 |
| Redis | 6379 | 缓存服务 |

### 1.3 环境要求

在开始部署之前，请确保目标服务器满足以下最低要求：

- **操作系统**: CentOS 7+ / Ubuntu 18+ / Rocky Linux 8+ / Debian 10+
- **CPU**: 最低 2 核，推荐 4 核或更多
- **内存**: 最低 4GB，推荐 8GB 或更多
- **硬盘**: 最低 50GB 可用空间，推荐 100GB SSD
- **网络**: 具备互联网访问能力，用于下载 Docker 镜像

## 2. 服务器环境准备

### 2.1 安装 Docker

以下是在 CentOS/Rocky Linux 系统上安装 Docker 的步骤。如果您的服务器已安装 Docker，请跳过此步骤。

```bash
# 1. 安装必要依赖
sudo yum install -y yum-utils device-mapper-persistent-data lvm2

# 2. 添加 Docker 官方仓库
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 3. 安装 Docker 引擎
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 4. 启动 Docker 服务
sudo systemctl start docker

# 5. 设置开机自启动
sudo systemctl enable docker

# 6. 验证安装
docker --version
docker compose version
```

对于 Ubuntu/Debian 系统，请使用以下命令：

```bash
# 1. 更新软件包索引
sudo apt-get update

# 2. 安装必要依赖
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# 3. 添加 Docker 官方 GPG 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 4. 设置 Docker 仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 安装 Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 6. 启动并设置开机自启动
sudo systemctl start docker
sudo systemctl enable docker
```

### 2.2 配置 Docker 镜像加速

为了加速 Docker 镜像的下载，建议配置国内镜像加速器。

```bash
# 创建 Docker 配置目录
sudo mkdir -p /etc/docker

# 配置镜像加速器
sudo tee /etc/docker/daemon.json <<-EOF
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://registry.docker-cn.com"
  ],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  },
  "storage-driver": "overlay2"
}
EOF

# 重启 Docker 服务
sudo systemctl daemon-reload
sudo systemctl restart docker

# 验证配置
docker info | grep "Registry Mirrors"
```

### 2.3 安装 Git（用于拉取代码）

```bash
# CentOS/Rocky Linux
sudo yum install -y git

# Ubuntu/Debian
sudo apt-get install -y git
```

## 3. 项目部署

### 3.1 创建部署目录结构

在服务器上创建项目部署目录：

```bash
# 创建项目根目录
sudo mkdir -p /work/projects/xlcp
sudo mkdir -p /work/projects/xlcp/{backend,frontend,data/{mysql,redis},logs,sql}

# 设置目录所有者（请将 username 替换为实际用户名）
sudo chown -R $USER:$USER /work/projects/xlcp

# 进入项目目录
cd /work/projects/xlcp
```

目录结构说明：

```
/work/projects/xlcp/
├── backend/            # 后端服务目录
│   ├── config/         # 配置文件目录
│   └── Dockerfile      # Docker 构建文件
├── frontend/           # 前端服务目录
│   ├── dist/           # 前端构建产物
│   └── nginx.conf      # Nginx 配置文件
├── data/               # 数据持久化目录
│   ├── mysql/          # MySQL 数据文件
│   └── redis/          # Redis 数据文件
├── logs/               # 日志目录
│   ├── backend/        # 后端日志
│   └── nginx/          # Nginx 日志
├── sql/                # SQL 初始化脚本
├── docker-compose.yml  # Docker Compose 配置
└── README.md          # 部署文档
```

### 3.2 获取项目代码

您可以通过以下两种方式之一获取项目代码：

**方式一：从 Git 仓库克隆**

```bash
cd /work/projects/xlcp
git clone <your-repository-url> ./source
```

**方式二：从本地复制**

在您的开发机器上执行以下命令，将项目复制到服务器：

```bash
# 复制整个项目到服务器
scp -r /Volumes/Dpan/github/xlcp root@192.168.10.150:/work/projects/xlcp/source

# 或者只复制必要文件
scp -r /Volumes/Dpan/github/xlcp/backend root@192.168.10.150:/work/projects/xlcp/
scp -r /Volumes/Dpan/github/xlcp/frontend/dist root@192.168.10.150:/work/projects/xlcp/frontend/
scp -r /Volumes/Dpan/github/xlcp/backend/sql/mysql/*.sql root@192.168.10.150:/work/projects/xlcp/sql/
```

### 3.3 复制配置文件

将预先准备好的配置文件复制到服务器：

```bash
# 复制 Docker Compose 配置
cp deploy/docker-compose.yml /work/projects/xlcp/

# 复制后端配置
cp deploy/config/application-prod.yaml /work/projects/xlcp/backend/config/

# 复制后端 Dockerfile
cp deploy/docker/backend/Dockerfile /work/projects/xlcp/backend/

# 复制前端 Nginx 配置
cp deploy/docker/frontend/nginx.conf /work/projects/xlcp/frontend/

# 复制 SQL 初始化脚本
cp backend/sql/mysql/*.sql /work/projects/xlcp/sql/
```

### 3.4 编译后端项目

在有 Maven 环境的机器上编译后端项目：

```bash
cd /Volumes/Dpan/github/xlcp/backend

# 清理并打包（跳过测试）
mvn clean package -DskipTests -Dmaven.javadoc.skip=true

# 构建完成后，jar 包位于以下位置
ls -lh yudao-server/target/yudao-server.jar
```

将编译好的 jar 包复制到服务器：

```bash
scp yudao-server/target/yudao-server.jar root@192.168.10.150:/work/projects/xlcp/backend/
```

### 3.5 构建前端项目

在有 Node.js 环境的机器上构建前端：

```bash
cd /Volumes/Dpan/github/xlcp/frontend

# 安装依赖
pnpm install

# 生产环境构建
pnpm build:prod

# 构建完成后，构建产物在 dist 目录
ls -lh dist/
```

将构建产物复制到服务器：

```bash
scp -r dist/* root@192.168.10.150:/work/projects/xlcp/frontend/
```

## 4. 配置文件说明

### 4.1 Docker Compose 配置

主要配置项说明：

```yaml
version: "3.8"

services:
  # MySQL 数据库服务
  mysql:
    image: mysql:8.0                    # 使用 MySQL 8.0 镜像
    container_name: xlcp-mysql     # 容器名称
    restart: unless-stopped             # 异常退出后自动重启
    environment:
      MYSQL_ROOT_PASSWORD: Prison2024!@  # root 用户密码
      MYSQL_DATABASE: prison             # 数据库名称
    volumes:
      - ./data/mysql:/var/lib/mysql     # 数据持久化
      - ./sql:/docker-entrypoint-initdb.d:ro  # 初始化脚本
    ports:
      - "3306:3306"                     # 端口映射
    deploy:
      resources:
        limits:
          memory: 2G                    # 内存限制

  # Redis 缓存服务
  redis:
    image: redis:6.2-alpine
    container_name: xlcp-redis
    command: redis-server --requirepass Redis2024!@  # 设置密码
    volumes:
      - ./data/redis:/data
    deploy:
      resources:
        limits:
          memory: 512M

  # 后端服务
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: xlcp-backend
    environment:
      SPRING_PROFILES_ACTIVE: prod  # 生产环境配置
      JAVA_OPTS: -Xms512m -Xmx1024m  # JVM 内存配置
    volumes:
      - ./backend/config:/app/config:ro  # 配置文件挂载
      - ./logs/backend:/app/logs         # 日志目录挂载
    depends_on:
      mysql:
        condition: service_healthy   # 等待 MySQL 健康检查通过
      redis:
        condition: service_healthy   # 等待 Redis 健康检查通过

  # 前端服务
  frontend:
    image: nginx:alpine
    container_name: xlcp-frontend
    volumes:
      - ./frontend/dist:/usr/share/nginx/html:ro  # 前端静态文件
      - ./frontend/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./logs/nginx:/var/log/nginx              # Nginx 日志
```

### 4.2 后端生产配置

配置文件位置：`backend/config/application-prod.yaml`

主要配置项：

```yaml
spring:
  datasource:
    dynamic:
      datasource:
        master:
          url: jdbc:mysql://mysql:3306/prison?useSSL=false&serverTimezone=Asia/Shanghai...
          username: root
          password: Prison2024!@
  data:
    redis:
      host: redis        # 使用 Docker 网络中的服务名
      port: 6379
      password: Redis2024!@

server:
  port: 48080           # 后端服务端口

logging:
  level:
    cn.iocoder.yudao: DEBUG
```

**重要说明**：在 Docker 环境中，使用 Docker Compose 定义的服务名（如 `mysql`、`redis`）作为主机名，而非 IP 地址。

### 4.3 Nginx 配置

配置文件位置：`frontend/nginx.conf`

主要功能：

- 静态文件服务
- API 请求代理到后端服务
- Gzip 压缩
- 缓存配置
- 安全头配置

```nginx
upstream backend {
    server backend:48080;  # 后端服务地址
    keepalive 32;
}

server {
    listen 80;
    
    # 前端路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # API 代理
    location /prod-api/ {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 5. 部署执行

### 5.1 启动服务

```bash
cd /work/projects/xlcp

# 启动所有服务（后台运行）
docker compose up -d

# 查看启动状态
docker compose ps

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

### 5.2 验证部署

执行以下命令验证各服务是否正常运行：

```bash
# 1. 检查 MySQL
docker exec -it xlcp-mysql mysql -uroot -pPrison2024!@ -e "SHOW DATABASES;"

# 预期输出应包含 prison 数据库

# 2. 检查 Redis
docker exec -it xlcp-redis redis-cli -a Redis2024!@ ping

# 预期输出：PONG

# 3. 检查后端健康状态
curl http://localhost:48080/actuator/health/

# 预期输出：{"status":"UP"}

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

# 预期输出：HTTP/1.1 200 OK
```

### 5.3 查看日志

```bash
# 查看后端日志
docker logs xlcp-backend
tail -f /work/projects/xlcp/logs/backend/yudao-server.log

# 查看 Nginx 日志
docker logs xlcp-frontend
tail -f /work/projects/xlcp/logs/nginx/access.log
tail -f /work/projects/xlcp/logs/nginx/error.log
```

## 6. 访问地址

部署完成后，系统可通过以下地址访问：

| 服务 | 地址 | 说明 |
|------|------|------|
| 前端页面 | http://192.168.10.150:8080 | 监狱管理系统 Web 界面 |
| 后端 API | http://192.168.10.150:48080 | 后端服务接口 |
| 健康检查 | http://192.168.10.150:48080/actuator/health | 服务健康状态 |
| MySQL | 192.168.10.150:3306 | 数据库连接 |
| Redis | 192.168.10.150:6379 | 缓存服务 |

## 7. 运维管理

### 7.1 服务管理命令

```bash
# 启动所有服务
docker compose start

# 停止所有服务
docker compose stop

# 重启所有服务
docker compose restart

# 重启单个服务
docker compose restart backend
docker compose restart frontend

# 查看服务状态
docker compose ps

# 查看服务资源使用
docker stats

# 进入容器内部
docker exec -it xlcp-backend /bin/sh
docker exec -it xlcp-mysql mysql -uroot -pPrison2024!@
docker exec -it xlcp-redis redis-cli -a Redis2024!@
```

### 7.2 日志管理

```bash
# 查看所有服务日志
docker compose logs

# 查看指定服务日志
docker compose logs backend
docker compose logs frontend
docker compose logs mysql
docker compose logs redis

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

# 查看最近 100 行日志
docker logs --tail 100 xlcp-backend
```

### 7.3 数据备份

```bash
# 备份 MySQL 数据库
BACKUP_DIR=/work/projects/xlcp/backup
mkdir -p $BACKUP_DIR
BACKUP_DATE=$(date +%Y%m%d_%H%M%S)

docker exec xlcp-mysql mysqldump -uroot -pPrison2024!@ prison > $BACKUP_DIR/prison_$BACKUP_DATE.sql

# 压缩备份文件
gzip $BACKUP_DIR/prison_$BACKUP_DATE.sql

# 查看备份文件
ls -lh $BACKUP_DIR/

# 备份 Redis 数据
docker exec xlcp-redis redis-cli -a Redis2024!@ BGSAVE
docker cp xlcp-redis:/data/dump.rdb $BACKUP_DIR/redis_$BACKUP_DATE.rdb
```

### 7.4 版本更新

```bash
# 1. 停止当前服务
cd /work/projects/xlcp
docker compose down

# 2. 备份重要数据
cp -r data data.backup.$(date +%Y%m%d)

# 3. 更新代码
cd source
git pull

# 4. 重新编译
cd ../backend
mvn clean package -DskipTests
cd ../frontend
pnpm install && pnpm build:prod

# 5. 更新构建产物
cp -r dist/* ../frontend/
cp target/*.jar ../backend/

# 6. 重新构建镜像并启动
cd ..
docker compose build --no-cache
docker compose up -d

# 7. 验证部署
curl http://localhost:48080/actuator/health/
```

## 8. 常见问题排查

### 8.1 后端无法连接数据库

```bash
# 检查 MySQL 容器状态
docker ps | grep mysql

# 检查 MySQL 日志
docker logs xlcp-mysql

# 检查 MySQL 健康状态
docker exec xlcp-mysql mysqladmin -uroot -pPrison2024!@ ping

# 检查网络连接
docker exec xlcp-backend ping mysql

# 常见原因及解决方案：
# 1. MySQL 容器未启动 → docker compose restart mysql
# 2. 密码错误 → 检查 application-prod.yaml 配置
# 3. 网络问题 → 检查 Docker 网络状态
```

### 8.2 前端 502 错误

```bash
# 检查后端服务状态
docker ps | grep backend

# 检查后端健康状态
curl http://localhost:48080/actuator/health/

# 检查后端日志
docker logs xlcp-backend

# 检查 Nginx 配置
docker exec xlcp-frontend cat /etc/nginx/nginx.conf

# 测试后端连通性
docker exec xlcp-frontend curl http://backend:48080/actuator/health/
```

### 8.3 内存不足

```bash
# 检查容器资源使用情况
docker stats

# 调整 JVM 内存配置，编辑 docker-compose.yml
environment:
  JAVA_OPTS: -Xms256m -Xmx512m

# 重新启动服务
docker compose restart backend
```

### 8.4 端口冲突

```bash
# 检查端口占用
netstat -tlnp | grep 8080
netstat -tlnp | grep 48080

# 如果端口被占用，可以修改 docker-compose.yml 中的端口映射
ports:
  - "8081:80"  # 改为 8081 端口
```

### 8.5 数据丢失

```bash
# 检查数据卷挂载
docker volume ls

# 检查数据目录权限
ls -la /work/projects/xlcp/data/

# 恢复数据（从备份）
gunzip -k /work/projects/xlcp/backup/prison_20240115.sql.gz
docker exec -i xlcp-mysql mysql -uroot -pPrison2024!@ prison < /work/projects/xlcp/backup/prison_20240115.sql
```

## 9. 安全加固建议

### 9.1 修改默认密码

生产环境中，请务必修改默认密码：

```yaml
# MySQL
MYSQL_ROOT_PASSWORD: YourStrongPassword123!@

# Redis
command: redis-server --requirepass YourStrongRedisPassword456!@

# 修改 application-prod.yaml 中的数据库密码
password: YourStrongPassword123!@
```

### 9.2 配置防火墙

```bash
# 只开放必要端口（CentOS）
firewall-cmd --permanent --add-port=8080/tcp
firewall-cmd --permanent --add-port=48080/tcp
firewall-cmd --reload

# 只开放必要端口（Ubuntu）
sudo ufw allow 8080/tcp
sudo ufw allow 48080/tcp
sudo ufw enable
```

### 9.3 启用 HTTPS（推荐）

建议使用 Nginx 反向代理并配置 SSL 证书：

```nginx
server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    
    # 其他配置...
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}
```

### 9.4 定期安全更新

```bash
# 更新系统软件包
sudo yum update -y  # CentOS
sudo apt-get update && sudo apt-get upgrade -y  # Ubuntu

# 更新 Docker
sudo yum update docker-ce  # CentOS
sudo apt-get update && sudo apt-get install docker-ce  # Ubuntu
```

### 9.5 监控与告警

建议配置以下监控：

- **服务监控**: 使用 Prometheus + Grafana 监控容器状态
- **日志监控**: 使用 ELK Stack 收集和分析日志
- **告警通知**: 配置邮件或企业微信告警通知

## 10. 联系与支持

如果在部署过程中遇到问题，请：

1. 查看本文档的常见问题排查章节
2. 检查各服务的日志文件
3. 联系系统管理员获取支持

---

**文档版本**: 1.0.0  
**最后更新**: 2026年1月21日  
**适用系统**: XL 监狱综合管理平台 v1.0