HelixDB/helix-foundry · 上手攻略

  • 仓库：HelixDB/helix-foundry
  • 链接：https://github.com/HelixDB/helix-foundry
  • 分类：database / tool / trending
  • 作者：spark
  • 更新：2026-10-13

是什么

helix-foundry 是 HelixDB 团队开源的 local-first 数据工作空间，底层同时使用 HelixDB（自有图数据库）和 DuckDB（列存分析引擎）。它把企业已经在跑的 PostgreSQL / MySQL / Neon / Supabase / Stripe / WorkOS / PostHog / S3 / REST API 等数据源连起来，在本机（不上云、不依赖账号）生成一个统一的“本体（ontology）”，你可以浏览、问答、查询。AI 默认本地运行；也可切到 Claude / OpenAI / Azure OpenAI / Bedrock / 自定义 OpenAI 兼容端点。

⚠️ 首次运行需联网拉取约 2.5 GB（HelixDB、Ollama、qwen3:4b 模型），Mac 上 docker 没有 Metal 加速，作者建议装原生 Ollama 提速。

解决什么问题

  • 数据散在数据库 + 文件 + SaaS，想做本机一体化分析却不想租云端数仓。
  • 想让 AI 主动建议 / 重组数据本体，又不愿把企业数据上传。
  • 需要 versioned data（不可变 Parquet snapshot）+ schema-drift 审查 + 历史回放。
  • 想用 SQL 问答数据，但不想给 AI 全网访问权限。
  • 想要 OpenAPI + TypeScript SDK + 工作区分级 API token。

快速安装

推荐路径：先确认 Docker + Compose v2 已就绪，再 ./scripts/setup.sh --compose。Compose v2 是硬要求，README 标注“已用 2.29 验证”。

1. 安装 Docker（v2 + Compose 插件）

参见 Docker 官方文档。需要 docker compose（不是 docker-compose）。

2. 克隆并启动

git clone https://github.com/helixdb/helix-foundry.git
cd helix-foundry
./scripts/setup.sh --compose
  • 脚本会自动生成 .env（包含 ENCRYPTION_KEY、PUBLIC_PORT、PUBLIC_ORIGIN 等）。
  • 默认端口 3001；占用则需手动改 .env（同时改 PUBLIC_PORT 与 PUBLIC_ORIGIN，否则保存操作会 403）。
  • 等待 health check：
curl -fsS http://localhost:3001/api/health
# {"ok":true,"service":"helix-foundry"}

3. 打开引导页

浏览器访问 http://localhost:3001（默认无登录），按 AI → Data → Ontology 三步走：

  1. 选 AI：Local / Claude / OpenAI / Azure OpenAI / Bedrock / 自定义 OpenAI 兼容端点。
  2. 接数据源：可用真实数据，也可选 “Continue with sample data”。
  3. 确认建议的本体（ontology）。

Apple Silicon 用户的可选加速

Docker 不能用 Metal；作者建议装原生 Ollama 后跳过 bundled 模型：

./scripts/setup.sh
grep -q '^MODEL_ENDPOINT=' .env || echo 'MODEL_ENDPOINT=http://host.docker.internal:11434' >> .env
docker compose up -d --build

此路径依赖 Docker Desktop 的 host.docker.internal；其他 Docker runtime 用默认命令即可。

核心用法

日常运维命令

docker compose --profile local ps -a           # 查看状态
docker compose --profile local logs -f app worker   # 跟踪日志（Ctrl+C 停止）
docker compose --profile local stop             # 停止
docker compose --profile local up -d           # 再次启动

升级

./scripts/upgrade.sh
  • 先备份到 ~/helix-foundry-backups/，备份失败即中止。
  • 拉取 + 重建；失败可重跑。
  • 若新版本升级了 HelixDB，会先询问（HelixDB 升级是单向的，只有那一份备份能让你回滚）。

备份 / 恢复

./scripts/backup.sh PATH              # 停服务 → 归档 HelixDB + 数据 volume
./scripts/backup.sh PATH --include-key  # 同时加密备份 .env（passphrase）
./scripts/restore.sh PATH --replace    # 恢复（需要相同 ENCRYPTION_KEY）
./scripts/restore.sh PATH --replace --env-file OTHER_ENV  # 用不同密钥恢复

⚠️ 备份不含 ENCRYPTION_KEY，密码管理器里单独留一份 .env；丢了密钥 = 凭据无法恢复。

本地开发

pnpm install
./scripts/setup.sh
docker run -d --name helix-foundry-dev -p 127.0.0.1:6996:8080 \
  -e HELIX_DATA_DIR=/var/lib/helix -v helix-foundry-dev:/var/lib/helix \
  ghcr.io/helixdb/helixdb:v0.0.12@sha256:f22b50fdab8fadbf8b5a881e656f293fdf5c688bad018f503b8dbc2f0f29543d
pnpm dev
# 打开 http://localhost:5173（API: 3001，executor: 3002，web: 5173）
# 本地 AI 还需要 ollama serve（端口 11434）

⚠️ Node.js 24 + pnpm 10.7 硬约束。提交 PR 前跑：pnpm typecheck && pnpm test && pnpm build。

关键文档

文档 内容
AGENTS.md 给 Coding Agent 用的运行手册：preflight / setup / 验证 / 排错
docs/GUIDE.md 功能 / 连接器 / AI & 评审 / 架构 / 开发
docs/DESIGN.md 视觉规范 / UI tokens / 进度反馈 / 无障碍
docs/onboarding.md Onboarding API 路由 / SDK 方法 / 导入上限
docs/OPERATIONS.md 安装 profile / 诊断 / 变更捕获 / 备份 / 升级 / 上限
docs/HOSTING.md Neon / Supabase / PlanetScale 登录、scope、权限
docs/API.md REST API 参考 / 鉴权 / TypeScript SDK
docs/VALIDATION.md 2026 年 9–10 月的测试结果、benchmark、已知上限

数据源与本体（节选自 docs/GUIDE.md）

docs/GUIDE.md 把连接器拆成几类，能直接拼出对今天的实际启动计划：

  • 托管数据库：Neon / Supabase / PlanetScale 用 sign-in 流程授权；PostgreSQL / MySQL 用原生 discovery + 流式 snapshot ingestion；Neo4j 支持连接。
  • SaaS 凭据类：Stripe / WorkOS / PostHog 直接 OAuth 或 token。
  • 通用数据：REST API（分页自动跟随）、S3 兼容存储、CSV / JSON / JSONL / Parquet 上传、批量 ingestion API。
  • 同步 / 变更捕获：PostgreSQL / MySQL 在数据库允许时走原生 change capture，否则走定时 snapshot 刷新。
  • 本体：相同客户 / 记录在多源之间的映射存储为 HelixDB 真实对象与关系；带审计的 edit overlay 在重 materialisation 后仍保留。

四个工作区页

  • Home：用户关键指标（AI 从数据集 schema 自动挑）、连接状态、数据健康度、待办项、继续上次位置、本体概览；顶部输入框可直接问数据相关问题。
  • Ontology → Explorer：图 / 表两种视图查看记录与关联；Object types 列出已发布的业务类型。Find a record 全文搜索当前 workspace，最少两字符触发，最多显示 8 条匹配 + 总数；编辑记录需要 before / after 预览并显式 Apply。
  • Data：所有连接器汇总在 Add data 一处；打开数据集看 sample，Details 里看 schema、profile、version、lineage、export、连接设置；Snapshot 可查看当前 / 历史 / schema 变更的 pending rows。
  • Analyst：AI 问答支持，read-only，返回执行结果 + snapshot 引用，避免越权写回。

评审与安全要点

  • AI 提议的本体改动需先经过：evidence + query 预览 → 有界修复 → stale-proposal 检测 → 原子发布 → 定义回滚 五步；不会绕过预览直接落库。
  • 凭据用 .env 中的 ENCRYPTION_KEY 加密；API 强制 loopback host 检查 + Origin 检查，浏览器跨 origin 改动直接 403。
  • 工作区分级 API token 默认只读，可显式授予写权限；OpenAPI 在 /api/docs 和 /api/openapi.json。
  • Pipeline 编译为 DAG → SQL（也可直接编辑 SQL），有 before / after 预览；持久化 job 带 lease + 崩溃恢复。

典型适用场景

  • 个人 / 小团队的本地数据工作空间：不想交云数仓的钱，机器性能够（README 标注“16 GB 内存基准 benchmark”）。
  • AI 辅助本体建模：把跨源数据接到 HelixDB，AI 提议对象 / 关系映射，人工 review 后才生效。
  • 只读 / 受控的 SQL 问答：DuckDB executor 在无外网、无连接器凭据的内部网络里跑生成查询；适合“问一句 AI 我能在数据里找出啥”的探索场景。
  • 数据民主化 Demo / 内部工具：自带 Neon / Supabase / PlanetScale OAuth 流（见 docs/HOSTING.md），适合给非技术同事演示一个“AI 直接问数据”的 sandbox。
  • 多 schema drift 治理：通过不可变 Parquet snapshot + 历史版本回放 + pending review，处理跨源 schema 漂移。
  • 本地原型 + 长期归档：版本化数据 + 备份 / 恢复脚本 + Docker 一键拉起，适合“数据放在我这边、可审计、可回滚”的小型 BI 原型。

坑与注意

  • ⚠️ 本地优先 = 单用户：“为单人在自己的电脑上运行而设计，没有账号、没有登录”，任何能访问 app 的人都能控制所有 workspace。
  • ⚠️ 不要反向代理 / 隧道 / 端口转发到公网；README 反复强调 “never expose it”，且 API 会拒绝非本机 Host。
  • ⚠️ 磁盘 / 内存：首次约 2.5 GB；导入大文件时磁盘占用可达文件大小的数倍；16 GB 内存是基准，Ollama 模型需要额外给 Docker 让出内存。
  • ⚠️ 首次启动慢：镜像 + 模型 + HelixDB 拉取，第一次启动需要“几分钟”。
  • ⚠️ Windows 未测试：脚本需要 bash；CI 跑 Linux，README 标注 macOS Apple Silicon 是开发与验证目标。
  • ⚠️ 备份密钥分离：.env 里的 ENCRYPTION_KEY 必须单独存放；旧版 backup.sh 把 config.env 明文保存在 backups/，README 建议及时清理。
  • ⚠️ HelixDB 升级是单向的：回滚只能靠升级前那份备份。
  • ⚠️ docker compose down -v 会删光：workspace、导入数据、存下来的凭据，README 明确禁止随意执行。
  • ⚠️ 写作日当前主版本是 v0.0.12（README 开发命令里以 SHA256 锁住的镜像标签 @ v0.0.12@sha256:f22b50fdab8fadbf8b5a881e656f293fdf5c688bad018f503b8dbc2f0f29543d），HelixDB 自身仍处早期版本（README 主分类为 database，成熟度 research）。

与同类对比

维度 helix-foundry 云端数仓（Snowflake / BigQuery） 本地 Notebook（DuckDB CLI）
本机优先 / 不出网 ✅ ❌ ✅
多源自动接 + 本体化 ✅ 部分（依赖 ETL） ❌ 手工 SQL
AI 提建议 + 人工 review ✅ 部分 ❌
DuckDB executor 隔离 SQL ✅ 不需要 ❌ 直接跑
跨设备同步 ❌ 单机 ✅ ❌
开源 ✅ Apache-2.0 ❌ ✅（内核）
适合规模 个人 / 小团队 企业级 个人

一句话推荐结论

如果你想要一个 “把企业内部一堆 SaaS 数据接到本机、用 AI 提议统一本体、并保持数据不出本机” 的本地工作空间，helix-foundry 是当前最对路的选择（前提是你能接受首次约 2.5 GB 下载 + 16 GB 内存基线 + 单机单用户定位）；若是企业级数仓 / 跨团队协作 / 公网访问需求，仍应选传统云端方案。