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：克隆代码

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

### Step 2：配置环境变量

```bash
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 部署

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

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

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

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

```nginx
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：数据库迁移

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

---

## 四、日常运维

### 服务管理

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

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

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

# 重启服务
docker-compose restart backend

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

### 数据库维护

```bash
# 备份数据库（使用腾讯云自动备份功能更佳）
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 应用防火墙

---

> 📎 **相关文档**：[快速开始指南](./quickstart.md) | [架构设计文档](./architecture.md)