Formbricks 开源调研平台技术指南：核心架构、自托管部署与本地开发全解

Formbricks 开源调研平台技术指南核心架构、自托管部署与本地开发全解【免费下载链接】formbricksOpen Source Qualtrics Alternative项目地址: https://gitcode.com/GitHub_Trending/fo/formbricksFormbricks 是一款免费开源、隐私优先的体验管理Experience Management, XM与调研平台定位为 Qualtrics 的开源替代品允许你在用户旅程的每个触点以应用内in-app、网站website、链接link和邮件email四种调研形态收集用户反馈。本篇指南以仓库 README.md 为主线结合 monorepo 源码与 Docker 编排文件系统讲解其核心能力、技术架构、一键自托管、生产级 Docker 部署以及本地开发环境搭建帮助你快速掌握从跑起来到按需定制的完整链路。项目定位与使命Formbricks 的使命是赋能你的团队打造令人无法抗拒的体验Empower your team, craft an irresistible experience。它同时是免费开源的调研平台通过无代码编辑器即可创建转化优化的调研问卷并提供多种题型与最佳实践模板。隐私优先的体验管理平台支持将调研精确投放给特定用户群体而无需改动应用代码既可以基于 Formbricks 自带的分析能力Insight Platform / Formbricks Hub消费数据也可以完全自建分析栈。仓库采用 AGPLv3 许可证开放核心核心应用包含设计并运行链接调研、网站调研与应用内调研所需的全部功能个人与商业使用均免费修改分发需注明变更并同样以 AGPLv3 发布。详见下文许可证一节。核心功能特性README 列出的核心能力均可从仓库模块结构中得到印证特性说明仓库佐证 无代码调研编辑器多种题型、可视化拖拽编排apps/web/modules/survey325 个文件含编辑器 UI 与题型实现 最佳实践模板库开箱即用的调研模板packages/types/templates.ts 定义模板类型 定向投放面向特定用户群体投放无需改应用代码apps/web/modules/segment 相关实现Playwright 侧 apps/web/playwright/segments.spec.ts 可分享链接调研生成独立链接分享投放docs/surveys/link-surveys 文档目录 组织协作邀请组织成员协作共建调研apps/web/modules/workspaces 与 packages/types/memberships.ts 生态集成Slack、Notion、Zapier、n8n 等apps/web/modules/integrations 与 docs/platform/features/integrations 开源自托管全透明、可自托管本仓库 Docker 体系见下文此外从仓库还可以看到更多深度能力多语言调研apps/web/locales 提供 15 种语言包、基于 SpiceDB/AuthZed 的细粒度权限模型authzed/schema.zed、AI 反馈分类与主题聚合Formbricks Hub、以及 XM Suite v5 分析Cube见 docker/cube。技术栈与 Monorepo 架构README 明确列出的技术栈为TypeScript、Next.js、React、TailwindCSS、Prisma、Auth.js、Zod、Vitest。对照仓库实际依赖package.json、pnpm-workspace.yaml当前版本细节如下包管理器pnpmpackageManager: pnpm11.7.0构建编排Turborepoturbo: 2.9.14任务图见 turbo.jsonWeb 应用Next.js16.2.11apps/web/package.json开发模式使用next dev --turbopackUIReact19.2.x、TailwindCSS4.x、Radix UI 组件族数据层Prisma7.8.0schema 位于 packages/database/schema208 个迁移文件在 packages/database/migration校验Zod4.3.x并用于 OpenAPI 规范生成docs/api-v3-reference/openapi.yml测试Vitest4.1.6单元/集成与 Playwright1.58.2E2Espec 位于 apps/web/playwright认证Better Auth1.7.0 SAMLboxyhq/saml-jackson另有 OTPotplib、OAuth provider授权AuthZedSpiceDBv1.52.0通过authzed/authzed-node客户端访问工作区结构pnpm-workspace.yaml声明了apps/*、docker、packages/*三类工作区并维护一份**依赖目录catalog**作为多包共享依赖版本的单一事实来源scripts/check-catalog.mjs由pnpm lint强制执行。主要成员apps/web主应用Next.js涵盖(app)、(auth)、api、modules、playwright、lib等子目录packages/databasePrisma schema、迁移与 Zod 校验zod/packages/surveys、packages/survey-ui问卷运行时与 UI 组件库前后端共享packages/js-core浏览器 SDK 核心配合 packages/types/formbricks-surveys.ts 等类型packages/ai、packages/jobs、packages/email、packages/storage、packages/loggerAI、任务队列、邮件、对象存储、日志等横切能力packages/workflows工作流编排。turbo.json中定义了build、dev、lint、typecheck、test、db:setup等任务及依赖顺序例如formbricks/web#dev会先构建ai/cache/database/jobs/logger/storage包再启动 Web 应用typecheck依赖formbricks/database#generate先执行prisma generate。快速开始两条路径README 为不同诉求的用户提供了两条路径☁️ 云端托管版Formbricks 提供带慷慨免费额度的托管云服务formbricks.com注册后即可直接开始创建调研适合希望零运维快速上手的团队。 自托管版核心应用以 AGPLv3 开源无需订阅即可使用 Docker 在自己的服务器上托管。仓库中的自托管体系非常完整详见 docker/README.md一键安装脚本docker/formbricks.sh 自动完成系统依赖安装、Docker 安装、域名与 HTTPS 配置、.env密钥生成、Traefik 反向代理配置等全流程生产 Composedocker/docker-compose.yml开发 Composedocker-compose.dev.yml含 MailHog、ValKey、RustFS 等本地依赖。一键自托管formbricks.sh 实战docker/formbricks.sh 是 README 推荐自托管方式的核心载体脚本内install_formbricks()实现了完整安装流程其交互式流程如下环境准备检测 Ubuntu 版本apt-get安装ca-certificates、curl、jq、lsb-release若未安装 Docker 则询问是否移除旧包后安装docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin并复用已有的 Docker 安装与守护进程录入域名输入应用域名推荐surveys.example.com不要带协议前缀HTTPS 配置询问是否由 Lets Encrypt 自动签发证书默认 Y需域名已解析到服务器 IP 且开放 80/443 端口、邮箱地址、是否启用 HSTS邮件服务可选填写 SMTP 主机、端口、用户名、密码及SMTP_AUTHENTICATED/SMTP_SECURE_ENABLED开关文件上传可选配置对象存储——外部 S3 兼容服务AWS S3 / DO Spaces 等或内置 RustFSS3 兼容对象存储含最小权限服务账号、CORS、上传策略自动初始化逻辑见 docker/rustfs-init.sh生成密钥并写入.envopenssl rand -hex 32生成NEXTAUTH_SECRET、ENCRYPTION_KEY、CRON_SECRET、POSTGRES_PASSWORD、HUB_API_KEY、CUBEJS_API_SECRET、AUTHZED_TOKEN、AUTHZED_DATABASE_PASSWORD.env文件权限收紧为0600生成 Traefik 配置写出traefik.yamlweb/websecure 入口、ACME 证书解析器、HSTS 中间件与traefik-dynamic.yamlTLS 1.2 强密码套件、曲线偏好、sniStrict: true、ALPN h2/http1.1/acme-tls并为formbricks与hub服务注入路由标签含/api/v3/feedbackRecords网关转发规则。安装完成后访问域名即可看到 Formbricks 首页引导向导。生产环境建议手动安装时至少在.env中为POSTGRES_PASSWORD、HUB_API_KEY、CUBEJS_API_SECRET、AUTHZED_TOKEN、AUTHZED_DATABASE_PASSWORD设置唯一随机值docker compose config可校验 Compose 语法并在缺少POSTGRES_PASSWORD时直接报错。生产 Docker 编排详解docker/docker-compose.yml 定义了完整生产栈以 docker/README.md 描述为准PostgreSQLpgvector 镜像Hub 向量能力依赖POSTGRES_PASSWORD初始化后不可再变更数据卷已初始化连接串使用POSTGRES_PASSWORD_URL_ENCODED配套值Formbricks Web镜像为ghcr.io/formbricks/formbricks构建过程见 apps/web/Dockerfile——多阶段构建pnpm install --frozen-lockfile、通过 BuildKit 密文挂载注入DATABASE_URL等构建期密钥运行镜像以非 root 的nextjs用户启动并内置启动期 Prisma 迁移formbricks-migrate / hub-migrate每次docker compose up都会运行且幂等——前者执行 Formbricks 的 Prisma 迁移后者用 goose river 写入 Hub 表Formbricks Hubghcr.io/formbricks/hub反馈记录 API默认与 Formbricks 共用数据库HUB_API_URL默认http://hub:8080图片标签默认:latest与主应用同步推进Cubecubejs/cube:v1.6.6XM Suite v5 分析引擎JWT issuer/audience 默认formbricks-web/formbricks-cube默认CUBEJS_EXTERNAL_DEFAULTfalse单副本内存缓存无需 Cube Store如需外部预聚合请先自建 Cube Store 再覆盖该变量SpiceDB权限服务见下节Traefik反向代理 TLSexposedByDefault: false仅对打标签的服务生效。AuthZed / SpiceDB 权限引擎生产与开发 Compose 均内置 SpiceDBv1.52.0使用 PostgreSQL 内专用spicedb库与账号启动链authzed-db-bootstrap幂等创建/更新凭据→spicedb-migratedatastore migrate head应用迁移→spicedbservegRPCspicedb:50051通过SPICEDB_GRPC_PRESHARED_KEY即AUTHZED_TOKEN认证生产密钥AUTHZED_TOKEN与AUTHZED_DATABASE_PASSWORD用openssl rand -hex 32生成并保存在0600权限的.env中SpiceDB 不对外暴露不通过 Traefik 发布运维命令见 docker/README.md 与 docs/self-hosting/advanced/authzed-operations.mdxpnpm authzed:smoke仓库开发环境的隔离持久化测试实为bash docker/authzed-smoke.shdocker compose --profile authzed-ops run --rm authzed-ops health只读健康检查仅健康连接时以0退出docker compose --profile authzed-ops run --rm authzed-ops schema check/schema apply --expected-current-digest sha256:digest非空实例必须先 check 取得 digest 再 applydocker compose --profile authzed-ops run --rm authzed-ops backfill关系数据回填审计dry runupgrade prepare/upgrade checkv6 迁移就绪门禁配置语义AUTHZED_ENABLED/AUTHZED_INSECURE接受true/false/1/0AUTHZED_ENDPOINT为裸host:port无 scheme/pathAUTHZED_CONSISTENCY默认fully_consistent。Schema 源文件为 authzed/schema.zed校验脚本见 authzed/validate.sh。注意捆绑 PostgreSQL 的track_commit_timestamp保持默认off因此 SpiceDB 会记录 Watch API 不可用schema、关系与权限检查 API 不受影响未来若要消费 Watch API 需显式开启该参数并重启。可选增强组件Qwen/vLLM 与 AI Taxonomy生产 Compose 通过 Compose profiles 提供两个可选 AI 组件基线docker compose up不会启动它们不影响无 AI 运行Qwen/vLLMCOMPOSE_PROFILESqwen——在栈内运行 Qwen 大模型暴露 OpenAI 兼容/v1端点。.env示例COMPOSE_PROFILESqwen AI_PROVIDERopenai-compatible AI_MODELqwen3-14b-awq AI_OPENAI_COMPATIBLE_BASE_URLhttp://vllm:8000/v1 AI_OPENAI_COMPATIBLE_PROVIDER_NAMEvllm AI_OPENAI_COMPATIBLE_SUPPORTS_STRUCTURED_OUTPUTS1可选覆盖项QWEN_VLLM_IMAGE、QWEN_MODEL_ID默认Qwen/Qwen3-14B-AWQ、QWEN_SERVED_MODEL_NAME、QWEN_MAX_MODEL_LEN8192、QWEN_MAX_NUM_SEQS8、QWEN_GPU_MEMORY_UTILIZATION0.9、QWEN_VLLM_PORT8000。前提具备 NVIDIA GPU 的 Docker 主机并安装 NVIDIA Container Toolkit模型缓存于qwen-model-cache卷。若自建 vLLM 端点则不要启用该 profile直接设置AI_PROVIDER、AI_MODEL、AI_OPENAI_COMPATIBLE_BASE_URL指向自己的端点。AI TaxonomyCOMPOSE_PROFILEStaxonomy——AI 主题分类 Beta 服务ghcr.io/formbricks/taxonomy。可共享捆绑 QwenCOMPOSE_PROFILESqwen,taxonomy或指向自建 OpenAI 兼容端点也可切到 Amazon BedrockTAXONOMY_LLM_PROVIDERbedrockAWS_REGIONAWS_BEARER_TOKEN_BEDROCK或 Vertex AI GeminiTAXONOMY_LLM_PROVIDERvertex-gemini 项目/位置/凭据。密钥采用服务端单向接线Web 只持有HUB_API_KEYtaxonomy 服务凭据不会到达 Web。TAXONOMY_MAX_RECORDS默认50000作为高级安全上限仅在评估 CPU/内存/LLM 容量后覆盖。启动后可执行带 token 的/v1/preflight校验内部认证与 LLM 连通性。本地开发环境搭建README 给出的前提为 Node.js18.x、pnpm 与 Docker用于 PostgreSQL 与 MailHog。对照仓库实际声明package.json 的engines字段当前仓库要求 Node20.19.0 21 || 22.12.0 23 || 24.0.0 25apps/web/Dockerfile 亦使用node:24-alpine3.23请以仓库为准。推荐的本地启动流程对应根目录 package.json 脚本# 1. 安装依赖根目录 pnpm install # 2. 启动开发基础设施PostgreSQL(pgvector)、SpiceDB、MailHog、ValKey、RustFS、Hub、Cube pnpm db:up # 等价于 pnpm dev:setup docker compose -f docker-compose.dev.yml up -d # 或拆分执行pnpm dev:setup 生成 .env 密钥pnpm db:down 停止基础设施 # 3. 启动全部工作区的开发服务Next.js 默认 :3000 pnpm dev # turbo run dev --parallel # 或一次性拉起pnpm go pnpm db:up turbo run go --concurrency 20开发栈要点见 docker-compose.dev.yml 与 docker/README.mdPostgreSQL 预载vector扩展shared_preload_librariesvector用于 Hub 向量检索MailHog 提供本地邮件捕获Web UI:8025SMTP:1025ValKeyRedis 兼容--maxmemory-policy noeviction承担缓存与队列packages/cacheRustFSrustfs/rustfsS3 API:9000Web 控制台:9001承担本地对象存储rustfs-init通过 docker/rustfs-init.sh 幂等初始化 bucket、CORS、最小权限策略与服务账号Hub 使用独立本地hub库HUB_API_KEY默认dev-api-key启用 Hub embeddings 需在仓库根.env设置EMBEDDING_PROVIDER、EMBEDDING_MODEL及对应凭据embeddings、sentiment/emotions/translation 等富化能力默认关闭须同时配置 API 与 worker 两侧本地可直接访问http://localhost:3000含/api/v3/feedbackRecords应用级代理路由与 Cube Playground4001可选docker compose -f docker-compose.dev.yml --profile authzed-ui up -d authzed-ui启动 gRPCui 浏览器调试界面http://127.0.0.1:50052仅开发环境。其他常用脚本根目录 package.jsonpnpm db:migrate:dev # 生成并应用 Prisma 迁移 pnpm db:migrate:deploy # 生产迁移 pnpm db:seed # 填充种子数据需 ALLOW_SEED pnpm lint # ESLint OpenAPI v3 lint catalog 校验 pnpm typecheck # 全工作区类型检查含 prisma generate pnpm test # turbo run testVitest pnpm test:e2e # Playwright E2E pnpm storybook # 组件文档 pnpm i18n # 生成并校验多语言资源 pnpm authzed:schema / authzed:backfill / authzed:health / authzed:perf # AuthZed 相关工具许可证AGPL 核心与 Enterprise 版README 的 License 章节在仓库中有精确落点AGPLv3 核心核心应用完整可用涵盖链接调研、网站调研与应用内调研的设计与运行允许个人与商业免费使用允许修改与再分发需注明变更内容与日期且修改版必须以 AGPLv3 发布Enterprise 版仓库内 apps/web/modules/ee 目录下的代码按企业许可apps/web/modules/ee/LICENSE提供面向大型团队与企业需求其内容同时已包含在 Docker 镜像中但需企业许可密钥解锁——生产使用需与 Formbricks 订阅条款一致并为正确数量的席位付费开发者可免订阅复制并修改该代码用于开发与测试白标与特殊授权README 明确当前不提供白标white-label销售授权即不允许其他公司以自有品牌转售 Formbricks 或将调研编辑器等部分抽取进自有产品。安全策略与漏洞披露SECURITY.md 是 README 安全章节的完整展开要点包括报告渠道请私发邮件至securityformbricks.com不要提交公开 GitHub issue公开即泄露响应时限48 小时内确认收悉验证与修复后按严重程度在 728 天内部署修复报告要素问题描述、可复现步骤尽量附截图、受影响版本、已知缓解措施、首选联系方式不设赏金Formbricks 明确不提供 bug bounty也不接受发票/付款要求但可按需在发布说明中署名致谢年度渗透测试由独立第三方执行关键漏洞优先处理并向相关方透明沟通。参与贡献README 列出的参与方式Star 仓库、创建 issue 反馈缺失或异常之处、为 issue 点赞以影响路线图优先级。当前阶段代码贡献仅作例外受理。完整贡献规范见 CONTRIBUTING.md开发规范见 AGENTS.md 与 CLAUDE.md。小结Formbricks 是一个调研即基础设施的开源项目前端是 Next.js React 的无代码编辑器与多形态投放中间是 Prisma PostgreSQL SpiceDB 的数据与权限底座外围是 Hub反馈记录 AI 富化、Cube分析与 RustFS存储等可插拔组件全部通过 pnpm workspace Turborepo 统一编排。无论你想快速跑一个 SaaS 调研平台还是希望基于 packages/js-core 构建自有反馈体系本文覆盖的 README 主线与仓库证据都能作为可靠的起点。【免费下载链接】formbricksOpen Source Qualtrics Alternative项目地址: https://gitcode.com/GitHub_Trending/fo/formbricks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考