模块以 register_*_routes(app, ...) 函数为统一挂载点(如 auth_routes.register_auth_routes、system_routes.register_system_routes),由宿主 api_server.py 在启动时调用并将自身通过 sys.modules['api_server'] 暴露给各路由子模块,形成「宿主持有依赖 → 路由模块按需解析」的反向依赖方向。
- 安全层:security.py 集中实现 CORS/DNS 重绑定防护、CSP/权限策略安全头、访问日志脱敏、SSE 一次性 ticket(内存 + 线程锁)、Bearer token 校验、loopback 信任判断以及 require_auth / require_event_stream_auth / require_settings_write_auth 等 FastAPI Depends 依赖。
- 共享状态:state.py 通过 _get_session_service() / _get_channel_runtime() 懒加载 SessionService、ChannelRuntime、MessageBus 等单例,避免未启用功能时的导入开销。
- 通用工具:helpers.py 提供 .env 原子写入、SPA deep-link 回退、路径参数白名单校验;models.py 定义跨路由共享的 Pydantic 响应模型;_compat.py 提供 host_attr / set_host_attr 供测试 monkeypatch api_server 上的配置。
- 业务路由按领域拆分文件:auth_routes(SSE ticket)、sessions_routes、runs_routes、channels_routes、qveris_routes、swarm_routes、live_routes、scheduled_routes、settings_routes、uploads_routes、alpha_routes、system_routes(健康检查、OpenAPI 文档、进程关闭、相关性计算)。每个文件仅注册路由,不直接持有全局状态,依赖通过 Depends、state 懒加载或 sys.modules 反向引用获取。