xlcp/deploy/DEPLOY_JAR.md

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. 本地已完成编译：

   # 后端编译
   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 包镜像

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 本地构建镜像

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 导出镜像

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

2.3 上传到服务器

# 上传镜像文件
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 服务器端加载镜像

# 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. 验证部署

# 健康检查
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 脚本

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 包部署（推荐生产）

# 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

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

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

服务管理

# 查看状态
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. 监控日志，及时发现异常

磁盘空间管理

 # 查看磁盘使用
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（可配置防火墙规则仅允许内网访问）

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. 后端服务无法启动

# 查看日志
docker compose logs backend

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

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

2. 前端页面无法访问

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

# 查看 Nginx 日志
docker compose logs frontend

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

3. 数据库连接失败

# 检查 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