tian/QAUP_Management

Fork 0

Tian jianyong ed4eddc071 修改部署文档

2025-08-01 19:44:48 +08:00

11 KiB

Raw Permalink Blame History

QAUP 系统 Docker 部署指南

概述

本文档详细介绍了如何在 Ubuntu 系统上使用 Docker 部署 QAUP 管理系统。该部署方案支持生产环境使用，包含完整的监控、日志管理和备份功能。

系统要求

硬件要求

CPU: 最少 2 核，推荐 4 核或以上
内存: 最少 4GB，推荐 8GB 或以上
磁盘: 最少 20GB 可用空间，推荐 50GB 或以上
网络: 稳定的网络连接（内网部署无需外网）

软件要求

操作系统: Ubuntu 18.04 LTS 或更高版本
Docker: 20.10 或更高版本
Docker Compose: 1.29 或更高版本
其他工具: curl, wget, unzip
Python环境（可选，用于开发工具）: Python 3.6+, pip

安装 Docker 和 Docker Compose

安装 Docker

# 更新包索引
sudo apt update

# 安装必要的包
sudo apt install apt-transport-https ca-certificates curl gnupg lsb-release

# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 设置稳定版仓库
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker Engine
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER

# 重新登录或运行以下命令
newgrp docker

安装 Docker Compose

# 下载 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 添加执行权限
sudo chmod +x /usr/local/bin/docker-compose

# 验证安装
docker-compose --version

项目结构说明

QAUP 系统采用了优化的部署结构，所有部署相关文件都集中在 deploy 目录下：

QAUP-Management/
├── deploy/                    # 部署目录（工作目录）
│   ├── deploy.sh             # 主部署脚本
│   ├── docker-compose.yml    # Docker Compose 配置
│   ├── docker-compose.prod.yml # 生产环境配置
│   ├── Dockerfile            # 应用镜像构建文件
│   ├── .env.template         # 环境变量模板
│   ├── docker/               # Docker 相关脚本和配置
│   │   ├── config-manager.sh # 配置管理脚本
│   │   ├── monitor.sh        # 监控脚本
│   │   ├── nginx/            # Nginx 配置
│   │   └── postgres/         # PostgreSQL 配置
│   └── docs/                 # 部署文档
├── qaup-admin/               # 后端主模块
├── qaup-ui/                  # 前端模块
└── 其他项目文件...

离线部署包结构（更新后）：

qaup-offline-deploy/
├── docker-compose.yml        # Docker Compose 配置（根目录）
├── docker-compose.prod.yml   # 生产环境配置（根目录）
├── .env.template             # 环境变量模板（根目录）
├── deploy.sh                 # 部署脚本
├── images/                   # Docker 镜像文件
├── scripts/                  # 部署脚本
└── README-离线部署.md        # 离线部署说明

重要说明：

所有部署操作都在 deploy 目录下进行
Docker 构建上下文指向项目根目录，确保能正确访问所有源码文件
部署脚本会自动处理路径映射，无需手动调整

部署步骤

1. 获取部署包

在线部署

# 克隆项目（如果有 Git 访问权限）
git clone <项目地址>
cd QAUP-Management/deploy

离线部署

# 解压离线部署包
tar -xzf qaup-offline-deploy.tar.gz
cd QAUP-Management/deploy

# 导入 Docker 镜像
./docker/load-images.sh

2. 路径配置验证

# 运行路径配置测试（推荐）
./test-paths.sh

3. 环境验证

# 运行环境验证脚本
./docker/validate-environment.sh

如果验证失败，请根据提示修复问题。

4. 数据准备

根据部署场景选择合适的数据准备方式：

场景1：全新部署（推荐新用户）

# 使用默认模板数据
./docker/postgres/db-manager.sh prepare-default

场景2：从现有系统迁移

# 设置数据库连接信息
export DB_HOST=your_db_host
export DB_USER=postgres
export DB_NAME=qaup

# 从现有数据库导出并准备数据
./docker/postgres/db-manager.sh prepare-export

场景3：查看当前数据状态

# 查看当前数据文件状态
./docker/postgres/db-manager.sh prepare-status

6. 配置系统

# 初始化配置
./docker/config-manager.sh init

# 编辑环境配置文件
nano .env

重要配置项说明：

# 数据库配置
POSTGRES_DB=qaup
POSTGRES_USER=postgres
POSTGRES_PASSWORD=请设置强密码
APP_DB_USER=qaup_app
APP_DB_PASSWORD=请设置强密码

# Redis 配置
REDIS_PASSWORD=请设置密码或留空

# 应用配置
SPRING_PROFILES_ACTIVE=prod
APP_PORT=8080

# Nginx 配置
NGINX_PORT=80
SERVER_NAME=your-domain.com  # 替换为实际域名或IP
API_PREFIX=/prod-api

# 目录配置
DATA_DIR=./data
LOG_DIR=./logs
BACKUP_DIR=./backup

4. 一键部署

# 运行一键部署脚本
./deploy.sh install

部署脚本将自动执行以下步骤：

检查系统要求
初始化配置
验证环境
构建 Docker 镜像
启动服务
等待服务就绪
运行健康检查

5. 验证部署

部署完成后，访问以下地址验证：

前端界面: http://your-server-ip
API 健康检查: http://your-server-ip/health
应用健康检查: http://your-server-ip/prod-api/actuator/health

服务管理

基本操作

# 查看服务状态
./deploy.sh status

# 启动服务
./deploy.sh start

# 停止服务
./deploy.sh stop

# 重启服务
./deploy.sh restart

# 查看日志
./deploy.sh logs all          # 所有服务日志
./deploy.sh logs app          # 应用日志
./deploy.sh logs nginx        # Nginx 日志

高级管理

# 使用 Docker Compose 管理器
./docker/docker-compose-manager.sh prod start
./docker/docker-compose-manager.sh prod stop
./docker/docker-compose-manager.sh prod restart
./docker/docker-compose-manager.sh prod status

# 日志管理
./docker/log-manager.sh view app 100     # 查看应用最近100行日志
./docker/log-manager.sh monitor all      # 实时监控所有日志
./docker/log-manager.sh analyze          # 分析错误日志
./docker/log-manager.sh cleanup 30       # 清理30天前的日志

# 系统监控
./docker/monitor.sh status               # 检查系统状态
./docker/monitor.sh watch 60             # 每60秒监控一次
./docker/monitor.sh resources            # 查看资源使用

监控和告警

系统监控

# 实时监控
./docker/monitor.sh watch

# 生成监控报告
./docker/monitor.sh report

# 检查告警
./docker/alert-manager.sh check

# 持续告警监控
./docker/alert-manager.sh monitor 300    # 每5分钟检查一次

健康检查

系统提供多层次的健康检查：

容器级健康检查: Docker 内置健康检查
服务级健康检查: 应用程序健康端点
系统级健康检查: 资源使用监控

数据备份和恢复

数据库备份

# 手动备份
docker exec qaup-postgres /backup-db.sh

# 查看备份文件
ls -la ./backup/postgres/

# 恢复数据库
docker exec qaup-postgres /restore-db.sh /backup/qaup_backup_20241231_120000.sql.gz

配置备份

# 备份配置文件
./docker/config-manager.sh backup

# 查看备份
ls -la ./backup/config/

故障排除

常见问题

1. 容器启动失败

# 查看容器状态
docker ps -a

# 查看容器日志
docker logs qaup-app
docker logs qaup-postgres
docker logs qaup-redis
docker logs qaup-nginx

# 检查资源使用
docker stats

2. 数据库连接失败

# 检查数据库容器状态
docker exec qaup-postgres pg_isready -h localhost -p 5432 -U postgres

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

# 测试数据库连接
docker exec qaup-postgres psql -U postgres -d qaup -c "SELECT version();"

3. 前端无法访问

# 检查 Nginx 状态
curl -I http://localhost/health

# 检查 Nginx 配置
docker exec qaup-nginx nginx -t

# 查看 Nginx 日志
docker logs qaup-nginx

4. 应用响应慢

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

# 查看应用日志
docker logs qaup-app | grep -i "error\|exception"

# 检查资源使用
docker stats qaup-app

日志分析

# 分析错误日志
./docker/log-manager.sh analyze

# 查看特定时间段的日志
docker logs qaup-app --since "2024-01-01T00:00:00" --until "2024-01-01T23:59:59"

# 搜索特定错误
docker logs qaup-app | grep -i "OutOfMemoryError"

性能优化

JVM 调优

编辑 .env 文件中的 JVM 参数：

# 生产环境 JVM 配置
JVM_OPTS=-Dname=qaup-admin.jar -Duser.timezone=Asia/Shanghai -server -Xms2g -Xmx4g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m -XX:+UseG1GC -XX:G1HeapRegionSize=16m

数据库优化

编辑 docker/postgres/postgresql.conf：

# 根据服务器配置调整
shared_buffers = 512MB          # 25% of RAM
effective_cache_size = 2GB      # 75% of RAM
work_mem = 8MB
maintenance_work_mem = 128MB

Nginx 优化

编辑 docker/nginx/nginx.conf：

worker_processes auto;
worker_connections 2048;
keepalive_timeout 65;
client_max_body_size 50M;

安全配置

防火墙设置

# 只开放必要端口
sudo ufw allow 22/tcp          # SSH
sudo ufw allow 80/tcp          # HTTP
sudo ufw allow 443/tcp         # HTTPS
sudo ufw enable

SSL/TLS 配置

获取 SSL 证书（Let's Encrypt 或商业证书）
将证书文件放置在 ./ssl/ 目录
更新 Nginx 配置启用 HTTPS

密码安全

# 生成强密码
./docker/secrets-manager.sh generate

# 检查密码强度
./docker/secrets-manager.sh check

更新和维护

系统更新

# 备份当前部署
./docker/config-manager.sh backup

# 更新部署
./deploy.sh update

# 验证更新
./deploy.sh status

定期维护

建议定期执行以下维护任务：

# 每日
./docker/alert-manager.sh check
./docker/monitor.sh status

# 每周
./docker/log-manager.sh cleanup 30
./docker/log-manager.sh compress

# 每月
docker system prune -f
./docker/config-manager.sh backup

可选工具安装

Python 开发工具（可选）

如果需要使用项目中的Python开发工具（如mock server），可以安装Python环境：

# 安装Python和pip
sudo apt update
sudo apt install python3 python3-pip

# 安装Flask（用于mock server）
pip3 install flask

# 运行mock server（开发测试用）
cd tools
python3 mock_server.py

联系支持

如果遇到无法解决的问题，请提供以下信息：

系统信息：uname -a
Docker 版本：docker --version
容器状态：docker ps -a
错误日志：相关服务的日志文件
配置文件：.env 文件（隐藏敏感信息）

注意: 本文档会根据系统更新持续维护，请定期查看最新版本。

11 KiB Raw Permalink Blame History Unescape Escape