OpnForm v2.8.1 介绍与选型指南

目标：从真实部署实例与官方仓库资料出发，讲清 OpnForm v2.8.1 的产品定位、技术架构、功能边界、许可模型与社区数据，并给出与 HeyForm、Formbricks、Bitpoll 的量化选型对比。社区数字取自 2026-11-02 GitHub API 实查，架构与功能结论均可在本专栏实测篇复现。

一、环境信息

本文全部实测数据来自以下真实环境（2026-11-01/02 部署）：

宿主：Linux x86_64（内网 IP 192.168.1.172），Docker 29.9.2（Docker version 29.9.2, build a82e528），Docker Compose v5.6.1
OpnForm：v2.8.1（容器内 APP_VERSION_DOCKER=2.8.1 实测），Laravel Framework 12.70.1，PHP 8.3.36，PostgreSQL 16.15，Redis 7
部署形态：官方 Docker Compose 七服务，对外端口 8161
演示账号：g25admin@example.com / G25test@12345
部署与运维细节：《OpnForm v2.8.1 Docker Compose 部署指南》、《OpnForm v2.8.1 配置参数详解》、《OpnForm v2.8.1 常用 CLI 命令与工具详解》

二、软件概述

2.1 一句话定位

OpnForm 是一个开源表单构建器（官方文档自述 "OpnForm is an open-source form builder"）：无需编码即可创建支持多页、条件逻辑、文件上传的在线表单，主打拖拽式表单设计 + 邮件/Slack/Discord/Webhook 集成 + AI 生成表单 + 数据分析，用 Laravel + Nuxt 双栈自托管，定位是 Typeform 等商业表单服务的开源替代。官方技术文档 docs.opnform.com，终端用户帮助站 help.opnform.com，产品主页 opnform.com。

2.2 项目渊源与社区数据

GitHub 仓库 OpnForm/OpnForm（2026-11-02 API 实查）：

指标	数值	来源
Stars	3957	GitHub API `stargazers_count`
Forks	569	GitHub API `forks_count`
Open Issues	23	GitHub API `open_issues_count`
Watchers/Subscribers	24	GitHub API `subscribers_count`
仓库创建时间	2022-09-20	GitHub API `created_at`
Docker 镜像发布者	`jhumanj/opnform-api`、`jhumanj/opnform-client`	官方 compose 文件

项目由 Jean-François Humeau（GitHub ID jhumanj）发起，monorepo 内含 api/（后端）、client/（前端）、docs/（Mintlify 文档站）三个主体目录（仓库 AGENTS.md 实测）。社区支持渠道：GitHub Issues/Discussions + 官方 Discord + Featurebase 功能请求板（README 徽章链接）。

2.3 许可与商业模式

⚠️ 许可证是选型时最容易看走眼的一项：README 徽章写 license-AGPLv3，但仓库根 LICENSE 文件实为 "OpnForm licensing" 双许可（GitHub API license 字段因此报 NOASSERTION）。原文三条边界（v2.8.1 仓库 LICENSE 逐字）：

api/app/Enterprise 目录下的内容适用该目录内单独的 LICENSE（企业许可）；
第三方组件沿用各自原始许可；
除上述目录外的其余代码适用 AGPLv3。

自托管许可边界（官方文档 introduction 与 cloud-vs-self-hosting 页）：核心功能无需 Enterprise license 即可免费自托管，免费实例含 OIDC 但限 2 用户；更多用户与进阶功能（见 4.4）需要激活自托管企业许可。商业模式为「OpnForm Cloud 托管服务 + 开源自托管 + 企业 License」三层。

2.4 版本与镜像

本批次钉住 v2.8.1：官方镜像走 latest 标签，版本以容器内 APP_VERSION_DOCKER 环境变量为准（实测 2.8.1）；更新路径为 docker compose pull && docker compose up -d（官方维护文档 docker.mdx）。
运行时底座实测版本：Laravel 12.70.1（php artisan --version）、PHP 8.3.36、PostgreSQL 16.15 (Debian 16.15-1.pgdg13+2)（artisan db:show 摘要段）。
官方 tech-stack 文档声明数据库支持 MySQL/MariaDB 与 PostgreSQL 两类；本专栏实测走 PostgreSQL 16（compose 官方默认）。

三、核心架构

3.1 技术栈

层	技术	实测/出处
后端	PHP 8.3 + Laravel 12（`api/`）	`artisan about`：Laravel Version 12.70.1 / PHP Version 8.3.36
前端	Vue 3 + Nuxt（SSR，`client/`）+ TailwindCSS	仓库 AGENTS.md 标注 Nuxt 4；容器内 `ui` 服务监听 3000
数据库	PostgreSQL（官方亦支持 MySQL/MariaDB）	`db:show`：PostgreSQL 16.15，44 张表
缓存/队列/会话	Redis	`artisan about`：Cache/Queue/Session 三驱动均 `redis`
入口	nginx（`ingress` 服务，路径分流）	`nginx.conf` 模板 + `NGINX_MAX_BODY_SIZE` 默认 64m
文件存储	本地卷 `opnform_storage`（S3 兼容为官方文档选项）	`artisan about`：`public/storage = LINKED`

3.2 七服务拓扑

官方 compose 把应用拆成 7 个服务（实测 docker compose ps 全部 healthy）：

服务	镜像	角色	healthcheck 判据
api	`jhumanj/opnform-api:latest`	Laravel REST API + OAuth/JWT	`php artisan about`
api-worker	同上	队列消费（`php artisan queue:work`）	`pgrep -f 'php artisan queue:work'`
api-scheduler	同上	定时任务（`php artisan schedule:work`）	`app:scheduler-status --mode=check --max-minutes=3`
ui	`jhumanj/opnform-client:latest`	Nuxt SSR 前端（:3000）	`wget --spider -q http://localhost:3000/login`
db	`postgres:16`	业务库（forge/forge）	`pg_isready`
redis	`redis:7`	缓存/队列/会话	`redis-cli ping`
ingress	`nginx:1`	唯一对外端口（本环境 8161→80）	`nginx -t && curl -f http://localhost/`

api/api-worker/api-scheduler 共享同一镜像与 api/.env，属「一镜像三角色」形态；排障时三者配置必须同步重建（详见 CLI 篇 4.1 与配置篇 3.2 的实测闭环）。

3.3 请求数据流

浏览器 → ingress（nginx，按路径分流）：/api/* 与 PHP 入口转发到 api 容器，其余（含公开表单页 /forms/<slug>）转发到 ui 容器做 SSR。
表单提交走 POST /api/forms/{slug}/answer，异步落库：请求先入 redis 队列，由 api-worker 消费后写 PostgreSQL（实测匿名提交返回 submission_id:null 属正常，约 5-8 秒后可查到记录）。
自托管模式注册专用健康端点 GET /api/healthcheck（api/routes.php 仅 self_hosted 时挂载），实测回显：

{"status":"ok","dependencies":{"database":true,"redis":true}}

一次请求同时验证 ingress→api→pgsql→redis 全链路，适合拨测。

3.4 认证与集成面

认证：JWT（POST /api/login 实测响应字段为 token、expires_in:86400，对应 JWT_TTL=1440 分钟），会话走 redis；自托管注册接口要求 hear_about_us 字段（实测缺失报 422）。
对外集成：Webhooks、Slack/Discord 通知、Zapier 入口（api-routes.php 路由实测存在）；开放 API POST /api/open/forms 可脚本化建表单（本专栏实测闭环）。
MCP/AI 草稿：路由层存在 mcp.enabled 中间件与 agent-drafts 系列端点（预览/交接/编辑器声明），配合 config('oauth.enabled') 走 MCP OAuth 会话——面向 AI 代理建表单的通道，自托管默认未激活。

四、功能特性

4.1 表单核心能力

官方文档 Features 清单（introduction.mdx，逐条核实）：

无代码构建器：表单/字段/提交数量不限量
输入类型：文本、日期、URL、电话、邮箱、单选/多选、下拉、数字、星级评分、文件上传等
单页或多页表单、条件逻辑（Form logic）、URL 预填、隐藏字段与表单密码
嵌入式部署（网站、Notion 页等）、自定义域名、可索引 SEO
邮件通知（表单所有者与填写者确认邮件）、Slack/Discord/Webhook 集成
验证码保护（默认 hcaptcha）、截止时间、提交数上限、可编辑提交、唯一提交 ID
表单模板库、数据分析、颜色/图片/自定义代码品牌化、去 OpnForm 品牌

4.2 AI 与自动化

AI 生成表单（"AI-powered form generation"）：官方特性列表项；数据库侧 ai_form_completions 相关迁移与 agent_form_draft_* 表实测存在（migrate:status 末条 2026_10_22_000000_add_agent_form_draft_version_history）。
REST API 自动化：本专栏实测跑通注册→登录→建工作区数据→建表单→提交→查询提交→CSV 导出全闭环（见部署篇 6 章）。

4.3 实测功能验证摘要

能力	实测方式	结果
建表单	`POST /api/open/forms`（枚举校验 presentation_style/width/size）	`{"type":"success","message":"Form created."}`，slug `g25-spqlvr`
公开页 SSR	`GET /forms/g25-spqlvr`	200，`<title>G25 反馈表单 - OpnForm</title>`
匿名提交	`POST /api/forms/g25-spqlvr/answer`	异步，5-8 秒后 psql 可查（实测 form_submissions=2）
CSV 导出	提交导出接口（完整命令见部署篇第六章闭环）	小数据量同步返回
健康检查	`GET /api/healthcheck`	status=ok，database/redis 全 true（原文见 3.3）

4.4 企业版功能边界

api/app/Enterprise 目录（单独许可）对应的官方文档功能页共 7 项：审计日志（audit-logs）、自定义代码（custom-code）、外部存储 S3（external-storage）、多工作区（multiple-workspaces）、单点登录 SSO（single-sign-on）、白标品牌化（white-label-branding）、工作区级自定义 SMTP（workspace-custom-smtp）。免费自托管（≤2 用户）不含这些；采购/激活路径见官方 license-activation 文档。

💡 技术拓展：许可分层与「同目录不同证」的写法在开源表单/问卷赛道是通行模式——Formbricks 用 ee/ 目录、HeyForm 用云版闭源。选型时不要只看 README 徽章，务必读仓库根 LICENSE 原文的目录边界条款；若需要闭源二次分发，AGPLv3 核心部分（网络交互条款 §13 同样要求向远端用户提供修改版源码）也需法务评估。

五、快速开始（最小可用示例）

以下五步全部在真实环境执行过（浏览器验收按本批次声明降级为 HTTP + <title> + API 闭环）：

# 1. 获取官方仓库与编排文件
git clone https://github.com/OpnForm/OpnForm.git
cd OpnForm

# 2. 起七服务（官方 compose + 本地端口覆盖到 8161）
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

# 3. 打开初始化向导，创建管理员（本例 g25admin@example.com）
#    浏览器访问 http://192.168.1.172:8161/setup
curl -s http://192.168.1.172:8161/setup | grep -o '<title>[^<]*</title>'
# <title>Setup - OpnForm - OpnForm</title>

# 4. 验证健康链路
curl -s http://192.168.1.172:8161/api/healthcheck
# {"status":"ok","dependencies":{"database":true,"redis":true}}

# 5. 登录后建第一个表单（枚举值按 4.1 校验规则）
curl -s -X POST http://192.168.1.172:8161/api/login -H 'Content-Type: application/json' \
  -d '{"email":"g25admin@example.com","password":"G25test@12345","remember":false}' | head -c 60
# {"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJod

setup 完成后 GET / 返回 200（不再 302 跳初始化页）。完整部署过程、端口覆盖写法与踩坑记录见《部署指南》；配置项含义见《配置参数详解》。

六、适用场景与限制

6.1 适用场景

替代 Typeform 的自建表单入口：营销活动报名、内部信息收集、文件上传类表单，无限量表单/提交，UI 现代（对话式/经典双呈现风格）。
合规隔离环境：官方 cloud-vs-self-hosting 文档明确点名 air-gapped/监管合规（如 HIPAA）场景——数据完全自持，本专栏实测全栈可跑在内网单宿主机（空闲态约 411MiB 内存，docker stats 实测）。
API 驱动的自动化：开放 API 可脚本化建表单、拉提交、导 CSV；另有 Webhook/Slack/Discord 出站集成与 MCP 草稿通道。
需要定制构建的团队：自托管支持自定义代码与 fork（官方对比表中这是自托管独占项）。

6.2 限制与风险

免费自托管限 2 用户：含 OIDC 但实例上限 2 人；多人协作需企业 License，评估成本时先数人头。
许可双轨：AGPLv3 核心 + api/app/Enterprise 专有目录，闭源分发或去品牌等进阶诉求要逐条对许可。
邮件默认不外发：MAIL_MAILER 默认 log（实测 artisan about Mail=log），通知类功能需自配 SMTP；工作区级 SMTP 属企业功能。
api 镜像缺 PHP intl 扩展：artisan db:show/db:table 打印摘要后必崩（实测 The "intl" PHP extension is required），库级巡检需绕行 psql——运维手册要预留替代路径。
单机 compose 无高可用：官方定位即单实例；HA/多区/自动备份在官方对比表里全部划归 Cloud 侧，自托管需自建。
latest 标签版本漂移：官方镜像主推 latest，升级前需按 APP_VERSION_DOCKER 记录当前版本（CLI 篇 4.1 的更新流程）。
上传体积受入口限制：nginx NGINX_MAX_BODY_SIZE 默认 64m，大文件场景需连同 PHP upload_max_filesize 链路一起调（配置篇 5.6 的四层链路实测）。

七、同类选型对比

7.1 候选说明

表单/问卷赛道站内已实测四个开源项目：OpnForm（本文）、HeyForm（对话式表单）、Formbricks（体验管理/XM，"开源 Qualtrics 替代"）、Bitpoll（轻量投票）。社区数据均为 2026-11-01/02 实查。

7.2 量化对比

维度	OpnForm v2.8.1	HeyForm 3.0.6	Formbricks	Bitpoll 0.11.0
Stars	3957	9058	13208	318
Forks	569	728	2603	—（站内篇未采）
Open Issues	23	18	166	—
仓库创建	2022-09-20	2024-03-20	2022-06-06	—
主语言	PHP(Laravel)+Vue(Nuxt)	TypeScript(NestJS)	TypeScript(Next.js)	Python(Django)
许可证	OpnForm licensing（AGPLv3 核心+Enterprise 目录）	AGPL-3.0	AGPLv3 核心+ee 目录（API 检测 NOASSERTION）	GPL-3.0
数据存储	PostgreSQL（亦支持 MySQL）+Redis	MongoDB+Redis	PostgreSQL+Redis	PostgreSQL（需独立提供）
自托管形态	7 容器，实测空闲约 411MiB	3 容器	多服务编排，依赖较多	官方仓库单 compose.yaml
功能重心	表单构建+集成+AI 生成	对话式表单+GraphQL API	多渠道体验管理/问卷方法论	投票征集
数据时点	2026-11-02 GitHub API	2026-11-02 GitHub API	2026-11-02 GitHub API	站内篇（2026-11-01）

7.3 选型建议

选 OpnForm：① 团队规模 ≤2 人（免费自托管甜区）或愿意购买企业 License；② 偏好 PHP/Laravel 技术栈、需要 fork 定制；③ 表单形态要经典页面与对话式兼顾，且要吃 AI 生成表单/Webhook 集成的现成能力。

选 HeyForm：一次一题的对话式体验优先、Node/Mongo 栈更顺手、纯 AGPL-3.0 许可边界更干净（站内实测篇：《HeyForm 3.0.6 介绍与选型指南》）。

选 Formbricks：需求超出「收表单」——要链接/网站/应用内多渠道投放、XM 指标体系、配额与合规类调研方法论（站内实测篇：《Formbricks 介绍与选型指南》）。

选 Bitpoll：只需要会议时间/选项投票，2-3 容器极简部署（站内实测篇：《Bitpoll 0.11.0 介绍与选型指南》）。

八、参考链接

官方文档站（部署/API/许可）：https://docs.opnform.com
GitHub 仓库：https://github.com/OpnForm/OpnForm
官方 Docker 部署与维护：https://docs.opnform.com/deployment/docker
云版 vs 自托管官方对比：https://docs.opnform.com/deployment/cloud-vs-self-hosting
自托管许可说明：https://docs.opnform.com/deployment/self-hosted-license
产品主页与定价：https://opnform.com
站内配套：《OpnForm v2.8.1 Docker Compose 部署指南》、《OpnForm v2.8.1 配置参数详解》、《OpnForm v2.8.1 常用 CLI 命令与工具详解》
同类实测：《HeyForm 3.0.6 介绍与选型指南》、《Formbricks 介绍与选型指南》、《Bitpoll 0.11.0 介绍与选型指南》