Convex

Convex 是什么？

Convex 是结合数据库、服务端函数和客户端库的响应式后端平台。查询是与数据库一起运行的 TypeScript 代码，订阅结果会响应存储数据的变化。

Convex 实时数据库使用关系型数据模型，同时存储类似 JSON 的文档。Schema 可选，文档可引用其他表中的文档，应用代码通过 JavaScript API 而非 SQL 读写。

Convex 还通过 AI Gateway 提供托管模型访问：后端 action 调用这一服务，供应商凭据由 Convex 持有，短期访问令牌限定于某个部署。

核心功能

查询、变更和 action

函数类型划分不同的执行边界：

• 查询读取数据，带缓存并支持响应式订阅。
• 变更写入数据，并作为数据库事务执行。
• Action 调用外部 API，不具备事务性，也不缓存。
• HTTP action 暴露 webhook 或自定义客户端端点。

托管模型访问

AI Gateway 提供文本生成、嵌入、决策、图像、视频、语音生成和转录路由。Decisions、Voice 和图像/视频生成处于 alpha 阶段，请求与响应格式可能变化。

使用指南

连接 React 界面

现有 Convex 后端可通过以下基本组件连接 React 界面：

1. 为部署创建 ConvexReactClient，并传给包裹组件树的 ConvexProvider。
2. 使用 useQuery 和生成的 api 对象读取后端数据。开发命令在 convex/_generated/api.js 中生成该对象，提供 JavaScript 自动补全和端到端 TypeScript 类型。
3. 使用 useMutation 修改数据。该 hook 返回异步函数；以参数调用它即可执行变更。

Convex 使用场景

• 实时聊天界面： Convex 提供实时聊天应用教程，消息持久保存并实时更新。
• 语义检索与推荐： 向量搜索查找与所给向量相似的文档。文档列出的用途包括 LLM 应用的上下文和相关内容推荐。
• 持久化代理： Agent 组件跨会话保存对话历史，将长时间运行的 AI 工作与响应式界面分离。它支持对历史进行向量/文本混合搜索，并通过 RAG 组件或自定义实现，使用其他来源进行基于 RAG 的提示词增强。
• 延迟与周期任务： 定时函数稍后运行一次，cron 任务周期运行。例如欢迎邮件和账户对账；Workpool 与 Workflow 组件添加带重试和延迟的队列或持久流程。

适用人群

• JavaScript 和 TypeScript 应用开发者： TypeScript 后端也接受 JavaScript；函数通过客户端库 API 暴露，适合同时负责界面和服务端代码的团队。
• 寻求托管运维的团队： Convex 将托管产品定位为更省运维；自托管则在团队自己的服务器上运行当前后端代码。

支持平台

• React 客户端： ConvexReactClient 使用 WebSocket 推送结果，无需轮询，并在连接中断后重新连接。
• 前端托管： 前端可使用 Vercel、Netlify 或自定义托管，与后端部署分开。
• 身份验证： 连接/调用使用 OpenID Connect JWT。Convex Auth 支持客户端 React 和 React Native 注册/登录流程，但仍为 beta，功能少于第三方集成。
• 数据区域： 可部署于北弗吉尼亚、爱尔兰、悉尼或加拿大中部。美国以外用量加收 30%（标准费率的 1.3 倍）。

为部署提供支持的所有基础设施都托管在所选区域。更换区域须新建项目或部署并导出/导入数据，现有部署不能原地迁移。

价格套餐

价格采集于 2026 年 11 月 2 日，以展示的美国东部基准美元计价。包含资源跨区域共享。

套餐与开发者访问

Business 列出每月最低 $2,500；部署类别和基础设施单价另行公布。Enterprise 列出年度承诺折扣，但未给出具体折扣或年度总价。

Free、Starter 与 Professional 资源

每个单元格列出包含额度和额外用量费率。第一列的付费超额适用于 Starter；Free 额度固定。存储按 GB/月计费，其他资源按各自所列计量单位计费。

无服务器查询/变更计算免费。调用包括客户端调用、计划任务、订阅更新和文件访问。文件存储包括备份；出站流量包括函数文件访问及备份生成/恢复。文本/向量索引和查询分别共用相应搜索计量。

用量汇总于团队所有项目，不按项目或开发者单独分配。Free 套餐长期超额可能导致 HTTP 错误，但 Convex 称不会因超额删除已成功写入的变更记录。FAQ 提到 Starter，也用“Starter Plus”表示持续流量；不能据此推断另有单独定价层级。

Business 与 Enterprise 部署费率

美国东部月费矩阵列出四个类别；活跃部署按日折算。其他单位见各行。

以下基础设施计量与部署类别同时适用：

破折号保留公布值，不表示价格为零或包含该权益。

AI 费用与支出控制

AI Gateway 要求付费团队，支持云生产/开发或与项目关联的本地部署。Free 和自托管部署不能使用；自托管 action 可使用自己的密钥调用供应商。

Gateway 费用取决于模型、时间、缓存 token、图像/视频分辨率和时长，或语音字符数/秒数/token。费用出现在 Convex 发票上；取消已提交的视频请求仍可能产生生成费用。

云部署支持 AI Gateway 每日/月度禁用阈值：触发时禁用整个部署，而非仅模型请求；非开发部署还支持警告阈值。项目关联的本地请求共享团队支出限额；达到限额后，进行中的请求或使用已签发短期凭据的请求仍可能完成。

续订与退款

费用不可取消或退款，明确合同例外除外。Order Form 决定月度/年度周期；自助超额自动计费，达到发票阈值时可能产生中途收费。

Order Form 订阅以相同期限自动续订，除非任一方在到期至少 60 天前通知不续订。若客户选择不自动续订，订阅按当前条款和价格转为逐月续订；任一方可提前 30 天书面通知终止。

若 Convex 在收到书面违约通知后 30 天内未补救重大违约，客户作为非违约方可书面通知终止协议或受影响的 Order Form。若客户依据该条款终止协议，Convex 退还截至终止生效日已终止 Order Form 剩余期限内预付但未使用费用的按比例金额。这是合同例外，并非普遍的试用退款期。

Convex 替代方案

Supabase 提供按项目划分的 Postgres、身份验证、带 Row Level Security 的存储、实时服务和 Edge Functions。其 Postgres 基础使其成为面向 SQL 团队的相关替代方案。

Firebase Cloud Firestore 提供适用于移动端、网页和服务端的 NoSQL 数据库，以及实时监听器和移动端与网页的离线支持。该文档所述离线行为解决断网访问问题，但不能证明 Convex 具备同等行为。

注意事项

事务与执行边界

• 外部副作用： action 出错时不自动重试，因为外部请求可能已生效。调用方处理重试；返回后未完成的 promise 可能完成，也可能不会。
• 独立事务： action 通过查询和变更间接访问数据库。独立的 runQuery/runMutation 调用不一定共享一致状态；一个组合查询/变更具有一致的事务边界。
• 文档大小： 文档上限 1 MiB，嵌套深度上限 16。
• 事务大小： 一次查询或变更最多读取 16 MiB、写入 16 MiB。扫描后被过滤器排除的数据仍计入读取量。

Action 指南称 action 在 10 分钟后超时；限制参考则列出 Convex 运行时 action 为 30 分钟、Node 运行时 action 为 10 分钟，查询/变更用户代码为 1 秒且不含数据库操作。这些公开描述不一致。

搜索与生成边界

向量搜索仅限 action，使用余弦相似度进行近似最近邻搜索。结果成员本身不具响应性，但单独查询可使每个结果的数据保持响应式；记录在取回前可能变化或消失。每张表允许四个向量索引，维度为 2 至 4,096。

图像/视频生成处于 alpha，请求/响应格式可能变化。图像使用文本提示词，不支持输入图像或蒙版编辑。同步视频约 5 分钟后失败，允许下载 64 MiB；取消、超时或响应丢失仍可能收费。异步操作在 7 天后过期；供应商保留视频的时间可能更短。

自托管许可证

后端的 FSL Apache 2.0 公平源码许可证不允许创建旨在与托管的 Convex Cloud 竞争的产品。代码创建两年后转为 Apache 2.0；当前版本从第一天起并非不受限制的 Apache 2.0。

指定 Beta Features 仅供评估，不属于合同中的 Platform，且不提供服务承诺、支持、保证或使用责任；Convex 可停止提供。

数据权利与模型处理

客户/许可方保留 Customer Data 权利，并授予 Convex 有限处理许可，用于平台交付、维护/支持/改进、客户发起的集成及法律义务。这是客户授予平台的许可，并非转移数据所有权。

Convex 拥有 Aggregated Data，可用于分析、产品开发和基准比较等合法商业目的。该数据不得识别客户/用户、以可识别形式包含其信息，也不得合理地允许重新识别。

AI 条款禁止在未获客户事先书面同意时，使用 Customer Data 训练/改进 Convex 或第三方基础模型。相似输入可能产生相似输出；不保证结果准确、完整、无错误或适合特定用途。

ZDR 标记记录上次更新时目录匹配的零保留状态。必须逐请求启用路由，无合格端点时请求失败；仅有标记不构成保证。图像/视频/音频路由不接受此选项。

隐私、删除和处理地点

Convex 隐私政策不涵盖应用 Customer Data，后者受客户协议和应用政策约束。对于政策涵盖的信息，Convex 可能收集 IP/设备标识符、近似位置和活动数据，并使用 cookie 与分析工具。

政策涵盖的信息可能在包括美国在内的全球各地处理/存储，并在服务使用期间或出于收集目的、交付、争议、审计、法律抗辩、商业目的、执行及法律义务而保留；未规定统一固定期限。

依据 DPA，Convex 必须在协议到期或终止时删除 Customer Personal Data。备份/归档副本按其保留时间表删除；法律要求保留的副本须隔离，并防止进一步处理，适用法律要求的处理除外。分处理商列表将基础设施/数据库服务与所选区域关联，同时列出美国的支持、分析、计费和 AI 路由，以及德国的社区管理。

Convex 表示客户代码、数据库、文件和搜索索引采用 AES-256 静态加密，传输加密，生产访问受限，并符合 SOC 2 Type 2。Convex 称受 HIPAA 约束的企业在签署其 Business Associate Agreement 后可在平台处理 PHI；这些厂商声明不能证明每个客户的应用均合规。

FAQ

Q1. 每个 Convex 函数都有实时性和事务保证吗？

没有。查询带缓存且可订阅，变更具有事务性；外部 action 不继承同样的保证。

Q2. Free 套餐包含 AI Gateway 吗？

不包含。它要求付费团队，模型使用另按量计费。自托管部署使用自己的供应商凭据。

Q3. 选择欧洲区域是否意味着所有类型的数据都留在那里？

不是。部署基础设施、隐私政策涵盖的个人信息、分处理商和模型路由保留的范围各不相同。