Skip to main content

云托管部署

云托管（CloudBase Run）是部署 Agent 的推荐方式，支持长连接、自定义运行时、弹性扩缩容，适合复杂 Agent 和高并发场景。

前置条件​

  • 已开通云开发环境
  • 已安装 Python 3.9+
  • 已完成 Agent 开发
  • 已安装 CloudBase CLI（可选，用于 CLI 部署）

代码示例​

项目结构​

my-agent/
├── index.js          # 入口文件
├── package.json      # 依赖配置
└── Dockerfile        # 容器配置

入口文件​

// index.js
const { LangchainAgent, createAgentServer } = require("@cloudbase/agent-adapter-langchain");
const { createReactAgent } = require("@langchain/langgraph/prebuilt");
const { ChatOpenAI } = require("@langchain/openai");
const { tool } = require("@langchain/core/tools");
const { z } = require("zod");

// 定义工具（可选）
const searchTool = tool(
  async ({ query }) => {
    return `搜索结果：关于 "${query}" 的相关信息...`;
  },
  {
    name: "search",
    description: "搜索信息",
    schema: z.object({
      query: z.string().describe("搜索关键词"),
    }),
  }
);

// 创建模型
const model = new ChatOpenAI({
  model: process.env.TCB_AI_MODEL || "hunyuan-turbos-latest",
  apiKey: process.env.TCB_API_KEY,
  configuration: {
    baseURL: `https://${process.env.TCB_ENV_ID}.api.tcloudbasegateway.com/v1/ai/hunyuan/v1`,
  },
});

// 创建 ReAct Agent
const reactAgent = createReactAgent({
  llm: model,
  tools: [searchTool],
});

// 包装为云开发 Agent
const agent = new LangchainAgent({
  name: "SearchAgent",
  description: "智能搜索助手",
  agent: reactAgent,
});

// 导出服务
module.exports = createAgentServer(agent);

依赖配置​

{
  "name": "my-agent",
  "main": "index.js",
  "dependencies": {
    "@cloudbase/agent-adapter-langchain": "latest",
    "@cloudbase/agent-server": "latest",
    "@langchain/langgraph": "latest",
    "@langchain/openai": "latest",
    "@langchain/core": "latest",
    "zod": "^3.22.0"
  }
}

Dockerfile​

FROM node:18-slim

WORKDIR /app

# 安装依赖
COPY package*.json ./
RUN npm install --production

# 复制代码
COPY . .

# 设置环境变量
ENV PORT=3000
EXPOSE 3000

# 启动命令
CMD ["node", "index.js"]

部署方式​

方式一：控制台部署​

  1. 进入 云开发控制台
  2. 选择「云托管」→「新建服务」
  3. 选择「本地代码」上传方式
  4. 上传项目代码包（包含 Dockerfile）
  5. 配置服务参数：
    • 服务名称：自定义名称，如 my-agent
    • 访问类型：选择 WEB（公网访问）
    • CPU：根据需求选择，推荐 0.5-2 核
    • 内存：CPU × 2，如 0.5 核对应 1GB
    • 最小实例数：开发环境设为 0，生产环境设为 1
    • 最大实例数：根据并发需求设置，推荐 5-20
  6. 点击「确定」开始部署

方式二：CLI 部署​

使用 CloudBase CLI 可以快速部署云托管服务：

# 安装 CLI（如未安装）
npm install -g @cloudbase/cli

# 登录云开发
tcb login

# 在项目目录下执行部署
tcb cloudrun deploy

CLI 会自动识别项目中的 Dockerfile，打包并部署到云托管。部署过程中会提示输入：

  • 环境 ID
  • 服务名称
  • 访问类型等配置

配置说明​

资源配置​

配置项说明推荐值
CPUCPU 核数0.5-2
内存内存大小CPU × 2
最小实例数最小运行实例0（按需启动）或 1（避免冷启动）
最大实例数最大运行实例5-20
tip

资源约束：内存 = 2 × CPU，例如 0.5 vCPU 对应 1GB 内存。

访问配置​

访问类型说明适用场景
WEB公网访问Web 应用
VPCVPC 内网访问服务间调用
PRIVATE小程序内网直连小程序

环境变量​

在控制台「服务配置」中设置环境变量：

变量名说明
TCB_ENV_ID云开发环境 ID
TCB_API_KEYAPI 密钥
TCB_AI_MODEL大模型名称，如 hunyuan-turbos-latest
tip

云开发内置了腾讯混元和 DeepSeek 大模型，无需额外申请外部 API Key。支持的模型列表请参考 大模型配置指南。

本地调试​

# 构建镜像
docker build -t my-agent .

# 运行容器
docker run -p 3000:3000 \
  -e TCB_ENV_ID=your-env-id \
  -e TCB_API_KEY=your-api-key \
  -e TCB_AI_MODEL=hunyuan-turbos-latest \
  my-agent

监控与运维​

查看日志​

通过云开发控制台查看服务日志：

  1. 进入「云托管」→ 选择对应服务
  2. 点击「日志」查看运行日志

性能监控​

监控指标：

  • 请求量
  • 响应时间
  • 错误率
  • CPU/内存使用率

弹性扩缩容​

云托管支持自动扩缩容：

  • 根据请求量自动扩容
  • 空闲时自动缩容到 0
  • 可配置最小/最大实例数

最佳实践​

  1. 资源配置

    • 根据 Agent 复杂度配置 CPU/内存
    • 生产环境设置最小实例数 >= 1 避免冷启动

  2. 访问控制

    • 小程序优先使用 PRIVATE 内网直连
    • Web 应用使用 WEB + SDK 鉴权

  3. 环境隔离

    • 开发/测试/生产使用不同环境
    • 敏感信息通过环境变量配置

  4. 镜像优化

    • 使用精简基础镜像
    • 分层构建减少镜像大小
    • 优化依赖减少冷启动时间

相关文档​