aiagent/docs/deployment-guide.md

🚀 部署与运维指南

Deployment & Operations Guide

本文档面向运维人员，提供天工智能体平台的生产环境部署方案与日常运维指导。

---

一、环境要求

服务器最低配置

环境	CPU	内存	磁盘	网络
开发	2 核	4 GB	20 GB SSD	内网
预发布	4 核	8 GB	50 GB SSD	内网
生产	8 核	16 GB	100 GB SSD	公网

依赖软件

组件	版本	安装方式
Docker	24+	apt install docker.io 或官方脚本
Docker Compose	2.20+	apt install docker-compose-plugin
Nginx	1.24+	apt install nginx
MySQL	8.0+	腾讯云数据库（推荐）或自建
Redis	7+	Docker 运行

---

二、部署架构

                         ┌──────────────┐
                         │   用户浏览器   │
                         └──────┬───────┘
                                │ HTTPS (443)
                         ┌──────▼───────┐
                         │    Nginx     │
                         │  SSL 终止    │
                         │  反向代理    │
                         └──┬───────┬───┘
                            │       │
                 ┌──────────▼─┐ ┌──▼──────────┐
                 │ 前端静态资源 │ │  后端 API    │
                 │ :8038      │ │ :8037       │
                 │ (Vue SPA)  │ │ (FastAPI)   │
                 └────────────┘ └──┬──────┬───┘
                                   │      │
                          ┌────────▼─┐ ┌──▼────────┐
                          │  MySQL   │ │   Redis    │
                          │ (腾讯云)  │ │  (Docker)  │
                          └──────────┘ └───────────┘
                                             │
                                     ┌──────▼──────┐
                                     │ Celery Worker│
                                     │ 异步任务处理  │
                                     └─────────────┘

---

三、部署步骤

Step 1：克隆代码

git clone <repository-url> /opt/aiagent
cd /opt/aiagent

Step 2：配置环境变量

cd backend

# 复制环境变量模板
cp env.example .env

# ⚠️ 编辑 .env 文件
vim .env

关键配置项

变量	说明	示例
DATABASE_URL	MySQL 连接字符串	mysql+asyncmy://user:pass@host:3306/aiagent?charset=utf8mb4
REDIS_URL	Redis 连接地址	redis://localhost:6379/0
SECRET_KEY	JWT 密钥（需随机生成）	openssl rand -hex 32
ACCESS_TOKEN_EXPIRE_MINUTES	Access Token 有效期	30
REFRESH_TOKEN_EXPIRE_DAYS	Refresh Token 有效期	7
CORS_ORIGINS	允许的前端域名	["http://localhost:8038", "https://your-domain.com"]

⚠️ 安全警告：SECRET_KEY 必须使用强随机字符串，切勿硬编码在代码中。

Step 3：使用 Docker Compose 部署

# 构建并启动所有服务
docker-compose -f docker-compose.dev.yml up -d --build

# 确认所有容器正常运行
docker-compose ps

Step 4：配置 Nginx（生产环境）

参考 nginx.conf，关键配置如下：

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;  # HTTP 重定向到 HTTPS
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL 证书配置
    ssl_certificate     /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    # 前端静态资源
    location / {
        proxy_pass http://localhost:8038;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 后端 API
    location /api/ {
        proxy_pass http://localhost:8037;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        # SSE 支持
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding on;
    }
}

Step 5：数据库迁移

docker exec -it aiagent-backend-1 alembic upgrade head

---

四、日常运维

服务管理

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

# 查看日志（实时）
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f backend

# 重启服务
docker-compose restart backend

# 滚动更新
docker-compose pull
docker-compose up -d --build

数据库维护

# 备份数据库（使用腾讯云自动备份功能更佳）
mysqldump -h <host> -u <user> -p aiagent > backup_$(date +%Y%m%d).sql

# 执行数据库迁移
docker exec -it aiagent-backend-1 alembic upgrade head

# 查看迁移历史
docker exec -it aiagent-backend-1 alembic history

监控与告警

指标	说明	建议阈值
CPU 使用率	服务器 CPU	< 80%
内存使用率	服务器内存	< 85%
磁盘使用率	数据盘	< 80%
API 响应时间	接口平均延迟	< 500ms
错误率	5xx 错误占比	< 1%

---

五、常见运维问题

问题	排查步骤
❌ 服务无法启动	docker-compose logs 查看错误日志
🔌 数据库连接失败	检查 .env 中 DATABASE_URL 和网络连通性
⏰ API 响应缓慢	检查慢查询、Redis 缓存命中率、LLM API 延迟
🚫 502 Bad Gateway	Nginx 无法连接后端，检查后端服务是否正常运行
💾 磁盘空间不足	docker system prune -a 清理无用镜像和容器
🔄 证书过期	使用 acme.sh 或 certbot 自动续签 SSL 证书

---

六、备份策略

数据	备份频率	保留期限	方式
MySQL 数据库	每日	30 天	腾讯云自动备份或 mysqldump
用户上传文件	实时同步	—	对象存储（如腾讯云 COS）
配置文件 (.env)	变更时	—	Git 私有仓库 + 加密
Docker 镜像	发布时	最近 5 个版本	镜像仓库

---

七、安全加固

• ✅ 关闭不必要的端口：仅开放 80/443
• ✅ 使用 HTTPS：Let's Encrypt 免费证书
• ✅ 限制数据库访问：仅允许应用服务器 IP 连接
• ✅ 定期更新依赖：docker-compose pull 拉取最新镜像
• ✅ 日志审计：使用 ELK 或腾讯云 CLS 聚合分析
• ✅ WAF 防护：建议使用腾讯云 Web 应用防火墙

---

📎 相关文档：快速开始指南 | 架构设计文档