从Docker到Kubernetes：AgentField生产环境部署完全指南（含Helm与高可用配置）

从Docker到KubernetesAgentField生产环境部署完全指南含Helm与高可用配置【免费下载链接】agentfieldBuild, run and scale AI agents like API and microservices项目地址: https://gitcode.com/gh_mirrors/ag/agentfieldAgentField 是一个将 AI Agent 当作 API 和微服务来构建、运行与扩展的开源平台。本指南带你走通 AgentField 生产环境部署的完整路径先用 Docker Compose 几分钟拉起本地评估环境再用 Helm Chart 把控制平面部署到 Kubernetes 集群最后覆盖存储选型、API 认证、优雅停机与高可用调优等生产级配置帮你避开常见部署坑。一、部署前先看懂 AgentField 的组件构成AgentField 由两部分组成无状态的Go 控制平面Control Plane和有状态的Agent 节点群。控制平面提供 REST/gRPC API、工作流引擎与 Web UI每个 Agent 以独立微服务运行通过 SDKPython、Go、TypeScript注册回调地址并接受调度。理解这一点后生产部署的核心思路就清晰了控制平面可以水平扩展状态必须外置PostgreSQL 或持久卷每个 Agent 节点需要通过集群内 Service DNS 名称注册不能用localhost。架构细节可参考 docs/ARCHITECTURE.md。二、第一步用 Docker Compose 快速评估最快上手方式是仓库自带的 Docker Compose 配置一条命令拉起控制平面 PostgreSQLpgvector 可选的演示 Agentcd deployments/docker docker compose --profile python-demo up --build启动后访问http://localhost:8080/ui/即可看到控制台。完整说明见 deployments/docker/README.md编排文件为 deployments/docker/docker-compose.yml。⚠️两个新手容易踩的坑主机管理 401 问题从宿主机访问容器时控制平面会把它视为另一台机器安装软件包、读写凭据类接口会返回 401。设置 API Key 即可解决AGENTFIELD_API_KEY$(openssl rand -hex 24) docker compose up --build回调地址控制平面必须能访问 Agent 注册的 URL。同一 Compose 网络内用服务名如http://demo-python-agent:8001Agent 在宿主机上时需用host.docker.internal。三、第二步用 Helm 部署到 Kubernetes生产推荐仓库在 deployments/helm/agentfield 提供了官方 Helm Chart内置控制平面 Deployment、Service、PVC 以及可选的 PostgreSQL 与演示 Agent。生产级推荐安装命令helm upgrade --install agentfield deployments/helm/agentfield \ -n agentfield --create-namespace \ --set postgres.enabledtrue \ --set controlPlane.storage.modepostgres \ --set demoPythonAgent.enabledtrue随后端口转发验证kubectl -n agentfield port-forward svc/agentfield-control-plane 8080:8080 curl -s http://localhost:8080/api/v1/health核心配置项完整清单见 deployments/helm/agentfield/values.yaml配置项默认值生产建议controlPlane.storage.modelocalSQLite/BoltDBpostgres实现控制平面无状态化postgres.enabledfalsetrue自动注入连接串apiAuth.enabledfalsetrue配合apiKey保护管理接口controlPlane.persistence.size1Gi按执行历史量调大controlPlane.ingress.enabledfalse接入自有 Ingress 与 TLS✅安全提示开启apiAuth后API 调用需携带X-API-Key头而 UI 仍然可访问——这是外部管理控制平面的推荐做法。如果不想用 Helm仓库也提供了纯 Kustomize 清单deployments/kubernetes/README.md包含python-demo、local-demo、postgres-demo三套 overlay适合希望所见即所得的团队。四、高可用与优雅停机生产环境的关键调优这是 AgentField 部署中最容易被忽视、却直接决定滚动更新成功率的部分官方文档 docs/deploying-on-kubernetes.md 有详细说明4.1 控制平面停机时序Chart 已默认配置shutdownMinDelay: 5s—— 收到 SIGTERM 后先保持服务让 kube-proxy 有时间把 Pod 从 Service endpoints 摘除terminationGracePeriodSeconds: 60—— 覆盖 5s 延迟 30s 排空 约 20s 收尾缓冲就绪探针periodSeconds: 2、failureThreshold: 1—— 排空 Pod 在 2 秒内即被标记 Unready。如果你的集群在 Kubernetes 1.30可以再加一个原生的preStopsleep 钩子5 秒进一步保证摘流先于监听关闭。4.2 Agent 节点的排空保护所有 Agent 镜像收到 SIGTERM 后会在AGENTFIELD_SHUTDOWN_TIMEOUT默认 30s内排空在途任务因此 Agent Pod 的terminationGracePeriodSeconds至少要比该值大 15 秒Chart 中的 45 秒正是 30 15Agent Deployment 保持replicas: 1同一节点 ID 的多副本注册会互相触发替换-收割逻辑官方推荐单副本拓扑对长耗时推理任务如 10 分钟需同步调大AGENTFIELD_SHUTDOWN_TIMEOUT与控制平面的AGENTFIELD_AGENT_DRAIN_GRACE并注意后者是全局配置调大后故障节点的在途任务也会滞留更久。4.3 就绪探针的陷阱Chart 默认探针路径是/api/v1/health而非/api/v1/health/ready这是为了防止latest标签 节点缓存旧镜像时新路径 404 导致零 endpoints。只有当所有 Pod 都升级到 v0.1.137 之后的镜像才应将controlPlane.readinessProbe.path切换为/api/v1/health/ready它在排空窗口内返回 503摘流更精准liveness 探针始终保留/api/v1/health。4.4 数据保留控制平面默认每 5 分钟清理一次执行记录AGENTFIELD_EXECUTION_RETENTION_PERIOD0s表示终态记录永久保留。需要控制磁盘增长时按业务要求设置非零保留期即可参考 docs/ENVIRONMENT_VARIABLES.md。五、部署后验证部署完成后建议做三步检查# 1. 健康检查 curl -s http://localhost:8080/api/v1/health # 2. 执行一次演示 Agent curl -X POST http://localhost:8080/api/v1/execute/demo-python-agent.hello \ -H Content-Type: application/json -d {input:{name:World}} # 3. 查看可验证凭证链VC curl -s http://localhost:8080/api/v1/did/workflow/$run_id/vc-chain | head -c 1200打开 UI 后你会看到执行记录、Agent 拓扑与监控大盘确认各节点在线且执行成功即完成部署六、小结阶段工具适用场景本地评估deployments/docker Docker Compose几分钟内体验 UI 执行 API生产部署deployments/helm/agentfield Helm Chartvalues.yaml驱动的自定义安装极简集群deployments/kubernetes Kustomize透明清单、最少工具链记住三个生产要点状态外置到 PostgreSQL、管理接口开启 API Key 认证、停机时序参数保持官方默认值。按此路径你可以把 AgentField 从一台笔记本上的演示平滑扩展为生产环境中的 Agent 微服务集群。【免费下载链接】agentfieldBuild, run and scale AI agents like API and microservices项目地址: https://gitcode.com/gh_mirrors/ag/agentfield创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考