OmniRoute Fly.io 云部署实战指南：基于 flyctl 与 Fly Volume 的完整发布流程

OmniRoute Fly.io 云部署实战指南基于 flyctl 与 Fly Volume 的完整发布流程【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute本文是一份基于仓库内已验证配置整理的 Fly.io 部署操作指南面向两类场景首次把当前 OmniRoute 项目部署到 Fly.io、以及后续代码更新后的持续发布。读完本文你将掌握flyctl完整发布链路、fly.toml关键配置、Secrets 安全参数体系、Fly Volume 持久化验证方法以及 fork 场景下“保留自有 fly.toml 同步上游”的升级流程并了解这些配置在源码层的落地原理。1. 部署目标与整体思路当前项目在 Fly.io 上的部署方案非常简洁核心要点如下平台Fly.io部署方式本地flyctl直接发布不需要第三方 CI/CD运行方式直接复用仓库根目录现有的 Dockerfile 与 fly.toml数据持久化Fly Volume 挂载到容器内/data访问地址https://omniroute.fly.dev/应用名决定整个流程可以概括为一条主线应用名 → 创建应用 → 设置 Secrets → 首次部署 → 日志验证数据落盘。后续每次发版只需要flyctl deploy。2. 关键配置解读fly.toml 与 Dockerfile2.1 fly.toml 核心配置仓库根目录的 fly.toml 已经过验证包含以下关键项字段值以仓库当前文件为准app omniroute primary_region sin [[mounts]] source data destination /data [processes] app node run-standalone.mjs [http_service] internal_port 20128 [env] TZ Asia/Shanghai HOST 0.0.0.0 HOSTNAME 0.0.0.0 BIND 0.0.0.0各字段的实战含义app omniroute决定实际部署到哪个 Fly 应用控制台里看的必须是这个应用不要和历史遗留的oroute等名字混淆primary_region sin指定首选部署区域新加坡destination /data持久卷在容器内的挂载目录这是数据持久化的锚点[processes] app node run-standalone.mjs启动进程入口。run-standalone.mjs位于 scripts/dev/run-standalone.mjs它会先调用bootstrapEnv()完成密钥引导再以优先 WS-aware 入口server-ws.mjs启动 Next.js standalone 服务internal_port 20128容器内服务监听端口与 Dockerfile 中EXPOSE 20128、ENV PORT20128保持一致。仓库实际的fly.toml中还包含几处部署增强配置理解即可官方文档裁剪版未列出[[mounts]] auto_extend_size_threshold 80 auto_extend_size_increment 1GB auto_extend_size_limit 10GB [http_service] force_https true auto_stop_machines stop auto_start_machines true min_machines_running 1 [[vm]] memory 1gb cpu_kind shared cpus 1它们分别实现卷容量自动扩容阈值 80%每次增 1GB上限 10GB、强制 HTTPS、机器空闲自动停机/按需自动启动以及 1 核 1GB 的最小虚拟机规格。2.2 Dockerfile 里的运行时事实Dockerfile 提供了几条与部署强相关的源码级事实镜像默认ENV DATA_DIR/app/data也就是说如果不在 Fly Secrets 里显式设置DATA_DIR/data数据会落到容器临时层/app/data重启即丢失——这正是文档反复强调“本项目必须设置DATA_DIR/data”的根本原因运行时以非 root 的node用户执行USER node入口为 scripts/check-permissions.sh校验挂载卷属主并带HEALTHCHECKscripts/dev/healthcheck.mjs镜像提供runner-base精简版与runner-web内置 Chromium/Playwright用于 Gemini Web、Claude Web 等 web-cookie 供应商两种形态纯 API 网关场景用 base 即可。3. 必备工具与登录3.1 安装 Fly CLIWindows PowerShell 一键安装pwsh -Command iwr https://fly.io/install.ps1 -useb | iex如果安装脚本在当前环境失败也可以手动下载flyctl二进制并加入PATH。3.2 登录与状态检查flyctl auth login flyctl auth whoami flyctl versionauth whoami用于确认登录身份version用于核对 CLI 版本后续所有命令都依赖这一步通过。4. 首次部署当前项目4.1 获取代码并进入目录git clone 你的仓库地址 cd OmniRoute说明如果你是 fork 部署请将你的仓库地址替换为你 fork 后的仓库地址下文第 9 节会讲解 fork 同步流程。4.2 确认应用名打开fly.toml重点看这一行app omniroute如果你准备部署到自己的新应用可改成全局唯一名称例如app omniroute-yourname注意两点控制台里要看的是与fly.toml里app一致的应用以前如果用过别的名字例如oroute不要和omniroute混淆否则会出现“Secrets 页面为空”的假象。4.3 创建应用如果该应用尚不存在flyctl apps create omniroute如果你已经改了应用名把omniroute替换成你的名字。4.4 首次部署flyctl deployflyctl会自动构建镜像多阶段base → builder → runner、创建/复用data卷并挂载到/data然后启动机器。5. 必配参数Secrets 体系本项目在 Fly.io 上建议至少配置以下参数。这些参数已在当前omniroute应用上实际部署验证API_KEY_SECRETDATA_DIRJWT_SECRETMACHINE_ID_SALTNEXT_PUBLIC_BASE_URLSTORAGE_ENCRYPTION_KEY5.1 关于 INITIAL_PASSWORD当前项目没有设置INITIAL_PASSWORD按部署需求不使用它。如果不设置启动日志会提示默认密码是CHANGEME部署后应尽快在系统设置中修改登录密码。如果你希望无人值守初始化后台密码也可以后续补设INITIAL_PASSWORD。源码佐证这条“默认密码”警告来自 scripts/build/bootstrap-env.mjs其中明确写着INITIAL_PASSWORD is not set — using default CHANGEME同时 src/lib/env/runtimeEnv.ts 的运行时环境 schemawebRuntimeEnvSchema也会校验INITIAL_PASSWORD、JWT_SECRET、API_KEY_SECRET、DATA_DIR、NEXT_PUBLIC_BASE_URL等变量的合法性。6. 推荐参数说明6.1 Secrets 中设置变量名是否推荐说明API_KEY_SECRET必需API Key 生成与校验使用JWT_SECRET必需登录态和 JWT 签名使用STORAGE_ENCRYPTION_KEY强烈推荐加密存储敏感连接信息MACHINE_ID_SALT推荐生成稳定机器标识INITIAL_PASSWORD可选首次部署时直接指定后台初始密码OAuth/API 私密凭证按需各类外部平台鉴权配置6.2 当前项目推荐值变量名推荐值DATA_DIR/dataNEXT_PUBLIC_BASE_URLhttps://omniroute.fly.dev说明DATA_DIR/data非常关键必须与 Fly Volume 挂载点一致NEXT_PUBLIC_BASE_URL用于调度器、前端回调等场景且运行时环境校验要求它必须是http://或https://开头的合法 URL见 src/lib/env/runtimeEnv.ts 的optionalHttpUrl校验。源码佐证为什么 Secrets 如此重要scripts/build/bootstrap-env.mjs 是零配置引导的核心首次启动时若JWT_SECRET、STORAGE_ENCRYPTION_KEY、API_KEY_SECRET缺失它会自动生成随机值并写入{DATA_DIR}/server.env。这带来两个部署结论在 Fly 上只要把DATA_DIR指到持久卷/data即使你不手动设置密钥首次启动也会自动生成并持久化——但重启后密钥不丢失的前提是server.env落在持久卷里环境变量优先级从低到高为自动生成默认值 →{DATA_DIR}/server.env→ 首选.env→process.envFly Secrets 注入的进程环境变量优先级最高。因此手动设置 Secrets 后会自动覆盖引导阶段生成的随机值保证多机/重建场景下密钥稳定。7. 一键设置参数下面的 PowerShell 命令会生成安全随机值并把当前项目需要的参数一次性写入 Fly Secrets。注意不包含INITIAL_PASSWORD适用于当前项目omniroute。$apiKeySecret [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower() $jwtSecret [Convert]::ToHexString((1..64 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower() $machineIdSalt [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower() $storageKey [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower() flyctl secrets set API_KEY_SECRET$apiKeySecret JWT_SECRET$jwtSecret MACHINE_ID_SALT$machineIdSalt STORAGE_ENCRYPTION_KEY$storageKey DATA_DIR/data NEXT_PUBLIC_BASE_URLhttps://omniroute.fly.dev -a omniroute如果你还要加初始密码flyctl secrets set INITIAL_PASSWORD你的强密码 -a omniroute在 Linux/macOS 上也可以用openssl rand -hex 32生成随机值并逐条设置flyctl secrets set STORAGE_ENCRYPTION_KEY$(openssl rand -hex 32) -a omniroute密钥生成思路API_KEY_SECRET、MACHINE_ID_SALT、STORAGE_ENCRYPTION_KEY用 32 字节64 位 hexJWT_SECRET用 64 字节128 位 hex与 bootstrap 引导逻辑里randomBytes(32)/randomBytes(64)的强度对齐。8. 查看当前参数flyctl secrets list -a omniroute如果控制台Secrets页面没有显示你期待的变量先检查看的应用是不是omniroutefly.toml的app是否和控制台应用一致。9. 后续更新发布代码有更新后发布步骤很简单git pull flyctl deploy如果只更新参数、不改代码flyctl secrets set KEYvalue -a omnirouteFly 会自动对机器做滚动更新结合fly.toml中auto_start_machines/min_machines_running 1升级过程保持最少 1 台机器在线。9.1 跟踪原仓库更新并保留 fork 的 fly.toml如果当前仓库是 fork需要同步原仓库更新时推荐按下面的流程执行核心目标是同步代码但保留 fork 自己定制的fly.toml应用名、卷挂载、区域等部署配置不被上游覆盖。先确认远程git remote -v应至少包含origin指向你自己的 forkupstream指向原仓库。如果没有upstream先添加git remote add upstream 原仓库地址原仓库地址请以你 fork 来源为准下面所有提到upstream的引用都以这个地址为基准。同步上游前先抓取最新提交和标签git fetch upstream --tags查看当前版本和上游标签git describe --tags --always git show --no-patch --oneline v3.4.7文档中的v3.4.7属于历史示例版本用于演示标签同步流程实际发布请以仓库当前版本标签为准使用:latest或当前版本标签即可。合并上游最新main并强制保留 fork 当前的fly.tomlgit merge upstream/main git checkout HEAD~1 -- fly.toml git add -- fly.toml git commit -m chore(deploy): keep fork fly.toml git push origin main各命令含义git merge upstream/main同步原仓库最新代码git checkout HEAD~1 -- fly.toml恢复合并前 fork 自己的fly.toml如果上游没有改fly.toml这一步不会带来额外差异如果上游改了fly.toml这一步能确保 Fly 应用名、挂载卷、区域等 fork 自定义部署配置不被覆盖。如果你明确只想对齐某个发布标签可以先确认该标签是否已包含在upstream/main中git merge-base --is-ancestor v3.4.7 upstream/main返回成功表示upstream/main已经包含该版本直接合并upstream/main即可。9.2 同步上游后的标准发布顺序同步原仓库完成后推荐按下面顺序发布git fetch upstream --tagsgit merge upstream/main恢复 fork 的fly.tomlgit push origin mainflyctl deployflyctl status -a omnirouteflyctl logs --no-tail -a omniroute10. 发布后检查10.1 查看应用状态flyctl status -a omniroute10.2 查看启动日志flyctl logs --no-tail -a omniroute10.3 检查网站可访问try { (Invoke-WebRequest -Uri https://omniroute.fly.dev -MaximumRedirection 5 -UseBasicParsing).StatusCode } catch { if ($_.Exception.Response) { $_.Exception.Response.StatusCode.value__ } else { throw } }返回200说明站点已正常响应配合fly.toml的force_https trueHTTP 请求会被自动重定向到 HTTPS。11. 成功标志部署成功后日志里应看到类似内容[bootstrap] Secrets persisted to: /data/server.env [DB] SQLite database ready: /data/storage.sqlite这两个点很关键/data/server.env说明运行时密钥落到了持久卷对应 scripts/build/bootstrap-env.mjs 中writeEnvFile(serverEnvPath, persisted)的行为/data/storage.sqlite说明 SQLite 数据库写入持久卷。如果你看到的是/app/data/...说明DATA_DIR没配对回退到了 Dockerfile 里的默认值/app/data需要立即修正——重新flyctl secrets set DATA_DIR/data -a omniroute并重启机器。12. 常见问题12.1 Secrets 页面是空的通常有两种原因还没执行flyctl secrets set打开的是另一个应用例如oroute不是omniroute。12.2 flyctl deploy 报 app not found先创建应用flyctl apps create omniroute12.3 fly.toml 解析失败重点检查注释里是否有乱码字符TOML 引号和缩进是否正确。12.4 数据没有持久化检查以下两点fly.toml中是否存在destination /dataDATA_DIR是否设置为/data。12.5 不设置 INITIAL_PASSWORD 是否能跑可以运行但会回退到默认CHANGEME引导脚本会打印警告。生产环境建议尽快在系统设置中修改后台密码。13. 新项目复用建议如果以后有新项目照着这份文档部署最少改这几项修改fly.toml里的app修改NEXT_PUBLIC_BASE_URL新域名保持DATA_DIR/data重新生成API_KEY_SECRET、JWT_SECRET、MACHINE_ID_SALT、STORAGE_ENCRYPTION_KEY首次部署后检查日志是否写入/data。不要直接复用旧项目的密钥。这一点在源码层也有约束bootstrap-env.mjs在检测到数据库中已存在enc:v1:前缀的加密凭据时会拒绝自动生成新的STORAGE_ENCRYPTION_KEY防止旧数据无法解密密钥一旦丢失恢复成本极高所以新项目务必生成全新的随机值。14. 当前项目的最小发布清单日常维护最常用的命令flyctl auth whoami flyctl status -a omniroute flyctl secrets list -a omniroute flyctl deploy flyctl logs --no-tail -a omniroute如果只是正常发版核心就是flyctl deploy如果是新环境首次部署核心步骤是flyctl auth loginflyctl apps create omnirouteflyctl secrets set ... -a omnirouteflyctl deployflyctl logs --no-tail -a omniroute附相关文档与源码索引官方部署文档英文原版docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md中文版部署文档docs/i18n/zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md部署配置fly.toml 与 Dockerfile启动入口scripts/dev/run-standalone.mjs密钥引导与持久化scripts/build/bootstrap-env.mjs运行时环境校验src/lib/env/runtimeEnv.ts【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考