使用 Railway.com 一键部署自托管 Convex 后端模板部署、Admin Key 与 Dashboard 配置全指南【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址: https://gitcode.com/gh_mirrors/co/convex-backend导读本文以开源仓库 convex-backend 中官方维护的 Railway 自托管指南 为骨架完整讲解如何通过 Railway 的一键部署模板SQLite / Postgres / MySQL 三种数据库形态快速上线 Convex 后端并覆盖 Admin Key 生成、api/http 域名分离、HTTP Actions 路由、Dashboard 访问、前端应用对接以及常见故障排查。读完本文你将能够独立在 Railway 上完成一整套可用的自托管 Convex 环境搭建并理解其端口、环境变量与数据持久化背后的实现原理。一、部署前必读社区维护与三套模板概览Railway 上的自托管方案由社区维护原作者 orenaksakal 完成了整理工作遇到问题可以前往 Convex 社区 Discord 的#self-hosted频道寻求帮助。与 Fly.io 部署方案 类似Railway 方案同样是围绕仓库 self-hosted 总览 中定义的三个服务展开Convex 后端convex-backendConvex 控制台convex-dashboard你的前端应用自行托管或托管在 Netlify / Vercel 等平台Railway 官方提供了三个开箱即用的部署模板区别仅在底层数据库模板名称底层存储适用场景Convex SQLite本地 SQLite 文件存于 Railway Volume快速体验、开发环境、轻量负载Convex Postgres外部 Postgres 数据库生产级高可用场景Convex MySQL外部 MySQL 数据库生产级高可用场景三个模板都带有一键部署按钮Railway 的 Deploy on Railway.com 按钮点击后在 Railway 控制台中确认即可完成创建模板内已预配置好所需的环境变量。说明本文仅描述模板的名称与使用方式模板的实际部署链接可通过 Railway 官方部署页railway.com/deploy下对应模板名获取此处不展开外部链接。二、整体部署流程两步走整个 Railway 部署只需两大步骤其余都是可选的精细化配置部署模板直接一键部署即可模板已预配置环境变量。生成 Admin Key通过 Railway SSH 进入convex-backend容器执行./generate_admin_key.sh获取管理员密钥。⚠️ 可选步骤如果你希望将api 域名与http 域名分离即 Convex 客户端地址与 HTTP Actions 地址使用不同域名请参考下文第四节。三、生成 Admin Key通过 Railway SSHAdmin Key 是访问 Dashboard 和 CLI 的凭证必须妥善保管。生成流程如下参照 Railway 官方 SSH 文档在你的机器上配置好 Railway SSH 能力将你的 Convex 部署项目链接到本地railway link执行railway ssh当提示选择服务时选择convex-backend进入容器后先运行ls查看目录再运行./generate_admin_key.sh将屏幕上输出的整段 admin key 复制保存这是你的管理员密钥请保密。从源码层面看该脚本的实现位于 self-hosted/docker-build/generate_admin_key.sh核心逻辑是调用容器内的generate_key可执行文件以实例名INSTANCE_NAME和实例密钥INSTANCE_SECRET为输入生成密钥#!/usr/bin/env bash set -e source ./read_credentials.sh ADMIN_KEY$(./generate_key $INSTANCE_NAME $INSTANCE_SECRET) echo $ADMIN_KEY其中read_credentials.sh负责从环境变量读取INSTANCE_NAME与INSTANCE_SECRET并给出默认值。这两项与 docker-compose.yml 中透传的环境变量一一对应是自托管实例身份的核心标识。四、可选分离 api 与 http 域名Railway 模板默认使用同一个域名对外提供服务。如果你希望把 Convex 客户端 API 地址与 HTTP Actions 地址拆分成不同域名可按以下步骤操作在 Railway 控制台选择convex-backend服务进入Settings选项卡滚动到Public Networking公网连接区域悬停到已有域名上点击Edit或Delete按钮点击Generate Domain生成 Railway 自动域名或点击Custom Domain绑定自定义域名端口选择是关键为 ConvexapiURL 选择端口3210为 httpaction路由选择端口3211修改完成后同时重新部署convex-dashboard与convex-backend两个服务。这两个端口的来源可以直接在仓库中找到佐证self-hosted/docker-build/run_backend.sh 中明确将容器内部端口固定为--port 3210与--site-proxy-port 3211且 Dockerfile.backend 中对应EXPOSE 3210与EXPOSE 3211。脚本中的注释解释了设计意图容器内部端口固定以避免冲突而--convex-origin与--convex-site则用于声明后端对外可达的地址它们会出现在存储 URL、action 回调等场景中。五、HTTP Actions 的访问路径Railway 部署后HTTP Actions 运行在你的 Railway 应用域名下的/http路径。示例假设你的 Railway 应用部署在https://self-hosted-backend.railway.app你在 Convex 中将某个 HTTP action 路由到/sendEmail那么它的真实调用地址为https://self-hosted-backend.railway.app/http/sendEmail。这条路径规则与 Fly.io 方案 完全一致属于自托管部署的统一约定。在 run_backend.sh 中可以看到--site-proxy-port 3211就是专门承载该 HTTP 入口的站点代理端口。六、数据存储SQLite 文件与 Railway Volume如果你部署的是SQLite 模板所有数据都存储在本地 SQLite 文件中文件与上传内容存放在 Railway 的 Volume 中。通过 SSH 进入容器后可以确认railway ssh ls在data目录下可以看到数据库文件与存储目录。结合 run_backend.sh 的默认路径定义容器内的数据布局如下环境变量默认路径用途DATA_DIR/convex/data数据根目录SQLITE_DB/convex/data/db.sqlite3SQLite 数据库文件STORAGE_DIR/convex/data/storage上传文件存储目录TMPDIR/convex/data/tmp临时文件目录如果想要把数据迁移到独立的 SQL 数据库Postgres 或 MySQL可以参考仓库中的 Postgres / MySQL 数据库接入指南。要点包括通过POSTGRES_URL或MYSQL_URL环境变量指定数据库连接串注意连接串不要包含数据库名与查询参数后端实际使用的数据库名由实例名推导而来将INSTANCE_NAME中的-替换为_默认实例名为convex-self-hosted对应数据库convex_self_hosted强烈建议后端与数据库部署在同一区域尽量减小网络延迟否则查询性能会受影响切换数据库前先用npx convex export导出数据。 若使用 S3 存储替代本地文件系统可参考 S3 存储配置设置AWS_*与S3_STORAGE_*_BUCKET系列环境变量后run_backend.sh 会自动切换到--s3-storage模式。七、访问部署后的 DashboardDashboard控制台让你能够查看日志、读写数据、运行函数等。Railway 部署后进入你的 Railway 应用选择convex-dashboard服务访问其公网 URL提示时粘贴你之前生成的 Admin Key即可开始使用。在本地运行 Dashboard如果你更愿意在本地跑 Dashboard可以直接使用 Docker 运行官方镜像docker run -e NEXT_PUBLIC_DEPLOYMENT_URLbackend-url -p 6791:6791 ghcr.io/get-convex/convex-dashboard:latest其中backend-url替换为你的 Convex 后端地址即 3210 端口对应的 URL。Dashboard 默认监听6791端口这与 docker-compose.yml 中DASHBOARD_PORT的默认值一致。更多 Dashboard 的本地构建与可选配置如NEXT_PUBLIC_LOAD_MONACO_INTERNALLY让 Monaco 编辑器不再从 CDN 加载可查看 Dashboard 本地运行文档。八、对接你的前端应用Convex 后端负责数据库与计算函数但它不托管你的 Web 应用。前端应用需要自行托管如 Netlify、Vercel并通过环境变量指向自托管后端。关键点自托管场景下不使用云产品的CONVEX_DEPLOY_KEY而是改用以下两个变量写入.env.local切勿提交到版本控制CONVEX_SELF_HOSTED_URLhttps://self-hosted-backend.railway.app CONVEX_SELF_HOSTED_ADMIN_KEYyour admin key然后安装最新版 Convex CLI 并推送代码npm install convexlatest npx convex dev # 持续部署边改边同步 npx convex deploy # 一次性部署npx convex dev会持续同步你编辑的函数并自动在前端项目的.env.local中写入VITE_CONVEX_URL等前端变量npx convex deploy则适合 CI 等一次性部署场景。仓库 self-hosted 总览 对此有更完整的说明包括npx convex --help查看全部可用命令、npx convex export/npx convex import数据迁移等。九、常见问题排查Troubleshooting性能问题Railway 模板默认分配的资源是满足启动所需的最小值。如果应用负载较高可能会遇到 Railway 侧的限流ratelimiting与性能下降建议提高内存与 CPU 配置。磁盘空间不足Hobby爱好者计划的 Railway 配置为convex_dataVolume 分配5GB空间你的 SQLite 数据库与存储文件都放在这里。空间不足时可通过升级套餐将 Volume 扩容到50GB。其他问题可加入 Convex 社区 Discord 寻求帮助#self-hosted频道。十、原理小结从模板到容器的完整链路最后把整条链路串起来看Railway 模板本质上就是把 self-hosted/docker/docker-compose.yml 定义的两个服务backend与dashboard搬到了 Railway 上其中backend镜像为ghcr.io/get-convex/convex-backend容器内部通过 run_backend.sh 启动固定监听 3210客户端 API与 3211HTTP Actions 站点代理两个端口并依据POSTGRES_URL/MYSQL_URL/ 缺省情况自动选择 Postgres、MySQL 或 SQLite 数据库驱动对应--db postgres-v5、--db mysql-v5与默认 SQLitedashboard镜像为ghcr.io/get-convex/convex-dashboard通过NEXT_PUBLIC_DEPLOYMENT_URL指向后端地址监听 6791 端口并依赖后端健康检查curl -f http://localhost:3210/version通过后才启动Admin Key 由 generate_admin_key.sh 基于INSTANCE_NAME与INSTANCE_SECRET派生成为 CLI 与 Dashboard 的共享凭证。理解了这一层映射关系你在 Railway 上调整域名、端口、数据库或存储配置时就能有的放矢也能平滑迁移到 Fly.io 或其他自托管方案。【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址: https://gitcode.com/gh_mirrors/co/convex-backend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考