Gateway — 纯透传代理

设计原则

• 纯透传：不解析/修改 request body
• 不修改响应：原样转发上游响应
• 仅替换 Authorization：用户 JWT → 引擎 API Key
• URL 透明：保留路径和查询参数

实现

@router.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "PATCH"])
async def proxy(request, path):
    upstream = f"{engine_upstream_url}/{path}?{query}"
    # 转发 body、headers（替换 Authorization）
    # 根据 content-type 判断流式/非流式

环境变量

变量	默认值	说明
UA_ENGINE_UPSTREAM_URL	http://engine-hermes-test:8642	上游引擎地址
UA_API_SERVER_KEY	ua-engine-dev-key	引擎认证 Key
UA_JWT_SECRET	(开发密钥)	保留字段

多 Profile 路由

• 独立运行实例（standard）：按 X-Hermes-Profile 头路由（nginx 端口映射）
• 共享运行实例（multiplex）：路径前缀路由——统一接口路径前加 /p/{profile}/ 转发到引擎单进程（X-Hermes-Profile 头双写保留一个迭代）；实例模式读自 agent_instances.runtime_config.isolation_mode，缺省 standard，存量实例零迁移
• IM 渠道（dispatcher 直连引擎）三处 URL（会话重置 / 消息转发 / 流式转发）按实例形态同样加前缀

流式处理

网关对外提供两个流式出口，按路径分流：

• POST /v1/runs（含 /v1/runs/{id}/events）→ 统一 VES 事件流（Veyra Event Stream）： hermes 经 runs 事件转换器，消息式引擎（CC/DeepSeek/OpenClaw/Dify）由网关合成 run 后经 通用映射器归一。门户与需要完整过程的调用方只消费这一种协议
• POST /v1/chat/completions → OpenAI chunk 流：引擎私有帧（工具进度、Dify 事件等）由 openai_surface 清洗掉，对外与 OpenAI SDK 及生态工具兼容
• 常规 JSON → 标准 Response（非流式响应保持引擎原生格式）
• 捕获 ReadError/RemoteProtocolError 优雅处理上游断连