DuckDB 沙箱如何隔离 AI 生成的 SQL?Helix Foundry Executor 安全执行源码解读
DuckDB 沙箱如何隔离 AI 生成的 SQL?Helix Foundry Executor 安全执行源码解读
Helix Foundry 是一个本地优先(local-first)的数据工作区,它把公司的数据连接进同一个 ontology,运行在你自己的电脑上,底层由 HelixDB 和 DuckDB 支撑。当你向它的 Analyst 用自然语言提问时,模型会生成一段 SQL 去查数据——这段"别人写的代码"如果直接执行,风险不小。Helix Foundry 专门用了一个名为 Executor 的独立服务来承接所有 DuckDB 作业,通过进程级沙箱 + 数据库级配置锁死 + SQL 白名单校验三层隔离,让 AI 生成的 SQL 只能"看见"你允许它看见的那几张表。这篇文章带你完整读懂这套安全执行机制。
先认识主角:Executor 在整个系统里的位置
在 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):
- 正则预检:SQL 必须以
SELECT或WITH开头,任何DROP、DELETE、COPY、ATTACH开头的语句直接抛出Only a single SELECT query is allowed; - 语句拆分校验:用 DuckDB 的
extractStatements真正解析 SQL,确认它恰好只有 1 条语句——SELECT ...; DELETE ...这种"夹带"写法在这里无所遁形; - 包一层子查询:最终执行的是
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 不可信,怎么办?
- 进程层:一次性子进程 + 环境变量白名单 + 超时 SIGKILL + 并发限流,崩溃和失控都被限制在最小爆炸半径内;
- SQL 层:只放行单条
SELECT/WITH,输入表白名单加载,恶意意图根本没有执行面; - 数据库层:内存库 + 禁用扩展 +
allowed_paths+ 关闭外部访问 +lock_configuration锁死配置,让 SQL 在引擎内部也无法"自救"越狱。
这种层层设防的本地优先架构,让 Helix Foundry 敢把"用自然语言查任意数据"做成日常功能,而你的数据始终只留在这台你自己的电脑上。如果你想继续深入,可以从 services/executor/src/engine.ts 读起,配合 docs/OPERATIONS.md 里关于部署限制与内存预算的章节,完整理解每个默认值背后的取舍。
