DuckDB 沙箱如何隔离 AI 生成的 SQL?Helix Foundry Executor 安全执行源码解读

原创2026-10-13 22:45:521,461 阅读
文章标签:后端前端人工智能大模型AI Agent知识图谱数据集成变更数据捕获MCP 服务本地部署数据可视化RAG

DuckDB 沙箱如何隔离 AI 生成的 SQL?Helix Foundry Executor 安全执行源码解读

Helix Foundry 是一个本地优先(local-first)的数据工作区,它把公司的数据连接进同一个 ontology,运行在你自己的电脑上,底层由 HelixDB 和 DuckDB 支撑。当你向它的 Analyst 用自然语言提问时,模型会生成一段 SQL 去查数据——这段"别人写的代码"如果直接执行,风险不小。Helix Foundry 专门用了一个名为 Executor 的独立服务来承接所有 DuckDB 作业,通过进程级沙箱 + 数据库级配置锁死 + SQL 白名单校验三层隔离,让 AI 生成的 SQL 只能"看见"你允许它看见的那几张表。这篇文章带你完整读懂这套安全执行机制。

先认识主角:Executor 在整个系统里的位置

Helix Foundry 本地数据工作区的 Explorer 视图,展示 DuckDB 沙箱之上的 ontology 数据图谱

在 compose.yaml 中,Executor 是一个独立容器,与 app(API)、worker、helix 等服务平级。API 收到任何"需要跑 SQL"的请求——自然语言问答、仪表盘查询、导入、管道构建——都会通过 HTTP 把作业投递给 Executor 的 /execute 接口,客户端封装见 apps/api/src/executor.ts。Executor 收到作业后并不会在自身进程里执行,而是为每个作业 fork 一个一次性的子进程来跑 DuckDB,跑完(无论成功、失败还是被杀)就销毁整个环境。

这个"一次一弃"的设计是后面所有隔离措施的地基。

第一层隔离:一次性子进程与受限环境 🛡️

打开 services/executor/src/jobs.ts,可以看到作业执行的核心函数 run:

  • 子进程隔离:Executor 用 spawn 启动一个全新的 Node 进程来运行 services/executor/src/runner.ts(该脚本从 stdin 读入作业 JSON,调用引擎执行后把结果 JSON 写回 stdout)。即使一段恶意 SQL 把 DuckDB 连接搞崩,受害的也只是一个"用完即弃"的子进程,Executor 主进程毫发无损。
  • 环境变量白名单:子进程只拿到 PATH、DATA_DIR、DUCKDB_MEMORY、EXECUTOR_SCRATCH 等寥寥几个变量(见 jobs.ts),父进程里的密钥、凭证一律带不进去。
  • 输出熔断:子进程 stdout 累计超过 10 MB 直接被 SIGKILL,防止"SELECT 出一个宇宙"式的大输出拖垮系统。
  • 超时即杀:每个作业从进入队列的那一刻就开始计时,超时后 SIGKILL 直接了断,没有协商余地。

此外,Executor 自带一个小型任务调度器:同一时刻最多 2 个 DuckDB 作业并行,另有 50 个等待排队,队列满了返回 429,等待超时的作业返回 503(jobs.ts)。这种"小批量 + 排队"的策略让资源占用始终可预期。

第二层隔离:SQL 白名单——只许一条 SELECT 🔍

进程只是外壳,真正"锁住"AI 生成 SQL 的是 services/executor/src/engine.ts 里的执行引擎。在拿到 sql 之后,引擎做了三道检查(engine.ts):

  1. 正则预检:SQL 必须以 SELECT 或 WITH 开头,任何 DROP、DELETE、COPY、ATTACH 开头的语句直接抛出 Only a single SELECT query is allowed;
  2. 语句拆分校验:用 DuckDB 的 extractStatements 真正解析 SQL,确认它恰好只有 1 条语句——SELECT ...; DELETE ... 这种"夹带"写法在这里无所遁形;
  3. 包一层子查询:最终执行的是 CREATE TABLE result AS SELECT * FROM (你的SQL) AS foundry_result,结果被收进一个受控表。

同时,数据输入本身也是白名单制的:只有 job.inputs 里声明的、且通过了 safePart 字符校验(^<a href="https://link.gitcode.com/i/35549c14b2a47dcc9bb76e616d12f08e" target="_blank">a-zA-Z0-9_-]{1,100}$,[engine.ts)的数据集,才会被从本地 Parquet 快照加载成内存表。也就是说,沙箱里只装得进你主动声明的那几张表,AI 的 SQL 就算想 SELECT * FROM secrets,也只会得到一个"表不存在"的错误。

第三层隔离:DuckDB 配置"上锁" 🔒

沙箱不只是"少给数据",还主动关掉了 DuckDB 的一票危险能力。引擎在每次建库时就写死了运行参数(engine.ts):

配置 值 作用
数据库 :memory: 内存库 不落盘,进程一死全清空
memory_limit 512 MB(DUCKDB_MEMORY 可调) 防止内存吃满
threads 2 限制并行,防止 CPU 占满
allow_unsigned_extensions false 禁用未签名扩展,SQL 无法加载外部插件
autoinstall/autoload_known_extensions false 禁止任何自动安装/加载扩展

在执行 SQL 之前,引擎还会连续三条 SET 把沙箱彻底封死(engine.ts):

  • SET allowed_paths = [...]:DuckDB 只能访问那一个指定的结果输出路径,read_csv 之类函数读不了机器上的任何其他文件;
  • SET enable_external_access = false:关闭一切外部访问,httpfs、read_parquet('http://...') 这类"借道读远端文件"的手法全部失效;
  • SET lock_configuration = true:锁定配置,这是关键一手——AI 的 SQL 即使在语句里再写 SET enable_external_access = true 试图自我解锁,也会被 DuckDB 直接拒绝。沙箱规则只有引擎自己有权设置,被执行的 SQL 没有这个权利。

配合 compose 层面的容器加固(compose.yaml)——mem_limit: 2g 内存上限、pids_limit: 128 进程数上限、cap_drop: [ALL] 丢弃全部 Linux 权限、no-new-privileges 禁止提权,加上 Executor 只挂在与外网断开的内部网络——整个执行链路形成闭环:AI 生成的 SQL 没有文件系统越权、没有网络外联、没有提权路径、没有持久化能力,超时会死,超内存也会死。

时间即资源:两套超时如何兜底 ⏱️

再严密的沙箱也需要时间预算。services/executor/src/limits.ts 定义了两档:

  • EXECUTOR_QUERY_TIMEOUT(默认 120 秒):面向"有人在等答案"的查询——仪表盘、自然语言提问;
  • EXECUTOR_JOB_TIMEOUT(默认 900 秒):面向整表读写的导入、管道、发布作业。

注意计时起点是Executor 收到作业的时刻,排队时间也一并计入,一个在队列里耗光时间的作业会直接失败而不会"迟到的爆发"。API 侧读同一套配置并多等 15 秒(REPLY_MARGIN),保证永远能先收到 Executor 的答复而不是自己先超时。详细的运维说明见 docs/OPERATIONS.md 的 Deployment limits 一节。

善后:临时文件的自动清理 🧹

DuckDB 内存不够时会把数据溢出(spill)到磁盘,Executor 为每个作业在 DATA_DIR/scratch 下开一个独立的临时目录,作业结束——包括被超时杀死、被 OOM 杀死、容器停止等各种非正常结局——该目录都会被删除(jobs.ts)。Executor 启动时还会清扫上次异常退出遗留的作业目录(jobs.ts),所以 scratch 目录不会成为垃圾堆积地,备份脚本也干脆把它整体排除在外。

如何调整这些安全参数

所有参数都在 .env 中配置,留空即用默认值,修改后重启容器即可生效:

参数 默认 含义
DUCKDB_MEMORY 512 MB 单个作业的 DuckDB 内存上限
DUCKDB_SPILL_LIMIT 不限(磁盘 90%) 单个作业溢出文件占用的磁盘上限,如 20GB
EXECUTOR_RESULT_LIMIT 2 GB 发布查询结果行数写入的大小上限
EXECUTOR_QUERY_TIMEOUT 120 查询类作业超时(秒)
EXECUTOR_JOB_TIMEOUT 900 导入/管道/发布作业超时(秒)

配置非法值(比如 2m)时,API、worker 和 Executor 会在启动阶段就拒绝启动并给出带参数名的错误信息,而不是让每个作业都失败——这是一种"fail fast"的安全姿态(limits.ts)。

总结:三层沙箱,各守一道门

回看 Helix Foundry Executor 的设计,它回答的其实是同一个问题:AI 生成的 SQL 不可信,怎么办?

  1. 进程层:一次性子进程 + 环境变量白名单 + 超时 SIGKILL + 并发限流,崩溃和失控都被限制在最小爆炸半径内;
  2. SQL 层:只放行单条 SELECT/WITH,输入表白名单加载,恶意意图根本没有执行面;
  3. 数据库层:内存库 + 禁用扩展 + allowed_paths + 关闭外部访问 + lock_configuration 锁死配置,让 SQL 在引擎内部也无法"自救"越狱。

这种层层设防的本地优先架构,让 Helix Foundry 敢把"用自然语言查任意数据"做成日常功能,而你的数据始终只留在这台你自己的电脑上。如果你想继续深入,可以从 services/executor/src/engine.ts 读起,配合 docs/OPERATIONS.md 里关于部署限制与内存预算的章节,完整理解每个默认值背后的取舍。

登录后查看全文
helix-foundry