方案简介

本配方面向生产/集群场景：使用官方发布的 Helm Chart（OCI 制品 coze-loop 1.0.0-helm）在 Kubernetes 集群中部署 Coze Loop 开源版，通过 Nginx Ingress 将服务暴露到外部网络，并经 model_config.yaml 接入 Volcengine Ark 或 OpenAI 等模型。本地试用可用 Minikube 快速搭建 K8s 集群。适合已有容器平台运维能力的团队，将 AI Agent 的 prompt 调试、评估与可观测平台纳入统一的集群管理。

亮点与能力

• Helm 一键部署 Coze Loop 全套服务到 K8s 集群
• 通过 Ingress 将服务暴露到外部网络，域名与 URL 按集群分配
• 支持修改 values.yaml 覆盖默认设置，改后重跑 make helm-up 生效
• 支持接入 OpenAI、Volcengine Ark 等模型
• 提供 prompt 调试、评估实验管理、SDK trace 上报与观测等全生命周期能力

组成与分工

• Coze Loop：核心应用，AI Agent 全生命周期管理平台
• Helm：包管理工具，拉取并安装 coze-loop Chart（OCI 制品）
• Kubernetes：容器编排集群，承载 Coze Loop 各服务 Pod
• Minikube：本地快速搭建 K8s 集群用于试用
• Nginx Ingress / Nginx：集群流量入口，将服务暴露到外部网络；nginx Pod 正常运行是部署成功的判定之一
• Volcengine Ark / OpenAI：外部模型服务，经 model_config.yaml 接入

前置要求

• 已准备好的 Kubernetes 集群，并已启用 Nginx Ingress 插件
• 已安装 Kubectl 与 Helm 工具
• 本地试用可用 Minikube 搭建集群
• 有效的模型 API Key（如 Volcengine Ark API Key）

实施步骤

1. 获取 Helm Chart 包

Bash
helm pull oci://docker.io/cozedev/coze-loop --version 1.0.0-helm
tar -zxvf coze-loop-1.0.0-helm.tgz && cd coze-loop && rm -f ../coze-loop-1.0.0-helm.tgz

2. 配置模型

进入 coze-loop 目录，编辑 release/deployment/helm-chart/umbrella/conf/model_config.yaml，配置 api_key（Volcengine Ark API Key）与 model（火山方舟模型接入点的 Endpoint ID）字段。

3. 配置 Ingress 规则

根据实际集群情况，手动修改项目目录中 templates/ingress.yaml 的 ingressClassName 等参数，并配置 class、instance、host、IP 分配等元素。

4. 部署并启动服务

Bash

Run in the coze-loop/ directory

make helm-up

After the service deployment is complete, check the status of the cluster pods

make helm-pod

Check the service startup logs. If both the app and nginx are running normally, the deployment is successful

make helm-logf-app
make helm-logf-nginx

5. 访问与定制

通过浏览器访问服务，访问域名与 URL 取决于集群分配的域名与 URL。参考 examples/ 目录中的示例，修改 values.yaml 覆盖默认设置，改完后重跑 make helm-up 使更改生效。

使用与配置要点

• 定制配置：修改 values.yaml 覆盖默认设置后，重新执行 make helm-up 生效
• 状态检查：make helm-pod 查看集群 Pod 状态
• 日志排查：make helm-logf-app 与 make helm-logf-nginx 分别查看 app 与 nginx 日志，两者均正常运行即部署成功
• 验证成功：通过集群分配的域名/URL 用浏览器访问平台

注意事项与常见问题

• Ingress 配置需根据实际集群情况手动修改 ingressClassName、class、instance、host、IP 分配等参数，不能直接套用默认值
• 访问域名与 URL 依赖集群分配，无法预先固定
• 本地快速试用建议使用 Minikube 搭建集群，详见 Wiki Quick Start

优缺点

• ✓ 适合生产级集群部署
• ✓ 可通过 values.yaml 覆盖默认
• ✕ 需自备 K8s 集群与 Ingress
• ✕ Ingress 需手动按集群修改

出处

本方案挖掘自开源项目 coze-dev/coze-loop，方案内容与实施命令均来自其 README 原文。