agent_management/agent_templates/agents/code_ai_agent/docs/DEPLOYMENT.md

代码助手 Agent 部署指南

📋 目录

• 部署方式
• 环境配置
• Docker 部署
• 云平台部署
• 监控和日志
• 故障排查

---

部署方式

代码助手 Agent 支持多种部署方式：

1. 本地部署 - 适合开发和测试
2. Docker 部署 - 适合单机部署
3. Docker Compose 部署 - 适合本地或小规模部署
4. 云平台部署 - 适合生产环境

---

环境配置

必需环境变量

变量名	说明	示例
OPENAI_API_KEY	LiteLLM Gateway API Key	sk-rxegkFOciNmQLhOHr3qP3A
OPENAI_BASE_URL	LiteLLM Gateway Base URL	https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io/v1

可选环境变量

变量名	说明	默认值
LITELLM_MODEL	模型名称	openai:taiji/gpt-4o-mini
API_HOST	API 服务监听地址	0.0.0.0
API_PORT	API 服务端口	8000

---

Docker 部署

1. 构建镜像

docker build -t code-assistant-agent:latest .

2. 运行容器

docker run -d \
  --name code-assistant-agent \
  -p 8000:8000 \
  -e OPENAI_API_KEY=your_api_key \
  -e OPENAI_BASE_URL=your_gateway_url \
  -v $(pwd)/projects:/tmp/projects \
  code-assistant-agent:latest

3. 验证部署

# 检查容器状态
docker ps | grep code-assistant-agent

# 检查健康状态
curl http://localhost:8000/health

# 查看日志
docker logs -f code-assistant-agent

---

Docker Compose 部署

1. 配置环境变量

创建 .env 文件：

OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=your_gateway_url
LITELLM_MODEL=openai:taiji/gpt-4o-mini
API_HOST=0.0.0.0
API_PORT=8000

2. 启动服务

docker-compose up -d

3. 查看状态

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

---

云平台部署

Azure Container Apps

1. 准备镜像

# 登录 Azure Container Registry
az acr login --name your-registry

# 构建并推送镜像
docker build -t your-registry.azurecr.io/code-assistant-agent:latest .
docker push your-registry.azurecr.io/code-assistant-agent:latest

2. 创建 Container App

az containerapp create \
  --name code-assistant-agent \
  --resource-group your-resource-group \
  --image your-registry.azurecr.io/code-assistant-agent:latest \
  --target-port 8000 \
  --ingress external \
  --env-vars \
    OPENAI_API_KEY=your_key \
    OPENAI_BASE_URL=your_gateway_url \
    LITELLM_MODEL=openai:taiji/gpt-4o-mini

3. 配置自动扩缩容

az containerapp update \
  --name code-assistant-agent \
  --resource-group your-resource-group \
  --min-replicas 1 \
  --max-replicas 10 \
  --cpu 1.0 \
  --memory 2.0Gi

AWS ECS / EKS

1. 构建并推送镜像到 ECR

# 登录 ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin your-account.dkr.ecr.us-east-1.amazonaws.com

# 构建并推送
docker build -t code-assistant-agent:latest .
docker tag code-assistant-agent:latest your-account.dkr.ecr.us-east-1.amazonaws.com/code-assistant-agent:latest
docker push your-account.dkr.ecr.us-east-1.amazonaws.com/code-assistant-agent:latest

2. 创建 ECS 任务定义

创建 task-definition.json:

{
  "family": "code-assistant-agent",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "1024",
  "memory": "2048",
  "containerDefinitions": [
    {
      "name": "code-assistant-agent",
      "image": "your-account.dkr.ecr.us-east-1.amazonaws.com/code-assistant-agent:latest",
      "portMappings": [
        {
          "containerPort": 8000,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {
          "name": "OPENAI_API_KEY",
          "value": "your_api_key"
        },
        {
          "name": "OPENAI_BASE_URL",
          "value": "your_gateway_url"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/code-assistant-agent",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

3. 注册任务定义并创建服务

# 注册任务定义
aws ecs register-task-definition --cli-input-json file://task-definition.json

# 创建服务
aws ecs create-service \
  --cluster your-cluster \
  --service-name code-assistant-agent \
  --task-definition code-assistant-agent \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxx],securityGroups=[sg-xxx],assignPublicIp=ENABLED}"

Google Cloud Run

1. 构建并推送镜像

# 构建镜像
gcloud builds submit --tag gcr.io/your-project/code-assistant-agent

# 或者使用 Docker
docker build -t gcr.io/your-project/code-assistant-agent .
docker push gcr.io/your-project/code-assistant-agent

2. 部署服务

gcloud run deploy code-assistant-agent \
  --image gcr.io/your-project/code-assistant-agent \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars \
    OPENAI_API_KEY=your_key,OPENAI_BASE_URL=your_url \
  --memory 2Gi \
  --cpu 1 \
  --min-instances 1 \
  --max-instances 10

---

监控和日志

健康检查

服务提供健康检查端点：

curl http://your-domain:8000/health

响应：

{
  "status": "healthy",
  "service": "代码助手 Agent API"
}

日志收集

Docker 日志

# 查看实时日志
docker logs -f code-assistant-agent

# 查看最近 100 行
docker logs --tail 100 code-assistant-agent

应用日志

服务使用标准输出，可以通过容器日志系统收集。

监控指标

建议监控以下指标：

• 请求速率: 每秒请求数
• 响应时间: API 响应时间
• 错误率: 5xx 错误比例
• 资源使用: CPU、内存使用率
• AI 调用: LiteLLM Gateway 调用成功率

---

故障排查

常见问题

1. 服务无法启动

问题: 容器启动失败

排查步骤:

# 查看容器日志
docker logs code-assistant-agent

# 检查环境变量
docker exec code-assistant-agent env | grep OPENAI

# 检查端口占用
netstat -tulpn | grep 8000

2. API 调用失败

问题: 返回 500 错误

排查步骤:

• 检查 LiteLLM Gateway 连接
• 验证 API Key 是否正确
• 查看服务日志

3. AI 调用超时

问题: 请求超时

解决方案:

• 增加超时时间配置
• 检查网络连接
• 验证 Gateway 服务状态

4. 文件操作失败

问题: 无法创建文件

排查步骤:

# 检查目录权限
ls -la /tmp/projects

# 检查磁盘空间
df -h

# 检查容器挂载
docker inspect code-assistant-agent | grep Mounts

调试模式

启用详细日志：

docker run -e LOG_LEVEL=debug ...

---

安全建议

1. API Key 管理: 使用密钥管理服务（如 Azure Key Vault、AWS Secrets Manager）
2. HTTPS: 生产环境必须使用 HTTPS
3. 访问控制: 配置 API 网关或反向代理进行访问控制
4. 资源限制: 设置适当的 CPU 和内存限制
5. 网络隔离: 使用私有网络和防火墙规则

---

性能优化

1. 连接池: 配置 HTTP 客户端连接池
2. 缓存: 对频繁请求的结果进行缓存
3. 异步处理: 使用异步任务队列处理长时间任务
4. 负载均衡: 部署多个实例并使用负载均衡器

---

文档版本: 1.0.0
最后更新: 2025-01-08