Lightdash Sandbox 沙箱开发指南E2B 模板、镜像规范与发布流水线实践【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash导读sandboxes/CLAUDE.md是 Lightdash 仓库中面向生产级沙箱sandbox开发的权威规范文档它定义了sandboxes/目录下每个独立沙箱镜像的生命周期从e2b.Dockerfile的镜像定义、build-sandbox.ts的 E2B 构建脚本到assign-tag.ts的发布打标再到与后端parseConfig.ts的运行时配置对齐、.github/workflows/post-release.yml中的发布矩阵形成一套构建—配置—发布—验证闭环。读完本文你将掌握如何在 Lightdash 中新增或维护一个生产沙箱模板理解镜像精简、安全与可复现的硬性规则并能把本地 Docker 调试路径与云端 E2B 发布流程无缝衔接。沙箱目录的角色定位独立镜像 多 Provider 消费Lightdash 的沙箱是 AI 代理coding agent、write-back、data-app 生成等实际运行的隔离执行环境。规范文档第一条就点明sandboxes/下每个生产沙箱都是一个独立镜像被一个或多个SandboxProvider实现消费。因此镜像本身、后端运行时配置、本地开发路径与发布工作流四者必须始终对齐否则就会出现本地能跑、线上镜像不匹配的漂移问题。从仓库现状看sandboxes/下共有四个生产模板与一个辅助目录sandboxesagent-onboarding/agent 引导/入门沙箱ai-coding-agent/AI 编码代理沙箱ai-writeback/写回write-back沙箱data-apps/Data Apps 生成沙箱内部还包含template/可生成的应用脚手架与benchmark/性能基准子目录microvm-agent/非 E2B 模板的辅助脚本目录。每个生产模板都遵循同一套文件骨架这正是Required template files一节所要求的。模板必备文件一个生产沙箱的最小骨架规范要求每个 E2B 模板至少包含以下文件逐一对照 sandboxes/data-apps 可确认其真实形态文件职责仓库实例e2b.Dockerfile生产镜像定义E2B 云端构建的唯一事实来源sandboxes/data-apps/e2b.Dockerfilebuild-sandbox.ts用 E2B SDK 构建 Dockerfile、应用主标签与额外标签、流式输出构建日志、失败时非零退出sandboxes/data-apps/build-sandbox.tsassign-tag.ts不重建镜像仅对已有构建打发布标签sandboxes/data-apps/assign-tag.tspackage.json/pnpm-lock.yaml/pnpm-workspace.yaml独立的私有 workspace不隶属于根 pnpm workspace各模板目录下均存在build-local-image.sh仅当功能支持SANDBOX_PROVIDERdocker时需要本地 Dockerfile 变更必须从e2b.Dockerfile派生不得维护两份独立镜像定义sandboxes/data-apps/build-local-image.sh.gitignore覆盖.env、node_modules、生成的 Dockerfile、打包 tarball 与其他构建产物各模板目录此外复杂模板还应提供 README说明输入/输出、运行时限制、本地工作流、模板名与环境变量。从源码看 build-sandbox.ts 的执行细节sandboxes/data-apps/build-sandbox.ts 揭示了脚本的关键行为加载.env脚本启动时解析同目录.env将E2B_API_KEY等键注入环境变量使密钥可随其他配置存放打包 SDK通过execFileSync(bash, [pack-query-sdk.sh])先打包本地 query-sdk tarballlightdash-query-sdk.tgz供 Dockerfile 内file:lightdash-query-sdk.tgz引用构建目标E2B_TEMPLATE_NAME默认lightdash-data-app加主标签E2B_TEMPLATE_TAG构成name:tag构建目标E2B_TEMPLATE_EXTRA_TAGS以逗号分隔传入tags选项使一次构建可同时被多个别名寻址如版本号与latest标签为空时回落到 E2B 隐式的default标签后台构建与轮询Template.buildInBackground提交构建data-app 模板默认cpuCount: 2、memoryMB: 2048随后循环Template.getBuildStatus流式打印日志ready成功、error以process.exit(1)失败命令行传入--no-cache可强制绕过 E2B 构建缓存错误处理catch 块打印错误 message/status/body/stack 后退出非零确保 CI 可感知失败。e2b.Dockerfile 的镜像内容层次sandboxes/data-apps/e2b.Dockerfile 是镜像定义的样板以node:24为基础全局安装pnpm11.17.0与sfw2.0.6再由sfw npm install -g安装anthropic-ai/claude-code与openai/codex随后将模板脚手架文件与预打包的 SDK tarball 拷贝进/app用sed把workspace:*替换为本地 tarball 后执行pnpm install再通过npx shadcn2.3.0 init --defaults --force与add --overwrite预装 shadcn/ui 组件button badge card table dialog tabs select input label popover tooltip separator skeleton dropdown-menu sheet scroll-area switch checkbox avatar alert progress resizable使沙箱一启动即可直接生成应用COPY template/tailwind.config.js则修正 shadcn init 对配色约定的改写保证 oklch 色彩体系单一最后chown -R user:user /app使 E2B 运行时用户可写。镜像规则精简、安全、可复现规范中的镜像规则是安全与可维护性的底线逐条拆解如下只安装代理被允许使用的工具受限代理restricted-agent镜像要刻意保持最小化——镜像体积越小攻击面与启动开销越小包安装统一走sfw路由唯一例外是安装sfw本身需要可复现性时固定工具版本例如 Dockerfile 中的sfw2.0.6、claude-code2.1.272、codex0.147.0都是精确 pin 的版本号绝不把凭据或本地.env烘焙进镜像——镜像会被分发与复用任何密钥都必须通过运行时注入如E2B_API_KEY运行时的 workdir、用户、home 目录、已安装 skills、可写路径必须与后端服务使用的常量和路径一致这是构建产物与运行时契约对齐的体现E2B 自带运行时用户E2B 构建器会注入user账号若纯 Docker 需要额外建用户应在生成的Dockerfile.local中补充而不是改坏e2b.Dockerfile的共享定义预装运行时依赖代理默认不应再安装包除非功能明确允许——沙箱应开箱即用。命名与运行时配置模板名、标签与 parseConfig.ts 的三方对齐规范要求每个模板要有稳定的生产名与一套环境变量族模板名、主标签、额外标签、源标签且build-sandbox.ts、assign-tag.ts与 packages/backend/src/config/parseConfig.ts 中的默认值必须完全一致。从parseConfig.ts的parseAppRuntimeConfig约 2544–2639 行可以看到这套约定在后端的具体落地E2B_TEMPLATE_NAME默认lightdash/lightdash-data-appE2B_AI_WRITEBACK_TEMPLATE_NAME默认lightdash-ai-writeback后端模板标签默认取运行中的 LightdashVERSIONe2bTemplateTag: process.env.E2B_TEMPLATE_TAG ?? (VERSION as string)这正是每次发布都启动与它匹配的沙箱镜像的实现机制——发布工作流保证该版本标签必然存在运维也可通过覆盖E2B_TEMPLATE_TAG在故障时回滚或固定版本SANDBOX_PROVIDER经parseSandboxProvider解析2490–2504 行接受e2b、docker、lambda-microvm、azure-sandboxes、gcp-cloud-run空值默认e2b并对大小写/空白做归一化真实拼写错误则抛ParseError而非静默回退Docker Provider 对应三个镜像名SANDBOX_DOCKER_IMAGE默认lightdash-sandbox:local、SANDBOX_AI_WRITEBACK_DOCKER_IMAGE默认lightdash-ai-writeback:local、SANDBOX_AGENT_ONBOARDING_DOCKER_IMAGE默认lightdash-agent-onboarding:local运行时治理参数SANDBOX_IDLE_TIMEOUT_MS默认30 * 60 * 100030 分钟空闲回收SANDBOX_SNAPSHOT_RETENTION_MS默认7 * 24 * 60 * 60 * 10007 天快照保留。由此可见本地脚本默认值 后端配置默认值不是巧合而是强制契约任何一处漂移都会导致发布出的模板标签与后端启动的沙箱版本不一致。发布流水线post-release 模板矩阵 publish-e2b-template 复用工作流规范强制要求每个 E2B 模板都必须登记在 .github/workflows/post-release.yml 的模板矩阵中矩阵调用可复用的 .github/workflows/publish-e2b-template.yml严禁把构建与重打标步骤复制进发布工作流本身。模板矩阵post-release.yml矩阵约 726–790 行按region: [us, eu]与四个模板做笛卡尔组合每个条目声明模板目录、生产名、四个环境变量名*_TEMPLATE_NAME/*_TEMPLATE_TAG/*_TEMPLATE_EXTRA_TAGS/*_TEMPLATE_SOURCE_TAG、additional_watch_paths与install_root_deps。例如>sfw pnpm install --frozen-lockfile E2B_API_KEY... pnpm run build使用模板特定的 name/tag/extra-tag 变量进行发布风格构建验证必须绕过 E2B 缓存的 Dockerfile 变更时追加--no-cache对应build-sandbox.ts中process.argv.includes(--no-cache)的解析。Docker 支撑的本地开发./build-local-image.shsandboxes/data-apps/build-local-image.sh 展示了单一镜像定义原则的落地它先用bash ./pack-query-sdk.sh打包 SDK再用sed从e2b.Dockerfile派生出Dockerfile.local——唯一改动是把最后的chown -R user:user /app替换为先useradd -m -s /bin/bash user失败则忽略再 chown因为纯node基础镜像没有 E2B 注入的user账号。随后docker build -t $IMAGE -f Dockerfile.local .。注意本地镜像默认标签lightdash-sandbox:local必须与parseConfig.ts中SANDBOX_DOCKER_IMAGE的默认值以及本地 bootstrap 脚本保持一致否则后端SANDBOX_PROVIDERdocker时找不到镜像。验证清单上线前必须通过的检查项规范以一份可执行的验证清单收尾涵盖四个层面独立冻结安装运行sfw pnpm install --frozen-lockfile确认 TypeScript 脚本build-sandbox.ts、assign-tag.ts启动时无模块或配置错误工作流覆盖解析变更后的 workflow YAML确认每个build-sandbox.ts模板都有发布工作流覆盖即已登记在post-release.yml矩阵中且新增/改名工作流条目必须与模板变更在同一提交中本地镜像Docker 支持或 Dockerfile 变更时构建本地镜像./build-local-image.sh真实 E2B 构建仅在确有外部发布与构建成本意图时执行验证版本化标签与latest双标签最后通过拥有该服务的后端所支持的每个 Provider对沙箱创建做冒烟测试smoke-test确保SandboxProvider实际能拉起沙箱。实践要点小结关注点关键结论依据单一镜像来源本地 Dockerfile 必须从e2b.Dockerfile派生不得维护两份定义build-local-image.sh三方默认值一致build-sandbox.ts、assign-tag.ts、parseConfig.ts的模板名/标签默认值必须同步parseConfig.ts版本跟随后端模板标签默认等于运行中VERSION保证发布与镜像匹配parseConfig.ts2619 行发布免重复建设模板与烘焙依赖未变时重打标latest→ 新版本不重建publish-e2b-template.yml变更检测范围watch 路径覆盖共享包/SDK/skills不止沙箱目录post-release.yml 749–775 行密钥永不入镜像凭据与.env仅运行时注入e2b.Dockerfile按此规范维护沙箱模板可以确保 Lightdash 的 AI 执行环境始终与后端运行时契约、发布版本、本地调试路径保持同步构建出的镜像精简、安全且可复现。【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/18 4:01:42 · 阅读 1.2k Lightdash Sandbox 沙箱开发指南：E2B 模板、镜像规范与发布流水线实践
Lightdash Sandbox 沙箱开发指南E2B 模板、镜像规范与发布流水线实践【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash导读sandboxes/CLAUDE.md是 Lightdash 仓库中面向生产级沙箱sandbox开发的权威规范文档它定义了sandboxes/目录下每个独立沙箱镜像的生命周期从e2b.Dockerfile的镜像定义、build-sandbox.ts的 E2B 构建脚本到assign-tag.ts的发布打标再到与后端parseConfig.ts的运行时配置对齐、.github/workflows/post-release.yml中的发布矩阵形成一套构建—配置—发布—验证闭环。读完本文你将掌握如何在 Lightdash 中新增或维护一个生产沙箱模板理解镜像精简、安全与可复现的硬性规则并能把本地 Docker 调试路径与云端 E2B 发布流程无缝衔接。沙箱目录的角色定位独立镜像 多 Provider 消费Lightdash 的沙箱是 AI 代理coding agent、write-back、data-app 生成等实际运行的隔离执行环境。规范文档第一条就点明sandboxes/下每个生产沙箱都是一个独立镜像被一个或多个SandboxProvider实现消费。因此镜像本身、后端运行时配置、本地开发路径与发布工作流四者必须始终对齐否则就会出现本地能跑、线上镜像不匹配的漂移问题。从仓库现状看sandboxes/下共有四个生产模板与一个辅助目录sandboxesagent-onboarding/agent 引导/入门沙箱ai-coding-agent/AI 编码代理沙箱ai-writeback/写回write-back沙箱data-apps/Data Apps 生成沙箱内部还包含template/可生成的应用脚手架与benchmark/性能基准子目录microvm-agent/非 E2B 模板的辅助脚本目录。每个生产模板都遵循同一套文件骨架这正是Required template files一节所要求的。模板必备文件一个生产沙箱的最小骨架规范要求每个 E2B 模板至少包含以下文件逐一对照 sandboxes/data-apps 可确认其真实形态文件职责仓库实例e2b.Dockerfile生产镜像定义E2B 云端构建的唯一事实来源sandboxes/data-apps/e2b.Dockerfilebuild-sandbox.ts用 E2B SDK 构建 Dockerfile、应用主标签与额外标签、流式输出构建日志、失败时非零退出sandboxes/data-apps/build-sandbox.tsassign-tag.ts不重建镜像仅对已有构建打发布标签sandboxes/data-apps/assign-tag.tspackage.json/pnpm-lock.yaml/pnpm-workspace.yaml独立的私有 workspace不隶属于根 pnpm workspace各模板目录下均存在build-local-image.sh仅当功能支持SANDBOX_PROVIDERdocker时需要本地 Dockerfile 变更必须从e2b.Dockerfile派生不得维护两份独立镜像定义sandboxes/data-apps/build-local-image.sh.gitignore覆盖.env、node_modules、生成的 Dockerfile、打包 tarball 与其他构建产物各模板目录此外复杂模板还应提供 README说明输入/输出、运行时限制、本地工作流、模板名与环境变量。从源码看 build-sandbox.ts 的执行细节sandboxes/data-apps/build-sandbox.ts 揭示了脚本的关键行为加载.env脚本启动时解析同目录.env将E2B_API_KEY等键注入环境变量使密钥可随其他配置存放打包 SDK通过execFileSync(bash, [pack-query-sdk.sh])先打包本地 query-sdk tarballlightdash-query-sdk.tgz供 Dockerfile 内file:lightdash-query-sdk.tgz引用构建目标E2B_TEMPLATE_NAME默认lightdash-data-app加主标签E2B_TEMPLATE_TAG构成name:tag构建目标E2B_TEMPLATE_EXTRA_TAGS以逗号分隔传入tags选项使一次构建可同时被多个别名寻址如版本号与latest标签为空时回落到 E2B 隐式的default标签后台构建与轮询Template.buildInBackground提交构建data-app 模板默认cpuCount: 2、memoryMB: 2048随后循环Template.getBuildStatus流式打印日志ready成功、error以process.exit(1)失败命令行传入--no-cache可强制绕过 E2B 构建缓存错误处理catch 块打印错误 message/status/body/stack 后退出非零确保 CI 可感知失败。e2b.Dockerfile 的镜像内容层次sandboxes/data-apps/e2b.Dockerfile 是镜像定义的样板以node:24为基础全局安装pnpm11.17.0与sfw2.0.6再由sfw npm install -g安装anthropic-ai/claude-code与openai/codex随后将模板脚手架文件与预打包的 SDK tarball 拷贝进/app用sed把workspace:*替换为本地 tarball 后执行pnpm install再通过npx shadcn2.3.0 init --defaults --force与add --overwrite预装 shadcn/ui 组件button badge card table dialog tabs select input label popover tooltip separator skeleton dropdown-menu sheet scroll-area switch checkbox avatar alert progress resizable使沙箱一启动即可直接生成应用COPY template/tailwind.config.js则修正 shadcn init 对配色约定的改写保证 oklch 色彩体系单一最后chown -R user:user /app使 E2B 运行时用户可写。镜像规则精简、安全、可复现规范中的镜像规则是安全与可维护性的底线逐条拆解如下只安装代理被允许使用的工具受限代理restricted-agent镜像要刻意保持最小化——镜像体积越小攻击面与启动开销越小包安装统一走sfw路由唯一例外是安装sfw本身需要可复现性时固定工具版本例如 Dockerfile 中的sfw2.0.6、claude-code2.1.272、codex0.147.0都是精确 pin 的版本号绝不把凭据或本地.env烘焙进镜像——镜像会被分发与复用任何密钥都必须通过运行时注入如E2B_API_KEY运行时的 workdir、用户、home 目录、已安装 skills、可写路径必须与后端服务使用的常量和路径一致这是构建产物与运行时契约对齐的体现E2B 自带运行时用户E2B 构建器会注入user账号若纯 Docker 需要额外建用户应在生成的Dockerfile.local中补充而不是改坏e2b.Dockerfile的共享定义预装运行时依赖代理默认不应再安装包除非功能明确允许——沙箱应开箱即用。命名与运行时配置模板名、标签与 parseConfig.ts 的三方对齐规范要求每个模板要有稳定的生产名与一套环境变量族模板名、主标签、额外标签、源标签且build-sandbox.ts、assign-tag.ts与 packages/backend/src/config/parseConfig.ts 中的默认值必须完全一致。从parseConfig.ts的parseAppRuntimeConfig约 2544–2639 行可以看到这套约定在后端的具体落地E2B_TEMPLATE_NAME默认lightdash/lightdash-data-appE2B_AI_WRITEBACK_TEMPLATE_NAME默认lightdash-ai-writeback后端模板标签默认取运行中的 LightdashVERSIONe2bTemplateTag: process.env.E2B_TEMPLATE_TAG ?? (VERSION as string)这正是每次发布都启动与它匹配的沙箱镜像的实现机制——发布工作流保证该版本标签必然存在运维也可通过覆盖E2B_TEMPLATE_TAG在故障时回滚或固定版本SANDBOX_PROVIDER经parseSandboxProvider解析2490–2504 行接受e2b、docker、lambda-microvm、azure-sandboxes、gcp-cloud-run空值默认e2b并对大小写/空白做归一化真实拼写错误则抛ParseError而非静默回退Docker Provider 对应三个镜像名SANDBOX_DOCKER_IMAGE默认lightdash-sandbox:local、SANDBOX_AI_WRITEBACK_DOCKER_IMAGE默认lightdash-ai-writeback:local、SANDBOX_AGENT_ONBOARDING_DOCKER_IMAGE默认lightdash-agent-onboarding:local运行时治理参数SANDBOX_IDLE_TIMEOUT_MS默认30 * 60 * 100030 分钟空闲回收SANDBOX_SNAPSHOT_RETENTION_MS默认7 * 24 * 60 * 60 * 10007 天快照保留。由此可见本地脚本默认值 后端配置默认值不是巧合而是强制契约任何一处漂移都会导致发布出的模板标签与后端启动的沙箱版本不一致。发布流水线post-release 模板矩阵 publish-e2b-template 复用工作流规范强制要求每个 E2B 模板都必须登记在 .github/workflows/post-release.yml 的模板矩阵中矩阵调用可复用的 .github/workflows/publish-e2b-template.yml严禁把构建与重打标步骤复制进发布工作流本身。模板矩阵post-release.yml矩阵约 726–790 行按region: [us, eu]与四个模板做笛卡尔组合每个条目声明模板目录、生产名、四个环境变量名*_TEMPLATE_NAME/*_TEMPLATE_TAG/*_TEMPLATE_EXTRA_TAGS/*_TEMPLATE_SOURCE_TAG、additional_watch_paths与install_root_deps。例如>sfw pnpm install --frozen-lockfile E2B_API_KEY... pnpm run build使用模板特定的 name/tag/extra-tag 变量进行发布风格构建验证必须绕过 E2B 缓存的 Dockerfile 变更时追加--no-cache对应build-sandbox.ts中process.argv.includes(--no-cache)的解析。Docker 支撑的本地开发./build-local-image.shsandboxes/data-apps/build-local-image.sh 展示了单一镜像定义原则的落地它先用bash ./pack-query-sdk.sh打包 SDK再用sed从e2b.Dockerfile派生出Dockerfile.local——唯一改动是把最后的chown -R user:user /app替换为先useradd -m -s /bin/bash user失败则忽略再 chown因为纯node基础镜像没有 E2B 注入的user账号。随后docker build -t $IMAGE -f Dockerfile.local .。注意本地镜像默认标签lightdash-sandbox:local必须与parseConfig.ts中SANDBOX_DOCKER_IMAGE的默认值以及本地 bootstrap 脚本保持一致否则后端SANDBOX_PROVIDERdocker时找不到镜像。验证清单上线前必须通过的检查项规范以一份可执行的验证清单收尾涵盖四个层面独立冻结安装运行sfw pnpm install --frozen-lockfile确认 TypeScript 脚本build-sandbox.ts、assign-tag.ts启动时无模块或配置错误工作流覆盖解析变更后的 workflow YAML确认每个build-sandbox.ts模板都有发布工作流覆盖即已登记在post-release.yml矩阵中且新增/改名工作流条目必须与模板变更在同一提交中本地镜像Docker 支持或 Dockerfile 变更时构建本地镜像./build-local-image.sh真实 E2B 构建仅在确有外部发布与构建成本意图时执行验证版本化标签与latest双标签最后通过拥有该服务的后端所支持的每个 Provider对沙箱创建做冒烟测试smoke-test确保SandboxProvider实际能拉起沙箱。实践要点小结关注点关键结论依据单一镜像来源本地 Dockerfile 必须从e2b.Dockerfile派生不得维护两份定义build-local-image.sh三方默认值一致build-sandbox.ts、assign-tag.ts、parseConfig.ts的模板名/标签默认值必须同步parseConfig.ts版本跟随后端模板标签默认等于运行中VERSION保证发布与镜像匹配parseConfig.ts2619 行发布免重复建设模板与烘焙依赖未变时重打标latest→ 新版本不重建publish-e2b-template.yml变更检测范围watch 路径覆盖共享包/SDK/skills不止沙箱目录post-release.yml 749–775 行密钥永不入镜像凭据与.env仅运行时注入e2b.Dockerfile按此规范维护沙箱模板可以确保 Lightdash 的 AI 执行环境始终与后端运行时契约、发布版本、本地调试路径保持同步构建出的镜像精简、安全且可复现。【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考