在 Fly.io 上自托管 Convex Backend：从零部署到生产环境的完整指南

• 数据库
• 后端

导读

本指南以仓库中 self-hosted/advanced/fly/README.md 为骨架，完整讲解如何将 Convex 后端（backend）、管理面板（dashboard）与前端应用部署到 Fly.io 这一 PaaS 平台。你将掌握通过fly launch创建应用、配置CONVEX_CLOUD_ORIGIN/CONVEX_SITE_ORIGIN环境变量、生成 admin key、用convexCLI 推送函数代码，以及针对 SQLite 数据卷、HTTP Actions 路由和资源调优的完整实战方案。

部署全景：自托管 Convex 的三个组成部分

自托管 Convex 需要部署三个服务（见 self-hosted/README.md）：

1. Convex backend：运行全部数据库与计算函数的核心服务；
2. Convex dashboard：用于查看日志、读写数据、运行函数的可视化管理面板；
3. 你的前端应用：可以自己托管，也可以放在 Netlify、Vercel 等托管服务上。

仓库在self-hosted/advanced/fly/目录下预先为 backend 与 dashboard 各准备了一份fly.toml配置（backend/fly.toml 与 dashboard/fly.toml），让部署到 Fly.io 的过程几乎零门槛。下文将按 backend → dashboard → 前端应用 的顺序逐步展开。

准备阶段：获取 Fly 配置文件与安装 CLI

1. 拷贝 fly 配置目录

原文档推荐使用degit（一个从 Git 仓库拷贝文件的工具）将self-hosted/advanced/fly目录复制到本地，可以放在任何位置，不一定要放进你的项目目录：

npx degit get-convex/convex-backend/self-hosted/fly fly cd fly

说明：上述命令从上游 GitHub 仓库拉取。如果无法访问外部网络，也可以直接从当前仓库手动拷贝self-hosted/advanced/fly/下的backend/与dashboard/两个子目录。

拷贝后你会得到两个子目录：

• fly/backend/：包含部署 Convex backend 的 fly.toml；
• fly/dashboard/：包含部署 Convex dashboard 的 fly.toml。

2. 安装 Fly CLI

按 Fly.io 官方文档安装flyctl（Fly CLI）。安装完成后可以用fly version验证是否可用。

部署 Convex Backend 到 Fly.io

原文档特别强调：所谓"部署"在 Convex 语境下有两层含义——一是把 Convex backend 的 Docker 镜像部署到 Fly.io，二是把你应用里的 Convex functions 部署到运行 Convex 的那台 Fly machine 上。本节处理第一层。

第一步：创建 Fly 应用

cd backend fly launch

交互式提示时，选择y将仓库自带的fly.toml配置复制到新应用。如果使用 Postgres 或 MySQL 作为数据库，建议将primary_region修改为与数据库相同的区域，以降低跨区域网络延迟。

部署成功后终端会打印应用 URL，形如https://<app-name>.fly.dev。原文档将其记为fly-backend-url，后续所有环境变量配置都会用到它。

读懂 backend 的 fly.toml：关键配置项

仓库自带的 backend/fly.toml 是一份可直接运行的基准配置，逐段解读如下：

app = 'convex-backend' primary_region = 'iad' [build] # 改为 :${REV} 可以固定到特定版本 image = 'ghcr.io/get-convex/convex-backend:latest' [env] TMPDIR = '/convex/data/tmp' [[mounts]] source = 'convex_data' destination = '/convex/data' [http_service] internal_port = 3210 force_https = true auto_stop_machines = 'stop' auto_start_machines = true min_machines_running = 1 processes = ['app'] [[http_service.checks]] interval = '5s' timeout = '30s' grace_period = '5s' method = 'GET' path = '/version' protocol = 'http' [[vm]] memory = '1gb' cpu_kind = 'shared' cpus = 4

• app/primary_region：应用名与首选区域（默认iad，即美国弗吉尼亚北部）。
• [build].image：直接使用 Convex 官方发布的 backend 镜像ghcr.io/get-convex/convex-backend:latest。若想锁定版本，可将latest改为具体的镜像 tag（如:${REV}）。
• [[mounts]]：将名为convex_data的 Fly volume 挂载到容器内/convex/data。这是 SQLite 数据库与文件存储的持久化位置（详见下文"数据库"小节）。
• [http_service]：backend 对外的 HTTP 服务监听容器内3210端口，强制 HTTPS；auto_stop_machines = 'stop'配合min_machines_running = 1意味着空闲时机器可停止、但至少保留一台运行，auto_start_machines = true保证请求到达时自动拉起。
• [[http_service.checks]]：Fly 每 5 秒对/version路径发起一次健康检查（超时 30 秒、宽限期 5 秒），用于判定实例是否存活。该路径由 backend 自身提供，可作为部署成功的验证点。
• [[vm]]：默认分配 1GB 内存、4 个共享 CPU，是 Fly 上能跑起来的最小资源，适合起步；生产环境建议按负载调大（见"故障排查"）。

第二步：设置环境变量CONVEX_CLOUD_ORIGIN与CONVEX_SITE_ORIGIN

这两个环境变量告诉 backend 它自己被托管在什么地址，backend 据此生成指向自身的 URL（例如存储链接、action 回调地址等）。在 Convex functions 内部，可以通过process.env.CONVEX_CLOUD_URL获取 Convex 客户端 API 地址，通过process.env.CONVEX_SITE_URL获取 HTTP API 地址。

方式一：写入 fly.toml 的[env]段

[env] TMPDIR = '/convex/data/tmp' CONVEX_CLOUD_ORIGIN = '<fly-backend-url>' CONVEX_SITE_ORIGIN = '<fly-backend-url>/http'

修改后重新部署生效：

fly deploy

方式二：存为 Fly secrets

如果不希望把变量明文留在 fly.toml 中（例如多人共用同一个已提交到版本库的 fly.toml，但各自有独立的 Fly backend），可以用fly secrets set写入：

fly secrets set CONVEX_CLOUD_ORIGIN="<fly-backend-url>" CONVEX_SITE_ORIGIN="<fly-backend-url>/http"

从源码看这两个变量的去向

查看 run_backend.sh 可以发现，容器启动脚本会把它们映射为 backend 二进制（convex-local-backend）的两个命令行参数：

--convex-origin "$CONVEX_CLOUD_ORIGIN" \ --convex-site "$CONVEX_SITE_ORIGIN" \

脚本注释写得很清楚：--port与--site-proxy-port是容器内部端口，--convex-origin与--convex-site才是"外部世界访问 backend 的方式"，它们会出现在存储 URL、action 回调等地方。这也是为什么CONVEX_SITE_ORIGIN要带上/http后缀——backend 的 HTTP API 正是挂在站点路径的/http之下（下文"HTTP Actions"会再次印证）。这个机制对注册 webhook 的库以及 Convex Auth 生成 auth 回调地址尤其重要。

第三步：验证 backend 运行

浏览器访问<fly-backend-url>，应看到提示 backend 正在运行的消息。若访问失败，用fly logs查看日志定位问题。也可以直接请求/version端点检查健康检查是否通过。

第四步：生成 admin key

admin key 用于授权convexCLI 和访问 dashboard，通过容器内的生成脚本获得：

fly ssh console --command "./generate_admin_key.sh"

从源码看，该脚本（generate_admin_key.sh）会读取实例凭据（read_credentials.sh中的INSTANCE_NAME与INSTANCE_SECRET），调用generate_key工具输出 admin key 字符串。请妥善保存此 key——忘记后可随时用同一条命令重新生成。

第五步：在应用项目里配置.env.local

进入使用 Convex 的应用目录，创建.env.local（不要提交到版本控制）：

CONVEX_SELF_HOSTED_URL='<fly-backend-url>' CONVEX_SELF_HOSTED_ADMIN_KEY='<your-admin-key>'

第六步：部署 Convex functions

如果项目还没安装 Convex：

cd <your-frontend-app-directory> npm install convex@latest

开发模式（持续部署）：npx convex dev会在你编辑代码时持续把函数推送到 backend，同时自动在.env.local写入前端所需的变量（如VITE_CONVEX_URL）。

一次性部署：

npx convex deploy --env-file <path to env file>

部署到其他 backend：通过--env-file指定不同环境文件，或在调用npx convex deploy前先设置好自托管环境变量（CONVEX_SELF_HOSTED_URL与CONVEX_SELF_HOSTED_ADMIN_KEY）。

关于开发与生产：backend 实例本身并不区分开发/生产，区别只取决于你调用npx convex dev（实时更新）还是npx convex deploy（一次性推送）。利用这一特性，你可以通过不同的环境变量组合，为 staging 或 preview 创建多个 backend。

HTTP Actions 的路由规则

HTTP actions 运行在 Fly 应用 URL 的/http路径之下。示例：

• Fly 应用部署在https://self-hosted-backend.fly.dev；
• 你的 HTTP action 路由到/sendEmail；
• 实际访问地址为https://self-hosted-backend.fly.dev/http/sendEmail。

这正好解释了上文CONVEX_SITE_ORIGIN = '<fly-backend-url>/http'的由来：site 源即 HTTP API 的根路径。从 run_backend.sh 可以看到容器内--port 3210对应主服务、--site-proxy-port 3211对应 site 代理，fly.toml 中http_service.internal_port = 3210与之对应。

数据存储：SQLite、Fly Volume 与 Postgres/MySQL 切换

默认情况下，所有数据存放在本地 SQLite 数据库中，文件存放在 Fly volume 的文件系统里。登录容器即可看到数据目录：

fly ssh console ls

数据实际落在data目录（/convex/data），其中db.sqlite3是 SQLite 数据库文件（见 run_backend.sh 中SQLITE_DB=${SQLITE_DB:-"$DATA_DIR/db.sqlite3"}的默认值），storage是文件存储目录，tmp是临时目录。它们都通过 fly.toml 的[[mounts]]挂载到持久化 volumeconvex_data上，因此重启/重建机器数据不会丢失。

若要将数据迁移到独立的 SQL 数据库（Postgres 或 MySQL），可参考仓库中的 postgres_or_mysql.md。从 run_backend.sh 的源码可以看出，设置POSTGRES_URL或MYSQL_URL环境变量后，脚本会自动切换为--db postgres-v5/--db mysql-v5驱动并传入连接串；需要额外存储容量时可参考 s3_storage.md 配置 S3 存储。

部署 Dashboard

dashboard 用于查看日志、读写数据、运行函数等，支持本地 Docker 运行或部署到 Fly.io。

本地运行

docker run -e 'NEXT_PUBLIC_DEPLOYMENT_URL=<fly-backend-url>' -p '6791:6791' 'ghcr.io/get-convex/convex-dashboard:latest'

部署到 Fly.io

1. 进入拷贝自仓库的 dashboard 目录：

   cd dashboard

2. 用 backend URL 部署。写入 fly.toml的方式：

   fly launch -e NEXT_PUBLIC_DEPLOYMENT_URL="<fly-backend-url>"

   存为 secret的方式（适合多人共用已入库的 fly.toml、各自部署独立 dashboard 的场景）：

   fly launch fly secrets set NEXT_PUBLIC_DEPLOYMENT_URL="<fly-backend-url>"

   部署完成后即可访问 fly 输出的 dashboard URL。仓库自带的 dashboard/fly.toml 中，dashboard 容器内部监听6791端口（与本地 Docker 运行时的-p '6791:6791'一致），对外暴露 80/443 端口并强制 HTTPS，默认分配 1GB 内存、1 个共享 CPU。

3. 登录：访问 dashboard 后输入前面生成的 admin key。建议把 key 存入密码管理器以便随时取用；忘记时可通过fly ssh console --command "./generate_admin_key.sh"重新生成。登录成功后即可看到你的表、函数、日志等信息。

部署前端应用

Convex backend 只运行数据库与计算函数，并不托管你的 Web 应用。如果前端托管在 Netlify、Vercel 等服务上，请参考 self-hosted/README.md 中的部署说明，关键点在于：不要设置CONVEX_DEPLOY_KEY，而是把环境变量替换为自托管对应的CONVEX_SELF_HOSTED_URL（backend 的 URL）与CONVEX_SELF_HOSTED_ADMIN_KEY（用generate_admin_key.sh生成的 admin key）。

故障排查与资源调优

原文档提供了两个最常见的性能/容量问题及建议：

• 性能问题：默认 fly 配置只分配能跑起来的最小资源（backend 为 1GB 内存 + 4 共享 CPU，见 backend/fly.toml）。高负载下可能遇到 Fly 的限流和性能不佳，建议增大内存与 CPU——修改 fly.toml 的[[vm]]段后fly deploy即可。
• 磁盘空间不足：默认配置给convex_datavolume 分配 1GB 空间，SQLite 数据库与存储都放在这里。空间不足时用fly volume extend扩容。

其他进阶调优手段还包括：参考 knobs.md 调整 backend 内部可调参数、参考 benchmarking.md 进行压测评估、参考 upgrading.md 升级自托管版本等，这些文档均位于 self-hosted/advanced 目录下。

小结

至此，你已经完成了 Fly.io 上的完整自托管链路：backend（含 SQLite 数据卷与/version健康检查）→ 环境变量与 admin key →convexCLI 推送函数 → HTTP Actions 路由 → dashboard 登录管理 → 前端应用接入。核心要点可归纳为：用CONVEX_CLOUD_ORIGIN/CONVEX_SITE_ORIGIN让 backend 认识自己的外部地址（对应源码中的--convex-origin/--convex-site参数），用.env.local中的CONVEX_SELF_HOSTED_URL/CONVEX_SELF_HOSTED_ADMIN_KEY让 CLI 认识你的 backend，再根据负载与容量需求随时调整 fly.toml 资源与 volume 大小。

• 数据库
• 后端