QAUP_Management/deploy/DeployGuide.md

# QAUP 系统部署和更新说明

## 开发环境操作

### 生成程序更新文件

当代码修改后，需要生成新的jar文件供客户更新：

```bash
./deploy/simple/build-update.sh
```
生成包含详细说明的更新包：
- `qaup-admin.jar` - 应用程序
- `UPDATE-INSTRUCTIONS.md` - 详细更新说明
- `VERSION-INFO.txt` - 版本信息

**注意**：如果只需要jar文件，可以从生成的更新包中提取 `qaup-admin.jar` 文件单独发送给客户。

### 生成完整部署包
```bash
./deploy/simple/package.sh
```
生成包含所有组件的完整部署包，用于首次部署或重大版本更新。

---

## 客户环境操作

### 首次部署

### 1. 解压部署包
```bash
mkdir qaup-deploy
tar -xzf qaup-deploy-20250105-143022.tar.gz -C qaup-deploy
cd qaup-deploy
```

### 2. 执行部署
```bash
./deploy.sh
```

### 3. 验证部署
```bash
# 检查服务状态
docker compose ps

# 访问系统
curl http://localhost:8080/actuator/health
```

## 程序更新（仅更新jar文件）

### 更新前准备

1. **确认当前系统状态**：
   ```bash
   cd qaup-deploy
   docker compose ps
   ```

2. **备份重要数据**（可选但推荐）：
   ```bash
   # 备份数据库
   docker exec qaup-postgres pg_dump -U qaup qaup > backup-$(date +%Y%m%d).sql
   
   # 备份配置文件
   cp config.yml config.yml.backup
   ```

### 更新步骤

### 1. 准备新版本文件

#### 如果收到的是完整更新包（.tar.gz文件）：
```bash
# 解压更新包
tar -xzf qaup-update-20250105-143022.tar.gz
cd qaup-update-20250105-143022

# 查看更新说明
cat UPDATE-INSTRUCTIONS.md

# 复制jar文件到部署目录
cd ../qaup-deploy
cp ../qaup-update-20250105-143022/qaup-admin.jar new-app.jar
```

#### 如果收到的是jar文件：
```bash
cd qaup-deploy
cp /path/to/qaup-admin-20250105-143022.jar new-app.jar
```

### 2. 执行程序更新
```bash
./update.sh
```

### 3. 验证更新结果
```bash
# 检查服务状态
docker compose ps

# 检查应用日志
docker compose logs -f qaup-app

# 访问系统确认功能正常
curl http://localhost:8080/actuator/health
```

## 更新失败处理

如果更新失败，脚本会自动尝试回滚。如果自动回滚也失败：

### 手动回滚：
```bash
# 停止应用
docker compose stop qaup-app

# 恢复备份文件
cp app.jar.backup.* app.jar

# 启动应用
docker compose start qaup-app
```

### 检查问题：
```bash
# 查看应用日志
docker compose logs qaup-app

# 查看所有服务状态
docker compose ps -a
```

## 配置文件更新

如果新版本需要更新配置文件：

1. **备份当前配置**：
   ```bash
   cp config.yml config.yml.backup
   ```

2. **更新配置**：
   ```bash
   # 编辑配置文件
   vi config.yml
   ```

3. **重启应用**：
   ```bash
   docker compose restart qaup-app
   ```

## 常见问题

### Q: 更新后无法访问系统
A: 检查端口是否被占用，查看应用日志：
```bash
docker compose logs qaup-app
netstat -tlnp | grep 8080
```

### Q: 数据库连接失败
A: 检查数据库服务状态：
```bash
docker compose logs qaup-postgres
docker exec qaup-postgres pg_isready -U qaup
```

### Q: 如何完全重新部署
A: 如果更新出现严重问题，可以重新部署：
```bash
# 停止所有服务
docker compose down

# 清理数据（注意：这会删除所有数据）
rm -rf data/

# 重新部署
./deploy.sh
```

## 完整系统重新部署

如果需要重新部署整个系统（包括更新Docker镜像、配置等）：

### 1. 获取新的部署包
```bash
# 解压新的部署包到新目录
mkdir qaup-deploy-new
tar -xzf qaup-deploy-new-20250110-100000.tar.gz -C qaup-deploy-new
cd qaup-deploy-new
```

### 2. 迁移数据（如果需要保留数据）
```bash
# 从旧系统备份数据
cd ../qaup-deploy
docker exec qaup-postgres pg_dump -U qaup qaup > ../data-backup.sql

# 停止旧系统
docker compose down

# 在新系统中恢复数据
cd ../qaup-deploy-new
./deploy.sh
docker exec -i qaup-postgres psql -U qaup qaup < ../data-backup.sql
```

## 操作流程总结

### 开发环境 → 客户环境流程

#### 程序更新流程：
```
开发环境:
1. 代码修改完成
2. ./deploy/simple/build-update.sh       # 生成更新包
3. 发送更新包或jar文件给客户

客户环境:
1. cd qaup-deploy
2. cp new-jar-file.jar new-app.jar       # 重命名文件
3. ./update.sh                           # 执行更新
4. 验证更新结果
```

#### 完整部署流程：
```
开发环境:
1. ./deploy/simple/package.sh            # 生成完整部署包
2. 发送部署包给客户

客户环境:
1. mkdir qaup-deploy && tar -xzf qaup-deploy-xxx.tar.gz -C qaup-deploy  # 解压部署包
2. cd qaup-deploy
3. ./deploy.sh                           # 执行部署
4. 验证部署结果
```

## 更新记录

建议记录每次更新的信息：
- 更新时间
- 版本号
- 更新人员
- 更新类型（程序更新/完整部署）
- 是否成功
- 遇到的问题

示例：
```
2025-01-05 14:30 - v1.0.1 → v1.0.2 - 张三 - 程序更新 - 成功
2025-01-10 09:15 - v1.0.2 → v1.0.3 - 李四 - 程序更新 - 失败，已回滚
2025-01-15 16:00 - v1.0.3 → v1.1.0 - 王五 - 完整部署 - 成功
```

## 文件说明

### 开发环境脚本：
- `deploy/simple/build-update.sh` - 生成程序更新包
- `deploy/simple/package.sh` - 生成完整部署包

### 客户环境脚本：
- `deploy.sh` - 首次部署脚本
- `update.sh` - 程序更新脚本
- `DeployGuide.md` - 本说明文档