A2A 智能网关（gateway）

基于设计文档《A2A需求分析-网关-K8s全链路架构详细设计方案》实现的智能网关核心服务。

本期范围：网关核心 + 可视化运维后台。Agent/CLI 为预留接口，K8s 算力层不实际部署。

技术栈

• 后端：Python + FastAPI + Uvicorn + redis-py（asyncio）
• 存储：Redis（任务池 / Agent 池 / 调度索引 / 心跳 ZSet / 审计日志）
• 前端：Vue 3 + Vite + Element Plus（完整运维后台）
• 后台任务：asyncio 循环（心跳扫描 / 调度 / 超时检查），配 Redis 分布式锁防多实例重复执行

目录结构

gateway/
├── docker-compose.yml        # 本地一键启动 Redis
├── requirements.txt          # Python 依赖
├── .env.example              # 环境变量示例
├── backend/
│   ├── app/
│   │   ├── main.py           # FastAPI 入口
│   │   ├── config.py         # 配置
│   │   ├── constants.py      # Redis 键名/TTL/状态常量
│   │   ├── models/schemas.py # Pydantic 模型
│   │   ├── repository/       # Redis 存储层（task/agent/log）
│   │   ├── services/         # 业务服务（任务/Agent/调度/心跳/通信/超时/锁）
│   │   ├── api/              # 路由（cli/agent/admin）
│   │   ├── middleware.py     # 日志中间件
│   │   └── scheduler_loop.py # 后台任务循环
│   └── tests/                # 单元与集成测试
└── frontend/                 # Vue3 + Element Plus 运维后台

快速启动

1. 启动 Redis

docker compose up -d

无 Docker 时需本机提供 Redis 实例，并设置 REDIS_URL。

2. 启动后端

cd backend
pip install -r ../requirements.txt
# 复制 .env.example 为 .env 并按需修改
uvicorn app.main:app --host 0.0.0.0 --port 8000

接口文档（Swagger）：http://localhost:8000/docs

3. 启动前端运维后台

cd frontend
# 使用 Node >= 18（推荐 18/20/22）
npm install
npm run dev

访问 http://localhost:5173 ，Vite 已将 /api 代理到后端 :8000。

4. 运行后端测试

cd backend
python -m pytest -q

核心机制

任务池（Redis）

• task:info:{request_id}：任务全量信息（Hash）
• task:pending / task:running：调度状态索引（Set）
• 状态流转：pending → running → success/failed
• TTL 默认 24h 自动归档；RequestID 幂等去重

Agent 池（Redis）

• agent:info:{agent_id}：Agent 信息（Hash）
• agent:heartbeat：心跳时间戳（ZSet，score=最后心跳）
• agent:tag:{tag}：能力标签索引（Set）
• 心跳保活：网关每 60s 扫描，连续 120s 未心跳标记 offline

规则调度

标签精准匹配 → 负载过滤（当前负载 < 并发上限）→ 最低负载（停留时间久者优先）→ 绑定 Agent 并下发。

认证

CLI 提交任务与 Agent 注册时，请求体必须携带 auth 字段，值须与网关配置的 GATEWAY_AUTH（.env 中设置）一致，否则返回 401。示例：

curl -X POST http://localhost:8000/api/cli/tasks \
  -H "Content-Type: application/json" \
  -d '{"auth": "<GATEWAY_AUTH>", "task_type": "compile", "task_tags": ["build"], "payload": {"cmd": "python -m build"}}'

预留 Agent 协议接口

所有接口中 register 必须携带 auth 字段，其余接口以已注册的 agent_id 关联身份。

接口	说明
POST /api/agent/register	Agent 启动注册（auth + 能力标签、并发上限、地址）
POST /api/agent/unregister	优雅注销
POST /api/agent/heartbeat	心跳（约每 10s，同步负载）
POST /api/agent/result	任务结果回传

通信中转

以 RequestID + AgentID 双维度关联 CLI 会话与 Agent，正向下发任务指令、反向回传进度与结果。本期为状态机闭环 + 日志记录，实际网络下发由 Agent 接入时扩展。

运维后台

• 任务管理：列表 / 筛选 / 详情 / 进度 / 取消
• Agent 管理：卡片网格 / 标签 / 负载 / 心跳 / 离线高亮
• 日志审计：全链路时间线，按 RequestID / AgentID 筛选
• 手动管控：取消任务 / 重置任务 / 下线 Agent

环境变量

见 .env.example，关键参数：

变量	默认	说明
REDIS_URL	redis://localhost:6379/0	Redis 连接
HEARTBEAT_SCAN_INTERVAL	60	心跳扫描间隔（秒）
AGENT_HEARTBEAT_TIMEOUT	120	心跳超时剔除阈值（秒）
DISPATCH_INTERVAL	2	调度循环间隔（秒）
TASK_TIMEOUT_CHECK_INTERVAL	5	任务超时检查间隔（秒）
DEFAULT_TASK_TIMEOUT	3600	任务默认超时（秒）
TASK_TTL	86400	任务数据保留 TTL（秒）