HeyForm 3.0.6 介绍与选型指南
HeyForm 3.0.6 认知与选型：Node+Mongo+Redis 三容器开源表单构建器的版本脉络、架构、功能盘点、2026-11-02 GitHub API 社区数据实查，及与 OpnForm/Formbricks 的量化对比（含站内 Bitpoll/Fider 互链）。
HeyForm 3.0.6 介绍与选型指南
本文是 HeyForm 专栏的认知与选型篇。版本结论：截至 2026-11-02，HeyForm 官方最新稳定版为 v3.0.6（GitHub Release 发布于 2026-11-01，Docker Hub
latest与v3.0.6同 digest），自托管选型建议直接采用该版本并显式钉住 tag。文中社区数据均来自 2026-11-02 的 GitHub API 实查，资源占用等实测数据来自本地 v3.0.6 三容器栈（实测日期 2026-11-01/02）。
1. 一句话定位
HeyForm 是 Heyooo Inc. 出品的开源表单构建器（GitHub 仓库描述「Open-Source Form Builder」）：无需编码即可创建对话式（conversational）问卷、测评、报名表与投票，主打一次一题的沉浸式填写体验 + 条件逻辑 + Webhook/第三方集成 + CSV 导出，用 Node.js + MongoDB + Redis(KeyDB) 三件套即可完整自托管，适合替代 Typeform 等商业表单服务。官方站点 heyform.net，文档 docs.heyform.net。
2. 项目背景与版本脉络
| 事实 | 内容 | 来源（查询日期 2026-11-02） |
|---|---|---|
| 官方仓库 | github.com/heyform/heyform，描述「Open-Source Form Builder」 | GitHub API |
| 主办方 | Heyooo, Inc.（server 包 author 字段），官网 heyform.net | 镜像内 package.json 实测 |
| 开源协议 | AGPL-3.0 | GitHub API license 字段 |
| 仓库创建时间 | 2024-03-20 | GitHub API created_at |
| 主语言 | TypeScript | GitHub API |
| 最新版本 | v3.0.6，2026-11-01 发布（非 prerelease） | GitHub Releases API |
| 发布节奏 | v3.0.0(08-06)→v3.0.1(08-13)→v3.0.2(08-28)→v3.0.3(09-09)→v3.0.4(10-15)→v3.0.5(10-24)→v3.0.6(11-01)，约 1-3 周一个小版本 | GitHub Releases API |
| 镜像发布 | Docker Hub heyform/community-edition，latest 与 v3.0.6 一致 | 2026-11-01 查询（本地网络 11-02 访问 Docker Hub API 超时，沿用前日查询记录） |
| 商业模式 | 官方云（my.heyform.net）+ 开源社区版（AGPL），云版含更多企业功能 | 官方 README |
一个值得注意的信号：v3.0.x 系列近三个月连发 7 版、pushed_at 为 2026-11-01，项目处于活跃维护期；同时 open issues 仅 18 个，维护者对积压处理较快。
3. 架构与技术栈
3.1 组件构成
HeyForm 是 monorepo（packages/ 目录，GitHub API 实查）：
| 包 | 角色 |
|---|---|
server | Node.js 后端：NestJS 10.4 + Apollo Server 4.13（GraphQL）+ Mongoose + Bull 任务队列 |
webapp | 管理端 SPA（React），即登录后看到的表单编辑器/工作台 |
form-renderer | 公开表单页渲染器 |
embed | 表单嵌入式 JS 库（把表单嵌进自己的网站） |
shared-types-enums / utils / answer-utils | 前后端共享类型、工具与答案处理 |
运行时依赖三件套（本地实测）：
| 容器 | 镜像 | 实测版本 | 角色 |
|---|---|---|---|
| server | heyform/community-edition:v3.0.6 | Alpine 3.23.7 / Node v22.23.4，监听 9157 | GraphQL + REST + SPA |
| mongo | mongo:8.2 | mongod v8.2.12 | 主存储（26 个集合） |
| keydb | eqalpha/keydb:x86_64_v6.3.3 | redis_version 6.3.3 | Bull 队列 + 会话缓存（AOF 持久化） |
官方 compose 示例用 percona/percona-server-mongodb:4.4 与 eqalpha/keydb:6.3.3；本地用官方 mongo:8.2 同样跑通，说明对 MongoDB 大版本兼容面较宽。单容器资源占用（docker stats --no-stream，2026-11-02 实测）：server 159.2MiB / mongo 278.3MiB / keydb 15.7MiB——整个栈 <500MB，1 核 1GB 的小机器即可承载小规模使用。
3.2 API 面
- 管理面统一走 GraphQL（
POST /graphql），resolver 全景覆盖 form(24 个)/submission/integration/team/project/user/auth/endpoint/apps/template 等（镜像内dist/resolver/实测）。 - 少量 REST 控制器：
/health、/api/export/submissions（CSV 导出）、/api/upload、/api/image、/api/config、/logout等（镜像内dist/controller实测）。 - 安全护栏（实测）：所有登录态请求要求
x-device-id头与 session 内设备一致（DeviceIdGuard，缺失→403）；匿名提交端点要求x-anonymous-id；GraphQL 密码策略强制大小写+数字、≥8 位；内置限流（全局 1000/min、上传 30/min）。
4. 功能盘点（以 v3.0.6 实测为准）
- 字段类型：short_text/long_text/number/multiple_choice/rating/date/file upload/图片选择等 FieldKindEnum 全集（镜像内枚举实测；注意 kind 必须用枚举值，自造值会静默丢答案，见部署篇坑 3）。
- 三种表单模式：GENERAL=1 经典整页、INTERACTIVE=2 对话式（一次一题，Typeform 式）、POPUP=3 弹窗；表单类别 SURVEY/QUIZ/CONTACT。
- 条件逻辑与跳转：logics 草稿机制（
updateFormSchemas存草稿 →publishForm发布，version 不匹配报 INVALID_DRAFT_VERSION）。 - 主题定制：themeSettings、自定义 CSS、Google Fonts 开关；品牌 brandkitmodels 集合。
- 集成：内置 app 为 googlesheets / privatusanalytics / webhook（镜像
dist/apps/实测），REST resolver 支持 updateIntegrationSettings/Status、integrationRecords 重试记录等；webhook 出站默认禁止私网地址（SSRF 防护），ALLOW_PRIVATE_OUTBOUND=true才放行；Zapier/Make 经 webhook 桥接。 - 分析：formAnalytic（完成率/提交量，range 支持 7d/30d 等）、提交列表含 endAt/ip。
- 导出：CSV 下载（
GET /api/export/submissions?formId=），实测表头含每题列 + Start/Submit Date (UTC)。 - 团队/项目：createTeam 自动建默认 project，表单按项目组织，支持邀请成员。
- AI 建表：
createFormWithAImutation，配置OPENAI_API_KEY后启用。 - 其他：Stripe 收款表单、OIDC/Google/Apple 第三方登录、reCAPTCHA/Akismet 反垃圾、提交 IP 限制、隐藏字段/变量、多语言 translations。
5. 社区数据实查（2026-11-02，GitHub API）
| 指标 | HeyForm | OpnForm | Formbricks |
|---|---|---|---|
| Stars | 9,058 | 3,956 | 13,207 |
| Forks | 728 | 569 | 2,603 |
| Contributors | 48 | — | — |
| Open Issues | 18 | 23 | 165 |
| 主语言 | TypeScript | PHP (Laravel) | TypeScript |
| 协议 | AGPL-3.0 | 自定义（"OpnForm licensing"，API 报 NOASSERTION） | 混合（主体 AGPL-3.0，SDK 包 MIT，ee/ 目录单独授权） |
| 创建时间 | 2024-03 | — | 2022-06 |
| 最近推送 | 2026-11-01 | 2026-11-01 | 2026-11-01 |
三者均为活跃项目。OpnForm 是 Typeform 式对话表单 + Laravel 栈（PHP+MySQL/Redis），Formbricks 定位「开源 Qualtrics 替代」（体验管理，Next.js+Postgres，依赖更多）。
6. 量化对比与选型
6.1 与同类表单工具对比
| 维度 | HeyForm v3.0.6 | OpnForm | Formbricks |
|---|---|---|---|
| 表单体验 | 对话式一次一题为招牌，兼整页/弹窗 | 对话式，表单即页面 | 问卷/流程为主，嵌入式调研 |
| 运行时栈 | Node+MongoDB+Redis | PHP+MySQL+Redis | Next.js+Postgres+Redis 等 |
| 自托管依赖数 | 3 容器（实测 <500MB） | 4+ 容器 | 4+ 容器（含 MinIO 等） |
| 数据导出 | CSV 实测走通 | CSV/Excel | CSV + API |
| 集成 | webhook/Google Sheets/Plausible + Zapier/Make | 有限 | 原生渠道较多 |
| 协议对二次开发 | AGPL-3.0（网络分发需开源） | 自定义许可，需逐条审阅 | AGPL + EE 分层 |
| 适合场景 | 报名/问卷/测评/收集表，重交互体验 | 重表单美观+Laravel 团队 | 重调研逻辑/体验管理指标 |
注：「FformiX」经 GitHub 搜索无此项目，本节以任务所指的同类工具 OpnForm 与站内已收官的 Formbricks 作为对比对象。
6.2 与站内已收官生态组件互链
- 需要投票/日程协调而非表单收集：看 《Bitpoll 0.11.0 介绍与选型指南》（Django+PostgreSQL）。
- 需要用户反馈墙/需求收集板而非一次性表单：看 《Fider 介绍与选型指南》（Go+PostgreSQL）。
- 需要调研级逻辑与体验管理：看 《Formbricks 介绍与选型指南》。
- 轻量匿名投票备选：站内 Framadate 专栏（PHP 单栈）。
6.3 选型结论
适合：① 想要 Typeform 式对话表单但必须数据自持；② 已有 Docker 环境、希望 3 容器极简栈；③ 需要 webhook 实时把提交推给内部系统（实测 Bull 队列带 3 次重试与记录查询）；④ 中小团队报名表/问卷/内部测评。
不适合/谨慎：① 需要复杂调研方法论（配额、PII 合规、多渠道）→ Formbricks；② 对 AGPL 敏感且要闭源分发嵌入式产品 → 需商业授权或换栈；③ 需要多用户细粒度权限的企业管理 → 社区版团队功能相对基础；④ 官方文档更新滞后于代码（见部署篇端口坑），运维需以镜像实测为准。
7. 版本采用建议
- 钉住
heyform/community-edition:v3.0.6，不用latest（项目发版频繁，约 1-3 周一版）。 - MongoDB 用官方
mongo:8.2或示例的 percona 4.4 均可；Redis 侧 KeyDB 6.3.3 实测兼容（协议即 Redis）。 - 升级前备份：
mongodump --db heyform --archive --gzip实测 6KB 级、mongorestore --dryRun校验通过（见 CLI 篇）。
参考来源：GitHub API（heyform/heyform、OpnForm/OpnForm、formbricks/formbricks，2026-11-02 查询）；GitHub Releases（v3.0.0-v3.0.6）；官方 README 与 docs.heyform.net/self-hosting（2026-11-02 抓取）；本地 v3.0.6 三容器栈实测（2026-11-01/02，取证记录见专栏部署篇环境信息）。