Convex Backend 开源反应式数据库：从架构解析、自托管部署到源码构建的完整实战指南

数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载Convex 是一个面向 Web 应用开发者的开源反应式数据库reactive database开发者可以用纯 TypeScript 编写服务端函数来完成数据读取与业务逻辑并获得强一致性保证。本指南以本仓库根目录 README.md 为主线系统讲解 Convex Backend 的项目定位、Docker 自托管流程、Postgres/MySQL 与 S3 的进阶配置、从源码构建本地后端的方法以及crates/与npm-packages/的仓库布局帮助你在自己的基础设施上完整跑通后端 Dashboard CLI的开发闭环。一、Convex Backend 是什么数据库、服务端函数与客户端库的一体化方案根据仓库根目录 README.md 的定义Convex 是the open-source reactive database designed to make life easy for web app developers, whether human or LLM。它把三类能力打包在一起数据库内置持久化存储默认使用本地 SQLite也可切换为 Postgres 或 MySQL服务端函数提供一处编写 query / mutation / action 等函数的地方业务逻辑以纯 TypeScript 编写客户端调用时保持强一致性客户端库提供前端 SDK帮助开发者构建动态、实时更新live-updating的应用。这套设计让开发者无需自行组合数据库 API 层 实时推送等多套基础设施即可构建和扩展动态应用。后端开发由 Convex 团队主导仓库与内部开发保持同步更新并欢迎小型 bug 修复见 CONTRIBUTING.md。从仓库布局看这一数据库 函数运行 客户端的分层在代码层面也清晰对应crates/local_backend应用服务器位于Runtime之上是 Convex 云的服务边缘也是自托管时的核心二进制convex-local-backendnpm-packages/udf-runtime为 query / mutation 搭建用户自定义函数UDF的 JS 执行环境npm-packages/system-udfs供系统例如 CLI使用的内置函数。二、快速开始云平台与本地开发两条路径对于不打算自托管的开发者官方提供云平台包含宽松的免费额度free tier许多小型应用和 side-project 可以在零成本、零维护的情况下完全跑在免费层上。如果你希望先体验 Convex 的开发体验仓库内自带了可直接运行的示例项目demo/convex 与 demo/src一个基于 Vite React 的消息示例应用npm-packages/demos/tutorial入门教程项目配合本地后端可直接运行详见下文从源码构建部分。本地开发的标准流程是先用convex dev启动本地后端CLI 会监听应用源码变化并自动把代码推送到后端同时自动更新.env.local中的CONVEX_URL。具体命令见 BUILD.md。三、Self-Hosting用 Docker 一键部署后端与 Dashboard自托管 Convex 需要部署三部分Convex 后端、Convex Dashboard以及你自己的前端应用可托管在自己服务器或 Netlify / Vercel 等托管服务。仓库推荐先用 Docker 跑通基础配置——默认后端会把全部状态存储在本地 SQLite 数据库中——之后再按需迁移到托管数据库或云平台。3.1 Docker Compose 启动使用仓库提供的 self-hosted/docker/docker-compose.ymldocker compose up该 Compose 文件定义了backend与dashboard两个服务服务镜像端口说明backendghcr.io/get-convex/convex-backend:latest${PORT:-3210}:3210、${SITE_PROXY_PORT:-3211}:3211Convex 主后端可通过:${REV}固定到特定版本dashboardghcr.io/get-convex/convex-dashboard:latest${DASHBOARD_PORT:-6791}:6791管理控制台depends_on后端健康检查通过后才启动后端镜像内置了健康检查每 5 秒curl -f http://localhost:3210/versionstart_period为 10 秒。启动后用docker compose exec生成管理员密钥admin keydocker compose exec backend ./generate_admin_key.sh访问地址约定如下Dashboardhttp://localhost:6791后端主地址http://127.0.0.1:3210后端 HTTP actions 地址http://127.0.0.1:32113.2 配置 .env.local 并连接 CLI在你的 Convex 项目中创建.env.local该文件不应提交到版本控制写入后端地址与刚才生成的 admin keyCONVEX_SELF_HOSTED_URLhttp://127.0.0.1:3210 CONVEX_SELF_HOSTED_ADMIN_KEYyour admin key然后安装最新版 Convex CLI 并开始推送代码、运行查询、导入数据npm install convexlatest npx convex dev npx convex --help # 查看所有可用命令3.3 数据持久化与存储默认情况下后端把数据存放在 Docker 管理的 volume 中。docker-compose.yml 中声明了data:/convex/data卷因此在任何云平台如 AWS EBS上运行容器时务必为容器配置持久化存储。数据层有两种可选的升级路径切换到 Postgres 或 MySQL详见 self-hosted/advanced/postgres_or_mysql.md使用 S3 存储为导出exports、快照snapshots、模块modules、文件files和搜索索引search indexes配置对象存储详见 self-hosted/advanced/s3_storage.md。3.4 使用 Convex Auth如果使用 Convex Auth需要按照官方手动配置流程进行设置目前 CLI 尚不支持自托管部署的自动配置。四、部署你的前端应用Convex 后端负责数据库与所有计算函数但不托管你的 Web 应用。当你在 Netlify / Vercel 等平台部署前端时需要把云平台部署说明中的环境变量替换为SELF_HOSTED等价项。例如不再设置CONVEX_DEPLOY_KEY而是设置CONVEX_SELF_HOSTED_URL为你的 Convex 后端地址设置CONVEX_SELF_HOSTED_ADMIN_KEY为用generate_admin_key.sh生成的 admin key。五、高级配置与运行方式索引仓库在 self-hosted/advanced 目录下提供了体系化的进阶文档覆盖从开发机到生产环境的完整路径直接运行二进制免 Docker 的二进制方式并说明了INSTANCE_SECRET与generate_key生成 admin key 的完整流程托管在 fly.io 与 托管在 Railway托管在自己的服务器数据库切换为 Postgres / MySQL使用 S3 存储文件清空或重置数据本地运行 Dashboard禁用日志功能升级自托管版本基准测试通过 knobs 进行高级调优。5.1 直接运行二进制的关键步骤源码级补充如果你选择直接运行convex-local-backend二进制而非 Dockerself-hosted/advanced/running_binary_directly.md 给出了三步关键操作生成实例密钥instance secret它是后端的根密钥持有者可以部署代码并读取数据务必保密、不得提交到版本控制export INSTANCE_SECRET$(openssl rand -hex 32)结果是一个 64 字符的十六进制字符串轮换该密钥会使后端所有既有 key/session 失效。生成 admin key以实例名称 实例密钥为输入用keybrokercrate 的generate_key二进制生成cargo run -p keybroker --bin generate_key -- convex-self-hosted $INSTANCE_SECRET输出形如convex-self-hosted|01c046ab1512d9306a6abda3eedec5dfe...。admin key 用于向后端推送代码及其他管理操作。仓库 Justfile 中的generate-admin-keyrecipe 与init-instance-secretrecipe 正是同一逻辑的本地实现前者用openssl rand -hex 32初始化 32 字节随机密钥后者调用generate_key二进制派生 admin key方便本地开发时免去手工步骤。启动后端数据库存储在当前工作目录而非二进制所在目录./convex-local-backend --instance-name convex-self-hosted --instance-secret $INSTANCE_SECRET如需切换数据库追加--db postgres-v5 connection string注意去掉数据库名和查询参数或--db mysql-v5 connection string。运行./convex-local-backend --help可查看端口、convex origin url、convex site url、本地存储目录等全部可配置项。5.2 数据库切换Postgres 与 MySQL 的连接要点self-hosted/advanced/postgres_or_mysql.md 指出 Convex 后端设计上同时兼容 SQLite、Postgres 与 MySQL默认 Docker 镜像使用 SQLite对于需要保障可用性的生产负载推荐使用托管 Postgres / MySQL。仓库测试覆盖了 Postgres v17 与 MySQL v8其他版本可能也可用。切换数据库前务必先用npx convex export导出数据。同时强调后端必须与数据库部署在同区域、尽可能靠近否则额外的网络延迟会直接影响查询性能。Neon 上的 Postgres从 Neon 面板复制连接串并创建数据库convex_self_hosted通过POSTGRES_URL环境变量指向不含库名和查询参数的连接串应以neon.tech结尾。连接成功后日志中会出现Connected to Postgres随后需用npx convex deploy把已有函数重新部署到新数据库。本地 Postgrespsql postgres -c CREATE DATABASE convex_self_hosted设置POSTGRES_URLpostgresql://usernamehost.docker.internal:5432与DO_NOT_REQUIRE_SSL1后docker compose up。本地 MySQLmysql -e CREATE DATABASE convex_self_hosted;设置MYSQL_URLmysql://usernamehost.docker.internal:3306与DO_NOT_REQUIRE_SSL1后docker compose up。PlanetScale 上的 MySQL数据库必须命名为convex_self_hostedMYSQL_URL不包含库名。数据库命名规则Convex 后端实际使用的数据库名等于实例名-替换为_。未设置实例名时 Docker 镜像默认convex-self-hosted对应数据库convex_self_hosted容器内可通过INSTANCE_NAME环境变量指定实例名。5.3 从 docker-compose.yml 看可用环境变量仓库 self-hosted/docker/docker-compose.yml 中声明了一组可直接覆盖的环境变量这些变量会被原样透传给后端容器是自托管调优的第一手入口变量默认值作用PORT3210后端主端口SITE_PROXY_PORT3211HTTP actions 端口DASHBOARD_PORT6791Dashboard 端口APPLICATION_MAX_CONCURRENT_MUTATIONS/_QUERIES/_V8_ACTIONS/_NODE_ACTIONS16各类函数的最大并发数CONVEX_CLOUD_ORIGINhttp://127.0.0.1:${PORT:-3210}云端 origin 地址CONVEX_SITE_ORIGINhttp://127.0.0.1:${SITE_PROXY_PORT:-3211}站点 origin 地址DATABASE_URL/POSTGRES_URL/MYSQL_URL—SQL 数据库连接串S3_ENDPOINT_URL、S3_STORAGE_*_BUCKET—S3 兼容对象存储配置INSTANCE_NAME/INSTANCE_SECRET—实例身份与根密钥RUST_LOGinfoRust 日志级别DISABLE_METRICS_ENDPOINTtrue置为false可启用 Prometheus 兼容的/metrics端点DOCUMENT_RETENTION_DELAY1728002 天文档保留时长秒默认调低以控制存储DISABLE_BEACON—禁用匿名使用统计信标DO_NOT_REQUIRE_SSL—本地数据库免 SSL 连接REDACT_LOGS_TO_CLIENT—对客户端日志脱敏六、从源码构建本地后端如果你希望从源码构建并运行完整的 Convex 后端参考仓库根目录 BUILD.md。6.1 依赖准备依赖用途安装建议Just仓库脚本工具执行Justfile中定义的脚本cargo install just或brew install justNode.js版本见.nvmrc运行 Convex CLI推荐通过 nvm 安装仓库根目录执行nvm useCargo Rust nightly版本见 rust-toolchain构建 Rust 后端通过 rustup 安装nightly 会自动安装pnpm Turborepo管理 JS 工作区npm clean-install --prefix scriptsConvex JS 依赖构建前端相关包just install-js6.2 构建并运行后端just run-local-backend该命令实际执行见 Justfilecargo run -p local_backend --bin convex-local-backend -- \ --instance-name open-source-convex-backend \ --instance-secret $(just init-instance-secret)其中init-instance-secret会生成或复用 32 字节随机实例密钥。如果启动报错 persisted db metadata ...说明本地数据库损坏需要在仓库根目录删除convex_local_backend.sqlite3后重试对应just reset-local-backend。6.3 运行仓库自带的 Demo 应用1. 启动后端按上文运行just run-local-backend。2. 开发模式运行 demoConvex CLI 会监听应用源码变化并推送代码到后端just install-js cd npm-packages/demos/tutorial just convex devJustfile 中的convexrecipe 会自动为 CLI 追加--admin-key $(just generate-admin-key) --url http://127.0.0.1:3210参数指向本地后端。3. 启动前端另开终端运行npm run dev:frontend注意与托管 Convex 工作流不同这里不要再运行dev:backend命令因为convex dev已经在运行后端。本地开发中常用的 CLI 命令均通过just convex前缀自动连接本地后端just convex data— 列出部署中的表just convex env— 列出 / 设置 / 更新 / 删除环境变量just convex logs— 将日志流式输出到终端传入--success会包含所有成功执行just convex import— 导入表just convex export— 导出表如果你同时使用本地后端和云平台请务必在测试客户端前先运行npx convex dev或just convex dev——dev命令会自动把正确的CONVEX_URL写入.env.local。6.4 构建 NPM 包client、CLI、docs、dashboard、ESLint 插件等npm clean-install --prefix scripts just install-js # 构建整个 monorepo just turbo run build # 也可以只构建某个包及其依赖例如 just turbo run build --filterdocs...开发单个包时各包package.json中提供了便捷命令。例如为 docs 启动 dev servercd npm-packages/docs just turbo run build --filterdocs^... # 先构建 docs 依赖的包 npm run dev如需修改 monorepo 包的依赖改对应package.json后运行just update-js。七、仓库布局与代码结构根据 README.md 与 environment 文件结构crates/— Rust 代码主二进制crates/local_backend 是基于Runtime的应用服务器也是 Convex 云的服务边缘它内部按职责拆分了大量模块例如 admin.rsadmin key 鉴权、config.rs命令行与环境变量配置解析、public_api.rs公共 API等其余 crate 覆盖数据库crates/database、搜索、存储、UDF 执行crates/udf、身份认证crates/authentication等领域。npm-packages/— TypeScript 包公开与内部内部包 npm-packages/udf-runtime搭建 query / mutation 的 UDF JS 执行环境内部包 npm-packages/system-udfs供系统如 CLI使用的函数。八、自托管注意事项密钥安全、平台支持与匿名信标README.md 的 Disclaimers 部分给出三条重要提示这里结合源码做进一步说明务必更换默认密钥如果选择从源码构建而非按官方自托管指南部署一定要把仓库中的默认 instance secret 和 admin key 换成自己的值。从前文可知INSTANCE_SECRET是根密钥持有者即可部署代码和读取数据。平台支持情况Convex 在 Linux 和 Mac 上经过最充分测试Windows 上的经验较少遇到问题可在社区#self-hosted频道反馈。匿名信标beacon自托管构建包含一个帮助 Convex 改进产品的信标信息量最小且匿名。如果你确实想禁用它可以在后端二进制上设置--disable-beacon标志。从源码 crates/local_backend/src/config.rs 可以看到该参数由 clap 定义为--disable-beacon同时支持DISABLE_BEACON环境变量crates/local_backend/src/beacon.rs 中的协程按 1 小时间隔上报一次心跳失败时按指数退避重试上报的 JSON 字段为database_uuid、migration_version、compiled_revision、commit_timestamp、uptime等。README 明确指出信标消息仅包含部署的随机标识符不用于其他用途数据库的迁移版本migration version后端的 Git revision后端运行时长uptime即不包含任何个人可识别信息且日志中会打印这些消息方便你知晓其内容。九、限制说明自托管 Convex 支持云产品免费层的全部功能云产品本身针对大规模场景做了深度优化。也就是说自托管方案适合功能完整、自由度高的部署需求而云托管则在规模化场景下具备更强的性能与运维能力两者定位互补。总结本文以仓库根 README.md 为核心串联了 Convex Backend 的项目定位、Docker 自托管全流程、Postgres/MySQL 与 S3 的进阶配置、从源码构建本地后端的具体步骤以及仓库的 Rust / TypeScript 双层布局。无论是想快速用docker compose up起一套本地 Convex还是基于just run-local-backend从源码深入开发都可以对照 BUILD.md 与 self-hosted/README.md 逐步落地。赞分享数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载相关推荐终极UE4SS部署指南从源码构建到实战应用的完整教程终极UE4SS部署指南从源码构建到实战应用的完整教程 UE4SS是一款强大的UE4/5游戏注入式LUA脚本系统集成了SDK生成器、实时属性编辑器和多种转储工游戏开发逆向工程Hoppscotch 开源生态全景解析从 Monorepo 架构到自托管部署的实战指南Hoppscotch 开源生态全景解析从 Monorepo 架构到自托管部署的实战指南 Hoppscotch 是一个开源的 API 开发生态系统提供 Web开发工具接口测试前端后端CLI如何搭好大麦自动抢票系统新手完整指南附准备清单如何搭好大麦自动抢票系统新手完整指南附准备清单 热门演出开售的那几秒购买按钮往往点都点不上刷新半天只剩“已售罄”。如果你总是差那么一下不如把这件事交GUI 自动化RPA创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考