# QAUP 系统部署和更新说明

## 一、打包环境操作

### 1. 生成程序更新文件

修改代码后，生成仅包含应用jar的更新包：

```bash
./deploy/package-update.sh
```

**输出**：

- `qaup-admin.jar` - 应用程序
- `UPDATE-INSTRUCTIONS.md` - 更新说明
- `VERSION-INFO.txt` - 版本信息

**注意**：如需单独jar文件，可直接从更新包中提取。

### 2. 生成完整部署包

生成包含所有组件的完整部署包（首次部署或重大更新）：

```bash
./deploy/package-all.sh
```

---

## 二、生产环境操作

### 1. 首次部署

#### 步骤

1. **解压部署包**：

   ```bash
   mkdir qaup-deploy

   tar -xzf qaup-deploy-xxx.tar.gz -C qaup-deploy
   cd qaup-deploy

   ```

2. **执行部署**：

   ```bash
   ./deploy-all.sh
   ```

3. **验证部署**：

   ```bash
   docker compose ps              # 检查服务状态
   curl http://localhost:8080/actuator/health  # 验证应用健康
   ```

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

#### 前置准备

```bash
cd qaup-deploy

# 1. 确认当前系统状态
docker compose ps

# 2. 备份重要数据（推荐）
docker exec qaup-postgres pg_dump -U qaup qaup > backup-$(date +%Y%m%d).sql
cp config.yml config.yml.backup
```

#### 更新步骤

```bash
# 1. 准备新版本文件（二选一）
# 方案A：使用完整更新包
cp /path/to/qaup-update-xxx/qaup-admin.jar new-app.jar

# 方案B：直接使用jar文件
cp /path/to/qaup-admin-xxx.jar new-app.jar

# 2. 执行更新
./deploy-update.sh

# 3. 验证更新
   docker compose ps              # 检查服务状态
   docker compose logs -f qaup-app  # 查看应用日志
   curl http://localhost:8080/actuator/health  # 验证应用健康
```

### 3. 配置文件更新

如果需要更新配置文件：

```bash
cd qaup-deploy

# 1. 备份当前配置
cp config.yml config.yml.backup

# 2. 编辑配置文件
vi config.yml

# 3. 重启应用
   docker compose restart qaup-app
```

### 4. 更新失败处理

#### 自动回滚

更新失败时脚本会自动尝试回滚。

#### 手动回滚

```bash
cd qaup-deploy

# 1. 停止应用
   docker compose stop qaup-app

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

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

#### 问题排查

```bash
# 查看应用日志
docker compose logs qaup-app

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

### 5. 完全重新部署

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

#### 方案A：不保留数据

```bash
cd qaup-deploy

# 1. 清理旧环境
   docker compose down
rm -rf data/  # 注意：会删除所有数据

# 2. 重新部署
./deploy-all.sh
```

#### 方案B：保留数据

```bash
# 1. 备份旧数据
cd qaup-deploy
docker exec qaup-postgres pg_dump -U qaup qaup > ../data-backup.sql

# 2. 清理旧环境
   docker compose down

# 3. 部署新系统
mkdir qaup-deploy-new
tar -xzf qaup-deploy-new-xxx.tar.gz -C qaup-deploy-new
cd qaup-deploy-new
./deploy-all.sh

# 4. 恢复数据
   docker exec -i qaup-postgres psql -U qaup qaup < ../data-backup.sql
```

## 三、常见问题

### Q: 更新后无法访问系统？

A: 检查端口和应用日志：

```bash
   docker compose logs qaup-app
```

### Q: 端口冲突？

A: 检查端口占用：

```bash
   netstat -tlnp | grep 8080
```

### Q: 数据库连接失败？

A: 检查数据库服务状态：

```bash
   docker compose logs qaup-postgres
docker exec qaup-postgres pg_isready -U qaup
```

## 四、更新记录

建议记录每次更新信息：

```
时间         | 版本号       | 人员 | 类型          | 结果   | 问题
2025-01-05   | v1.0.1→v1.0.2 | 张三 | 程序更新      | 成功   | - 
2025-01-10   | v1.0.2→v1.0.3 | 李四 | 程序更新      | 失败   | 配置错误，已回滚
```

## 五、数据库部署和更新策略

### 1. 数据库版本管理

系统使用Flyway进行数据库版本管理，所有迁移脚本位于`qaup-admin/src/main/resources/db/migration/`目录下。

**迁移脚本列表**：

- `V1.0.0__Initial_baseline.sql` - 基线结构（86KB）
- `V1.0.1__Initial_data.sql` - 初始数据（50KB）
- `README.md` - 迁移脚本说明

#### Flyway配置（在docker-compose.yml中）

```yaml
SPRING_FLYWAY_ENABLED: true                    # 启用Flyway
SPRING_FLYWAY_BASELINE_ON_MIGRATE: true        # 基线迁移（支持已有数据库）
SPRING_FLYWAY_VALIDATE_ON_MIGRATE: true        # 验证迁移
SPRING_FLYWAY_CLEAN_DISABLED: true             # 禁止清理生产数据库
SPRING_FLYWAY_LOCATIONS: classpath:db/migration # 迁移脚本路径
```

### 2. 数据库部署流程

#### 首次部署（全新环境）

```bash
# 1. 启动基础服务（PostgreSQL + Redis）
docker compose up -d qaup-postgres qaup-redis

# 2. 等待数据库就绪
sleep 30

# 3. 初始化数据库（执行Flyway迁移）
# 应用启动时会自动执行Flyway迁移
docker compose up -d qaup-app

# 4. 验证部署
docker compose ps
curl http://localhost:8080/actuator/health
```

#### 已有环境更新

```bash
# Flyway自动处理数据库迁移
# 应用启动时会自动检测并执行需要的迁移
docker compose restart qaup-app

# 检查迁移状态
docker exec qaup-postgres psql -U qaup -d qaup -c "SELECT * FROM flyway_schema_history ORDER BY installed_rank;"
```

### 3. 数据库迁移脚本管理

#### 脚本命名规范

- `V{版本号}__{描述}.sql` - 版本化迁移脚本
- `V1.0.0__Initial_baseline.sql` - 基线结构
- `V1.0.1__Initial_data.sql` - 初始数据
- `V1.0.2__Add_new_feature.sql` - 新功能

#### 迁移类型

1. **结构迁移** - 修改表结构、索引等
2. **数据迁移** - 数据清洗、转换等
3. **函数/存储过程迁移** - 业务逻辑更新

### 4. 数据库维护操作

#### 数据备份和恢复（仅限紧急情况）

```bash
# 备份数据
docker exec qaup-postgres pg_dump -U qaup qaup > backup-$(date +%Y%m%d_%H%M%S).sql

# 恢复数据（生产环境需要谨慎）
cat backup-20250115_143000.sql | docker exec -i qaup-postgres psql -U qaup -d qaup
```

#### 数据库状态监控

```bash
# 查看Flyway迁移状态（应用启动日志）
docker compose logs qaup-app | grep -i flyway

# 直接查询迁移历史
docker exec qaup-postgres psql -U qaup -d qaup -c "
SELECT version, description, installed_on 
FROM flyway_schema_history 
ORDER BY installed_rank;"

# 检查应用健康状态
curl http://localhost:8080/actuator/health
```

### 5. 数据库更新最佳实践

#### 开发环境

- 可以使用`flyway.clean()`清理数据库
- 可以使用`flyway.migrate().clean()`重建

#### 生产环境

- 禁止使用`flyway.clean()`
- 优先使用增量迁移脚本
- 重大变更需要测试环境验证

#### 回滚策略

1. **自动化回滚** - 备份恢复
2. **脚本化回滚** - 创建回滚脚本
3. **版本控制** - 通过Flyway版本管理

## 六、文件说明

### 打包环境脚本

- `deploy/package-update.sh` - 生成程序更新包
- `deploy/package-all.sh` - 生成完整部署包

### 生产环境脚本

- `deploy-all.sh` - 首次部署/完全重新部署
- `deploy-update.sh` - 程序更新脚本（自动处理数据库迁移）
- `DeployGuide.md` - 本说明文档

### 数据库脚本目录

- `src/main/resources/db/migration/` - Flyway迁移脚本
- `sql/qaup_database_complete_init.sql` - 完整初始化脚本（参考用途）
- `sql/unified_database_migration.sql` - 合并迁移脚本（历史用途）