本文回答什么问题:nanobot gateway 是怎么启动的?WebSocket 通道怎么和 AgentLoop 通信?HTTP 健康检查和静态资源怎么挂载?目标读者:想部署 / 自定义 WebUI 的开发者预计阅读时间:12 分钟源码版本:GitHub HKUDS/nanobotmain 分支主线代码(仓库相对路径)nanobot gateway是长跑进程,把 WebUI / 17 通道 / AgentLoop 串起来。本章聚焦 gateway 的 4 大职责:启动 / WebSocket / 健康检查 / 静态分发。1. 整体定位:为什么需要 Gateway单次nanobot chat用完即退出,但 web / Telegram / Discord 需要长跑 多连接。Gateway 解决:单进程服务多个客户端(WebSocket 多通道)健康检查(LB / k8s readiness probe)静态资源(WebUI 前端打包后由 gateway 托管)核心要点速查(建议收藏)核心文件:nanobot/gateway/runtime.py(gateway 启动 ~200 行)nanobot/gateway/protocol.py(WebSocket 协议 ~150 行)nanobot/web/server.py(HTTP server)4 大职责:启动 AgentLoop 启动 ChannelManager WebSocket 路由 HTTP 静态WebSocket 路径:/ws(WebUI 入口,详见第 24 章)健康端点:/health(返回{status: ok, uptime_seconds: ...})静态资源:/webui/(Vue 3 打包产物)默认端口:8720(-p/--port可改)2. gateway 启动流程(gateway/runtime.py)asyncdefrun_gateway(host:str,port:int,workspace:Path|None):# 1. 加载 Configconfigload_config()# 2. 创建共享 MessageBus(单例)busget_bus()# 3. 构造 AgentLoop(用 bus)loopAgentLoop(busbus,configconfig)# 4. 构造 ChannelManager(用 bus)channelsChannelManager(busbus)awaitchannels.start_all()# 自发现 17 通道# 5. 启动 HTTP WebSocket serverserverHTTPServer(hosthost,portport,looploop,channelschannels)awaitserver.serve_forever()3 个核心单例:Config MessageBus AgentLoop;多通道共享三者。3. WebSocket 协议(gateway/protocol.py)# gateway/protocol.py 简化asyncdefhandle_websocket(ws:WebSocket,loop:AgentLoop):每条 WebSocket 连接 一个独立 asyncio task。awaitws.accept()channelwebsocketsender_idws.headers.get(x-client-id,anonymous)asyncformsginws.iter_text():datajson.loads(msg)# 客户端发 InboundMessageinboundInboundMessage(channelchannel,sender_idsender_id,chat_iddata[chat_id],contentdata[content],)awaitloop.bus.publish_inbound(inbound)# 订阅 outboundasyncforoutinloop.bus.subscribe_outbound(channel):awaitws.send_json({content:out.content,event:out.event.type})关键设计:每条 WebSocket 一个 taskWebSocket 实现一个Channel子类(详见第 24 章)客户端用chat_id标识 session,断线重连不丢历史4. HTTP 路由(web/server.py)appFastAPI()app.get(/health)asyncdefhealth():return{status:ok,uptime_seconds:time.monotonic()-start_time}app.websocket(/ws)asyncdefws_endpoint(websocket:WebSocket):awaithandle_websocket(websocket,looploop)# 静态资源(WebUI 打包产物)app.mount(/,StaticFiles(directorywebui/dist,htmlTrue))3 个端点:/health(健康检查)、/ws(WebSocket)、/(其他)(WebUI 静态)。5. 4 大职责职责文件关键逻辑启动 AgentLoopgateway/runtime.pyloop AgentLoop(bus, config)启动 ChannelManagergateway/runtime.pychannels.start_all()自发现WebSocket 路由gateway/protocol.py每连接 1 task 订阅 outboundHTTP 静态web/server.pyFastAPI StaticFiles6. 实战:部署 gateway# 启动nanobot gateway--host0.0.0.0--port8720# systemd(写入 /etc/systemd/system/nanobot.service)[Unit]Descriptionnanobot gatewayAfternetwork.target[Service]TypesimpleUsernanobotExecStart/usr/local/bin/nanobot gateway--host0.0.0.0--port8720Restarton-failure[Install]WantedBymulti-user.targetsudosystemctlenablenanobotsudosystemctl start nanobot7. 常见问题 / 避坑Q:端口冲突怎么办?A:nanobot gateway --port18720改端口;WebUI 默认指向 8720,需要webui/.env同步改。Q:WebUI 连接失败?A:/health先验证 gateway 起来了;再检查 WebSocket 路径(/ws)。Q:多 channel 同时跑会抢 inbound?A:MessageBus 是单实例 FIFO,所有 channel 走同一队列,不会抢——按 publish 顺序处理。8. 小结4 大职责:启动 AgentLoop 启动 ChannelManager WebSocket HTTP关键模块:3 个端点:/health//ws//(静态)设计要点**:单例共享:Config MessageBus AgentLoop常见坑**:端口:默认 8720,可改本文要点速查gateway/runtime.py是入口,5 行构造 5 个核心单例gateway/protocol.py是 WebSocket 协议,每连接 1 taskweb/server.py是 HTTP 静态,FastAPI 实现下一步:第 10 章《AgentLoop 编排核心》—— AgentLoop 的 6 阶段流水线源码拆解按角色推荐系统架构师:必读(部署 健康检查必读)LLM Agent 开发者:选读(知道 AgentLoop 怎么被构造即可)聊天通道开发者:选读(知道 ChannelManager.start_all() 即可)Tool / MCP 工具开发者:选读下一步第 10 章《AgentLoop 编排核心》—— 6 阶段流水线源码拆解(主题群Agent 核心,第 3 周)第 24 章《WebSocket 通道》—— gateway 里 ws_endpoint 的 Channel 实现细节(主题群聊天通道,第 4 周)tags:#nanobot#AI Agent#LLM#Python#源码解析#WebUI#Gateway#FastAPI