企业官网建设流程全解析

1. 从“ax”这个标题说起：一个被低估的调度入口

第一次看到“ax”这个标题，很多人会以为是某个命令行工具的缩写，或者某个内部项目的代号。但把热搜词摊开来看——agentic、orchestrator、Kubernetes、CLI、ax调度、agentic rag、codex cli、claude cli、karmada——这些词拼在一起，指向的其实是一个非常具体的场景：在 Kubernetes 之上，用一套统一的 CLI 入口，去调度和管理多个 agentic 工作负载。

“ax”在这里我更愿意把它理解成一个调度入口的抽象层，而不是某个单一工具。它要解决的问题很朴素：当你的集群里同时跑着 codex cli、claude cli、各种 agentic rag 服务、以及一堆需要按需拉起的一次性任务时，你怎么用一个命令把它们编排起来？怎么让一个 agent 的输出成为下一个 agent 的输入？怎么在 K8s 原生的调度能力之上，再叠一层面向 agent 的调度语义？

这套东西适合谁？三类人最该看：一是已经在用 Kubernetes 跑 AI 工作负载、但被 YAML 和 kubectl 折腾得够呛的运维和平台工程师；二是想把自己的 agentic 应用从“本地脚本”升级成“集群服务”的开发者；三是正在评估 Karmada 这类多集群调度方案、想搞清楚 agentic cloud 到底怎么落地的人。哪怕你只是刚装完 codex cli、还在纠结unable to locate the codex cli binary这个报错，这篇文章里的排查思路也能直接用上。

我下面要讲的，不是某个官方文档的复述，而是我自己在把 agentic 工作负载往 K8s 上搬的过程中，踩过的坑、试过的方案、以及最后沉淀下来的一套可复现的做法。核心就一句话：用 CLI 做统一入口，用 K8s 做执行底座，用 orchestrator 做 agent 之间的粘合层。

2. 整体设计思路：为什么是 CLI + K8s + Orchestrator 这三件套

2.1 为什么入口选 CLI 而不是 Web UI

先说一个反直觉的结论：面向 agent 的调度，CLI 比 Web UI 更合适。原因不复杂。agentic 工作负载的特点是“短生命周期、高频触发、参数多变”。你今天要跑一个 codex cli 去改一段代码，明天要跑一个 claude cli 去审一段日志，后天要跑一个 agentic rag 去检索一批文档。这些任务的共同点是：它们几乎都是一次性的，而且触发时机往往来自另一个程序的输出，而不是人的点击。

Web UI 适合人主动操作，CLI 适合程序和人混合操作。当你需要在一个 shell 脚本里、在一个 CI 流水线里、在另一个 agent 的输出回调里触发任务时，CLI 是唯一自然的选择。ax run --agent codex --task "refactor auth module"这样一行命令，可以塞进任何地方；而一个 Web 表单不行。

更重要的是，CLI 天然适合做组合。Unix 哲学里最值钱的一句话是“每个程序只做一件事，但要做好，然后用管道把它们连起来”。agentic 调度的本质就是管道：agent A 的输出喂给 agent B，B 的结果再交给 C 去验证。CLI 让这种组合变得廉价。

2.2 为什么底座选 Kubernetes 而不是裸机脚本

有人会问：我就跑几个 agent，用 nohup 和 screen 不就行了？短期可以，长期一定崩。原因有三个。

第一是资源隔离。一个 agentic rag 服务可能吃满内存，一个 codex cli 任务可能瞬间拉起几十个进程。裸机上它们会互相抢资源，一个 OOM 全挂。K8s 的 request/limit 机制能把这些隔离干净。

第二是调度语义。agent 任务有优先级，有的要立刻跑，有的可以排队。K8s 的 PriorityClass、亲和性、污点容忍这些原语，直接就能用，不用自己造轮子。

第三是可观测性。agent 跑失败了，你需要知道是镜像拉取失败、还是 OOM、还是业务逻辑报错。K8s 的 events、logs、describe 三件套，比你自己在脚本里 echo 日志强太多。

但 K8s 原生调度有个短板：它不懂“agent 语义”。它不知道一个 Pod 是一个 agent，不知道 agent 之间有依赖关系，不知道一个 agent 的输出要传给下一个。这就是 orchestrator 要补的位。

2.3 Orchestrator 到底编排什么

很多人把 orchestrator 理解成“任务队列”，这太窄了。在 agentic 场景里，orchestrator 至少要管四件事：

• 依赖编排：agent B 必须等 agent A 成功后才能启动，这是 DAG 调度。
• 数据传递：A 的输出怎么变成 B 的输入，是通过共享卷、还是通过对象存储、还是通过消息队列。
• 失败重试：agent 任务失败后，是重试、还是跳过、还是触发补偿 agent。
• 状态追踪：一个多 agent 流水线跑到哪一步了，哪一步卡住了。

Karmada 这类多集群调度方案在这里的价值就体现出来了：当你的 agent 任务量大到一个集群扛不住，或者需要跨集群做容灾时，orchestrator 可以把任务分发到多个 K8s 集群，而 CLI 入口保持不变。这也是为什么“karmada 正式毕业”会和“agentic cloud”绑在一起被讨论——多集群调度是 agentic cloud 的底座能力之一。

3. 核心细节解析：CLI 入口、Agent 镜像、调度原语

3.1 CLI 入口的设计要点

一个合格的 ax CLI，至少要提供这几类子命令：

ax run # 提交一个 agent 任务 ax status # 查看任务状态 ax logs # 拉取任务日志 ax list # 列出所有 agent 任务 ax cancel # 取消任务 ax pipeline # 提交一个多 agent 流水线

设计上有几个坑要注意。第一，ax run的参数不要设计得太复杂，否则用户记不住。我的做法是：常用参数用 flag，复杂配置用--file指向一个 YAML。比如：

ax run --agent codex --task "fix bug" --image codex-cli:latest ax run --file pipeline.yaml

第二，ax status的输出要机器可读。默认给人看，加--json给程序看。这样 CI 流水线里可以直接ax status --json | jq '.phase'。

第三，CLI 本身不要做业务逻辑，它只做“翻译”：把命令行参数翻译成 K8s API 调用。业务逻辑全部放在 orchestrator 里。这样 CLI 可以随便换语言重写，不影响后端。

3.2 Agent 镜像怎么打

agentic 工作负载的镜像和普通服务镜像不一样。普通服务镜像是一个长期运行的进程，agent 镜像往往是“跑完就退出”。这带来几个特殊要求：

• 镜像要小：agent 任务频繁拉起，镜像大了拉取慢，调度延迟高。用多阶段构建，把编译工具链留在构建阶段。
• 入口要明确：镜像的 ENTRYPOINT 应该是一个明确的 agent 执行器，而不是一个 shell。这样 K8s 能正确判断任务是否结束。
• 退出码要规范：0 表示成功，非 0 表示失败。orchestrator 靠退出码判断是否重试。

一个典型的 codex cli agent 镜像 Dockerfile 大概长这样：

FROM node:20-slim AS builder WORKDIR /app COPY package*.json ./ RUN npm ci --only=production FROM node:20-slim WORKDIR /app COPY --from=builder /app/node_modules ./node_modules COPY . . ENTRYPOINT ["node", "agent-runner.js"]

注意这里没有用CMD而是ENTRYPOINT，因为 agent 任务的参数是通过命令行传的，ENTRYPOINT能保证参数正确拼接。

3.3 调度原语的选择

在 K8s 上跑 agent 任务，用 Job 还是 Pod？我的经验是：一次性 agent 任务用 Job，长期运行的 agent 服务用 Deployment。

Job 的好处是它自带“完成”语义，K8s 会帮你追踪任务是否成功。配合backoffLimit可以控制重试次数，配合ttlSecondsAfterFinished可以自动清理完成的 Job，避免集群里堆一堆 Completed 的 Pod。

但 Job 有个坑：默认情况下 Job 的 Pod 失败后会重建，如果你的 agent 任务不是幂等的，重试会导致重复执行。解决办法是在 agent 内部做幂等，或者把backoffLimit设为 0，让 orchestrator 来决定是否重试。

对于需要 GPU 的 agent 任务，还要考虑 device plugin。K8s 的 device plugin 机制让 GPU 这类特殊资源能被调度器识别。你需要在节点上装好对应的 device plugin，然后在 Pod 的 resources 里声明nvidia.com/gpu: 1。这一步经常出问题，后面排查章节会细讲。

4. 实操过程：从零搭一个 ax 调度环境

4.1 环境准备与依赖安装

先列一下我用的环境：

K8s 集群可以用 kind 或 k3s 在本地起一个，测试够用。生产环境建议至少 3 节点，master 和 worker 分开。

安装 ax CLI 的过程，其实和装 codex cli、claude cli 那类工具很像，核心就三步：下载二进制、放到 PATH、验证版本。

curl -fsSL https://example.com/ax/install.sh | sh sudo mv ax /usr/local/bin/ ax version

如果你在 Windows 上遇到类似node_modules\@opencode\cli\bin\opencode.exe 与你运行的 windows 版本不兼容这种报错，本质是二进制架构不匹配。解决办法是确认下载的是 amd64 还是 arm64 版本，或者直接用 WSL2 跑 Linux 版本，省心得多。

4.2 部署 Orchestrator

orchestrator 我用 Helm 部署，因为它需要一套 CRD（自定义资源定义）来描述 agent 任务和流水线。核心 CRD 有两个：

• AgentTask：描述一个单 agent 任务
• AgentPipeline：描述一个多 agent 流水线

一个 AgentTask 的 YAML 大概长这样：

apiVersion: ax.io/v1 kind: AgentTask metadata: name: refactor-auth spec: agent: codex image: codex-cli:latest command: ["node", "agent-runner.js"] args: ["--task", "refactor auth module"] resources: requests: memory: "512Mi" cpu: "500m" limits: memory: "2Gi" cpu: "2" retryPolicy: maxRetries: 2 backoff: "30s"

提交这个 YAML 后，orchestrator 会把它翻译成一个 K8s Job，然后 Job 再拉起 Pod。这样做的价值是：用户只需要懂 AgentTask 这一层抽象，不需要懂 Job、Pod、ReplicaSet 这些 K8s 原生概念。

4.3 跑通第一个 agent 任务

环境搭好后，跑一个最简单的任务验证链路：

ax run --agent echo --task "hello ax"

这条命令背后发生了什么？我拆开讲：

1. ax CLI 把参数打包成一个 AgentTask 对象，通过 K8s API 提交。
2. orchestrator 的 controller 监听到新的 AgentTask，创建一个 Job。
3. Job controller 创建一个 Pod，调度到某个节点。
4. 节点上的 kubelet 拉起容器，执行 agent-runner。
5. agent-runner 执行任务，输出结果，退出码 0。
6. Job 标记为 Complete，orchestrator 更新 AgentTask 状态为 Succeeded。
7. ax CLI 轮询到状态变化，打印结果。

这一整条链路跑通，说明你的 ax 调度环境基本可用了。如果卡在某一步，排查章节有对应的速查表。

4.4 多 agent 流水线的编排

单任务跑通后，上流水线。一个典型场景是：codex 改代码 → claude 审代码 → 测试 agent 跑测试。

apiVersion: ax.io/v1 kind: AgentPipeline metadata: name: code-review-pipeline spec: steps: - name: refactor agent: codex task: "refactor auth module" - name: review agent: claude task: "review the changes from refactor" dependsOn: [refactor] - name: test agent: tester task: "run unit tests" dependsOn: [review]

orchestrator 会把这条流水线翻译成一个 DAG，按依赖顺序依次拉起 Job。每个步骤的输出通过共享的 PVC（PersistentVolumeClaim）传递，或者通过对象存储传递。我倾向于用对象存储，因为 PVC 跨节点挂载有坑，而且多集群场景下 PVC 根本传不过去。

这里有个经验：步骤之间的数据传递格式要提前约定好。codex 的输出是代码 diff，claude 的输入就得能解析 diff。如果格式对不上，流水线会在第二步卡住。我的做法是在每个 agent 的入口加一层适配器，把上游输出转成自己需要的格式。

5. 常见问题与排查技巧实录

5.1 Agent 任务起不来：从 Pending 到 Running 的排查路径

任务提交后一直 Pending，是最常见的问题。排查顺序如下：

kubectl describe pod是排查第一现场，Events 里 90% 的问题都能看出来。我遇到过最隐蔽的一次是：节点上 GPU device plugin 没装好，Pod 一直 Pending，Events 里只写Insufficient nvidia.com/gpu，但没告诉你为什么不足。后来kubectl describe node才发现节点根本没上报 GPU 资源。

5.2 CLI 连不上集群：认证与上下文问题

axCLI 底层用的是 kubeconfig，所以它连不上集群，八成是 kubeconfig 的问题。排查三步：

kubectl config current-context # 当前上下文对不对 kubectl cluster-info # 集群能不能通 kubectl auth can-i create jobs # 权限够不够

如果kubectl能通但ax不通，那就是 ax 读的 kubeconfig 路径不对。默认是~/.kube/config，如果你的配置在别处，用KUBECONFIG环境变量指定。

还有一种情况是权限问题。ax CLI 需要创建 Job、Pod、ConfigMap 等资源的权限。如果用的是受限的 ServiceAccount，会报forbidden。解决办法是给对应的 Role 补权限，或者换一个有权限的上下文。

5.3 Agent 输出丢失：日志与结果的持久化

agent 任务跑完了，但结果找不到了，这是第二常见的问题。原因通常是：Pod 被清理了，日志跟着没了。

K8s 的 Pod 日志默认存在节点上，Pod 删除后日志就没了。解决办法有两个：一是把 agent 的输出写到外部存储（对象存储、数据库），二是配置日志采集，把容器日志实时收集到中心化日志系统。

我自己的做法是双保险：agent 内部把结果写到对象存储，同时 stdout 输出一份给日志系统。这样即使对象存储写失败，还能从日志里捞。

5.4 多集群调度的坑：Karmada 场景下的注意事项

当你用 Karmada 把 agent 任务分发到多个集群时，有几个坑必须提前知道：

• 镜像同步：任务调度到哪个集群，那个集群就得有对应的 agent 镜像。Karmada 本身不管镜像同步，需要配合镜像仓库的多地域复制。
• 存储一致性：跨集群的 PVC 基本不可用，所以数据传递必须走对象存储或消息队列。
• 网络延迟：agent 之间跨集群通信，延迟比同集群高一个数量级，流水线的超时时间要相应调大。
• 状态回传：任务在远端集群执行，状态要回传到中心集群，这依赖 Karmada 的 status 同步机制，偶尔会有延迟。

这些坑我在实际项目里都踩过，最惨的一次是流水线跑到第三步，因为跨集群存储挂载失败，整个流水线卡死，排查了半天才发现是 PVC 的问题。后来全部改成对象存储，再没出过类似问题。

5.5 常见问题速查表

6. 几个我踩过的坑和独家经验

第一个坑是镜像 tag 用 latest。测试环境图省事用 latest，结果某次 agent 镜像更新后，正在跑的流水线拉到了新镜像，行为变了，整个流水线结果不可复现。后来强制规定：所有 agent 镜像必须用明确的版本 tag，禁止 latest。

第二个坑是agent 任务没有超时。一个 agent 卡住了，Job 会一直跑，占着资源不放。解决办法是在 AgentTask 里加activeDeadlineSeconds，超时自动终止。这个值要根据 agent 的正常执行时间设，设太短会误杀，设太长没意义。我的经验是设成正常执行时间的 3 倍。

第三个坑是日志级别开太高。agent 调试时开了 debug 日志，结果日志量爆炸，把节点磁盘写满了。后来规定：生产环境 agent 默认 info 级别，需要 debug 时单独开一个任务，跑完就删。

第四个坑是CLI 版本和 orchestrator 版本不匹配。ax CLI 升级了，但 orchestrator 没升级，导致提交的 AgentTask 字段 orchestrator 不认识，任务静默失败。解决办法是 CLI 启动时检查版本兼容性，不兼容直接报错退出。

这些经验没有一条是从文档里看来的，全是实际跑出来的。agentic 调度这个领域还太新，很多最佳实践还没沉淀下来，只能自己踩。

7. 后续可以怎么扩展

这套 ax 调度环境跑通后，往上还能叠不少东西。比如把 agentic rag 接进来，让 agent 在回答问题前先检索一批文档；比如把 codex cli 和 claude cli 做成可切换的 agent 后端，同一个任务可以指定用哪个 agent 跑；比如接入 Karmada 做真正的多集群调度，让 agent 任务按集群负载自动分发。

我个人最看好的方向是agent 之间的自动协商。现在的流水线依赖是人工写死的，未来可以让 agent 自己决定下一步调用谁。codex 改完代码后，自己判断需不需要 claude 来审，需不需要测试 agent 来验证。这才是 agentic 的真正含义——不是人编排 agent，而是 agent 编排 agent。

不过在那之前，先把单集群的调度跑稳。CLI 入口、K8s 底座、orchestrator 粘合层这三件套搭好，后面加什么都是往上叠。我自己的体会是，这套东西的价值不在于技术多先进，而在于它把 agentic 工作负载的管理成本降下来了。以前跑一个 agent 要手动 ssh 到机器上敲命令，现在一行ax run搞定，这个体验的提升是实打实的。