xlcp/deploy/README.md

# XL监狱综合管理平台 - Docker 部署指南

## 📋 目录结构

```
deploy/
├── docker-compose.yml          # Docker Compose 编排文件
├── .env                        # 环境变量配置
├── .gitignore                  # Git 忽略文件
├── config/
│   └── application-prod.yaml   # 生产环境配置
├── data/                       # 数据目录（自动创建）
│   ├── mysql/                  # MySQL 数据文件
│   ├── redis/                  # Redis 数据文件
│   └── upload/                # 上传文件
├── logs/                       # 日志目录（自动创建）
│   ├── backend/                # 后端日志
│   └── nginx/                  # Nginx 日志
├── docker/
│   └── frontend/
│       └── nginx.conf          # Nginx 配置
├── sql/
│   └── prison_schema.sql       # 数据库初始化脚本
└── scripts/
    ├── build.sh               # 镜像构建脚本（已弃用）
    ├── deploy.sh              # 远程部署脚本（已弃用）
    ├── init-db.sh            # 数据库初始化脚本
    └── init-permissions.sh    # 权限初始化脚本
```

## 🚀 快速开始

### 前置要求

- Docker 20.10+
- Docker Compose 2.0+ (或 docker-compose 1.29+)
- 服务器至少 4GB 内存, 20GB 磁盘空间
- SSH 免密登录到目标服务器 (如果远程部署)

### 方式一: 本地部署

#### 1. 克隆项目

```bash
cd /path/to/xlcp
```

#### 2. 配置环境变量

编辑 `.env` 文件,根据需要修改配置:

```bash
vi deploy/.env
```

关键配置项:
- `MYSQL_ROOT_PASSWORD`: MySQL root 密码
- `REDIS_PASSWORD`: Redis 密码
- `BACKEND_PORT`: 后端服务端口 (默认 48080)
- `FRONTEND_PORT`: 前端服务端口 (默认 80)

#### 3. 构建镜像

```bash
cd deploy
./scripts/build.sh
```

#### 4. 启动服务

```bash
docker compose up -d
```

或使用 docker-compose:

```bash
docker-compose up -d
```

#### 5. 查看日志

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

# 查看特定服务日志
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f mysql
docker compose logs -f redis
```

#### 6. 停止服务

```bash
docker compose down
```

#### 7. 完全清理

```bash
docker compose down -v  # 同时删除数据卷
```

### 方式二: 远程部署 (推荐生产环境)

#### 1. 配置远程服务器信息

```bash
# 方式 1: 使用默认配置 (root@192.168.10.150)
cd deploy
./scripts/deploy.sh

# 方式 2: 自定义服务器
REMOTE_SERVER=user@your-server-ip ./scripts/deploy.sh

# 方式 3: 自定义部署目录
REMOTE_SERVER=root@192.168.10.150 REMOTE_DEPLOY_DIR=/projects/data/xlcp ./scripts/deploy.sh
```

#### 2. 部署流程

脚本会自动执行:
1. ✅ 检查 SSH 连接
2. ✅ 检查远程 Docker 环境
3. ✅ 创建远程目录结构
4. ✅ 上传部署文件
5. ✅ 启动所有容器
6. ✅ 健康检查
7. ✅ 显示访问信息

#### 3. 访问服务

部署完成后:
- 前端: http://192.168.10.150/
- 后端 API: http://192.168.10.150:48080/admin-api/
- 健康检查: http://192.168.10.150:48080/actuator/health

#### 4. 查看远程日志

```bash
ssh root@192.168.10.150
cd /projects/data/xlcp
docker compose logs -f
```

## 🔧 服务管理

### 查看服务状态

```bash
docker compose ps
```

### 重启单个服务

```bash
# 重启后端
docker compose restart backend

# 重启前端
docker compose restart frontend

# 重启 MySQL
docker compose restart mysql
```

### 进入容器

```bash
# 进入后端容器
docker compose exec backend sh

# 进入 MySQL 容器
docker compose exec mysql bash

# 进入 Redis 容器
docker compose exec redis sh
```

### 更新服务

```bash
# 1. 重新构建镜像
docker compose build backend frontend

# 2. 重启服务
docker compose up -d backend frontend
```

## 📊 数据库管理

### 初始化数据库

```bash
cd deploy
./scripts/init-db.sh
```

### 手动执行 SQL

```bash
# 进入 MySQL 容器
docker compose exec mysql bash

# 连接 MySQL
mysql -u root -pPrison2024!@ prison

# 执行 SQL
source /docker-entrypoint-initdb.d/01-prison_schema.sql
```

### 数据库备份

```bash
# 备份整个数据库
docker exec xlcp-mysql mysqldump -u root -pPrison2024!@ prison > prison_backup_$(date +%Y%m%d).sql

# 恢复数据库
docker exec -i xlcp-mysql mysql -u root -pPrison2024!@ prison < prison_backup_20250122.sql
```

### 查看数据库

```bash
docker exec xlcp-mysql mysql -u root -pPrison2024!@ prison -e "SHOW TABLES;"
```

## 🔍 故障排查

### 服务无法启动

1. 查看服务日志

```bash
docker compose logs backend
docker compose logs frontend
```

2. 检查端口占用

```bash
netstat -tlnp | grep -E '3306|6379|48080|80'
```

3. 检查磁盘空间

```bash
df -h
docker system df
```

### 健康检查失败

1. 检查后端服务是否启动

```bash
curl http://localhost:48080/actuator/health
```

2. 检查前端服务是否启动

```bash
curl http://localhost/
```

3. 查看详细日志

```bash
docker compose logs -f backend
```

### 数据库连接失败

1. 检查 MySQL 容器状态

```bash
docker compose ps mysql
docker compose logs mysql
```

2. 测试数据库连接

```bash
docker exec xlcp-mysql mysqladmin ping -h localhost -u root -pPrison2024!@
```

3. 检查配置文件

```bash
cat config/application-prod.yaml | grep datasource
```

### 前端页面无法访问

1. 检查 Nginx 配置

```bash
docker compose exec frontend nginx -t
```

2. 查看 Nginx 日志

```bash
docker compose logs frontend
```

3. 检查静态文件

```bash
docker compose exec frontend ls -la /usr/share/nginx/html
```

## 📈 监控和日志

### 实时监控

```bash
# 监控所有服务
docker compose logs -f

# 监控特定服务
docker compose logs -f backend
```

### 查看日志文件

```bash
# 后端日志 (Docker 内部)
docker compose exec backend cat /logs/yudao-server.log

# Nginx 日志
docker compose exec frontend tail -f /var/log/nginx/access.log
docker compose exec frontend tail -f /var/log/nginx/error.log

# MySQL 日志
docker compose exec mysql tail -f /var/log/mysql/error.log
```

### 资源监控

```bash
# 查看容器资源使用
docker stats

# 查看磁盘使用
docker system df

# 清理未使用的资源
docker system prune -a
```

## 🔒 安全建议

1. **修改默认密码**
   - MySQL root 密码
   - Redis 密码

2. **配置防火墙**
   ```bash
   # 仅开放必要端口
   firewall-cmd --permanent --add-port=48080/tcp
   firewall-cmd --permanent --add-port=80/tcp
   firewall-cmd --reload
   ```

3. **启用 HTTPS**
   - 准备 SSL 证书
   - 放置到 `deploy/docker/ssl/` 目录
   - 修改 `nginx.conf` 配置

4. **定期备份数据**
   - 数据库备份
   - 上传文件备份
   - 配置文件备份

## 📚 附录

### 环境变量说明

| 变量名 | 默认值 | 说明 |
|---------|---------|------|
| MYSQL_ROOT_PASSWORD | Prison2024!@ | MySQL root 密码 |
| MYSQL_DATABASE | prison | 数据库名称 |
| MYSQL_PORT | 3306 | MySQL 端口 |
| REDIS_PASSWORD | Prison2024!@ | Redis 密码 |
| REDIS_PORT | 6379 | Redis 端口 |
| BACKEND_PORT | 48080 | 后端服务端口 |
| FRONTEND_PORT | 80 | 前端服务端口 |
| SPRING_PROFILES_ACTIVE | prod | Spring 环境配置 |
| JAVA_OPTS | -Xms512m -Xmx1024m | JVM 参数 |

### 端口说明

| 服务 | 容器端口 | 宿主机端口 | 说明 |
|------|-----------|------------|------|
| MySQL | 3306 | 3306 | 数据库服务 |
| Redis | 6379 | 6379 | 缓存服务 |
| Backend | 48080 | 48080 | 后端 API 服务 |
| Frontend | 80 | 80 | 前端 Web 服务 |

### 常用命令

```bash
# 查看 Docker 版本
docker --version
docker compose version

# 查看容器列表
docker ps -a

# 查看镜像列表
docker images | grep xlcp

# 查看网络
docker network ls
docker network inspect xlcp_xlcp-network

# 查看数据卷
docker volume ls
docker volume inspect xlcp_mysql-data
```

## 🆘 获取帮助

- 查看部署脚本帮助: `./scripts/deploy.sh --help`
- 查看项目文档: `/README.md`
- 查看后端配置: `/backend/README.md`
- 查看前端配置: `/frontend/README.md`

## 📞 技术支持

如遇问题,请提供以下信息:
1. Docker 版本: `docker --version`
2. Docker Compose 版本: `docker compose version`
3. 操作系统版本: `cat /etc/os-release`
4. 错误日志: `docker compose logs`
5. 问题描述和复现步骤