Hexclave 开源用户基础设施平台全面解析:从 Auth 到支付、邮件与分析的一体化用户栈
Hexclave 开源用户基础设施平台全面解析:从 Auth 到支付、邮件与分析的一体化用户栈
Hexclave 是一个以"用户基础设施"(user infrastructure)为核心定位的开源平台,覆盖认证、团队、RBAC、支付、邮件、分析等全套用户相关能力,并以"应用目录"的形式按需开启。本文以仓库根目录 README.md 为主体,结合源码与配置,系统讲解它的功能边界、Agent-first 集成方式、十大核心应用(Apps)以及底层实现,帮助你快速判断是否值得引入并掌握它的使用方式。
项目定位:你选择前端、后端与数据库,其余交给 Hexclave
README 开篇即给出清晰定位:The user infrastructure platform(用户基础设施平台)。它围绕"用户"这一核心实体,一站式提供认证(authentication)、团队(teams)、支付(payments)、邮件(emails)、分析(analytics)等能力,并声明"new apps land regularly"(新应用会持续加入)。从仓库描述看,其哲学是:前端框架、后端语言、数据库选型都由你决定,而用户相关的基础设施——身份、登录、组织、计费、订阅、交易邮件、用户分析——由 Hexclave 统一承担,避免在 Auth0、Stripe、Resend、Segment 等多家服务之间手工拼接。
该定位在 README.md 中通过一张架构图直观展示,说明 Hexclave 在基础设施栈中所处的位置——介于你的应用与各类底层服务之间,把用户侧能力收拢为一个统一平台。
从仓库结构可以进一步验证这一定位:根目录是一个标准 pnpm + Turborepo 的 monorepo(见 package.json 与 pnpm-workspace.yaml),其中 apps/backend 承载全部 REST API 与业务逻辑,apps/dashboard 是管理后台,packages/* 发布面向不同框架的 SDK 与 CLI,examples/* 提供从 React、Next.js 到 Convex、Supabase、TanStack Start 的集成示例。README 所述的"一个用户模型驱动所有应用"在 packages/shared/src/apps/apps-config.ts 中得到印证:所有 App 共享同一套 AppId 类型与依赖声明体系。
Agent-first:一条 Prompt 完成集成
Hexclave 最鲜明的特色是面向 AI 编码 Agent 设计的集成体验。README 给出了两条核心路径:
- 人类开发者:把下面这段提示词粘贴给任意 coding agent,即可在项目中完成接入:
Read skill.hexclave.com and help me setup hexclave in this project
- AI 编码 Agent:使用 web fetch 工具或 curl 拉取技能文档,获取最新的集成指令:
curl -sSL "https://skill.hexclave.com?question=<your-question>&context=<your-context>"
<question> 与 <context> 两个参数让 Agent 可以携带具体问题与项目上下文,获取针对性指引。这一机制在仓库中有完整落地:skills/hexclave/SKILL.md 定义了名为 hexclave 的 Agent 技能(skill),其工作机制是每次调用都从 https://skill.hexclave.com 拉取最新指令,并把响应体视为权威依据——"它取代任何来自记忆或训练数据的 Hexclave 知识"。也就是说,技能正文本身是远程动态下发的,仓库里的 SKILL.md 只是一个指针,这保证了 Agent 拿到的始终是最新集成文档,而不是过时缓存。
如果你希望在本地开发环境中启动整套服务,仓库根目录 package.json 提供了对应的开发脚本(如 pnpm dev、pnpm start-deps),它们会通过 Docker Compose 拉起 Postgres、ClickHouse 等依赖(见 docker/dependencies/docker.compose.yaml)。值得注意的是,README 将"curl 技能文档"作为官方推荐的 Agent 接入方式,这说明它的文档体系本身就是为机器可读、可检索而设计的。
Apps 目录:按需开启的功能应用
README 的核心叙事是"Hexclave ships as a catalog of apps you switch on as your product needs them"——它不是一个臃肿的巨石框架,而是一个应用目录,产品需要什么就点亮什么。每个应用构建在同一个用户模型之上,因此天然互通。
这一设计在 packages/shared/src/apps/apps-config.ts 中有非常明确的代码级定义。每个 App 都带有一组元数据:
displayName/subtitle:展示名称与一句话描述;stage:成熟度标记,取值为alpha/beta/stable。从源码看,Authentication、Teams、RBAC、API Keys、Payments、Emails、Webhooks、Analytics、Launch Checklist 均处于stable,Data Vault 为beta,而 Workflows、TV mode、Neon 集成等处于alpha;tags:用于目录分类,如auth、security、comms、operations、developers、storage等;softRequirements:软依赖。例如teams软依赖authentication,payments同样软依赖authentication。expandAppSoftRequirements函数会把软依赖递归展开为完整集合——这意味着开启 Teams 时系统会建议同时具备认证能力,但这些依赖是"软"的,开发者仍然可以独立禁用某个被推荐的应用;parentAppId:父子归属关系。例如fraud-protection、onboarding归属于authentication,clickmaps、session-replays归属于analytics,源码中getParentAppId函数专门用于解析这种归属。
这种"目录式"组织方式让 README 中"一个用户模型 + 可插拔应用"的产品叙事有了具体的实现骨架,也解释了为什么新增应用可以"regularly"落地——只需在配置表中登记一条新记录,并配套对应的 API 路由即可。
十大核心功能深度解析
README 用十个应用卡片逐一说明了平台能力,下面结合后端源码逐一展开。所有 REST API 路由集中在 apps/backend/src/app/api/latest 目录下,按功能模块组织,可以直接作为功能的实现证据与二次开发参考。
1. Authentication:Passkeys、OAuth 与 CLI 认证的开箱即用
README 的描述是"认证开箱即用,支持 passkeys、OAuth 与 CLI 认证,放入一个组件即可跑完整流程,认证方式从 Dashboard 开关切换,无需改动代码"。
从 apps/backend/src/app/api/latest/auth 目录的完整路由清单可以确认,认证层覆盖了现代应用所需的几乎所有方式:
- Passkeys:
passkey/initiate-passkey-registration、passkey/initiate-passkey-authentication、passkey/register、passkey/sign-in——注册与登录均走独立的 initiate/verify 两步流程; - OAuth:
oauth/authorize、oauth/callback、oauth/connected-accounts、oauth/token,并按 provider 划分(如 Apple),还包含跨域授权的oauth/cross-domain; - 密码:
password/sign-up、password/sign-in、password/reset、password/send-reset-code、password/set、password/update,重置流程带验证码(verification-code-handler); - OTP:
otp/send-sign-in-code、otp/sign-in/check-code; - MFA:
mfa/sign-in及配套的验证码处理; - CLI 认证:
cli、cli/complete、cli/poll——完成设备/命令行场景的登录轮询; - 匿名用户:
anonymous/sign-up; - 会话管理:
sessions、sessions/[id]、sessions/current/refresh,提供会话列表、单条会话管理与会话刷新能力。
README 强调的"从 Dashboard 开关切换认证方式、不改代码"意味着:OAuth provider、MFA 开关、passkey 策略等都属于项目配置,前端统一通过 SDK 呈现。这也正是应用目录 + 配置驱动的架构优势所在。
2. Teams:面向团队而非单人的协作模型
README 的要点:为团队(而非仅个人用户)构建,提供工作区(workspaces)、邮件邀请(email invites)与真正起拦截作用的角色;工作区切换器会记住选择,邀请会自动为被邀请者注册账号,权限体系经得起审计。
对应后端实现位于 apps/backend/src/app/api/latest/teams、team-invitations、team-memberships、team-member-profiles:
- 团队本体的增删改查(
teams/route.tsx、teams/[team_id]/route.tsx); - 邀请的完整生命周期:
team-invitations/send-code发送邀请码、team-invitations/accept(含check-code、details两步确认)——邀请接受即触发账号注册,正是 README 所说"invites auto sign up new users"的实现; - 成员关系与成员资料:
team-memberships、team-member-profiles; - 权限部分(见下一节 RBAC)与团队强绑定:
team-permissions、team-permission-definitions。
"权限经得起审计"体现在权限并非简单的布尔标记,而是独立的定义表(*-permission-definitions)与赋值表(*-permissions)分离,便于追溯谁在什么条件下拥有什么权限。
3. RBAC:可嵌套角色与前后端一致的权限检查
README 的说法非常精炼:"角色可以嵌套,一次权限检查在服务端和客户端行为一致;在 Dashboard 定义权限,在代码任何位置检查"。
实现上,RBAC 分为项目级与团队级两套平行的定义/赋值模型:
- 定义端:project-permission-definitions 与 team-permission-definitions,用于声明权限点与角色;
- 赋值端:project-permissions(按 user_id 与 permission_id 管理)与 team-permissions(按 team_id 与 user_id 管理)。
"同一套权限检查服务端客户端通用"在 SDK 侧表现为:权限定义(permission definitions)作为一种共享类型同时存在于前后端,配合 -definitions 表做到单点定义、多处引用。角色嵌套的能力则来自定义表支持角色之间的层级引用。在应用目录配置(apps-config.ts)中,RBAC 的软依赖同样是 authentication,即基于认证体系之上构建授权体系。
4. API Keys:防泄露的密钥管理
README 列出的 API Keys 特性相当有安全意识:泄露的密钥自动吊销、密钥同时适用于用户和团队维度、完整密钥只展示一次、平台从不保存明文。
实现位于 apps/backend/src/app/api/latest/(api-keys)):
user-api-keys与team-api-keys两套平行的 CRUD 路由,外加check路由用于密钥有效性校验,分别对应 README 所说的"works for users and teams";handlers.tsx集中实现密钥的生成、哈希存储与校验逻辑;- 密钥泄露检测与自动吊销在 README 的
integrations路由中能找到佐证:integrations/credential-scanning/revoke 暴露了"凭据扫描 → 吊销"的联动入口,即当密钥被公开仓库扫描到后可以触发撤销。
"完整密钥只显示一次、不保存明文"是密钥类产品的标准安全实践(生成时返回明文、仅存哈希),与仓库中哈希校验的 handler 结构相符。
5. Payments:订阅、一次性收费与用量计费
README 对支付的定位是"免去计费管道(plumbing)",覆盖订阅、一次性收费、带额度的用量计费(usage metering with credits),并且"为个人或整个团队计费只用同一套模型,无两套代码路径"。
后端路由位于 apps/backend/src/app/api/latest/payments,粒度非常细:
products/[customer_type]:商品定义;items/[customer_type]:账单条目;billing/[customer_type]:计费会话;invoices/[customer_type]:发票;payment-method/[customer_type]:支付方式管理;purchases/:包含create-purchase-url、purchase-session、validate-code,支持外部支付链接与购买会话验证。
值得注意的细节:路由按 customer_type 区分,这正对应 README 中"Bill a person or a whole team with one model"的设计——同一套支付 API 以顾客类型为维度复用,而不是为用户与团队各写一套。底层支付通道通过 integrations/stripe/webhooks 与 Stripe 对接,账单、订阅、退款等事件在此入口被消费并回写业务模型。
6. Emails:事务邮件与营销邮件一个 API
README 的卖点:事务型与营销型邮件从同一个 API 发出;用 AI 编辑器改模板、一次主题定制全局生效;追踪每一次打开与点击。
后端实现集中在 apps/backend/src/app/api/latest/emails:
send-email:统一发送入口;render-email:模板渲染,支持服务端生成邮件正文;outbox:发件箱队列(含[id]详情),事务邮件与营销邮件共用;delivery-info:送达信息查询;unsubscribe-link与配套verification-handler:退订链路;notification-preference:按用户与通知分类管理偏好;capacity-boost:发送容量管理。
"AI 编辑器"与"主题一次定制"在后台配套的管理接口中体现:Dashboard 侧有 internal/email-templates、internal/email-themes、internal/email-drafts 等内部路由,负责模板、主题与草稿的在线编辑。打开/点击追踪则由 analytics 事件管道承接,与第 7 节的分析体系打通。
7. Analytics:免数据栈的用户分析
README 强调"无需自建数据栈即可了解用户":开箱即用的活跃用户数统计与 session replays(会话回放),支持用自然语言提问来构建看板,或直接写 SQL 保存查询,全程只需开启一个 flag。
实现证据:
- 事件接入:analytics/events/batch 提供批量事件上报入口;
- 查询层:analytics/query 与 analytics/query/timing 负责指标查询,配合 ClickHouse(仓库开发脚本会拉起 ClickHouse 依赖,见 docker/dependencies/docker.compose.yaml)这类列式存储支撑聚合查询;
- AI 自然语言查询:ai/query 路由把"用自然语言问问题"的入口接到了查询链路;
- 点击热图:analytics/clickmap;
- 会话回放:session-replays 提供
batch批量上报与按<a href="https://link.gitcode.com/i/af615eff0c7d037c257de0e283532136" target="_blank">session_replay_id]的分片读取。其存储实现非常直观——[session-replays/batch/route.tsx 中的 S3 键名session-replays/{projectId}/{branchId}/{replayId}/{batchId}.json.gz说明了回放数据按项目、分支、会话与批次分层存放,并做了 gzip 压缩。
在 apps-config.ts 中,clickmaps 与 session-replays 都以 analytics 为 parentAppId,印证了它们是分析体系下的子应用。
8. Webhooks:签名、防篡改的实时事件
README 描述:对每一个用户事件实时响应,webhook 带签名且防篡改,重试与退避(backoff)由平台处理,五行业代码完成验签,端点从 Dashboard 管理。
关键实现线索在 webhooks/svix-token:Hexclave 基于 Svix 这一成熟的 webhook 基础设施来提供签名、重试与端点管理。签名使用标准 Webhook 签名方案(如 HMAC),保证负载在传输途中被篡改时可被检测;重试与指数退避、事件重放则由 Svix 侧完成,这正是 README 所说"retries and backoff are handled for you"。开发者只需在收到请求时校验签名(README 声称五行业代码即可完成),端点列表与 secret 的轮换则统一在 Dashboard 中管理。
9. Data Vault:服务器端专用的用户密钥保险箱
README 对 Data Vault 的描述非常强调安全边界:"为用户交给你的秘密准备的保险箱,用你的密钥加密,我们永远看不到明文;存取各两行代码,设计上仅服务器端可用。"
实现是标准而严谨的 envelope encryption(信封加密)模式。看 data-vault/stores/[id]/get/route.tsx 的关键代码片段:
const encryptedData = entry.encrypted as { edkBase64?: string, ciphertextBase64?: string };
if (!encryptedData.edkBase64 || !encryptedData.ciphertextBase64) {
throw new HexclaveAssertionError("Corrupted encrypted data", encryptedData);
}
// ...
edkBase64: encryptedData.edkBase64,
ciphertextBase64: encryptedData.ciphertextBase64,
存储字段由 edkBase64(加密的数据密钥)与 ciphertextBase64(密文)两部分组成:平台只保存密文与数据密钥的加密版本,真正的解密发生在客户端用项目密钥解开 EDK 之后——因此平台侧"看不到明文"。get 与 set 两个路由分别对应 README 所说的"store and retrieve in two lines each",且该模块被标记为 server-only,避免把密钥材料暴露到浏览器端。data-vault 在应用目录中的 stage 为 beta,说明该能力仍在演进中。
10. Launch Checklist:上线前的强制检查清单
README 将其定位为"切到生产环境前必须跑完的检查":域名配置(domain setup)、回调地址锁定(callbacks locked)、密钥轮换(secrets rotated),并提供一个进度追踪器让团队对齐,确保上线当天不遗漏关键事项。
该应用在 apps-config.ts 中被标记为 stable 且无软依赖——意味着它独立于认证与支付体系,纯粹是一个面向发布流程的项目管理工具,任何项目都可以直接开启。这类"非基础设施、却是上线的关键保障"的应用,恰好体现了 Hexclave 应用目录超越传统用户服务的覆盖面。
SDK、CLI 与部署形态
除了十个应用,仓库还提供了完整的集成与交付生态:
- SDK 家族:
packages/下提供 packages/next、packages/react、packages/js 与 packages/tanstack-start 等多个框架适配层,README 的徽章也标明官方 SDK 覆盖 Next.js、React 与纯 JavaScript; - CLI:packages/cli 提供了命令行驱动平台的方式。从 packages/cli/src/commands 目录可以看到
config-file.ts(config pull/config push,同步项目配置)、deploy.ts(部署)、dev.ts(本地开发)等命令模块; - 集成示例:
examples/目录提供了 examples/react-example、examples/next、examples/convex、examples/supabase、examples/tanstack-start-demo 等,README 中"你选择前端、后端与数据库"的承诺在这里一一落地——认证逻辑在哪个框架下接入方式一致; - 部署形态:README 徽章标注"Cloud or self-hosted"(云托管或自托管均可)。自托管侧,仓库提供了 apps/backend/Dockerfile、apps/dashboard/Dockerfile 与 docker 目录中的依赖编排,
marshal/目录则负责把用户项目部署到 Fly.io / GCP / Vercel 等平台(见 marshal 的fly、gcp、vercel子模块); - 移动端 SDK:
sdks/下已有 Swift 实现(sdks/implementations/swift),表明 SDK 矩阵仍在扩展中。
开源、许可与贡献
README 明确说明 Hexclave 是开源的,并欢迎贡献:贡献指南见仓库根目录的 CONTRIBUTING.md,README 建议在动手做任何大改动前先在社区打个招呼。安全问题的上报通道由 .github/SECURITY.md 承载。
许可方面,README 的徽章标注为 MIT / AGPLv3 双重许可,仓库根目录的 LICENSE 是具体法律文本。工程质量方面,仓库配套了完整的测试体系:vitest.workspace.ts 定义了跨包的工作区测试,e2e/tests 下按 backend、frontend、js 等维度组织了端到端测试(见 e2e),.github/workflows 中还有针对 Prisma 迁移兼容性、数据库迁移向后兼容性、npm 发布的自动化流水线。
总结
Hexclave 的差异化不在于某个单一功能,而在于三点组合:应用目录式的按需启用、同一用户模型驱动全部应用、以及Agent-first 的集成方式。README 给出的使用路径是极简的——粘贴一条 Prompt,或 curl 一份技能文档,就能在一个既有项目里完成接入;随后按产品发展阶段,在 Dashboard 中逐步点亮 Teams、RBAC、Payments、Emails、Analytics 等应用。对于希望减少"手写认证 + 拼接 Stripe/Resend/分析工具"这类重复劳动、又要求数据主权与自托管能力的团队来说,这个仓库提供了一个完整的、可审计的备选方案。

