# XL监狱综合管理平台 - 生产部署包部署指南

## 📋 目录结构

```
deploy/
├── docker-compose.yml          # Docker Compose 编排文件
├── config/
│   └── application-prod.yaml   # 生产环境配置
├── docker/
│   └── backend/
│       ├── Dockerfile          # 后端镜像构建（基于已编译的 JAR）
│       └── .dockerignore
├── sql/
│   └── prison_schema.sql       # 数据库初始化脚本
└── scripts/
    ├── build.sh               # 本地镜像构建脚本
    ├── deploy.sh              # 远程部署脚本（含源码构建）
    ├── deploy-jar-only.sh     # 新增：仅部署已编译 JAR 包
    ├── init-db.sh            # 数据库初始化脚本
    └── save-images.sh        # 基础镜像打包脚本
```

## 🎯 两种部署模式对比

| 部署模式 | 使用场景 | 是否需要源码 | 是否需要编译 | 构建位置 |
|---------|---------|------------|------------|---------|
| **源码构建** | 开发环境、有构建权限的环境 | ✅ 需要 | ✅ 需要 | Docker 容器内 |
| **JAR 包部署** | 生产环境、无构建权限的环境 | ❌ 不需要 | ❌ 不需要 | 本地已完成编译 |

---

## 📦 方式一：JAR 包部署（推荐生产环境）

### 适用场景

- 生产服务器没有 Maven/Node.js 环境
- 希望快速部署，不想在服务器上编译
- 源码不对外开放，只交付编译产物

### 前置要求

1. **本地已完成编译**：
   ```bash
   # 后端编译
   cd backend
   mvn clean package -DskipTests

   # 前端编译（如果使用 Docker 构建 Nginx 镜像）
   cd frontend
   pnpm install
   pnpm build:prod
   ```

2. **服务器环境**：
   - Docker 20.10+
   - Docker Compose 2.0+
   - 至少 4GB 内存, 20GB 磁盘空间

### 部署步骤

#### 1. 本地构建 JAR 包镜像

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

# 使用专门的 JAR 包部署脚本
./scripts/deploy-jar-only.sh
```

这个脚本会：
- ✅ 检查后端 JAR 包是否存在（`backend/yudao-server/target/yudao-server.jar`）
- ✅ 检查前端构建产物是否存在（`frontend/dist/`）
- ✅ 使用 `docker/backend/Dockerfile.jar` 构建 Docker 镜像
- ✅ 上传镜像到远程服务器
- ✅ 上传必要的配置文件和 docker-compose.yml
- ✅ 在远程服务器启动服务

#### 2. 手动部署流程（如果不用脚本）

**2.1 本地构建镜像**

```bash
cd deploy

# 构建后端镜像（基于已编译的 JAR）
docker build -f docker/backend/Dockerfile.jar -t xlcp-backend:latest ../backend

# 构建前端镜像（基于已编译的 dist）
docker build -f docker/frontend/Dockerfile.dist -t xlcp-frontend:latest ../frontend
```

**2.2 导出镜像**

```bash
# 导出镜像为 tar 文件
docker save xlcp-backend xlcp-frontend | gzip > xlcp-images.tar.gz
```

**2.3 上传到服务器**

```bash
# 上传镜像文件
scp xlcp-images.tar.gz root@192.168.10.150:/projects/data/xlcp/

# 上传配置文件
rsync -avz \
    --exclude 'node_modules' \
    --exclude 'target' \
    --exclude '.git' \
    --exclude 'backend' \
    --exclude 'frontend' \
    ./ root@192.168.10.150:/projects/data/xlcp/deploy/
```

**2.4 服务器端加载镜像**

```bash
# SSH 到服务器
ssh root@192.168.10.150

# 进入目录
cd /projects/data/xlcp

# 加载镜像
docker load -i xlcp-images.tar.gz

# 启动服务
cd deploy
docker compose up -d
```

#### 3. 验证部署

```bash
# 健康检查
curl http://192.168.10.150:48080/actuator/health
curl http://192.168.10.150/

# 查看日志
ssh root@192.168.10.150 'cd /projects/data/xlcp/deploy && docker compose logs -f'
```

---

## 🔨 方式二：源码构建部署（开发环境）

### 适用场景

- 开发环境
- 服务器有完整的构建环境（Maven, Node.js）
- 需要在服务器上实时修改代码并重新构建

### 部署步骤

#### 使用现有的 deploy.sh 脚本

```bash
cd deploy

# 默认部署到 root@192.168.10.150
./scripts/deploy.sh

# 或指定服务器
REMOTE_SERVER=root@192.168.10.150 ./scripts/deploy.sh
```

脚本会：
1. 上传源代码到服务器
2. 在服务器上使用 Docker 构建镜像
3. 启动所有服务

---

## 📂 文件说明

### 核心配置文件

- **docker-compose.yml**：服务编排文件，定义 MySQL、Redis、Backend、Frontend 服务
- **config/application-prod.yaml**：生产环境配置（数据库连接、Redis 配置等）

### Docker 镜像构建文件

- **docker/backend/Dockerfile**：多阶段构建，从源码编译（Maven + Java 源码 → JAR → 镜像）
- **docker/backend/Dockerfile.jar**：直接使用已编译的 JAR 包（JAR → 镜像）- **新增**
- **docker/frontend/Dockerfile**：前端构建（Node.js + Vue 源码 → dist → Nginx 镜像）
- **docker/frontend/Dockerfile.dist**：直接使用已编译的 dist（dist → Nginx 镜像）- **新增**

### 部署脚本

- **scripts/deploy.sh**：源码构建部署（上传源码 → 服务器构建）
- **scripts/deploy-jar-only.sh**：JAR 包部署（本地构建镜像 → 上传镜像）- **新增**
- **scripts/save-images.sh**：打包基础镜像（MySQL, Redis, Nginx, Java）
- **scripts/upload-to-150.sh**：上传镜像到 192.168.10.150
- **scripts/init-db.sh**：初始化数据库

---

## 🔍 部署流程详解

### JAR 包部署流程（推荐）

```
[本地] 编译 JAR 包
   ↓
[本地] 构建 Docker 镜像（基于 JAR）
   ↓
[本地] 导出镜像为 tar 文件
   ↓
[上传] 镜像文件 + 配置文件 → 服务器
   ↓
[服务器] 加载镜像
   ↓
[服务器] docker compose up -d
   ↓
[完成] 服务运行
```

### 源码构建部署流程

```
[上传] 源代码 + 配置文件 → 服务器
   ↓
[服务器] docker compose build（在容器内编译）
   ↓
[服务器] docker compose up -d
   ↓
[完成] 服务运行
```

---

## 🚀 快速命令参考

### JAR 包部署（推荐生产）

```bash
# 1. 本地编译
cd backend && mvn clean package -DskipTests
cd ../frontend && pnpm build:prod

# 2. 本地构建镜像
cd ../deploy
./scripts/deploy-jar-only.sh root@192.168.10.150
```

### 源码构建部署（开发环境）

```bash
# 直接部署（服务器上构建）
cd deploy
./scripts/deploy.sh root@192.168.10.150
```

### 服务管理

```bash
# 查看状态
ssh root@192.168.10.150 'cd /projects/data/xlcp/deploy && docker compose ps'

# 查看日志
ssh root@192.168.10.150 'cd /projects/data/xlcp/deploy && docker compose logs -f backend'

# 重启服务
ssh root@192.168.10.150 'cd /projects/data/xlcp/deploy && docker compose restart backend'

# 停止服务
ssh root@192.168.10.150 'cd /projects/data/xlcp/deploy && docker compose down'

# 更新服务（重新构建镜像）
docker compose build backend && docker compose up -d backend
```

---

## ⚠️ 注意事项

### 生产环境建议

1. **使用 JAR 包部署**，不要在服务器上编译
2. **修改默认密码**（MySQL root、Redis）
3. **配置防火墙**，仅开放必要端口（80, 443）
4. **启用 HTTPS**，配置 SSL 证书
5. **定期备份数据**（数据库、上传文件）
6. **监控日志**，及时发现异常

### 磁盘空间管理

```bash
 # 查看磁盘使用
docker system df

# 清理未使用的镜像
docker image prune -a

# 清理未使用的容器
docker container prune

# 清理未使用的卷
docker volume prune

# 全面清理（谨慎使用）
docker system prune -a --volumes
```

### 网络配置

如果服务器有防火墙，确保开放以下端口：

- **80**：HTTP 访问（前端）
- **443**：HTTPS 访问（前端，如果启用 SSL）
- **48080**：后端 API（可配置防火墙规则仅允许内网访问）

```bash
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --permanent --add-port=48080/tcp
firewall-cmd --reload
```

---

## 📚 附录

### 环境变量说明

| 变量名 | 默认值 | 说明 |
|---------|---------|------|
| 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 参数 |

### 访问地址

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

### 故障排查

#### 1. 后端服务无法启动

```bash
# 查看日志
docker compose logs backend

# 检查数据库连接
docker compose exec backend sh
curl http://mysql:3306

# 检查配置
docker compose exec backend cat /app/config/application-prod.yaml
```

#### 2. 前端页面无法访问

```bash
# 检查 Nginx 配置
docker compose exec frontend nginx -t

# 查看 Nginx 日志
docker compose logs frontend

# 检查静态文件
docker compose exec frontend ls -la /usr/share/nginx/html
```

#### 3. 数据库连接失败

```bash
# 检查 MySQL 容器
docker compose ps mysql
docker compose logs mysql

# 测试连接
docker compose exec mysql mysql -u root -pPrison2024!@ -e "SELECT 1"
```

---

## 🆘 获取帮助

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