tangweijie
bc40155ef0
- 新增 deploy/ 目录包含 Docker 部署配置、数据库脚本、部署脚本 - 更新 .gitignore 忽略 deploy 构建产物 - 添加 AGENTS.md AI Agent 指南 - 添加项目构建脚本 build.sh
394 lines
9.3 KiB
Markdown
394 lines
9.3 KiB
Markdown
# 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`
|