企业官网建设流程全解析

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

第一次看到“ax”这个标题，很多人会以为是某个库的缩写，或者干脆是打错了。但把热词铺开一看——ax调度、agent、kubernetes、workspace、gateway——这几个词凑在一起，指向其实非常明确：这是一套围绕Agent 工作负载在 Kubernetes 上的调度与网关接入的实践方案。ax 在这里我更倾向于把它理解成一个代号，代表“agent execution”这条链路，也就是智能体从被创建、被调度、被分配到工作空间，到最终通过网关对外提供服务的完整闭环。

为什么这个方向值得单独拿出来讲？因为过去一年里，Agent 类应用的部署形态发生了明显变化。早期大家跑一个 Agent，基本就是本地起个进程，配个 API Key，能对话就行。但现在不一样了，Agent 开始有记忆、有工具调用、有沙箱工作空间、有多实例并发，甚至一个 Agent 背后挂着好几个子 Agent 协同。这种负载放到单机上跑，资源隔离做不好，一个 Agent 把内存吃满，其他全挂；放到 Kubernetes 上跑，又会遇到调度策略、工作空间持久化、网关路由、502 报错排查这一堆问题。热词里那些“502 bad gateway”“workspace requires the virtual machine platform”“setting up workspace loading packages 卡住”，全都是真实踩坑现场。

这篇内容适合三类人看：一是正在把 Agent 从本地脚本往集群上迁的开发者；二是负责 Agent 平台基础设施、需要设计调度和网关方案的工程师；三是刚接触 Kubernetes，想搞明白 Agent 场景下调度到底特殊在哪的入门者。我会尽量把每个决策背后的“为什么”讲清楚，参数怎么算、配置怎么写、报错怎么查，都给出可以直接抄的路径。不堆概念，讲人话。

2. 整体设计思路：为什么 Agent 负载不能照搬普通微服务那套

2.1 Agent 负载的三个特殊之处

普通微服务是无状态的，请求来了处理完就走，副本随便扩缩容，调度器想放哪放哪。Agent 完全不是这个逻辑。第一个特殊点是有状态的工作空间。一个 Agent 在运行过程中会产生会话上下文、临时文件、工具调用的中间产物，这些东西往往需要挂载到一个持久化的 workspace 里。热词里“claude's workspace requires the virtual machine platform on windows”就是典型的 workspace 依赖问题——工作空间不是简单挂个空目录就行，它对运行环境有要求。

第二个特殊点是执行时长不可预测。普通接口几百毫秒返回，Agent 一次任务可能跑几分钟甚至几十分钟，中间还要调外部工具、等模型响应。这就导致调度时不能简单按 CPU 请求量来装箱，否则一个长任务把节点占死，其他 Pod 排队。

第三个特殊点是网关链路更长。Agent 对外通常不是直接暴露端口，而是经过一层 gateway 做鉴权、限流、协议转换。热词里“springcloud gateway”“vercel ai gateway”“gateway配置路由转发固定链接地址”都指向这个环节。链路一长，502 这类错误就特别容易出现，而且排查起来要一层层剥。

2.2 调度方案选型：为什么是 Kubernetes 而不是别的

有人会问，Agent 调度用 Docker Compose 或者 Nomad 不行吗？小规模确实行，但一旦涉及多租户、多 Agent 类型、动态扩缩容，Kubernetes 的优势就出来了。它的 Device Plugin 机制可以把特殊资源（比如 GPU、特定加速卡）抽象成可调度资源，热词里“kubernetes device plugin”就是这个点。Agent 如果要用到推理加速硬件，通过 Device Plugin 注册后，调度器就能像分配 CPU 一样分配这些设备。

另一个关键是 Kubernetes 的Workspace 抽象能力。通过 PersistentVolumeClaim 加 StorageClass，可以给每个 Agent 实例分配独立的工作空间，互不干扰。再配合 Namespace 做租户隔离，一个团队一个命名空间，资源配额和网络策略都能单独控制。这套组合拳是 Compose 给不了的。

至于 ax 调度这个说法，我理解它强调的是“agent execution 调度”，核心是在标准调度器之上加一层面向 Agent 的调度策略。标准 Kubernetes 调度看的是资源请求和节点亲和性，而 Agent 调度还要看工作空间就绪状态、网关注册状态、依赖的模型服务是否可用。这层逻辑通常通过自定义调度器扩展或者 Admission Webhook 来实现。

2.3 网关在整个链路里的位置

Gateway 不是可有可无的装饰。Agent 对外提供服务时，网关承担四件事：路由（把请求转发到正确的 Agent 实例）、鉴权（校验调用方身份）、限流（防止单个 Agent 被打爆）、协议适配（把外部 HTTP 请求转成 Agent 内部能理解的格式）。热词里“gateway nc adapter 下载”“gateway配置路由转发固定链接地址”说明很多人在做路由固定化这件事，也就是让某个 Agent 始终对应某个固定入口，而不是每次调度后地址都变。

这里有个设计取舍：是让网关做服务发现动态路由，还是给每个 Agent 分配固定地址？动态路由灵活，但调试麻烦；固定地址稳定，但扩缩容时要额外维护映射。我的经验是，对外暴露的 Agent 用固定地址加网关转发，内部子 Agent 之间用动态服务发现，这样兼顾稳定性和灵活性。

3. 核心细节解析：调度、工作空间、网关三块硬骨头

3.1 ax 调度的核心参数与计算逻辑

Agent 调度最容易被忽视的是资源请求的设置。很多人拍脑袋写requests: cpu 500m, memory 1Gi，结果要么调度不上去，要么节点被压垮。正确的做法是先测出单个 Agent 实例的基线资源和峰值资源。

基线资源是 Agent 空闲等待时的占用，比如一个常驻的 Agent 进程，不处理任务时可能占 200MB 内存、50m CPU。峰值资源是处理任务时的占用，可能飙到 2GB 内存、1 核 CPU。调度请求应该按基线设，限制按峰值设，这样调度器能装下更多实例，同时用 limit 防止单个实例失控。

具体计算可以这样：假设节点有 16 核 64GB，预留 2 核 8GB 给系统组件，可用 14 核 56GB。单 Agent 基线 50m CPU、200MB 内存，那么理论上能装 280 个实例（按 CPU 算）或 280 个（按内存算）。但实际要考虑峰值，如果峰值是基线的 4 倍，那实际安全并发数要打对折。我一般会留 30% 余量，也就是单节点跑 100 到 150 个 Agent 实例比较稳。

注意：Agent 的内存峰值往往出现在模型响应解析和工具调用返回处理阶段，这两个时刻要重点监控。用kubectl top pod配合 Prometheus 抓一段时间的数据，比拍脑袋靠谱得多。

3.2 Workspace 的持久化与初始化陷阱

Workspace 这块坑最多。热词里“setting up workspace: loading packages...卡住”和“couldn't complete the workspace policy acknowledgment”都是初始化阶段的问题。Agent 的工作空间通常需要预装依赖包、初始化配置文件、拉取工具链，这个过程如果放在 Pod 启动时做，很容易超时或卡住。

我的做法是把 workspace 初始化拆成两步：基础镜像预置和运行时挂载。基础镜像里把常用的依赖、工具链、Python 包全部装好，做成一个几百 MB 到 1GB 的镜像。运行时只挂载用户数据目录和会话目录，这两个目录用 PVC 持久化。这样 Pod 启动时不需要再装包，秒级就绪。

PVC 的 StorageClass 选择也有讲究。如果 Agent 读写频繁，用本地 SSD 的 StorageClass；如果只是存会话记录，用网络存储就行。读写性能差的工作空间会让 Agent 响应变慢，用户感知很明显。

apiVersion: v1 kind: PersistentVolumeClaim metadata: name: agent-workspace-pvc spec: accessModes: - ReadWriteOnce storageClassName: local-ssd resources: requests: storage: 20Gi

这段 PVC 定义里，ReadWriteOnce表示同一时间只能被一个节点挂载，适合单 Agent 实例独占工作空间的场景。如果多个 Agent 要共享工作空间，得用ReadWriteMany，但性能会下降，需要权衡。

3.3 Gateway 配置：从路由到 502 排查

Gateway 配置的核心是路由规则。以 Spring Cloud Gateway 为例，一条典型的 Agent 路由长这样：

spring: cloud: gateway: routes: - id: agent-route uri: http://agent-service:8080 predicates: - Path=/agent/** filters: - StripPrefix=1 - name: RequestRateLimiter args: redis-rate-limiter.replenishRate: 10 redis-rate-limiter.burstCapacity: 20

这条规则的意思是：所有/agent/**的请求转发到agent-service:8080，转发前去掉第一层路径，并且做限流，每秒补充 10 个令牌，突发上限 20。限流参数要根据 Agent 的处理能力来定，如果单个 Agent 每秒只能处理 5 个请求，那 replenishRate 设 10 就会把 Agent 打爆。

502 Bad Gateway 在 Agent 场景下高频出现，原因通常有三类：上游 Agent 实例没就绪、网关到 Agent 的网络不通、Agent 处理超时导致连接被断。排查顺序是先用kubectl get endpoints看 Agent 的 Endpoint 是否注册，再用curl从网关 Pod 内部直接访问 Agent 地址，最后看 Agent 日志有没有超时或崩溃。热词里“unexpected status 502 bad gateway: cc switch local proxy failed”这种，多半是本地代理层和网关层之间的连接问题，要检查代理配置和网关的健康检查路径是否一致。

4. 实操过程：从零搭一套 Agent 调度加网关链路

4.1 环境准备与基础组件安装

先确认 Kubernetes 集群版本在 1.24 以上，因为 Device Plugin 和调度器扩展的 API 在这个版本之后才稳定。集群至少三个节点，一个控制面两个工作节点，方便观察调度分布。

安装顺序是：先装 StorageClass 提供方（比如本地盘方案或网络存储方案），再装网关（Spring Cloud Gateway 或类似方案），最后装 Agent 运行时。网关和 Agent 之间通过 Service 通信，不要直接写 Pod IP，否则 Pod 重建后地址就失效了。

kubectl create namespace agent-system kubectl create namespace agent-workspace kubectl apply -f storageclass.yaml kubectl apply -f gateway-deployment.yaml kubectl apply -f agent-runtime-daemonset.yaml

这里把 Agent 运行时做成 DaemonSet 是有考虑的：每个节点跑一个运行时守护进程，负责管理该节点上所有 Agent 实例的工作空间挂载和生命周期。这样比每个 Agent 一个 Pod 更省资源，启动也更快。

4.2 Agent 实例的调度配置实战

一个完整的 Agent 实例定义需要包含资源请求、工作空间挂载、网关注册三个部分。下面是一个精简后的模板：

apiVersion: apps/v1 kind: Deployment metadata: name: agent-instance namespace: agent-workspace spec: replicas: 3 selector: matchLabels: app: agent template: metadata: labels: app: agent spec: containers: - name: agent image: agent-runtime:latest resources: requests: cpu: 100m memory: 256Mi limits: cpu: 1 memory: 2Gi volumeMounts: - name: workspace mountPath: /workspace env: - name: GATEWAY_URL value: http://gateway.agent-system:8080 - name: AGENT_ID valueFrom: fieldRef: fieldPath: metadata.name volumes: - name: workspace persistentVolumeClaim: claimName: agent-workspace-pvc

关键点在AGENT_ID这个环境变量，它用 Pod 名字作为 Agent 的唯一标识，启动后 Agent 会拿这个 ID 去网关注册。网关收到注册请求后，把 ID 和 Pod IP 的映射写进路由表。这样网关就知道哪个请求该转发到哪个 Agent。

调度策略上，我给 Agent 加了节点亲和性，让它们尽量分散到不同节点，避免单节点故障导致全部 Agent 不可用：

affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: app: agent topologyKey: kubernetes.io/hostname

preferred而不是required，是因为如果节点不够，硬性反亲和会导致 Pod 调度不上去。用 preferred 让调度器尽量分散，实在分散不了也能跑。

4.3 网关注册与健康检查配置

Agent 启动后要向网关注册，注册内容包含 Agent ID、访问地址、健康检查路径。网关定期调健康检查路径，连续失败三次就把这个 Agent 从路由表摘掉。健康检查路径建议单独做一个轻量接口，不要用业务接口，否则业务繁忙时健康检查超时会导致误摘。

# Agent 侧注册逻辑示意 import requests import os agent_id = os.environ["AGENT_ID"] gateway_url = os.environ["GATEWAY_URL"] def register(): payload = { "id": agent_id, "endpoint": f"http://{os.environ['POD_IP']}:8080", "health_path": "/healthz" } requests.post(f"{gateway_url}/register", json=payload) def healthz(): return {"status": "ok"}

注册是幂等的，Agent 重启后重新注册，网关更新映射即可。这里有个细节：Agent 优雅退出时要主动调注销接口，否则网关要等健康检查失败才摘除，这期间会有请求打到已经退出的实例上，产生 502。

4.4 完整链路验证与压测

链路搭好后，用curl从集群外部打网关地址，看请求能不能正确路由到 Agent。然后做一轮压测，观察三个指标：网关的请求延迟、Agent 的 CPU 和内存曲线、502 出现的频率。

压测工具用hey或wrk都行，命令大概是这样：

hey -n 1000 -c 50 -m POST -d '{"task":"test"}' http://gateway.example.com/agent/run

1000 个请求，50 并发。如果 502 比例超过 1%，就要查是网关限流太严还是 Agent 处理不过来。我实测下来，单 Agent 实例在 2 核 4G 的配置下，处理简单任务能到每秒 20 到 30 个请求，复杂任务会降到个位数。压测数据是调优限流参数的依据，不要凭感觉设。

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

5.1 502 与连接超时速查表

这张表是我踩坑后整理的，基本覆盖了 Agent 部署中最常见的几类问题。排查时按顺序来，先看 Pod 状态，再看网关日志，最后看 Agent 日志，一层层缩小范围。

5.2 几个容易忽略的实操心得

第一个心得是就绪探针的初始延迟要给够。Agent 启动时要加载模型配置、初始化工作空间、注册到网关，这个过程可能需要 10 到 30 秒。如果initialDelaySeconds设成 5 秒，探针会在 Agent 还没准备好时就判定失败，导致 Pod 反复重启。我一般设 20 秒起步，复杂 Agent 设 60 秒。

第二个心得是网关的健康检查路径要独立。不要用/或者业务接口做健康检查，单独开一个/healthz，里面只做最轻量的检查，比如返回一个固定字符串。这样即使业务繁忙，健康检查也不会超时。

第三个心得是工作空间的清理策略要明确。Agent 退出后，工作空间里的临时文件要不要保留？我的做法是保留会话记录，清理临时文件。通过一个 init 容器在启动时清理超过 7 天的临时文件，避免磁盘被占满。

提示：如果 Agent 用到 GPU 或其他特殊设备，记得在 Pod 定义里加resources.limits里的设备资源，比如nvidia.com/gpu: 1，同时确保节点上装了对应的 Device Plugin。没有 Device Plugin，调度器不认识这些资源，Pod 会一直 Pending。

5.3 Agent 安全与未授权访问的防范

热词里出现了“kubernetes 未授权访问漏洞”，这个在 Agent 场景下尤其要重视。Agent 的工作空间里可能有敏感数据，网关的注册接口如果没鉴权，任何人都能注册一个假 Agent 把流量劫持走。

基本防范措施有三条：网关注册接口加 Token 鉴权，Agent 和网关之间走 mTLS，工作空间 PVC 的访问权限限制到具体 ServiceAccount。这三条做到位，大部分未授权访问风险就堵住了。另外，Agent 的 API 不要直接暴露到公网，所有外部请求必须经过网关，网关做鉴权和限流。

6. 关于 Agent 记忆与框架选型的补充思考

热词里还有几个词值得单独聊：agent记忆、agent框架、harness和agent区别、skill和agent的区别。这些概念在实际项目中会直接影响调度和网关的设计。

Agent 记忆分短期和长期。短期记忆就是当前会话的上下文，放在工作空间的会话文件里，Pod 重启就丢。长期记忆需要外部存储，比如向量数据库，Agent 通过工具调用去读写。调度时要考虑长期记忆服务的可用性，如果记忆服务挂了，Agent 虽然能启动但功能不完整，这时候网关的健康检查应该把记忆服务也纳入，不健康就不注册。

Harness 和 Agent 的区别，我的理解是 Harness 是执行框架，负责调度工具调用、管理执行流程；Agent 是决策主体，负责决定调什么工具、怎么调。一个 Harness 可以跑多个 Agent，一个 Agent 也可以换不同 Harness。在 Kubernetes 上部署时，Harness 通常作为 Sidecar 和 Agent 跑在同一个 Pod 里，共享工作空间，这样工具调用的中间产物不用跨 Pod 传输，效率更高。

Skill 和 Agent 的区别更简单：Skill 是能力单元，比如“查天气”是一个 Skill；Agent 是使用 Skill 的主体。一个 Agent 可以挂多个 Skill。调度时 Skill 通常以插件形式加载，不需要单独调度，但 Skill 依赖的外部服务需要保证可达。

这些概念理清楚，调度策略和网关路由的设计就有了依据。不是所有东西都要塞进一个 Pod，该拆的拆，该合的合，核心原则是减少跨网络调用，把强耦合的组件放在一起。

7. 我个人的几点经验体会

搞 Agent 调度和网关这套东西，最大的感受是不要过早优化。一开始就想着做多租户、做精细调度、做复杂网关规则，结果往往是配置写了一堆，问题更多。我的建议是先跑通最小链路：一个 Agent 实例、一个网关路由、一个工作空间，能正常处理请求。然后再加副本、加限流、加健康检查。每加一层，压测一轮，确认稳定再加下一层。

另一个体会是日志要打全。Agent 出问题时，光看 Pod 状态看不出所以然，必须结合网关日志、Agent 日志、工作空间里的执行日志一起看。我习惯在 Agent 启动时把关键配置打印出来，包括注册的网关地址、工作空间路径、资源限制，这样排查时一眼就能看出配置有没有生效。

最后分享一个小技巧：给 Agent 的每个请求打一个 trace ID，从网关一路传到 Agent 内部，这样排查 502 时能快速定位是哪个环节断的。trace ID 用请求头传递，网关生成，Agent 记录到日志里。这个成本很低，但排查效率提升非常明显。