部署指南

技术文档站（techsite）部署约定

技术文档站与介绍站点采用同样的部署方式：本地构建 + 打包上传 + 服务器解压 + nginx 容器启动，区别仅在域名。

当前域名：docs.vaiteam.tomatoinfo.cn
未来域名：ai-orchestration.cn
部署目录：techsite/deploy
构建脚本：bash deploy/build.sh
服务器脚本：bash deploy/deploy.sh

域名切换时，优先调整：

APISIX 路由 host
techsite/.vitepress/config.ts 中 TECH_DOMAIN（可通过环境变量覆盖）
techsite/deploy/conf/docs.conf 的 server_name

部署架构

VAI TEAM 采用微服务架构，由以下组件组成：

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│    Web      │    │ Dispatcher  │    │   Agent     │
│  (Nginx)    │───▶│  (FastAPI)  │───▶│ (Python)    │
│  Port 8080  │    │  Port 8000  │    │ Multi-Inst  │
└─────────────┘    └─────────────┘    └─────────────┘
                          │
                          ▼
                   ┌─────────────┐
                   │  Database   │
                   │ (SQLite/PG) │
                   └─────────────┘

服务	说明	默认端口	资源需求
Web	前端控制台（Nginx + Vue SPA）	8080	100MB RAM
Dispatcher	调度中心（FastAPI + 业务逻辑）	8000	512MB RAM
Agent	AI 工作节点（可水平扩展）	—	256MB RAM/实例
Database	数据存储（SQLite 或 PostgreSQL）	5432	取决于项目数量

开发环境部署

适用于本地开发、功能测试：

bash

# 使用开发配置
docker compose -f docker-compose.dev.yml up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

开发环境特点：

代码热重载
详细调试日志
SQLite 数据库
无 HTTPS

生产环境部署

基础部署

bash

# 使用生产配置
docker compose -f docker-compose.prod.yml up -d

生产环境配置清单

1. HTTPS 配置

方案一：Nginx 反向代理

nginx

server {
    listen 443 ssl http2;
    server_name ai-orchestration.cn;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost: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;
    }
    
    location /api/ {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

方案二：云负载均衡器

使用阿里云 SLB、腾讯云 CLB 等托管服务终止 HTTPS。

2. 数据库配置

切换到 PostgreSQL：

bash

# .env 配置
DATABASE_URL=postgresql://vaiteam:password@localhost:5432/vaiteam_db

# 启动 PostgreSQL
docker run -d \
  --name vaiteam-postgres \
  -e POSTGRES_DB=vaiteam_db \
  -e POSTGRES_USER=vaiteam \
  -e POSTGRES_PASSWORD=secure_password \
  -v postgres_data:/var/lib/postgresql/data \
  -p 5432:5432 \
  postgres:15

3. 持久化存储

确保以下目录持久化：

yaml

# docker-compose.prod.yml
volumes:
  - ./data:/app/data              # 数据库文件（SQLite 模式）
  - ./logs:/app/logs              # 应用日志
  - ./agent_workspaces:/workspaces # Agent 工作区

4. 监控与日志

日志配置：

bash

# 日志轮转
echo "*/5 * * * * docker system prune -f" | crontab -

# 日志收集（可选）
docker run -d \
  --name log-collector \
  -v /var/lib/docker/containers:/var/lib/docker/containers:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  fluent/fluent-bit

监控配置：

bash

# 资源监控
docker stats

# 健康检查
curl -f http://localhost:8000/health || exit 1

环境变量配置

核心配置

变量	说明	示例值	必填
`ADMIN_USER`	管理员用户名	`admin`	✅
`ADMIN_PASS`	管理员密码	`SecurePass123!`	✅
`SECRET_KEY`	JWT 签名密钥	`random-32-char-string`	✅
`DATABASE_URL`	数据库连接	`sqlite:///data/app.db`	✅

模型配置

变量	说明	示例值
`DEEPSEEK_API_KEY`	DeepSeek API 密钥	`sk-xxx`
`DEEPSEEK_BASE_URL`	DeepSeek API 地址	`https://api.deepseek.com`
`OPENAI_API_KEY`	OpenAI API 密钥	`sk-xxx`
`ANTHROPIC_API_KEY`	Anthropic API 密钥	`sk-ant-xxx`

高级配置

变量	说明	默认值
`MAX_AGENTS`	最大 Agent 数量	`5`
`TASK_TIMEOUT`	任务超时时间（秒）	`1800`
`LOG_LEVEL`	日志级别	`INFO`
`CORS_ORIGINS`	跨域白名单	`*`

完整 .env 示例

bash

# 基础配置
ADMIN_USER=admin
ADMIN_PASS=YourSecurePassword123!
SECRET_KEY=your-random-32-character-secret-key

# 数据库
DATABASE_URL=postgresql://vaiteam:password@postgres:5432/vaiteam_db

# 模型配置
DEEPSEEK_API_KEY=sk-your-deepseek-api-key
DEEPSEEK_BASE_URL=https://api.deepseek.com

# 可选：其他模型
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

# 高级配置
MAX_AGENTS=10
TASK_TIMEOUT=3600
LOG_LEVEL=INFO
CORS_ORIGINS=https://ai-orchestration.cn,https://demo.ai-orchestration.cn

扩展部署

多 Agent 扩展

bash

# 启动额外的 Agent 实例
docker run -d \
  --name vaiteam-agent-2 \
  --env-file .env \
  -v agent_workspace_2:/workspace \
  vaiteam/agent:latest

# 或通过 docker-compose 扩展
docker compose up -d --scale agent=3

集群部署

对于大规模使用，可以考虑：

Dispatcher 高可用 — 多实例 + 负载均衡
Agent 池 — 独立的 Agent 集群
数据库集群 — PostgreSQL 主从或分片
Redis 缓存 — 加速频繁查询

备份与恢复

数据备份

bash

# SQLite 备份
cp data/app.db data/app.db.backup.$(date +%Y%m%d)

# PostgreSQL 备份
pg_dump -h localhost -U vaiteam vaiteam_db > backup.sql

# Agent 工作区备份
tar -czf agent_workspaces_backup.tar.gz agent_workspaces/

项目 Checkpoint

使用内置的 Checkpoint 功能：

bash

# 创建项目快照
curl -X POST http://localhost:8000/api/projects/{project_id}/checkpoint \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "v1.0-release", "description": "生产发布版本"}'

# 恢复到指定快照
curl -X POST http://localhost:8000/api/projects/{project_id}/restore \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"checkpoint_id": "checkpoint_uuid"}'

性能优化

资源配置建议

项目规模	CPU	内存	存储	Agent 数量
小型（1-5 项目）	2 核	4GB	20GB	2-3
中型（5-20 项目）	4 核	8GB	100GB	5-8
大型（20+ 项目）	8 核	16GB	500GB	10+

性能调优

bash

# 数据库连接池
DATABASE_POOL_SIZE=20
DATABASE_MAX_OVERFLOW=10

# Agent 并发控制
MAX_CONCURRENT_TASKS_PER_AGENT=2

# 模型调用优化
MODEL_REQUEST_TIMEOUT=60
MODEL_RETRY_ATTEMPTS=3

故障排查

常见问题

服务启动失败：

bash

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

# 检查 Docker 状态
docker compose ps
docker compose logs dispatcher

Agent 离线：

bash

# 检查 Agent 日志
docker compose logs agent

# 重启 Agent
docker compose restart agent

数据库连接失败：

bash

# 测试数据库连接
docker exec -it vaiteam-postgres psql -U vaiteam -d vaiteam_db -c "SELECT 1;"

健康检查端点

端点	说明
`GET /health`	服务整体健康状态
`GET /api/agents/status`	Agent 状态检查
`GET /api/models/test`	模型连接测试

安全配置

网络安全

bash

# 防火墙配置（仅开放必要端口）
ufw allow 22    # SSH
ufw allow 80    # HTTP
ufw allow 443   # HTTPS
ufw deny 8000   # 内部 API 端口
ufw deny 8080   # 内部 Web 端口

应用安全

定期更新管理员密码
使用强随机 SECRET_KEY
限制 CORS_ORIGINS 到具体域名
配置 API 访问频率限制

更多安全配置将在后续版本中补充。

部署指南 ​

技术文档站（techsite）部署约定 ​

部署架构 ​

开发环境部署 ​

生产环境部署 ​

基础部署 ​

推荐的生产环境架构 ​

生产环境配置清单 ​

1. HTTPS 配置 ​

2. 数据库配置 ​

3. 持久化存储 ​

4. 监控与日志 ​

环境变量配置 ​

核心配置 ​

模型配置 ​

高级配置 ​

完整 .env 示例 ​

扩展部署 ​

多 Agent 扩展 ​

集群部署 ​

备份与恢复 ​

数据备份 ​

项目 Checkpoint ​

性能优化 ​

资源配置建议 ​

性能调优 ​

故障排查 ​

常见问题 ​

健康检查端点 ​

安全配置 ​

网络安全 ​

应用安全 ​

部署指南

技术文档站（techsite）部署约定

部署架构

开发环境部署

生产环境部署

基础部署

推荐的生产环境架构

生产环境配置清单

1. HTTPS 配置

2. 数据库配置

3. 持久化存储

4. 监控与日志

环境变量配置

核心配置

模型配置

高级配置

完整 .env 示例

扩展部署

多 Agent 扩展

集群部署

备份与恢复

数据备份

项目 Checkpoint

性能优化

资源配置建议

性能调优

故障排查

常见问题

健康检查端点

安全配置

网络安全

应用安全