Hexclave 开源用户基础设施平台全面解析:从 Auth 到支付、邮件与分析的一体化用户栈

原创2026-10-08 19:01:281,862 阅读
文章标签:后端认证鉴权前端MCP 服务

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 在基础设施栈中所处的位置——介于你的应用与各类底层服务之间,把用户侧能力收拢为一个统一平台。

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 给出了两条核心路径:

  1. 人类开发者:把下面这段提示词粘贴给任意 coding agent,即可在项目中完成接入:
Read skill.hexclave.com and help me setup hexclave in this project
  1. 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 路由即可。

Hexclave Dashboard 管理界面,用于开关与配置各类应用

十大核心功能深度解析

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 分为项目级与团队级两套平行的定义/赋值模型:

"同一套权限检查服务端客户端通用"在 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 与部署形态

除了十个应用,仓库还提供了完整的集成与交付生态:

开源、许可与贡献

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/分析工具"这类重复劳动、又要求数据主权与自托管能力的团队来说,这个仓库提供了一个完整的、可审计的备选方案。

登录后查看全文
hexclave