Gateway 概览¶

适用范围：独立 Python Runtime。 桌面端操作见 Desktop 使用指南。

Echo Agent Gateway 是基于 aiohttp 构建的 HTTP/WebSocket 网关服务器，负责将外部消息接入系统内部、管理会话生命周期、执行认证与速率限制，并将消息路由到各平台通道。

核心功能¶

功能	说明
外部消息接入	通过 HTTP POST 和 WebSocket 接收来自第三方系统的消息
会话生命周期管理	创建、恢复、重置、销毁会话
认证与速率限制	多模式认证 + 令牌桶限流
跨平台投递路由	根据目标平台自动选择投递通道
渐进式消息编辑	支持流式输出时的消息实时更新
健康监控	提供 `{api_prefix}/health` 端点（默认 `/api/v1/health`）用于健康探测

架构组成¶

GatewayServer 作为主协调器，编排以下子系统：

GatewayServer
├── Auth              # 认证模块（多模式）
├── RateLimiter       # 令牌桶速率限制器
├── DeliveryRouter    # 跨平台投递路由
├── ProgressiveEditor # 渐进式消息编辑
├── MediaCache        # 媒体文件缓存
├── SessionResetPolicy # 会话重置策略
└── HookRegistry      # 钩子注册表

子系统文件¶

文件	职责
`auth.py`	认证逻辑（open / allowlist / pairing 三种模式）
`router.py`	消息投递路由
`rate_limiter.py`	基于令牌桶的速率限制
`server.py`	aiohttp 应用初始化与路由注册
`health.py`	健康检查端点
`ws_session.py`	会话 WebSocket 的平台与会话键归一化
`ws_dashboard.py`	仪表盘 WebSocket（供监控面板连接）

API 模块¶

Gateway 在 gateway/api/ 目录下提供以下 REST API 模块：

analytics — 数据统计与分析
channels — 通道管理
config — 运行时配置只读查询
cron_api — 定时任务管理
knowledge — 知识库操作
logs — 日志查询
memory — 记忆存储
sessions — 会话 CRUD
skills — 技能管理
tasks — 异步任务队列

WebSocket 端点¶

端点	用途	协议
`/ws`（可配置）	CLI 与外部集成实时通信	JSON over WebSocket
`/ws/dashboard`	监控仪表盘实时数据推送	JSON over WebSocket

健康检查¶

GET /api/v1/health

健康状态不是 unhealthy 时返回 200，为 unhealthy 时返回 503；响应体为 JSON。可用作探针地址，具体探针策略应按部署环境设置。

速率限制¶

Gateway 使用令牌桶算法进行速率限制，按 platform + chat_id 粒度隔离：

默认限制：30 RPM（每分钟 30 次请求）
可通过配置文件调整
超限时返回 429 Too Many Requests

速率限制粒度

限流以 platform:chat_id 为 key，不同平台的同一用户分别计数。这意味着同一个用户在 Telegram 和 Web 上各自拥有独立的速率配额。

配置示例¶

gateway:
  enabled: true
  host: "0.0.0.0"
  port: 8090
  auth:
    mode: "allowlist"  # open | allowlist | pairing
    allowed_users: ["user1", "telegram:123456"]
    api_tokens: ["token-xxx"]
    admin_tokens: ["admin-xxx"]
    allowed_origins: ["https://my-dashboard.example.com"]
    allowed_hosts: ["my-dashboard.example.com"]

生产环境注意

在生产环境中务必将 auth.mode 设置为 allowlist 或 pairing，切勿使用 open 模式。同时请为 api_tokens 和 admin_tokens 使用足够长度的随机字符串。

默认监听地址¶

Gateway 默认监听 127.0.0.1:58123。端口用 gateway.port 配置，主机用 gateway.host；两者也可通过 ECHO_AGENT_GATEWAY__PORT、ECHO_AGENT_GATEWAY__HOST 环境变量覆盖（配置路径层级使用双下划线）。

gateway.port 设为 0 时由系统动态分配，实际端口写入 workspace/.echo-agent/gateway.json。

快速启动¶

可以单独以前台进程启动 Gateway，也可以将其注册为系统服务：

echo-agent gateway              # 前台启动
echo-agent gateway install      # 注册为后台常驻服务

echo-agent run 运行完整 Agent；配置 gateway.enabled: true 时，它也会启动 Gateway。echo-agent gateway 会在当前进程中启用 Gateway，无须在配置中预先设置 gateway.enabled。Gateway 运行后，可用 echo-agent cli 作为瘦客户端连接。

使用默认监听地址和 API 前缀时，访问 http://127.0.0.1:58123/api/v1/health 检查状态。