# QAUP系统部署指南

本文档提供了QAUP系统的完整部署指南，包括环境配置、服务启动、监控和故障排除。

## 目录结构

- [1. 系统架构概述](#1-系统架构概述)
- [2. 环境准备](#2-环境准备)
- [3. 配置管理](#3-配置管理)
- [4. 服务部署](#4-服务部署)
- [5. 监控与维护](#6-监控与维护)
- [6. 故障排除](#7-故障排除)
- [7. 性能优化](#8-性能优化)

## 1. 系统架构概述

QAUP系统采用微服务架构，主要组件包括：

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端界面       │    │   后端服务       │    │   ADXP适配器     │
│   (qaup-ui)     │◄──►│ (qaup-collision) │◄──►│ (adxp-adapter)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       ▼                       │
         │              ┌─────────────────┐              │
         │              │   外部接口       │              │
         │              │   (地图、车辆)   │              │
         │              └─────────────────┘              │
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 ▼
                    ┌─────────────────┐    ┌─────────────────┐
                    │   数据存储       │    │   缓存服务       │
                    │  (PostgreSQL)   │    │    (Redis)      │
                    └─────────────────┘    └─────────────────┘
```

### 核心服务

- **qaup-collision**: 核心碰撞检测和数据处理服务
- **adxp-adapter**: ADXP数据适配器，负责与机场系统通信
- **qaup-admin**: 管理后台服务
- **qaup-ui**: 前端用户界面

## 2. 环境准备

### 2.1 系统要求

#### 最低配置

- **操作系统**: Linux (Ubuntu 20.04+) / Windows Server 2019+
- **内存**: 8GB RAM
- **存储**: 50GB SSD
- **网络**: 千兆以太网

#### 推荐配置

- **操作系统**: Linux (Ubuntu 22.04 LTS)
- **内存**: 16GB RAM 或更高
- **存储**: 100GB SSD
- **网络**: 千兆以太网

### 2.2 软件依赖

```bash
# 必需软件版本
- Docker: 24.0+
- Docker Compose: 2.20+
- JDK: 21+ (OpenJDK 推荐)
- Maven: 3.8+
- Node.js: 18+ (用于前端构建)
```

### 2.3 端口分配

| 服务 | 端口 | 描述 |
|-----|------|------|
| qaup-collision | 8080 | 核心服务API |
| qaup-admin | 8081 | 管理后台API |
| qaup-ui | 80/443 | 前端界面 |
| adxp-adapter | 8086 | ADXP适配器 |
| PostgreSQL | 5432 | 数据库服务 |
| Redis | 6379 | 缓存服务 |

## 3. 配置管理

### 3.1 环境变量配置

在项目根目录创建 `.env` 文件：

```bash
# ============================================
# QAUP系统环境变量配置
# ============================================

# 数据库配置
DB_HOST=localhost
DB_PORT=5432
DB_NAME=qaup
DB_USERNAME=qaup
DB_PASSWORD=qaup123

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# 应用服务配置
SERVER_PORT=8080
ADMIN_PORT=8081
ADAPTER_PORT=8086

# ADXP适配器配置
ADXP_SERVER_URL=http://localhost:8090
ADXP_USERNAME=admin
ADXP_PASSWORD=admin123
ADXP_ENABLED=true

# 日志配置
LOG_LEVEL=INFO
LOG_PATH=/app/logs

# 数据采集配置
DATA_COLLECTOR_INTERVAL=250
DATA_COLLECTOR_ENABLED=true

# 外部服务配置
AIRPORT_VEHICLE_API_URL=http://10.32.38.3:8090
MAP_SERVICE_URL=http://221.215.103.144:8090/iserver/services/map-QDJC_DT-GX3/rest/maps

# 安全配置
JWT_SECRET=your-jwt-secret-key-here
ENCRYPT_KEY=your-encryption-key-here

# 监控配置
ACTUATOR_ENABLED=true
HEALTH_CHECK_INTERVAL=30
```

### 3.2 配置文件结构

```
config/
├── application.yml              # 主配置文件
├── application-dev.yml          # 开发环境配置
├── application-test.yml         # 测试环境配置
├── application-prod.yml         # 生产环境配置
├── application-druid.yml        # 数据库连接池配置
└── logback-spring.xml           # 日志配置
```

### 3.3 敏感信息管理

```bash
# 使用密钥管理敏感配置
docker secret create db_password db_password.txt
docker secret create jwt_secret jwt_secret.txt

# 在docker-compose.yml中引用
secrets:
  - db_password
  - jwt_secret
```

## 4. 服务部署

### 4.1 快速启动

使用提供的服务管理脚本：

```bash
# 进入部署目录
cd deploy/

# 启动所有服务
./qaup-service.sh start

# 查看服务状态
./qaup-service.sh status

# 查看服务日志
./qaup-service.sh logs qaup-app
```

### 4.2 手动部署步骤

#### 4.2.1 数据库初始化

```bash
# 启动数据库服务
docker compose up -d postgres

# 等待数据库启动
docker exec qaup-postgres pg_isready -U qaup

# 执行数据库迁移
docker exec qaup-app java -jar qaup-admin.jar --spring.profiles.active=prod,druid --spring.jpa.hibernate.ddl-auto=update
```

#### 4.2.2 应用服务部署

```bash
# 构建应用镜像
docker compose build qaup-app

# 启动应用服务
docker compose up -d qaup-app

# 等待应用启动
curl http://localhost:8080/actuator/health
```

#### 4.2.3 ADXP适配器部署

```bash
# 构建ADXP适配器镜像
docker compose -f docker-compose.yml -f docker-compose.adxp.yml build adxp-adapter

# 启动ADXP适配器
docker compose -f docker-compose.yml -f docker-compose.adxp.yml up -d adxp-adapter

# 检查适配器状态
curl http://localhost:8086/health
```

### 4.3 Docker Compose配置

创建 `docker-compose.yml`：

```yaml
version: '3.8'

services:
  postgres:
    image: postgis/postgis:15-3.3
    container_name: qaup-postgres
    environment:
      POSTGRES_DB: ${DB_NAME:-qaup}
      POSTGRES_USER: ${DB_USERNAME:-qaup}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-qaup123}
    ports:
      - "${DB_PORT:-5432}:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./sql/init:/docker-entrypoint-initdb.d
    networks:
      - qaup-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME:-qaup}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: qaup-redis
    ports:
      - "${REDIS_PORT:-6379}:6379"
    volumes:
      - redis_data:/data
    networks:
      - qaup-network
    command: redis-server --appendonly yes
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

  qaup-app:
    build:
      context: ../qaup-collision
      dockerfile: Dockerfile
    container_name: qaup-app
    environment:
      SPRING_PROFILES_ACTIVE: prod,druid
      DB_HOST: postgres
      REDIS_HOST: redis
      DB_USERNAME: ${DB_USERNAME}
      DB_PASSWORD: ${DB_PASSWORD}
    ports:
      - "${SERVER_PORT:-8080}:8080"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - qaup-network
    volumes:
      - ./logs:/app/logs
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  postgres_data:
  redis_data:

networks:
  qaup-network:
    driver: bridge
```

## 5. 前端部署

### 5.1 前端构建

```bash
# 进入前端目录
cd qaup-ui/

# 安装依赖
npm install

# 构建生产版本
npm run build:prod

# 使用Nginx部署
docker run -d -p 80:80 -v $(pwd)/dist:/usr/share/nginx/html nginx:alpine
```

### 5.2 Nginx配置

创建 `nginx.conf`：

```nginx
server {
    listen 80;
    server_name localhost;
    
    root /usr/share/nginx/html;
    index index.html;
    
    # 前端路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # API代理
    location /api/ {
        proxy_pass http://qaup-app:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # WebSocket支持
    location /ws/ {
        proxy_pass http://qaup-app:8080/ws/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

## 6. 监控与维护

### 6.1 健康检查

```bash
# 脚本化健康检查
#!/bin/bash
echo "QAUP系统健康检查 - $(date)"

services=("qaup-app:8080" "qaup-admin:8081" "adxp-adapter:8086")
for service in "${services[@]}"; do
    name=$(echo $service | cut -d: -f1)
    port=$(echo $service | cut -d: -f2)
    
    if curl -f -s http://localhost:$port/actuator/health > /dev/null; then
        echo "✓ $name 服务正常"
    else
        echo "✗ $name 服务异常"
    fi
done

# 检查数据库连接
if docker exec qaup-postgres pg_isready -U qaup > /dev/null; then
    echo "✓ 数据库连接正常"
else
    echo "✗ 数据库连接异常"
fi

# 检查Redis连接
if docker exec qaup-redis redis-cli ping > /dev/null; then
    echo "✓ Redis连接正常"
else
    echo "✗ Redis连接异常"
fi
```

### 6.2 日志管理

```bash
# 日志轮转配置
# /etc/logrotate.d/qaup
/app/logs/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 644 qaup qaup
    postrotate
        docker kill -s USR1 qaup-app
    endscript
}
```

### 6.3 性能监控

使用Actuator端点监控：

```bash
# 应用指标
curl http://localhost:8080/actuator/metrics

# 数据库连接池监控
curl http://localhost:8080/actuator/druid

# 系统信息
curl http://localhost:8080/actuator/info
```

## 7. 故障排除

### 7.1 常见问题

#### 服务启动失败

```bash
# 检查端口占用
netstat -tlnp | grep :8080

# 检查Docker容器日志
docker logs qaup-app --tail 100

# 检查资源使用
docker stats
```

#### 数据库连接问题

```bash
# 检查数据库状态
docker exec qaup-postgres pg_isready -U qaup

# 检查网络连接
docker exec qaup-app ping postgres

# 检查数据库日志
docker logs qaup-postgres --tail 50
```

#### ADXP适配器问题

```bash
# 检查适配器配置
docker exec adxp-adapter cat /app/config/adxp.properties

# 测试ADXP连接
curl -X GET "http://localhost:8090/api/health" \
     -H "Authorization: Bearer $ADXP_TOKEN"

# 检查消息队列
docker exec qaup-app java -jar qaup-admin.jar \
     --spring.profiles.active=test \
     --adxp.test.connection=true
```

### 7.2 紧急恢复

```bash
# 快速重启所有服务
./qaup-service.sh restart

# 重建数据库（慎用）
docker-compose down -v
docker volume prune -f
./qaup-service.sh start

# 从备份恢复
docker exec -i qaup-postgres psql -U qaup -d qaup < backup.sql
```

### 7.3 调试模式

```bash
# 启用调试日志
export LOG_LEVEL=DEBUG
./qaup-service.sh restart

# 进入容器调试
docker exec -it qaup-app /bin/bash

# 查看实时日志
tail -f /app/logs/qaup-app.log | grep -E "(ERROR|WARN|Exception)"
```

## 8. 性能优化

### 8.1 JVM调优

```bash
# 生产环境JVM参数
JAVA_OPTS="
  -Xms2g -Xmx4g
  -XX:+UseG1GC
  -XX:MaxGCPauseMillis=200
  -XX:+UnlockExperimentalVMOptions
  -XX:+UseJVMCICompiler
  -Djava.security.egd=file:/dev/./urandom
  -Dspring.jmx.enabled=false
"
```

### 8.2 数据库优化

```sql
-- PostgreSQL配置优化
ALTER SYSTEM SET shared_buffers = '512MB';
ALTER SYSTEM SET effective_cache_size = '2GB';
ALTER SYSTEM SET maintenance_work_mem = '64MB';
ALTER SYSTEM SET checkpoint_completion_target = 0.9;
ALTER SYSTEM SET wal_buffers = '16MB';
ALTER SYSTEM SET default_statistics_target = 100;
ALTER SYSTEM SET random_page_cost = 1.1;
ALTER SYSTEM SET effective_io_concurrency = 200;

SELECT pg_reload_conf();
```

### 8.3 Redis优化

```bash
# Redis配置优化
maxmemory 512mb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000
```

## 9. 安全配置

### 9.1 网络安全

```yaml
# docker-compose.yml中的网络安全配置
networks:
  qaup-network:
    driver: bridge
    internal: true  # 内部网络
```

### 9.2 SSL/TLS配置

```nginx
# Nginx SSL配置
server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /etc/ssl/certs/qaup.crt;
    ssl_certificate_key /etc/ssl/private/qaup.key;
    
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
    ssl_prefer_server_ciphers off;
    
    # HSTS
    add_header Strict-Transport-Security "max-age=63072000" always;
}
```

### 9.3 访问控制

```java
// Spring Security配置示例
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/actuator/health").permitAll()
                .requestMatchers("/api/**").authenticated()
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2.jwt());
        
        return http.build();
    }
}
```

## 10. 备份与恢复

### 10.1 数据备份

```bash
#!/bin/bash
# backup.sh - 数据备份脚本

BACKUP_DIR="/backup/qaup/$(date +%Y%m%d_%H%M%S)"
mkdir -p $BACKUP_DIR

# 数据库备份
docker exec qaup-postgres pg_dump -U qaup qaup > $BACKUP_DIR/database.sql

# 配置文件备份
cp .env $BACKUP_DIR/
cp -r config/ $BACKUP_DIR/

# 日志备份
tar -czf $BACKUP_DIR/logs.tar.gz /app/logs/

echo "备份完成: $BACKUP_DIR"
```

### 10.2 数据恢复

```bash
#!/bin/bash
# restore.sh - 数据恢复脚本

BACKUP_FILE=$1

if [ -z "$BACKUP_FILE" ]; then
    echo "使用方法: ./restore.sh <backup_file>"
    exit 1
fi

# 停止应用服务
docker compose stop qaup-app

# 恢复数据库
docker exec -i qaup-postgres psql -U qaup qaup < $BACKUP_FILE/database.sql

# 重启服务
docker compose start qaup-app

echo "恢复完成"
```

## 附录

### A. 部署检查清单

- [ ] 系统环境准备完成
- [ ] Docker和依赖软件安装
- [ ] 配置文件准备和验证
- [ ] 数据库初始化完成
- [ ] 所有服务启动成功
- [ ] 健康检查通过
- [ ] 前端访问正常
- [ ] 监控和日志配置完成
- [ ] 备份策略实施

### B. 紧急联系信息

- **技术支持**: <tech-support@qaup.com>
- **运维团队**: <ops@qaup.com>
- **值班电话**: +86-xxx-xxxx-xxxx

### C. 相关文档

- [API文档](./api_documentation.md)
- [配置指南](./configuration_guide.md)
- [JDK21升级指南](./JDK21-升级指南.md)
- [环境配置](./environment.md)

---

**文档版本**: v2.0  
**最后更新**: 2025-01-17  
**维护者**: QAUP Development Team