乐于分享
好东西不私藏

OpenHands 源码-API 路由设计与中间件

OpenHands 源码-API 路由设计与中间件

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-conversations1719 行会话 CRUD、发消息、SSE 流
event_router/conversation/{id}/events110 行事件查询、计数、批量获取
settings_router/settings696 行LLM 配置、Agent Profile
sandbox_router/sandboxes220 行沙箱生命周期管理
user_router/users58 行/me、/git-info
webhook_router/webhooks725 行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 result

Injector 模式的核心思想:

🔹 异步生成器:每个 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技术推荐官」获取更多源码解析内容

相关学习资料