企业官网建设流程全解析

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

第一次看到“ax”这个标题，很多人会以为是某个命令行工具的缩写，或者某个内部项目的代号。但把热搜词摊开来看——ax、agentic、orchestrator、kubernetes、workspace——这几个词凑在一起，指向的其实是一个非常具体的技术命题：在 Kubernetes 之上，为 agentic 工作负载构建一套轻量级的调度与编排层。ax 在这里我更愿意把它理解成 “agent executor” 或者 “agent exchange” 的缩写，它不是一个现成的开源项目名，而是一类架构模式的代称。

为什么这个命题现在值得聊？因为过去两年，agentic 应用从 demo 走向生产，最大的瓶颈已经不是模型能力，而是运行时环境。一个 agent 要干活，它需要 workspace（工作空间）来存放中间文件、需要 orchestrator（编排器）来协调多个子任务、需要调度器来决定哪个节点跑哪个 agent、需要隔离机制来防止一个 agent 把另一个 agent 的上下文污染掉。这些东西，Kubernetes 原生能力能覆盖一部分，但覆盖得不够顺手。ax 要解决的，就是这“不够顺手”的部分。

这篇文章适合三类人看：第一类是在做 agentic 应用落地、已经被 workspace 管理和调度问题折磨过的工程师；第二类是想把现有 Kubernetes 集群改造成 agent 运行底座的平台团队；第三类是对 agentic orchestration 这个概念感兴趣、想搞清楚它和传统微服务编排到底差在哪里的技术负责人。我会从设计思路、核心细节、实操过程、问题排查四个维度展开，尽量把每个决策背后的“为什么”讲清楚，而不是只丢一堆 YAML 出来。

需要提前说明的是，ax 不是一个有官方文档的标准项目，它更像是一种架构实践。下面涉及的具体实现，一部分来自我在实际项目中的取舍，一部分来自社区里常见的做法，我会明确标注哪些是“我试过可行的”，哪些是“理论上应该这样但需要你根据环境调整”。

2. 整体设计与思路拆解：为什么是 Kubernetes + Agentic Orchestrator

2.1 为什么不在裸机上直接跑 agent

很多人第一反应是：agent 不就是个进程吗，我写个 Python 脚本，用 supervisor 管起来不就行了？这个方案在单机、单 agent、低频调用的场景下确实够用。但一旦进入 agentic 场景，问题就来了。agentic 的核心特征是多步推理 + 工具调用 + 状态保持，一个任务可能拆成十几个子步骤，每个子步骤可能调用不同的工具、访问不同的数据源、产生不同的中间产物。这些中间产物需要有个地方存，这就是 workspace 概念的由来。

裸机方案的问题在于：第一，资源隔离靠进程级别，一个 agent 跑飞了把内存吃满，其他 agent 跟着遭殃；第二，workspace 管理靠本地目录，多机部署时目录同步是个噩梦；第三，扩缩容靠手动，流量高峰时加机器、低谷时减机器，运维成本高；第四，故障恢复靠重启脚本，agent 跑到一半挂了，中间状态全丢。Kubernetes 恰好在这四个维度上都有成熟方案：Pod 级别的资源隔离、PVC 或 emptyDir 的 workspace 挂载、HPA 或 KEDA 的弹性伸缩、以及基于 controller 的故障自愈。

但 Kubernetes 原生调度器是给无状态微服务设计的，它不理解 agent 的“任务亲和性”。比如一个 agent 需要访问某个特定的向量数据库分片，或者需要 GPU 资源来跑本地推理，或者需要和另一个 agent 共享 workspace。这些需求，原生调度器要么不支持，要么需要写很复杂的 affinity 规则。这就是为什么需要一个 agentic orchestrator 层，它站在 Kubernetes 之上，把 agent 的语义需求翻译成 Kubernetes 能理解的调度原语。

2.2 ax 的核心抽象：Agent、Workspace、Task 三元组

ax 的设计里，最核心的三个概念是 Agent、Workspace、Task。Agent 是执行单元，它封装了一个具体的 agentic 能力，比如“代码生成 agent”、“数据检索 agent”、“报告撰写 agent”。Workspace 是状态载体，它可以是 emptyDir（临时）、PVC（持久）、或者 ConfigMap（只读配置）。Task 是调度单元，它描述了一次具体的执行请求：用哪个 Agent、挂哪个 Workspace、跑在什么资源约束下、优先级多高、超时多久。

这三个概念的关系是：一个 Task 绑定一个 Agent 和一个 Workspace，orchestrator 负责把 Task 调度到合适的节点上，Kubernetes 负责实际拉起 Pod。为什么这样设计？因为 agentic 场景下，同一个 Agent 可能被多个 Task 复用，同一个 Workspace 可能被多个 Agent 共享。如果把 Agent 和 Workspace 硬编码在一起，复用性就很差。拆成三元组之后，你可以灵活组合：Agent A 加 Workspace X 跑一个任务，Agent B 加 Workspace X 跑另一个任务，两者共享中间数据但互不干扰执行。

这里有个关键决策：Workspace 的生命周期管理。我试过两种方案。方案一是 Workspace 随 Task 创建、随 Task 销毁，优点是干净，缺点是如果 Task 需要重试，中间状态就丢了。方案二是 Workspace 独立于 Task 存在，Task 只是“借用”它，优点是重试友好，缺点是垃圾回收需要额外逻辑。最终我选了方案二，但加了一个 TTL 机制：Workspace 创建时打上 TTL 标签，orchestrator 定期扫描，超过 TTL 且没有活跃 Task 引用的 Workspace 自动回收。这个 TTL 默认设 24 小时，可以通过注解覆盖。

2.3 调度策略的取舍：Bin Packing 还是 Spread

调度策略上，ax 面临一个经典选择：是把 agent 尽量塞到少数节点上（Bin Packing），还是尽量分散到多个节点上（Spread）。Bin Packing 的优点是资源利用率高，缺点是单点故障影响面大。Spread 的优点是隔离性好，缺点是资源碎片化。

我的选择是混合策略：对于无状态的、短生命周期的 agent（比如单次问答），用 Bin Packing，因为它们挂了重启成本低；对于有状态的、长生命周期的 agent（比如持续运行的监控 agent），用 Spread，因为它们挂了恢复成本高。这个策略通过给 Task 打上ax.io/lifecycle标签来实现，orchestrator 根据标签选择不同的调度 profile。

具体实现上，Bin Packing 用podAffinity加preferredDuringSchedulingIgnoredDuringExecution，Spread 用podAntiAffinity加同样的 preferred 规则。为什么不用 required？因为 required 太刚性，节点资源不足时会导致 Pod 一直 Pending。preferred 允许调度器在条件不满足时降级，保证可用性优先。

3. 核心细节解析与实操要点：Workspace 挂载与 Agent 生命周期

3.1 Workspace 的三种挂载模式及选择依据

Workspace 在 ax 里有三种挂载模式，对应不同的使用场景。第一种是emptyDir，挂载到 Pod 的/workspace目录，生命周期和 Pod 绑定。适合纯计算型 agent，比如代码解释器，中间产物不需要持久化。第二种是persistentVolumeClaim，挂载到同一个路径，生命周期独立于 Pod。适合需要跨 Task 共享数据的 agent，比如一个 agent 生成数据集，另一个 agent 消费数据集。第三种是configMap或secret，只读挂载，适合存放 agent 的配置文件、提示词模板、API 凭证。

选择依据很简单：问自己三个问题。第一，这个 workspace 里的数据，Pod 重启后还需要吗？需要就用 PVC，不需要就用 emptyDir。第二，这个 workspace 里的数据，需要被其他 Pod 读取吗？需要就用 PVC 加ReadWriteMany访问模式，不需要就用ReadWriteOnce。第三，这个 workspace 里的数据，是静态配置还是动态生成？静态就用 ConfigMap，动态就用 PVC。

这里有个坑：ReadWriteMany不是所有存储类都支持。我踩过的坑是，在某个云厂商的默认存储类上创建了ReadWriteMany的 PVC，结果 Pod 一直卡在 ContainerCreating，事件里报FailedMount。排查后发现是存储类不支持多节点读写。解决方案是换用支持 NFS 或 CephFS 的存储类，或者改用对象存储加 initContainer 同步。如果你的环境没有共享存储，一个退而求其次的方案是：每个 Pod 用独立的 emptyDir，通过一个 sidecar 容器做定期同步，但一致性会弱一些。

3.2 Agent 容器的启动流程与 initContainer 的作用

一个 ax agent 的 Pod 里，通常有三个容器：initContainer、主 agent 容器、sidecar 容器。initContainer 负责准备工作空间，比如从对象存储拉取初始数据、解压数据集、设置目录权限。主 agent 容器跑实际的 agentic 逻辑。sidecar 容器负责日志收集、指标暴露、或者 workspace 同步。

为什么要把准备工作放在 initContainer 而不是主容器里？因为 initContainer 和主容器的生命周期是分离的，initContainer 跑完就退出，不占用主容器的资源配额。而且 initContainer 可以按顺序执行多个，每个负责一个独立的准备步骤，失败时更容易定位问题。我见过有人把所有准备工作塞进主容器的 entrypoint 脚本里，结果脚本一长，调试起来非常痛苦，而且主容器的资源配额被准备工作占了一部分，agent 实际能用的资源就少了。

initContainer 的一个常见用途是等待依赖就绪。比如 agent 需要访问一个向量数据库，但数据库可能还没启动。可以在 initContainer 里跑一个循环，用nc -z或curl探测数据库端口，直到通了再退出。这样主容器启动时，依赖一定是就绪的。注意要设置合理的超时，否则 initContainer 会一直卡住，Pod 永远起不来。我一般设 300 秒超时，超过就失败，让 orchestrator 决定是重试还是告警。

3.3 资源配额与 QoS 等级的设置经验

Agent 的资源需求差异很大。一个简单的检索 agent 可能只需要 100m CPU、128Mi 内存，一个跑本地推理的 agent 可能需要 4 核 CPU、16Gi 内存、甚至一张 GPU。ax 的做法是让 Task 描述里显式声明资源需求，orchestrator 负责校验和调度。

这里的关键是QoS 等级的选择。Kubernetes 有三种 QoS：Guaranteed、Burstable、BestEffort。Guaranteed 要求 requests 等于 limits，适合对延迟敏感的 agent。Burstable 允许 requests 小于 limits，适合有突发流量的 agent。BestEffort 不设 requests 和 limits，适合完全不在乎性能的后台任务。

我的经验是：生产环境的 agent 一律用 Guaranteed 或 Burstable，不用 BestEffort。因为 BestEffort 的 Pod 在节点资源紧张时最先被驱逐，agent 跑到一半被驱逐，中间状态丢失，用户体验很差。如果实在不确定资源需求，先用 Burstable，设一个保守的 requests 和一个宽松的 limits，跑一段时间后看监控数据再调整。调整的时候注意，limits 不是越高越好，设太高会导致节点超卖，多个 agent 同时跑时互相争抢，反而更慢。

GPU 资源的声明要特别小心。Kubernetes 里 GPU 是扩展资源，写法是nvidia.com/gpu: 1。注意 GPU 不支持超卖，一个 GPU 只能分配给一个 Pod。如果你的 agent 只是偶尔用 GPU，可以考虑用 MIG（Multi-Instance GPU）或者时间片共享，但这需要节点层面的配置，不是所有环境都支持。

4. 实操过程与核心环节实现：从零搭建一个 ax 调度层

4.1 环境准备与前置检查

在开始之前，你需要一个可用的 Kubernetes 集群，版本建议 1.26 及以上。为什么是 1.26？因为 1.26 引入了PodSchedulingReadiness特性，允许 Pod 在准备好之前不参与调度，这对 agent 场景很有用——agent 可能需要先加载模型权重再接受任务。另外 1.26 的kubectl对--subresource的支持更完善，调试起来方便。

前置检查清单如下。第一，确认集群有可用的存储类，kubectl get storageclass能看到至少一个非 default 的存储类。第二，确认节点有足够的资源，kubectl describe nodes看 Allocatable 和 Allocated 的差值。第三，确认你有 cluster-admin 权限，因为要创建 CRD 和 ClusterRole。第四，确认网络插件支持 NetworkPolicy，因为 agent 之间可能需要网络隔离。

如果是在 Windows 上做开发，注意一个常见问题：某些 agent 运行时需要虚拟化平台支持。如果你在 Windows 上跑 Docker Desktop，需要在 BIOS 里开启虚拟化，并在 Docker Desktop 设置里启用 WSL2 后端。这个坑我踩过，报错信息通常是requires the virtual machine platform on windows，解决方案是在“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”，然后重启。

4.2 定义 Agent 和 Task 的 CRD

ax 的核心是两组 CRD：Agent 和 Task。Agent 描述一个可复用的执行单元，Task 描述一次具体的执行请求。下面是我实际使用的 CRD 定义，做了简化，去掉了部分生产环境才需要的字段。

apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: agents.ax.io spec: group: ax.io versions: - name: v1alpha1 served: true storage: true schema: openAPIV3Schema: type: object properties: spec: type: object properties: image: type: string command: type: array items: type: string workspaceMode: type: string enum: [emptyDir, pvc, configMap] defaultResources: type: object properties: cpu: type: string memory: type: string scope: Namespaced names: plural: agents singular: agent kind: Agent shortNames: - ag

Task 的 CRD 类似，但多了agentRef、workspaceRef、priority、timeoutSeconds这些字段。为什么用 CRD 而不是 ConfigMap？因为 CRD 有 schema 校验，写错了字段名会直接报错，而 ConfigMap 不会。而且 CRD 可以被 RBAC 精细控制，比如只允许某个 ServiceAccount 创建 Task，不允许修改 Agent。

创建完 CRD 后，用kubectl get crd | grep ax.io确认。如果看到agents.ax.io和tasks.ax.io，说明创建成功。接下来要写一个 controller 来监听这些资源。controller 可以用 client-go 写，也可以用 kubebuilder 生成骨架。我推荐 kubebuilder，因为它帮你处理了 informer、workqueue、leader election 这些样板代码，你只需要关注 reconcile 逻辑。

4.3 Orchestrator 的 Reconcile 逻辑与调度决策

Orchestrator 的核心是一个 reconcile 循环：监听 Task 的创建事件，读取 Task 的 spec，找到对应的 Agent，生成一个 Pod 的 spec，提交给 Kubernetes API Server。这个过程中有几个关键决策点。

第一个决策点是节点选择。Orchestrator 需要根据 Task 的资源需求、Workspace 的访问模式、Agent 的亲和性规则，计算出一个候选节点列表。我的做法是先用 Kubernetes 的NodeAffinity做粗筛，再用自定义的评分函数做细排。评分函数考虑三个因子：节点剩余资源、节点上已有 agent 的数量、节点到存储的网络延迟。权重分别是 0.5、0.3、0.2。这个权重不是拍脑袋定的，是跑了一周的 benchmark 后调出来的。如果你的场景对网络延迟特别敏感，可以把第三个因子的权重调高。

第二个决策点是并发控制。同一个 Agent 可能同时被多个 Task 引用，如果无限制地创建 Pod，节点资源很快会被打满。我的做法是给每个 Agent 设一个maxConcurrency字段，orchestrator 在 reconcile 时检查当前活跃的 Pod 数量，超过阈值就把 Task 放进一个等待队列，等有 Pod 退出后再调度。等待队列用 Kubernetes 的workqueue实现，支持优先级排序。

第三个决策点是超时与重试。Task 的 spec 里有timeoutSeconds和maxRetries。orchestrator 在创建 Pod 时，会设置一个activeDeadlineSeconds，等于 Task 的超时时间。Pod 超时后会被 Kubernetes 自动终止，orchestrator 监听到终止事件，检查重试次数，如果没超过上限就重新创建 Pod，超过就标记 Task 为 Failed。注意activeDeadlineSeconds是从 Pod 启动开始算的，不包括调度等待时间。如果你希望包括调度时间，需要在 orchestrator 层面自己计时。

4.4 一个完整的 Task 执行示例

下面是一个完整的 Task YAML，展示了如何引用一个 Agent、挂载一个 PVC Workspace、设置资源约束和超时。

apiVersion: ax.io/v1alpha1 kind: Task metadata: name: code-review-task-001 namespace: agentic labels: ax.io/lifecycle: short ax.io/priority: high spec: agentRef: name: code-review-agent workspaceRef: name: shared-repo-pvc mountPath: /workspace/repo resources: requests: cpu: "2" memory: "4Gi" limits: cpu: "4" memory: "8Gi" timeoutSeconds: 1800 maxRetries: 2 env: - name: REVIEW_DEPTH value: "deep" - name: OUTPUT_FORMAT value: "markdown"

提交这个 Task 后，orchestrator 会在几秒内创建一个 Pod。你可以用kubectl get tasks -n agentic看 Task 状态，用kubectl get pods -n agentic -l ax.io/task=code-review-task-001看 Pod 状态。Pod 的日志里会输出 agent 的执行过程。如果一切正常，Task 状态会从 Pending 变成 Running，最后变成 Succeeded。

这里有个细节：workspaceRef里的shared-repo-pvc必须提前创建好，并且和 Task 在同一个 namespace。如果 PVC 不存在，orchestrator 会报错，Task 卡在 Pending。我建议在创建 Task 之前，先用kubectl get pvc -n agentic确认 PVC 存在且状态是 Bound。

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

5.1 Workspace 挂载失败：从事件里找线索

Workspace 挂载失败是最常见的问题，表现是 Pod 卡在 ContainerCreating，kubectl describe pod的 Events 里会有FailedMount或FailedAttachVolume。排查思路分三步。第一步，确认 PVC 状态，kubectl get pvc -n <namespace>，如果是 Pending，说明存储类没有正确配置，或者没有可用的 PV。第二步，确认访问模式，kubectl get pvc -o yaml看accessModes，如果是ReadWriteMany但存储类不支持，就会挂载失败。第三步，确认节点和存储的网络连通性，如果是 NFS 或 CephFS，检查节点的防火墙规则和路由表。

我遇到过一个比较隐蔽的问题：PVC 状态是 Bound，访问模式也对，但 Pod 就是挂不上。排查后发现是存储类的volumeBindingMode设成了WaitForFirstConsumer，而 Pod 的调度被一个不满足的 nodeAffinity 卡住了，导致 PV 一直没有绑定到具体节点。解决方案是放宽 nodeAffinity，或者把volumeBindingMode改成Immediate。但Immediate有它自己的问题，可能导致 PV 绑定到一个没有 Pod 的节点上，造成资源浪费。所以更推荐的做法是保留WaitForFirstConsumer，但确保 nodeAffinity 不会把 Pod 卡死。

5.2 Agent 启动卡住：从 initContainer 日志入手

Agent 启动卡住，表现是 Pod 状态是 Running，但主容器一直没有输出，或者 initContainer 一直不退出。排查思路是先用kubectl logs <pod> -c <init-container-name>看 initContainer 的日志。如果日志停在某一步不动，说明那一步卡住了。常见原因有三个：等待依赖超时、下载数据太慢、权限不足。

等待依赖超时是最常见的。比如 initContainer 在等一个数据库，但数据库地址配错了，或者网络策略不允许访问。解决方案是检查环境变量和 NetworkPolicy。下载数据太慢，通常是对象存储的带宽问题，可以考虑用 CDN 或者预先把数据打包进镜像。权限不足，通常是 PVC 的fsGroup没设对，导致容器里的非 root 用户无法写入。解决方案是在 Pod 的 securityContext 里设置fsGroup，值等于容器里运行用户的 GID。

还有一个坑是setting up workspace: loading packages...卡住。这个报错通常出现在 agent 启动时加载依赖包的阶段。原因可能是包管理器在等待网络，或者包源不可达。解决方案是检查容器的网络策略，确认允许访问包源，或者预先在镜像里把依赖装好，避免运行时下载。

5.3 调度失败：Pending Pod 的排查路径

Task 创建后，Pod 一直 Pending，kubectl describe pod的 Events 里会有FailedScheduling。排查路径如下。第一，看 Events 里的具体原因，常见的有Insufficient cpu、Insufficient memory、node(s) had taint、node(s) didn't match node selector。第二，根据原因调整。如果是资源不足，要么降低 requests，要么加节点。如果是 taint，要么去掉 taint，要么给 Pod 加 toleration。如果是 node selector 不匹配，检查标签是否正确。

我遇到过一个比较特殊的情况：节点资源明明够，但 Pod 就是调度不上去。排查后发现是节点的Allocatable和Capacity有差异，Capacity是物理资源，Allocatable是扣除了系统预留之后的资源。如果 requests 设得比Allocatable大，就会调度失败。解决方案是用kubectl describe node看Allocatable的实际值，而不是看Capacity。

5.4 常见问题速查表

5.5 几个我踩过的坑和对应的技巧

第一个坑是Task 的 namespace 和 Agent 的 namespace 不一致。ax 的设计里，Agent 是 namespace 级别的资源，Task 只能引用同 namespace 的 Agent。我一开始没注意，把 Agent 建在default，Task 建在agentic，结果 orchestrator 一直报agent not found。解决方案是要么把 Agent 和 Task 放同一个 namespace，要么把 Agent 改成 Cluster 级别的资源。我选了前者，因为 namespace 隔离更清晰。

第二个坑是PVC 的容量规划。Agent 产生的中间数据可能比预期大很多，PVC 满了之后写入失败，agent 报错退出。解决方案是给 PVC 设一个合理的容量，并在 orchestrator 里加一个监控，当 PVC 使用率超过 80% 时告警。另外，可以给 Workspace 加一个清理策略，Task 成功后自动删除临时文件，只保留最终产物。

第三个坑是日志太多导致节点磁盘满。Agent 的日志如果直接写到 stdout，会被 Kubernetes 的日志驱动收集到节点磁盘上。如果 agent 输出很频繁，节点磁盘很快会满。解决方案是给容器的日志设一个大小限制，在 Pod 的 spec 里加logging配置，或者用 sidecar 把日志转发到远端存储。我一般用 Fluent Bit 做 sidecar，配置简单，资源占用也小。

第四个坑是Agent 之间的时钟不同步。如果多个 agent 协作，时间戳不一致会导致排序错乱。解决方案是确保所有节点都开启了 NTP 同步，或者在 agent 层面统一用 UTC 时间。这个坑比较隐蔽，因为单机测试时不会出现，只有多节点部署时才暴露。

6. 从 ax 出发：Agentic Orchestration 的边界与延伸

ax 这套东西跑通之后，我最大的体会是：agentic orchestration 的难点不在调度算法，而在状态管理。传统微服务的调度是无状态的，请求来了就处理，处理完就结束。Agent 不一样，它有一个持续演进的 workspace，这个 workspace 里可能有半成品的数据、未完成的推理链、待确认的中间结果。调度器不仅要决定“在哪里跑”，还要决定“状态怎么迁移”、“失败怎么恢复”、“并发怎么隔离”。这三个问题，Kubernetes 原生能力只能解决一部分，剩下的需要 orchestrator 层来补。

如果你想把 ax 的思路用到自己的项目里，我的建议是从小处着手。先不要搞复杂的 CRD 和 controller，用一个简单的 Job 加一个 PVC 就能跑起来。等遇到瓶颈了，再逐步引入 orchestrator。比如，当你发现需要动态调整资源配额时，引入一个简单的 admission webhook；当你发现需要跨 Task 共享 workspace 时，引入一个 workspace 管理器；当你发现需要优先级调度时，引入一个自定义调度器。每一步都解决一个具体问题，而不是一开始就设计一个大而全的架构。

另外，agentic 场景下的可观测性和传统微服务很不一样。传统微服务看 QPS、延迟、错误率就够了，agent 还需要看推理步数、工具调用次数、workspace 大小变化、中间结果的语义一致性。这些指标目前没有标准方案，需要自己埋点。我一般会在 agent 的代码里加一个轻量的 metrics 库，把关键事件打成 Prometheus 指标，然后用 Grafana 做面板。这个投入是值得的，因为 agent 的行为很难预测，没有可观测性就等于盲人摸象。

最后分享一个我在实际使用中的小技巧：给每个 Task 的 Pod 加一个ax.io/task-id标签，值就是 Task 的名字。这样排查问题时，可以用kubectl get pods -l ax.io/task-id=<task-name>快速找到对应的 Pod，不用在几十个 Pod 里翻。这个标签还可以用来做日志聚合，Fluent Bit 可以根据标签把日志路由到不同的索引里。成本很低，但排查效率提升很明显。