OpenSandbox 生命周期服务器Lifecycle Server架构与开发指南FastAPI 控制面的分层设计、关键路径与协作规范【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandboxOpenSandbox 是一个面向 AI Agent 的安全沙箱运行时项目。其核心控制面是位于 server/ 目录下的生命周期服务器Lifecycle Server一个基于 FastAPI 的沙箱生命周期管理服务负责协调不受信任负载的创建、执行、暂停、恢复与销毁并同时集成 Docker 与 Kubernetes 两种运行时后端。本文以 server/AGENTS.md 为骨架结合仓库源码逐层拆解该服务的设计原则、目录职责、开发命令与代码协作护栏帮助读者快速理解这套路由薄、逻辑后置的架构并掌握在该模块内进行安全、规范开发的方法。一、模块定位与开发范围Scopeserver/AGENTS.md 首先明确了生命周期服务器在 monorepo 中的边界该文档覆盖opensandbox_server/**、tests/**、configuration.md与docker-compose.example.yaml。也就是说凡是涉及生命周期服务器行为、沙箱创建流程、或用户可见的服务器配置的改动都应先阅读本文档。同时文档给出了两条跨域路由规则specs 契约变更需先阅读根目录 AGENTS.md 与 specs/AGENTS.md。公开的 OpenAPI 契约以specs/下的文件如 specs/sandbox-lifecycle.yml为唯一事实来源source of truth。Kubernetes 运行时相关需阅读 kubernetes/AGENTS.md因为 K8s 运行时涉及 CRD、控制器与 Helm 部署等多层联动。这一范围划分与仓库根 AGENTS.md 的Routing规则完全一致对server/**或生命周期服务器行为的改动优先阅读 server 级文档跨切面spec、server、SDK 同时变更的改动则从 specs 级文档开始。二、关键路径导览从入口到持久化server/AGENTS.md 用一张表概括了服务内部的核心目录与职责。结合源码我们可以把这张表映射到真实的调用链上路径职责源码佐证opensandbox_server/cli.pyCLI 入口、配置初始化基于argparse提供--config参数支持example.config.toml、example.config.k8s.toml等示例文件映射见 cli.pyopensandbox_server/main.pyFastAPI 应用入口、启动装配定义 lifespan 启动/关闭流程、中间件链、路由注册与统一错误处理见 main.pyopensandbox_server/config.pyTOML 配置模型、默认值、校验定义AppConfig及ServerConfig、RuntimeConfig、DockerConfig、KubernetesRuntimeConfig等嵌套模型opensandbox_server/api/路由与请求/响应 Schema包含lifecycle.py、devops.py、pool.py、proxy.py、network_policy.py、templates.py、metrics.py、schema.pyopensandbox_server/services/业务逻辑与运行时集成sandbox_service.py、snapshot_service.py、runtime_resolver.py、validators.py、factory.py等opensandbox_server/services/docker/Docker 运行时端点、端口、诊断、快照docker_service.py、port_allocator.py、runtime.py、snapshot_runtime.py、docker_diagnostics.py、ossfs_mixin.py、windows_profile.pyopensandbox_server/services/k8s/K8s providers、模板、informer、egress、池、暂停/恢复与kubernetes/控制器协同opensandbox_server/repositories/持久化后端、快照元数据snapshots/factory.py、snapshots/sqlite.py、snapshots/postgresql.py、snapshots/migrate.pyopensandbox_server/integrations/可选外部集成如 OpenTelemetryotel.py、renew-intent 消费者renew_intent/opensandbox_server/extensions/扩展加载与行为钩子codec.py、keys.py、validation.py由services/extension_service.py统一管理opensandbox_server/middleware/认证与请求中间件auth.py、date_header.py、http_metrics.py、request_id.pytests/单元、集成、冒烟、K8s 测试覆盖test_docker_service.py、test_routes_*.py、test_snapshot_*.py及tests/k8s/子目录入口装配main.py 的启动流程main.py 是理解整个服务装配顺序的最佳入口。其关键设计点包括配置先行模块级先执行load_config()、configure_logging()与validate_tenant_config()再初始化路由器与中间件main.py。lifespan 生命周期启动时执行 API Key 确认、租户命名空间校验K8s 后端、线程池大小设置、安全运行时校验、renew-intent 消费者启动与 OTel 指标初始化关闭时逆序清理main.py。中间件顺序敏感DateHeaderMiddleware包裹完整栈AuthMiddleware与 CORS 先注册RequestIdMiddleware保证包括 401 在内的所有响应都带X-Request-IDHttpMetricsMiddleware作为最外层用户中间件以覆盖认证失败等早期响应。路由注册顺序有讲究注释明确要求非 proxy 路由必须先于proxy_router注册因为 proxy 路由包含 catch-all 规则会吞掉诊断路径main.py。统一错误 Schema通过全局异常处理器将 HTTP 错误规范化为{code: ..., message: ...}结构main.py。版本双轨制GET /version返回包版本来自 installed metadata而/openapi.json中的info.version是 API契约版本当前为0.1.0必须与 specs/sandbox-lifecycle.yml 保持同步。三、开发命令uv 驱动的工作流server/AGENTS.md 给出了完整的开发命令集基于uv包管理器pyproject.toml 定义了项目依赖与分组cd server uv sync --all-groups # 安装全部依赖组含 lint/type-check/test 工具 uv run ruff check # 代码风格与静态检查 uv run pytest tests/test_docker_service.py # 运行聚焦的 Docker 服务测试 uv run pytest tests/k8s # 运行 K8s 相关测试 uv run pyright # 类型检查 uv run pytest # 运行完整测试套件使用建议聚焦优先根 AGENTS.md 的 Guardrails 明确Prefer file-scoped or package-scoped checks before full-suite validation优先做文件级/包级检查再跑全量套件。因此日常迭代用uv run pytest tests/test_docker_service.py这类聚焦命令提交前再跑uv run pytest全量回归。类型检查是硬性要求项目启用了py.typeduv run pyright是质量门禁之一。测试即文档tests/下既有点级单元测试如test_docker_service.py、test_snapshot_models.py也有tests/k8s/的 K8s 集成测试与smoke.sh冒烟脚本是理解各服务行为最直接的可执行证据。四、分层架构原则路由薄、逻辑后置server/AGENTS.md 用一句话概括了服务的核心架构哲学Routes thin — logic in services/validators/repositories/runtime helpers路由保持轻薄逻辑落在 services/validators/repositories/runtime helpers 中。对照源码这条原则在三个层面落地路由层api/只做编排api/lifecycle.py等模块只负责参数解析、调用服务、返回响应具体业务判断如沙箱状态机、快照协调全部委托给services/层。运行时差异隔离在 docker/k8s 模块services/docker/与services/k8s/是两个并行的运行时实现通过services/runtime_resolver.py与services/factory.py根据配置的runtime.typedocker或kubernetes动态选择。这样上层 API 不必感知底层是容器还是 Pod。持久化独立成层repositories/封装 SQLite 与 PostgreSQL 两种快照元数据后端通过snapshots/factory.py统一创建配合snapshots/migrate.py完成迁移。这种分层的直接收益是任何一处行为变更都可以定位到唯一的归属层——改路由格式找api/改业务规则找services/改存储找repositories/改运行时行为找services/docker/或services/k8s/。五、协作护栏Always / Ask first / Neverserver/AGENTS.md 定义了三条协作护栏是参与该模块开发的行为红线Always必须遵守路由保持轻薄业务逻辑不得进入 route handler。运行时特有逻辑放 docker/k8s 模块不要把仅适用于 Docker 的逻辑默认当成 K8s 路径也安全。快照状态跨层协调快照的创建、暂停/恢复、元数据持久化需要在 services、repositories 与运行时模块之间协同改动时不得只改单层。配置默认值/示例/文档保持对齐改动 config.py 时必须同步更新 configuration.md、opensandbox_server/examples/下的示例 TOML 与 docker-compose.example.yaml。扩展既有 fixtures测试尽量复用tests/conftest.py中的现有 fixture而不是另起炉灶。每次修复都要带回归测试行为变更必须有测试守护。Ask first改动前先征询以下改动影响面大、兼容性风险高必须先沟通再动手删除或重命名端点影响 SDK 与外部调用方配置结构变更如 config.py 中模型的字段调整引入新的外部依赖快照 / 暂停恢复 / egress / 池pool语义的变更。Never绝对禁止route handler 中写业务逻辑无测试的行为变更假设Docker 下没问题就等于 K8s 路径安全——两条运行时路径必须分别验证tests/与tests/k8s/的测试分离正是为此设计。六、跨模块协作与文档治理server/AGENTS.md 还提醒开发者关注两个跨模块协作点specs 即契约specs/sandbox-lifecycle.yml是沙箱生命周期 API 的公开契约。服务器实现、SDK 客户端、文档示例必须与契约保持一致修改specs/时要同步更新或校验受影响的 server、SDK 与 release 产物。K8s 联动K8s 后端的很多能力CRD、控制器、task-executor、Helm charts在kubernetes/目录实现服务器侧的services/k8s/仅是消费方。改动跨域功能如 pause/resume 快照、池调度时需同时阅读 kubernetes/AGENTS.md。这种就近 AGENTS.md 全局根 AGENTS.md的多级路由机制保证了 monorepo 中任何改动都能快速找到正确的上下文来源——这也是整个 OpenSandbox 仓库server、execd、egress、ingress、SDKs、specs、kubernetes、cli 八大模块得以并行演进的基础设施。七、小结server/AGENTS.md 虽是一份面向开发者的协作指引但其中蕴含的信息远超流程规范本身它实际上是对生命周期服务器架构设计的最精炼书面总结——路由薄、逻辑后置的分层哲学、docker/k8s 双运行时隔离、快照状态跨层协调、配置三处对齐config.py / configuration.md / examples以及围绕uv的完整开发闭环。配合 main.py 的启动装配、config.py 的配置模型与 configuration.md 的参数参考开发者可以快速从知道改哪里进阶到知道为什么这么改、以及如何安全地改。如果你正打算为 OpenSandbox 贡献代码或二次开发建议的阅读路径是先读根 AGENTS.md 了解仓库全局 → 再读本文档掌握服务器模块的边界与护栏 → 用uv sync --all-groups uv run pytest跑通环境 → 从tests/test_docker_service.py这类聚焦测试入手沿着路由 → 服务 → 运行时 → 存储的调用链逐步深入。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考