DB-GPT Sandbox 使用指南：多运行时自动选择与沙箱 API 服务快速启动

DB-GPT Sandbox 使用指南：多运行时自动选择与沙箱 API 服务快速启动

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

DB-GPT Sandbox 是为 DB-GPT Agent 提供安全隔离代码执行环境的核心组件，支持 Docker、Podman、Nerdctl 与本地进程四种运行时，并能在同一会话内保持有状态环境（如首次安装的依赖在后续执行中可用）。本文以官方使用文档（packages/dbgpt-sandbox/src/docs/usage.md）为主线，结合仓库源码深入讲解环境准备、运行时自动选择机制、一键启动脚本与对外 API 接口，帮助读者快速将沙箱跑起来并理解其内部实现原理。

一、环境准备

沙箱本体以 Python 实现，对外暴露 FastAPI 服务，对环境要求如下：

• Python 3.8+：沙箱 API 服务运行的基础环境；仓库内启动脚本实际按 Python 3.10+ 做了显式检查（见 start_api.sh 中的错误提示 "Please install Python 3.10+"），建议直接使用 Python 3.10 及以上版本以避免兼容问题。
• 容器后端（可选但强烈推荐）：Docker / Podman / Nerdctl，三者至少安装其一。容器运行时提供真正的进程隔离，是生产与安全敏感场景的首选。
• 本地运行时（Local）：不做容器隔离，直接在宿主机执行，适合无容器环境下的回退或开发调试，但需要显式开启（下文详述）。

针对不同操作系统，官方建议如下：

在动手前可以先通过python3 --version、docker info（或podman info/nerdctl info）确认 Python 与容器后端均已就绪。需要特别说明的是，沙箱的"本地运行时不做容器隔离，适合无容器环境的回退/开发调试"这一设计，意味着它不应被用于隔离不可信代码的生产场景。

二、架构速览：四层设计的沙箱

在启动服务之前，理解沙箱的分层结构有助于正确使用其接口。根据 architecture.md 与源码目录结构，dbgpt-sandbox 采用四层设计：

• 用户层（user_layer）：service.py 与 schemas.py 对外提供统一的 API 调度，面向产品接口。
• 控制层（control_layer）：control_layer.py 负责跨任务会话管理、依赖安装、执行调度与状态查询。
• 执行层（execution_layer）：包含 base.py（统一抽象SandboxRuntime、SandboxSession、ExecutionResult、SessionConfig）、runtime_factory.py（自动选择运行时）以及 docker / podman / nerdctl / local 四个具体运行时实现。
• 展示层（display_layer）：display_layer.py 提供DisplayResult，用于容器型运行时的结果封装（包含 GUI、文件等）。

图注：dbgpt-sandbox 分层架构图，展示用户层、控制层、执行层、展示层之间的任务流转与结果回传路径。

需要注意的是：LocalRuntime.execute返回ExecutionResult，而容器运行时返回DisplayResult。若需在控制层统一结果，可在控制层将DisplayResult映射为ExecutionResult，或在 API 层做多态支持（见 architecture.md）。

三、运行时自动选择机制

沙箱启动时会根据本机环境自动选择一个最佳运行时，该逻辑由 runtime_factory.py 中的RuntimeFactory.create()实现：

1. 显式指定优先：若环境变量SANDBOX_RUNTIME已设置（或传入runtime_preference参数），则将其作为强制选择值，并校验对应运行时是否可用。
2. 自动探测兜底：未显式指定时，按Docker → Podman → Nerdctl → Local的优先级自动探测。其中 Docker 路径会先通过docker.from_env()建立客户端并调用client.info()确认守护进程实际可用，Podman / Nerdctl 则通过shutil.which()检查 CLI 是否在 PATH 中（见 utils.py 的EnvironmentDetector）。
3. 失败即关闭（fail-closed）：若没有任何容器运行时可用，且未显式开启本地运行时，会抛出RuntimeError("No container sandbox runtime is available...")，而不是悄悄退回不可靠的执行方式。

环境变量与强制指定

在 config.py 中，运行时选择由两个常量控制，均可通过环境变量覆盖：

本地运行时的开启非常谨慎：即使显式传入SANDBOX_RUNTIME=local，只要SANDBOX_ALLOW_LOCAL_RUNTIME未开启，RuntimeFactory._local_runtime()依然会抛错并提示 "LocalRuntime executes code on the host. Set SANDBOX_RUNTIME=local and SANDBOX_ALLOW_LOCAL_RUNTIME=true to opt in explicitly."。

这一点在单元测试 test_runtime_factory.py 中有完整覆盖：

• test_auto_runtime_fails_closed_without_container：禁用全部容器运行时后调用create()，断言抛出包含 "No container sandbox runtime" 的RuntimeError；
• test_local_runtime_requires_explicit_opt_in：未开启本地运行时许可时调用create("local")，断言抛出 "LocalRuntime executes code on the host"；
• test_local_runtime_can_be_enabled_explicitly：设置SANDBOX_ALLOW_LOCAL_RUNTIME=True后，create("local")返回LocalRuntime实例。

这组测试从侧面印证了官方文档所述"优先级：Docker → Podman → Nerdctl → Local"并非简单的降级逻辑，而是一套带显式许可的安全策略。

四、启动 API 服务

Linux / macOS 一键启动

在沙箱模块根目录（含scripts目录的路径）执行：

./scripts/start_api.sh # 自动创建 .venv 并安装依赖后启动

结合 start_api.sh 的源码，该脚本实际做了四件事：

1. 运行时选择：支持将第一个命令行参数作为运行时偏好，内部转换为SANDBOX_RUNTIME环境变量（./scripts/start_api.sh docker即强制选择 Docker）；
2. 虚拟环境准备：检测.venv是否存在，不存在则用python3/python创建；
3. 依赖安装：pip install --upgrade pip后执行pip install -r requirements.txt；
4. 启动服务：进入sandbox目录，以uvicorn user_layer.service:app --host 127.0.0.1 --port 8000 --reload启动 FastAPI 服务，监听http://127.0.0.1:8000。

也可以通过环境变量直接指定运行时，脚本会原样透传：

SANDBOX_RUNTIME=local ./scripts/start_api.sh # 通过环境变量指定本地运行时

Windows 启动

仓库同样提供了 PowerShell 与 cmd 两个版本的一键脚本：

• PowerShell：start_api.ps1，用法为.\scripts\start_api.ps1 -Runtime docker|podman|nerdctl|local；
• cmd：start_api.cmd，用法为scripts\start_api.cmd [docker|podman|nerdctl|local]。

两者逻辑与 Linux 版一致：自动创建.venv（Windows 下为.venv\Scripts\python.exe）、安装requirements.txt、启动 uvicorn 服务。Windows 上更建议在 WSL2 的 Ubuntu 20.04+ 中运行 Linux 版脚本，配合 WSL2 内的 Docker Desktop 或 Podman 使用。

服务健康检查

服务启动后，可通过以下地址验证：

curl http://127.0.0.1:8000/api/health # 返回 {"status": "ok"} curl http://127.0.0.1:8000/api/methods # 列出所有可用接口

五、对外 API 与编程接口

HTTP API（用户层）

service.py 中注册了以下路由，覆盖会话生命周期全流程：

会话管理接口（编程接口）

interfaces.md 定义了面向开发者的核心接口：

• create_session(user_id, task_id, image_type) -> str：创建新会话，返回session_id；
• configure_session(session_id, config_info) -> bool：配置会话参数，config_info支持：
  • language：语言，默认python；
  • dependencies：依赖列表（仅容器运行时支持自动安装 pip/npm）；
  • max_memory：如"512m"（容器）；
  • max_cpus：整数；
  • network_disabled：是否禁网，默认False；
  • env：环境变量字典。
• execute_code(session_id, code_type, code_content) -> dict：执行代码，返回包含输出、错误、耗时、退出码等信息的字典；
• get_session_status(session_id) -> dict：查询会话当前状态与资源使用情况（内存、CPU 等）；
• disconnect_session(user_id, task_id) -> bool：停止并销毁指定用户任务的会话。

有状态会话与依赖安装

沙箱的核心特性之一是有状态执行：SandboxSession在start后进入活跃状态（is_active=True），同一会话内的多次execute共享同一环境或容器实例。例如第一次执行安装 pip 依赖，第二次执行即可正常使用该依赖（见 architecture.md）。依赖安装策略按语言区分：

• Python：pip install --no-input --disable-pip-version-check；
• JavaScript：npm init -y+npm install 包。

六、配置参考与资源限制

语言与镜像映射

config.py 中LANGUAGE_IMAGES定义了容器运行时的默认镜像：

从源码结构看，容器运行时（Docker/Podman/Nerdctl）支持python、python-vnc、javascript、java、cpp、go、rust等语言；本地运行时则探测系统可用语言，至少保证python可用。仓库中还提供了 create_docker.py、create_docker_python_gpu.py 等镜像构建脚本，用于预构建沙箱镜像。

默认资源限制

沙箱内置了开箱即用的资源约束（config.py 与 utils.py 中的ResourceLimits）：

容器运行时通过容器参数实施限制，本地运行时则借助psutil监控（如ProcessManager.kill_process_tree可递归终止进程树）。执行结果统一通过ExecutionStatus枚举标记：SUCCESS/ERROR/TIMEOUT/RESOURCE_LIMIT（见 base.py）。

七、安全机制与使用限制

沙箱在设计上采取了多重安全措施，使用前应了解其边界：

• 运行时安全隔离：容器运行时（Docker/Podman/Nerdctl）提供进程级隔离；本地运行时不做隔离，仅适合无容器环境的回退/开发调试，且必须显式开启SANDBOX_ALLOW_LOCAL_RUNTIME。
• 代码静态检查：SecurityUtils.validate_code 会对常见危险操作告警：bash 场景检测rm -rf /、mkfs.、dd if=、fork 炸弹、curl | bash等；Python 及其他语言场景检测import os、subprocess、eval(、exec(、socket、urllib等敏感模式，并对pickle单独告警。注意该检查仅产生警告列表，实际拦截仍依赖容器隔离与资源限制。
• 网络隔离：会话配置支持network_disabled，可在安全隔离场景下禁用容器网络。
• 路径安全：PathUtils.ensure_safe_path防止路径遍历攻击，工作目录统一为/workspace（WORKING_DIR）。
• 超时与资源兜底：ExecutionStatus.TIMEOUT/RESOURCE_LIMIT用于标记被终止的执行，避免失控任务长期占用资源。

结语

本文围绕 DB-GPT Sandbox 的官方使用说明展开：完成环境准备后，只需一条./scripts/start_api.sh即可在本地拉起沙箱 API 服务；RuntimeFactory会自动在 Docker → Podman → Nerdctl → Local 之间择优选择，也可通过SANDBOX_RUNTIME强制指定；随后便可通过/api/connect、/api/configure、/api/execute等接口在隔离环境中执行多语言代码，并利用有状态会话完成依赖安装、环境变更等连续任务。深入阅读 runtime_factory.py、control_layer.py 与 base.py 等源码，可以进一步理解其安全隔离与有状态执行的底层设计，为后续接入 DB-GPT Agent 或扩展自定义运行时打下基础。

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT