高级部署指南

本文档整合了生产环境部署、CI/CD 自动化部署和多环境管理的最佳实践，帮助您将 AgentRun 智能体从开发环境顺利推进到生产环境。

内容说明

注意：此文档整合了以下官方文档的内容： - 本地开发与发布指南 - CI/CD 自动化发布指南
- 多环境管理最佳实践

实际内容需要从官方文档获取并填充。

1. 生产环境部署最佳实践

1.1 安全配置建议

• 访问凭证管理：使用 RAM 角色而非直接使用 AccessKey
• 网络隔离：合理配置 VPC 和安全组，限制不必要的网络访问
• 权限最小化：为智能体分配最小必要权限

1.2 性能优化策略

• 资源配置：根据实际负载调整 CPU、内存和并发数
• CPU 默认值：1.0 核（范围：0.05-16）
• 内存默认值：2048 MB（范围：128-32768）
• 磁盘大小默认值：512 MB（非 10240）
• 并发控制：配置 instanceConcurrency 参数（在底层 API 中映射为 sessionConcurrencyLimitPerInstance），默认值为 10（范围：1-200）
• 健康检查：配置合适的健康检查参数确保服务稳定性
• 日志管理：启用自动日志配置，便于问题排查

1.3 网络配置最佳实践

• 公网访问控制：
• 当未配置 VPC 时：internetAccess 默认为 true（公网访问），设置为 false 则仅私网访问
• 当配置 VPC 时：internetAccess 默认为 true（混合网络：VPC + 公网），设置为 false 则仅 VPC 内网访问
• VPC 配置：生产环境建议配置 VPC 以增强安全性

1.4 监控和告警设置

• 实时监控：配置关键指标的监控告警
• 日志分析：设置日志查询和分析规则
• 故障自愈：配置自动恢复机制

---

2. CI/CD 自动化部署

2.1 GitHub Actions 配置

name: Deploy AgentRun to Production
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install Serverless Devs
        run: npm install -g @serverless-devs/s
      - name: Deploy AgentRun
        env:
          ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}
          ACCESS_KEY_SECRET: ${{ secrets.ACCESS_KEY_SECRET }}
        run: |
          s config add --access default \
            --AccountID ${{ secrets.ACCOUNT_ID }} \
            --AccessKeyID $ACCESS_KEY_ID \
            --AccessKeySecret $ACCESS_KEY_SECRET
          s deploy --assume-yes

2.2 GitLab CI 配置

stages:
  - deploy

deploy_production:
  stage: deploy
  script:
    - npm install -g @serverless-devs/s
    - s config add --access default --AccountID $ACCOUNT_ID --AccessKeyID $ACCESS_KEY_ID --AccessKeySecret $ACCESS_KEY_SECRET
    - s deploy --assume-yes
  only:
    - main

2.3 自动化测试策略

• 部署前测试：在 CI 流水线中加入单元测试和集成测试
• 部署后验证：部署完成后自动验证服务可用性
• 回滚机制：配置自动回滚策略应对部署失败

---

3. 多环境管理策略

3.1 环境变量管理

使用 Serverless Devs 的变量功能管理不同环境的配置：

# s.yaml
edition: 3.0.0
name: agentrun-app
access: default

vars:
  # 环境变量
  region: ${env.REGION, 'cn-hangzhou'}
  environment: ${env.ENVIRONMENT, 'development'}

resources:
  my-agent:
    component: agentrun
    props:
      region: ${vars.region}
      agent:
        name: ${vars.environment}-my-agent
        description: "${vars.environment} environment agent"

        code:
          src: ./code
          language: python3.12
          command:
            - python3
            - main.py

        # 环境特定配置
        cpu: ${vars.environment == 'production' ? 2.0 : 1.0}
        memory: ${vars.environment == 'production' ? 4096 : 2048}
        instanceConcurrency: ${vars.environment == 'production' ? 50 : 10}

        environmentVariables:
          ENVIRONMENT: ${vars.environment}
          LOG_LEVEL: ${vars.environment == 'production' ? 'info' : 'debug'}

        # 网络配置（生产环境建议配置 VPC）
        vpcConfig: ${vars.environment == 'production' ? {
          vpcId: 'vpc-xxxxxxxxx',
          vSwitchIds: ['vsw-xxxxxxxxx'],
          securityGroupId: 'sg-xxxxxxxxx'
        } : undefined}
        internetAccess: ${vars.environment == 'production' ? true : true}

3.2 多环境部署命令

# 开发环境
ENVIRONMENT=development REGION=cn-hangzhou s deploy

# 测试环境  
ENVIRONMENT=staging REGION=cn-hangzhou s deploy

# 生产环境
ENVIRONMENT=production REGION=cn-hangzhou s deploy

3.3 环境隔离最佳实践

• 命名规范：使用环境前缀区分不同环境的资源
• 配置继承：基础配置共享，环境特定配置覆盖
• 权限分离：不同环境使用不同的访问凭证和权限
• 资源配置差异化：生产环境使用更高的资源配置（CPU、内存、并发数）

---

4. 完整部署流程示例

4.1 项目结构

my-agent-project/
├── code/                    # 智能体代码
├── config/
│   ├── dev.yaml            # 开发环境配置
│   ├── staging.yaml        # 测试环境配置  
│   └── prod.yaml           # 生产环境配置
├── .github/
│   └── workflows/
│       └── deploy.yml      # CI/CD 配置
└── s.yaml                  # 主配置文件

4.2 配置文件模板

config/prod.yaml

region: cn-hangzhou
agent:
  name: prod-my-agent
  cpu: 2.0
  memory: 4096
  instanceConcurrency: 50
  internetAccess: true
  logConfig: auto
  endpoints:
    - name: production
      description: "Production endpoint"
  vpcConfig:
    vpcId: vpc-xxxxxxxxx
    vSwitchIds:
      - vsw-xxxxxxxxx
    securityGroupId: sg-xxxxxxxxx

4.3 部署脚本

#!/bin/bash
# deploy.sh
ENV=$1
CONFIG_FILE="config/${ENV}.yaml"

if [ ! -f "$CONFIG_FILE" ]; then
  echo "Configuration file not found: $CONFIG_FILE"
  exit 1
fi

echo "Deploying to $ENV environment..."
s deploy --use-local -y --config "$CONFIG_FILE"
echo "Deployment completed!"

---

5. 关键配置参数说明

5.1 资源配置参数

参数	类型	默认值	说明	范围
cpu	Number	1.0	CPU 核数	0.05-16
memory	Number	2048	内存大小（MB）	128-32768
diskSize	Number	512	磁盘大小（MB）	-
port	Number	8000	监听端口	1-65535
instanceConcurrency	Number	10	实例并发数（映射到 sessionConcurrencyLimitPerInstance）	1-200

5.2 网络配置参数

参数	类型	默认值	说明
internetAccess	Boolean	true	是否允许公网访问
vpcConfig	Object	-	VPC 配置（包含 vpcId, vSwitchIds, securityGroupId）

网络模式说明： - 无 VPC + internetAccess: true → 公网模式 - 无 VPC + internetAccess: false → 私网模式
- 有 VPC + internetAccess: true → 混合模式（VPC + 公网） - 有 VPC + internetAccess: false → VPC 私网模式

5.3 其他重要参数

• 代码与容器互斥：code 和 customContainerConfig 为条件必填，二者选其一
• 角色格式支持：role 字段支持简化角色名称和完整 ARN 两种格式
• 端点灰度权重：端点配置中的 weight 字段用于灰度流量权重，范围为 0.0-1.0