Agent Gateway

ArchAIHarness 体系下的 Agent 智能网关：一体化管理 + 动态路由代理

---

项目简介

agent-gateway 是 OpenCode Agent 平台的核心控制面，同时承担两大职责：

1. Agent 生命周期管理：Kubernetes 上创建/删除/重启 Agent 工作负载
2. 智能路由代理：子域名 WebUI 代理 + /agent API 代理 + WebSocket 全量透传

---

架构总览

                          ┌─────────────────────────────────────────┐
                          │           Agent Gateway                 │
                          │  ┌───────────────────────────────────┐  │
*.localhost ────────────┼─▶│  SubdomainRoutingFilter → 8080    │  │
                          │  └───────────────────────────────────┘  │
                          │  ┌───────────────────────────────────┐  │
localhost/agent/* ───────┼─▶│  AgentApiRoutingFilter  → 4096    │  │
                          │  └───────────────────────────────────┘  │
                          │  ┌───────────────────────────────────┐  │
localhost/runtime/* ─────┼─▶│  RuntimeController    → Master API│  │
                          │  └───────────────────────────────────┘  │
                          └──────────────┬──────────────────────────┘
                                         │
                                         ▼
                          ┌─────────────────────────────────────────┐
                          │         Spring Cloud Gateway            │
                          │  WebSocket / HTTP 二进制零修改透传        │
                          └──────────────┬──────────────────────────┘
                                         │
                                         ▼
                          ┌─────────────────────────────────────────┐
                          │          Redis Runtime Repository       │
                          │  runtimeId/userId 双索引 + TTL 自动过期   │
                          └──────────────┬──────────────────────────┘
                                         │
                                         ▼
                          ┌─────────────────────────────────────────┐
                          │       Kubernetes Fabric8 Client         │
                          │  Deployment / Service 全生命周期管理       │
                          └─────────────────────────────────────────┘

---

路由规则

路由类型	匹配规则	目标端口	说明
子域名 WebUI	{runtimeId}.localhost/**	8080	VS Code Web 界面
Agent API	localhost/agent/**	4096	OpenCode 原生 API，去掉 /agent 前缀
Master API	localhost/runtime/**	8080	Agent 生命周期管理
健康检查	localhost/health	8080	K8s 探针

---

DDD 分层架构

src/main/java/com/archai/gateway/
├── domain/                    # 领域层（纯业务，无框架依赖）
│   ├── RuntimeStatus.java          # Agent 状态枚举
│   ├── RuntimeSnapshot.java        # Agent 运行快照
│   ├── RuntimeRepository.java      # 仓储端口（SPI）
│   └── RuntimeWorkloadPort.java    # 工作负载端口（SPI）
│
├── application/               # 应用层（编排，无 HTTP）
│   └── RuntimeCommandService.java  # Agent 命令服务
│
├── infrastructure/            # 基础设施层（技术实现）
│   ├── config/
│   │   └── AgentGatewayProperties.java  # 配置绑定
│   ├── redis/
│   │   └── RedisRuntimeRepository.java   # Redis 仓储实现
│   └── kubernetes/
│       └── KubernetesRuntimeWorkload.java # K8s 工作负载实现
│
└── interfaces/               # 接口层（对外暴露）
    ├── RuntimeController.java        # /runtime API
    ├── SubdomainRoutingFilter.java   # 子域名路由过滤器
    └── AgentApiRoutingFilter.java    # /agent 路由过滤器

---

技术栈

组件	版本	说明
Java	17	LTS 版本
Spring Boot	3.2.5	与 Spring Cloud 2023.0.3 严格兼容
Spring Cloud Gateway	2023.0.3	反应式网关
Spring Cloud Kubernetes	2023.0.3	Fabric8 K8s 客户端
Spring Data Redis Reactive	3.2.5	响应式 Redis
Lombok	1.18.38	简化代码

---

Master API 文档

创建 Agent

POST /runtime
Headers:
  x-user-id: {userId}

Response:
{
  "runtimeId": "rt-{userId}-{suffix}",
  "userId": "{userId}",
  "status": "running",
  "namespace": "agent-runtime",
  "deploymentName": "agent-rt-{userId}-{suffix}",
  "serviceName": "agent-rt-{userId}-{suffix}",
  "leaseExpireAt": "2025-06-26T13:00:00Z",
  "webuiUrl": "http://rt-{userId}-{suffix}.localhost/",
  "agentApiBase": "http://rt-{userId}-{suffix}.localhost/agent/"
}

查询 Agent 状态

GET /runtime
Headers:
  x-user-id: {userId}

删除 Agent

DELETE /runtime
Headers:
  x-user-id: {userId}

重启 Agent

POST /runtime/restart
Headers:
  x-user-id: {userId}

---

配置说明

配置项	默认值	说明
agent.gateway.namespace	agent-runtime	Agent 部署命名空间
agent.gateway.agent-image	build-on-vscode-opencode-image:local	Agent 镜像
agent.gateway.webui-port	8080	WebUI 容器端口
agent.gateway.agent-port	4096	Agent API 容器端口
agent.gateway.ttl-seconds	3600	Agent 租约 TTL（秒）
agent.gateway.workspace-pvc-name	agent-workspace	PVC 名称
agent.gateway.workspace-pvc-sub-path-root	workspaces	PVC 子路径根目录
agent.gateway.redis.host	redis.agent-runtime.svc.cluster.local	Redis 地址
agent.gateway.redis.port	6379	Redis 端口
agent.gateway.redis.db	0	Redis 数据库
agent.gateway.redis.key-prefix	agent-runtime	Redis 键前缀

---

本地开发

编译

mvn clean compile

打包

mvn clean package -DskipTests

本地运行

需要 K8s 环境 + Redis + PVC：

# 端口转发 Redis
kubectl -n agent-runtime port-forward svc/redis 6379:6379 &

# 本地启动
mvn spring-boot:run

---

K8s 部署

前置条件

• 命名空间 agent-runtime 已存在
• PVC agent-workspace 已存在
• Redis Service 已部署在 agent-runtime 命名空间

部署

# 构建镜像
docker build -t agent-gateway:local .

# 应用 K8s 资源
kubectl apply -f deploy/

---

WebSocket 支持

Spring Cloud Gateway 原生支持 WebSocket，无需额外配置：

• ✅ 子域名 WebSocket 自动路由到 WebUI 8080 端口
• ✅ /agent/ws/** 自动路由到 Agent 4096 端口
• ✅ 二进制零修改透传，支持 OpenCode Terminal / LSP / DAP
• ✅ WebSocket frame payload 最大支持 10MB

---

关键特性

特性	说明
反应式全栈	Reactor + WebFlux + Reactive Redis，零阻塞
动态路由	子域名 + 路径前缀动态解析到对应 Agent
双索引存储	Redis userId/runtimeId 双索引，查询 O(1)
TTL 自动过期	Agent 租约到期自动回收资源
K8s 原生集成	Fabric8 客户端，不手写 HTTP 请求
二进制透明代理	WebSocket/HTTP 零修改透传

---

项目约束（AI 必读）

1. 全反应式：禁止 Mono.block()、Thread.sleep() 等阻塞 API
2. 领域纯净：domain/ 层不得引入任何 Spring 依赖
3. SPI 设计：扩展点必须定义在领域层，基础设施层实现
4. 无硬编码：所有可调参数必须进 AgentGatewayProperties
5. Header 规范：Header 名全小写（x-user-id 不是 X-User-Id）

---

License

MIT