OpenHands 源码解析系列
第 14 讲:API 路由设计与中间件
基于 OpenHands 源码 · 2026-08-10
一、FastAPI 应用入口
OpenHands V1 的整个 Web 服务是一个 FastAPI 应用,入口在 openhands/app_server/app.py。这个文件只有 86 行,却包含了应用的完整骨架:
📄 openhands/app_server/app.py (第 54-86 行)
app = FastAPI(
title='OpenHands',
description='OpenHands: Code Less, Make More',
version=get_version(),
lifespan=combine_lifespans(*lifespans),
routes=[Mount(path='/mcp', app=mcp_app)],
)
@app.exception_handler(AuthenticationError)
async def authentication_error_handler(request: Request, exc: AuthenticationError):
return JSONResponse(
status_code=401,
content=str(exc),
)
app.include_router(v1_router.router)
app.include_router(health_router)
if os.getenv('SERVE_FRONTEND', 'true').lower() == 'true':
if os.path.isdir('./frontend/build'):
app.mount(
'/', SPAStaticFiles(directory='./frontend/build', html=True), name='dist'
)
app.add_middleware(LocalhostCORSMiddleware)
app.add_middleware(CacheControlMiddleware)
app.add_middleware(
RateLimitMiddleware,
rate_limiter=InMemoryRateLimiter(requests=10, seconds=1),
)关键设计点:
🔹 Lifespan 组合器:用 combine_lifespans() 把 MCP 服务和 AppLifespanService 的生命周期管理器串起来,通过 AsyncExitStack 实现嵌套的异步上下文管理
🔹 路由注册顺序:先注册 v1_router(所有 /api/v1/*),再注册 health_router(/alive、/health),最后挂载前端静态资源
🔹 中间件注册顺序:CORS → Cache-Control → Rate-Limit,注意 FastAPI 中间件是后进先出(LIFO),所以 Rate-Limit 最先执行
🔹 MCP 挂载:MCP 服务器通过 Mount(path='/mcp') 直接挂载到 FastAPI 根路由,独立于 v1 路由树
二、V1 路由聚合器
所有 API 路由统一挂在 /api/v1 前缀下。聚合器 v1_router.py 只做了路由组合,不写业务逻辑:
📄 openhands/app_server/v1_router.py (第 1-37 行,全文)
from fastapi import APIRouter
from openhands.app_server.app_conversation import app_conversation_router
from openhands.app_server.config_api.config_router import router as config_router
from openhands.app_server.event import event_router
from openhands.app_server.event_callback import webhook_router
from openhands.app_server.git.git_router import router as git_router
from openhands.app_server.pending_messages.pending_message_router import (
router as pending_message_router,
)
from openhands.app_server.sandbox import sandbox_router, sandbox_spec_router
from openhands.app_server.secrets.secrets_router import (
router as secrets_router,
)
from openhands.app_server.settings.settings_router import (
router as settings_router,
)
from openhands.app_server.user import skills_router, user_router
from openhands.app_server.web_client import web_client_router
# Include routers
router = APIRouter(prefix='/api/v1')
router.include_router(event_router.router)
router.include_router(app_conversation_router.router)
router.include_router(pending_message_router)
router.include_router(sandbox_router.router)
router.include_router(sandbox_spec_router.router)
router.include_router(settings_router)
router.include_router(secrets_router)
router.include_router(user_router.router)
router.include_router(skills_router.router)
router.include_router(webhook_router.router)
router.include_router(web_client_router.router)
router.include_router(git_router)
router.include_router(config_router)13 个子路由模块,按功能域划分:
| 路由模块 | 前缀 | 行数 | 职责 |
|---|---|---|---|
| app_conversation_router | /app-conversations | 1719 行 | 会话 CRUD、发消息、SSE 流 |
| event_router | /conversation/{id}/events | 110 行 | 事件查询、计数、批量获取 |
| settings_router | /settings | 696 行 | LLM 配置、Agent Profile |
| sandbox_router | /sandboxes | 220 行 | 沙箱生命周期管理 |
| user_router | /users | 58 行 | /me、/git-info |
| webhook_router | /webhooks | 725 行 | Webhook 回调、事件处理 |
| status_router | (无前缀) | 47 行 | /alive、/health、/ready |
设计模式:每个路由模块独立管理自己的前缀、标签和依赖,v1_router 只负责组合。这遵循了 FastAPI 推荐的模块化路由模式。
三、三层中间件架构
OpenHands 的中间件链定义在 openhands/app_server/middleware.py,共 141 行,包含三个核心中间件和一个限流器:
3.1 LocalhostCORSMiddleware — 智能 CORS
📄 openhands/app_server/middleware.py (第 21-56 行)
class LocalhostCORSMiddleware(CORSMiddleware):
"""Custom CORS middleware that allows any request from localhost/127.0.0.1 domains,
while using standard CORS rules for other origins.
"""
def __init__(self, app: ASGIApp) -> None:
config = get_global_config()
allow_origins = tuple(config.permitted_cors_origins)
super().__init__(
app,
allow_origins=allow_origins,
allow_credentials=True,
allow_methods=['*'],
allow_headers=['*'],
)
def is_allowed_origin(self, origin: str) -> bool:
if origin and not self.allow_origins and not self.allow_origin_regex:
parsed = urlparse(origin)
hostname = parsed.hostname or ''
# Allow any localhost/127.0.0.1 origin regardless of port
if hostname in ['localhost', '127.0.0.1']:
return True
# Allow any origin when no specific origins are configured (dev mode)
logging.getLogger(__name__).warning(
f'No CORS origins configured, allowing origin: {origin}. '
'Set OH_PERMITTED_CORS_ORIGINS for production environments.'
)
return True
result: bool = super().is_allowed_origin(origin)
return result三阶段判断逻辑:
🔹 开发友好:localhost/127.0.0.1 无条件放行(任何端口),方便本地开发
🔹 零配置宽容:如果未配置 OH_PERMITTED_CORS_ORIGINS,允许所有来源(但打 WARNING 日志提醒)
🔹 生产严格:配置了 CORS 白名单后,回退到 FastAPI 原生 CORS 校验
3.2 CacheControlMiddleware — 差异化缓存策略
📄 openhands/app_server/middleware.py (第 59-75 行)
class CacheControlMiddleware(BaseHTTPMiddleware):
async def dispatch(
self, request: Request, call_next: RequestResponseEndpoint
) -> Response:
response = await call_next(request)
if request.url.path.startswith('/assets'):
# Fingerprinted filenames → aggressive caching
response.headers['Cache-Control'] = 'public, max-age=2592000, immutable'
else:
response.headers['Cache-Control'] = (
'no-cache, no-store, must-revalidate, max-age=0'
)
response.headers['Pragma'] = 'no-cache'
response.headers['Expires'] = '0'
return response两条策略:
🔹 /assets/*:文件带 hash 指纹(如 main.a3f2e1.js),缓存 30 天 + immutable,浏览器不会重新请求
🔹 其他路径:三重保险(Cache-Control + Pragma + Expires),确保 API 响应不被浏览器或 CDN 缓存
3.3 RateLimitMiddleware + InMemoryRateLimiter — 内存限流
📄 openhands/app_server/middleware.py (第 78-141 行)
class InMemoryRateLimiter:
def __init__(self, requests: int = 2, seconds: int = 1, sleep_seconds: int = 1):
self.requests = requests
self.seconds = seconds
self.sleep_seconds = sleep_seconds
self.history = defaultdict(list)
async def __call__(self, request: Request) -> bool:
key = request.client.host if request.client else 'unknown'
now = datetime.now()
self._clean_old_requests(key)
self.history[key].append(now)
if len(self.history[key]) > self.requests * 2:
return False
elif len(self.history[key]) > self.requests:
if self.sleep_seconds > 0:
await asyncio.sleep(self.sleep_seconds)
return True
else:
return False
return True
class RateLimitMiddleware(BaseHTTPMiddleware):
def is_rate_limited_request(self, request: StarletteRequest) -> bool:
return not (
request.url.path.startswith('/assets')
or self._is_sandbox_resume_request(request)
)
def _is_sandbox_resume_request(self, request: StarletteRequest) -> bool:
return request.method == 'POST' and bool(_RESUME_RE.match(request.url.path))
# _RESUME_RE = re.compile(r'^/api/v1/sandboxes/[^/]+/resume/?$')限流策略详解:
🔹 按 IP 限流:key 是 request.client.host,每个 IP 独立计数
🔹 两档响应:超过 requests 次先 sleep 再放行(软限流),超过 requests * 2 次直接 429(硬限流)
🔹 默认参数:10 次/秒,超过 10 次 sleep 1 秒,超过 20 次 429
🔹 豁免路径:/assets/* 和沙箱 resume 接口不受限流(避免阻塞恢复流程)
四、依赖注入系统
OpenHands 没有用传统的 FastAPI Depends 做全局 DI,而是自建了一套基于 Injector 抽象的注入框架:
📄 openhands/app_server/services/injector.py (全文 34 行)
class Injector(Generic[T], ABC):
"""Object designed to facilitate dependency injection"""
@abstractmethod
async def inject(
self, state: InjectorState, request: Request | None = None
) -> AsyncGenerator[T, None]:
"""Inject an object. The state object may be used to store variables for
reuse by other injectors, as injection operations may be nested."""
yield None
@contextlib.asynccontextmanager
async def context(
self, state: InjectorState, request: Request | None = None
) -> AsyncGenerator[T, None]:
"""Context function suitable for use in async with clauses"""
async for result in self.inject(state, request):
yield result
async def depends(self, request: Request) -> AsyncGenerator[T, None]:
"""Depends function suitable for use with FastAPI dependency injection."""
async for result in self.inject(request.state, request):
yield resultInjector 模式的核心思想:
🔹 异步生成器:每个 Injector 返回 AsyncGenerator,天然支持"设置 → 使用 → 清理"生命周期
🔹 共享状态:InjectorState 就是 Starlette 的 State 对象,挂载在 request.state 上,多个 Injector 可以互相复用资源
🔹 两种使用方式:context() 用于 async with,depends() 用于 FastAPI 的 Depends()
全局配置 AppServerConfig 持有所有 Injector 的引用:
📄 openhands/app_server/config.py (第 214-237 行)
class AppServerConfig(OpenHandsModel):
# Dependency Injection Injectors
llm_model: LLMModelServiceInjector | None = None
event: EventServiceInjector | None = None
event_callback: EventCallbackServiceInjector | None = None
sandbox: SandboxServiceInjector | None = None
sandbox_spec: SandboxSpecServiceInjector | None = None
app_conversation_info: AppConversationInfoServiceInjector | None = None
app_conversation: AppConversationServiceInjector | None = None
pending_message: PendingMessageServiceInjector | None = None
user: UserContextInjector | None = None
jwt: JwtServiceInjector | None = None
httpx: HttpxClientInjector = Field(default_factory=HttpxClientInjector)
db_session: DbSessionInjector = Field(default_factory=DbSessionInjector)
lifespan: AppLifespanService | None = Field(default_factory=_get_default_lifespan)
app_mode: AppMode = AppMode.OPENHANDS环境变量决定具体实现。例如事件服务有三种后端可选:
📄 openhands/app_server/config.py (第 307-327 行)
if config.event is None:
provider = get_storage_provider()
if provider == StorageProvider.AWS:
config.event = AwsEventServiceInjector(bucket_name=bucket_name)
elif provider == StorageProvider.GCP:
config.event = GoogleCloudEventServiceInjector(bucket_name=bucket_name)
else:
config.event = FilesystemEventServiceInjector()五、认证与路由保护
每个路由模块通过 get_dependencies() 声明认证需求:
📄 openhands/app_server/utils/dependencies.py (全文 32 行)
_SESSION_API_KEY = os.getenv('SESSION_API_KEY')
_SESSION_API_KEY_HEADER = APIKeyHeader(name='X-Session-API-Key', auto_error=False)
def check_session_api_key(
session_api_key: str | None = Depends(_SESSION_API_KEY_HEADER),
):
if session_api_key != _SESSION_API_KEY:
raise HTTPException(status.HTTP_401_UNAUTHORIZED)
def get_dependencies() -> list[Depends]:
result = []
if _SESSION_API_KEY:
result.append(Depends(check_session_api_key))
elif get_global_config().app_mode == AppMode.SAAS:
result.append(Depends(APIKeyHeader(name='X-Access-Token', auto_error=False)))
return result两种认证模式:
🔹 自托管模式:设置 SESSION_API_KEY 环境变量后,所有请求必须携带匹配的 X-Session-API-Key 头
🔹 SaaS 模式:OpenAPI 文档显示 X-Access-Token 要求,但实际认证由 Cookie 中间件处理(auto_error=False 不会拦截请求)
用户认证抽象在 UserAuth 基类中:
📄 openhands/app_server/user_auth/user_auth.py (第 35-48 行)
class UserAuth(ABC):
"""Abstract base class for user authentication.
This is an extension point in OpenHands that allows applications to provide their own
authentication mechanisms. Applications can substitute their own implementation by:
1. Creating a class that inherits from UserAuth
2. Implementing all required methods
3. Setting server_config.user_auth_class to the fully qualified name of the class
"""
@abstractmethod
async def get_user_id(self) -> str | None:
@abstractmethod
async def get_user_email(self) -> str | None:
@abstractmethod
async def get_access_token(self) -> SecretStr | None:
@abstractmethod
async def get_provider_tokens(self) -> PROVIDER_TOKEN_TYPE | None:
@abstractmethod
async def get_user_settings_store(self) -> SettingsStore:
@abstractmethod
async def get_secrets_store(self) -> SecretsStore:
@abstractmethod
async def get_secrets(self) -> Secrets | None:六、异常处理体系
自定义异常类继承自 FastAPI 的 HTTPException,按业务域分层:
📄 openhands/app_server/errors.py (全文 62 行)
class OpenHandsError(HTTPException):
"""General Error"""
def __init__(self, detail=None, headers=None,
status_code=HTTP_500_INTERNAL_SERVER_ERROR): ...
class AuthError(OpenHandsError):
"""Error in authentication."""
def __init__(self, detail=None, headers=None,
status_code=HTTP_401_UNAUTHORIZED): ...
class PermissionsError(OpenHandsError):
"""Error in permissions."""
def __init__(self, detail=None, headers=None,
status_code=HTTP_403_FORBIDDEN): ...
class SandboxError(OpenHandsError): ...
class SandboxDeleteRetryError(OpenHandsError):
"""The sandbox exists but its delete could not complete and was kept for retry.
503 (vs 404) so a client distinguishes 'still here, try again' from 'not found'"""
def __init__(self, detail=None, headers=None,
status_code=HTTP_503_SERVICE_UNAVAILABLE): ...设计亮点:
🔹 503 vs 404 语义区分:SandboxDeleteRetryError 用 503 而非 404,告诉客户端"资源还在但操作失败,请重试",而非"资源不存在"
🔹 默认状态码:每个子类有合理的默认 HTTP 状态码,调用方可以覆盖
🔹 全局 handler:app.py 额外注册了 AuthenticationError 的 handler,返回 401 + 错误信息
七、健康检查与状态端点
独立于 v1 路由树,直接挂载到 FastAPI 根:
📄 openhands/app_server/status/status_router.py (全文 47 行)
router = APIRouter(tags=['Status'])
@router.get('/alive')
async def alive():
"""Endpoint for liveness probes.
If this responds then the server is considered alive."""
return {'status': 'ok'}
@router.get('/health')
async def health() -> str:
"""Health check endpoint. Used by load balancers and orchestrators."""
return 'OK'
@router.get('/ready')
async def ready() -> str:
"""Endpoint for readiness probes."""
return 'OK'
@router.get('/server_info')
async def get_server_info():
"""Returns system info: CPU count, memory usage, runtime details."""
return get_system_info()Kubernetes 就绪:四个端点分别对应 K8s 的 liveness probe、readiness probe 和自定义监控,无需认证即可访问。
八、架构总结
OpenHands V1 API 路由架构
请求进入
│
├─ RateLimitMiddleware (10 req/s, IP-based)
│ ├─ /assets/* → 豁免
│ ├─ /sandboxes/{id}/resume → 豁免
│ └─ 其他 → 软限流(sleep) / 硬限流(429)
│
├─ CacheControlMiddleware
│ ├─ /assets/* → max-age=2592000, immutable
│ └─ 其他 → no-cache, no-store
│
├─ LocalhostCORSMiddleware
│ ├─ localhost/127.0.0.1 → 放行
│ ├─ 无配置 → 放行(打 WARNING)
│ └─ 有配置 → 白名单校验
│
├─ /mcp/* → MCP HTTP 服务器
├─ /alive, /health, /ready, /server_info → 健康检查
│
├─ /api/v1/* (v1_router)
│ ├─ /app-conversations → 1719 行核心路由
│ ├─ /conversation/{id}/events → 事件查询
│ ├─ /settings → LLM 配置、Agent Profile
│ ├─ /sandboxes → 沙箱管理
│ ├─ /users → 用户信息
│ ├─ /webhooks → Webhook 回调
│ ├─ /secrets → 密钥管理
│ ├─ /git → Git 集成
│ └─ /config → 服务端配置
│
└─ /* → SPAStaticFiles (前端)
依赖注入: Injector → request.state 共享
认证: SESSION_API_KEY 或 Cookie + JWT
异常: OpenHandsError → AuthError / PermissionsError / SandboxError关键设计原则:
🔹 路由与逻辑分离:v1_router 只做组合,每个子路由管理自己的端点
🔹 中间件关注点分离:CORS、缓存、限流各管一层,互不干扰
🔹 DI 统一入口:AppServerConfig 持有所有 Injector,环境变量决定具体实现
🔹 认证可插拔:UserAuth 抽象 + get_impl 动态加载,支持自托管/SaaS 双模式
📚 系列导航
← 第 13 讲:数据库设计与 ORM 层
→ 第 15 讲:错误处理与日志系统
关注公众号「AI技术推荐官」获取更多源码解析内容
夜雨聆风