OmniRoute 部署实战使用 flyctl 将自托管 AI 网关发布到 Fly.io 的完整指南【免费下载链接】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统一 AI 网关支持 352 提供商、1200 模型与配额感知自动回退的开发者。全流程基于仓库内已实际验证的配置应用名omniroute、新加坡区域sin、Fly Volume 持久化到/data涵盖 Fly CLI 安装登录、首次部署、必配/推荐环境参数、一键写入 Secrets、OAuth 回调配置、fork 同步升级、发布后检查与常见问题排查。读完本文你将具备从零把 OmniRoute 部署到 Fly.io 并长期稳定迭代发布的能力。1. 部署目标与总体思路OmniRoute 在 Fly.io 上的部署遵循本地flyctl直接发布的模式不引入额外 CI/CD 编排平台Fly.io使用其 Machines Volume 原语发布方式本地 Fly CLI 构建镜像并部署运行载体直接复用仓库根目录的 fly.toml 与 Dockerfile无需额外改造数据持久化Fly Volume 挂载到容器内/data数据库与运行时密钥都落在此处对外访问https://omniroute.fly.dev/该指南同时覆盖两类场景首次部署以及后续代码更新后的滚动发布新项目也可以照着同样的流程复用部署。2. 仓库关键配置逐项解读当前仓库的 fly.toml 是经过验证可直接上线的部署配置关键项如下app omniroute primary_region sin [[mounts]] source data destination /data auto_extend_size_threshold 80 auto_extend_size_increment 1GB auto_extend_size_limit 10GB [processes] app node run-standalone.mjs [http_service] internal_port 20128 force_https true auto_stop_machines stop auto_start_machines true min_machines_running 1 processes [app] [[vm]] memory 1gb cpu_kind shared cpus 1 [env] TZ Asia/Shanghai HOST 0.0.0.0 HOSTNAME 0.0.0.0 BIND 0.0.0.0逐项说明app omniroute决定部署目标 Fly 应用控制台里必须看到同名应用primary_region sin主区域为新加坡Fly 会在该区域创建机器[[mounts]]Fly Volumedata挂载到容器内/data。auto_extend_size_*三项允许磁盘在用量超过 80% 时自动扩容每次 1GB上限 10GB[processes] app node run-standalone.mjs应用启动进程入口即仓库内的 scripts/dev/run-standalone.mjs。该脚本会先执行bootstrapEnv()完成密钥引导再选择server-ws.mjs若存在或server.js启动 Next.js standalone 服务[http_service] internal_port 20128容器内部监听端口与 Dockerfile 中的ENV PORT20128和EXPOSE 20128一致force_https、auto_stop/start_machines、min_machines_running共同保证对外只暴露 HTTPS 且常驻一台机器[env]HOST、HOSTNAME、BIND全部绑定0.0.0.0适配 Fly 的运行时网络。关键约束部署时必须让DATA_DIR/data否则数据库与密钥会写入容器临时目录机器重建即丢失详见第 6 节与第 9 节成功标志。3. 必备工具Fly CLI 安装与登录3.1 安装 Fly CLIWindows PowerShellpwsh -Command iwr https://fly.io/install.ps1 -useb | iex如果安装脚本在当前环境失败也可以手动下载flyctl二进制放入PATH。3.2 登录 Fly 账号flyctl auth login3.3 校验登录状态与环境flyctl auth whoami flyctl versionwhoami返回当前账号version确认 CLI 可用。后续所有部署命令都依赖登录态。4. 首次部署流程4.1 获取代码并进入仓库目录git clone 当前仓库地址 cd OmniRoute按你实际可访问的仓库地址替换当前仓库地址下文 fork 同步部分还会用到远程仓库管理。4.2 确认应用名打开仓库根目录的fly.toml重点看这一行app omniroute如果要部署到自己的新应用改成全局唯一名称例如app omniroute-yourname注意控制台里看的必须是fly.toml中app对应的应用如果以前用过别的名字例如oroute不要和omniroute混淆。4.3 创建应用若该应用尚不存在flyctl apps create omniroute改了应用名的把omniroute替换成你的名字。4.4 首次部署flyctl deployflyctl deploy会读取 fly.toml 与 Dockerfile构建阶段使用 Node 26 slim 基础镜像、以--ignore-scripts方式npm ci并单独重建better-sqlite3原生绑定最后产出 standalone 产物运行阶段以非 root 的node用户执行node dev/run-standalone.mjs即 scripts/dev/run-standalone.mjs并带有内置 HEALTHCHECK。5. 必配参数清单5.1 已在实际部署中验证的参数以下参数已在当前omniroute应用上真实部署使用变量名是否推荐说明API_KEY_SECRET必需API Key 的生成与校验JWT_SECRET必需登录态与 JWT 签名OMNIROUTE_WS_BRIDGE_SECRET生产必需WebSocket Bridge 鉴权密钥STORAGE_ENCRYPTION_KEY强烈推荐加密存储敏感连接信息MACHINE_ID_SALT推荐生成稳定的机器标识INITIAL_PASSWORD可选首次部署时直接指定后台初始密码OAuth/API 私密凭证按需各类外部平台鉴权配置源码佐证scripts/build/bootstrap-env.mjs 实现了零配置引导若JWT_SECRET、STORAGE_ENCRYPTION_KEY、API_KEY_SECRET缺失会自动用randomBytes生成并持久化到{DATA_DIR}/server.env且显式警告INITIAL_PASSWORD未设置时会回退到默认值CHANGEMEOMNIROUTE_WS_BRIDGE_SECRET被 src/app/api/internal/codex-responses-ws/route.ts 与 src/server/authz/policies/management.ts 引用用于 WebSocket 桥接与管理端鉴权——缺失会直接破坏 WS 握手STORAGE_ENCRYPTION_KEY还承担解密探针职责启动时会用当前密钥尝试解密数据库中enc:v1:前缀的凭据不匹配会打印错误并给出恢复建议scripts/build/bootstrap-env.mjs 中hasEncryptedCredentials与 decrypt-probe 逻辑。5.2 关于INITIAL_PASSWORD当前项目部署时没有设置INITIAL_PASSWORD按需求不使用。不设置的结果启动日志会提示默认密码是CHANGEME对应 scripts/build/bootstrap-env.mjs 中INITIAL_PASSWORD CHANGEME时的警告分支部署后应尽快在系统设置中修改登录密码。如果希望无人值守初始化后台密码可以后续补设INITIAL_PASSWORD。5.3 当前项目推荐值变量名推荐值DATA_DIR/dataNEXT_PUBLIC_BASE_URLhttps://omniroute.fly.dev说明DATA_DIR/data非常关键必须与 fly.toml 中 Fly Volume 挂载点destination /data保持一致否则持久化失效NEXT_PUBLIC_BASE_URL用于调度器、前端回调等场景仓库内由 src/server/origin/publicOrigin.ts 与 src/shared/utils/resolveOmniRouteBaseUrl.ts 解析使用。6. 一键写入全部 Secrets下面的 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() $wsBridgeSecret [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 OMNIROUTE_WS_BRIDGE_SECRET$wsBridgeSecret DATA_DIR/data NEXT_PUBLIC_BASE_URLhttps://omniroute.fly.dev -a omniroute在 Linux / macOS 上也可以用openssl rand -hex生成随机值flyctl secrets set OMNIROUTE_WS_BRIDGE_SECRET$(openssl rand -hex 32) -a omnirouteOMNIROUTE_WS_BRIDGE_SECRET生产环境必需缺失会破坏 WebSocket Bridge 握手。如果还需要初始密码flyctl secrets set INITIAL_PASSWORD你的强密码 -a omniroute查看当前已设置参数flyctl secrets list -a omniroute如果控制台Secrets页面没有显示你期待的变量先检查两点看的应用是不是omniroutefly.toml的app是否和控制台应用一致。7. OAuth 回调地址配置启用 OAuth 提供商时必读如果要在 Fly.io 部署上启用基于 OAuth 的提供商例如 Antigravity、Gemini、Cursor 等需要确认两点1. 把NEXT_PUBLIC_BASE_URL设置成你的公网 HTTPS 域名flyctl secrets set NEXT_PUBLIC_BASE_URLhttps://omniroute.fly.dev -a omniroute使用自定义域名时替换为对应域名例如https://omniroute.yourdomain.com。2. 在提供商控制台配置回调地址所有 OAuth 提供商共用同一个回调路径/callback没有按提供商区分的回调路由NEXT_PUBLIC_BASE_URL/callback例如无论 Gemini、Antigravity、Cursor 还是 GitLab Duo统一为https://omniroute.fly.dev/callback如果NEXT_PUBLIC_BASE_URL与在提供商处登记的回调 URL 不一致OAuth 流程会在浏览器重定向环节失败。仓库内 OAuth 回调统一收敛在 src/app/api/oauth/[provider]/[action]/route.ts 与 src/app/auth/callback/page.tsx 中处理。8. 后续更新与发布代码有更新后发布很简单git pull flyctl deploy只更新参数、不改代码时flyctl secrets set KEYvalue -a omniroute设置 Secret 后 Fly 会自动对 Machines 做滚动更新。8.1 跟踪上游更新并保留 fork 的fly.toml如果当前仓库是 fork需要同步上游更新且强制保留 fork 自己的fly.toml推荐按下面流程操作。先确认远程仓库git remote -v应至少包含origin指向自己的 fork与upstream指向原仓库。没有upstream时先添加git remote add upstream 上游仓库地址同步前先抓取最新提交与标签git fetch upstream --tags查看当前版本与上游标签git describe --tags --always git show --no-patch --oneline v3.4.7说明v3.4.7为历史示例版本当前项目实际版本是v3.8.0正式发布时请使用:latest或当前版本标签如:v3.8.0。合并上游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此步不产生额外差异若上游改了则能确保应用名、挂载卷、区域等 fork 自定义部署配置不被覆盖。如果只想对齐某个发布标签例如v3.4.7先确认该标签已包含在upstream/maingit merge-base --is-ancestor v3.4.7 upstream/main返回成功表示upstream/main已包含该版本直接合并upstream/main即可。8.2 同步上游后的标准发布顺序git fetch upstream --tagsgit merge upstream/main恢复 fork 的fly.tomlgit push origin mainflyctl deployflyctl status -a omnirouteflyctl logs --no-tail -a omniroute这就是当前项目升级时使用的实际发布流程。9. 发布后检查9.1 查看应用状态flyctl status -a omniroute9.2 查看启动日志flyctl logs --no-tail -a omniroute9.3 检查网站可访问try { (Invoke-WebRequest -Uri https://omniroute.fly.dev -MaximumRedirection 5 -UseBasicParsing).StatusCode } catch { if ($_.Exception.Response) { $_.Exception.Response.StatusCode.value__ } else { throw } }返回200说明站点已正常响应。10. 成功标志部署成功后日志中应看到类似内容[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)与log( Secrets persisted to: ${serverEnvPath})的输出/data/storage.sqlite说明 SQLite 数据库写入了持久卷重启/重建机器后数据不会丢失。如果看到的是/app/data/...说明DATA_DIR没配对需要立即修正。容器镜像默认ENV DATA_DIR/app/data见 DockerfileFly 部署时必须通过 Secrets 覆盖为/data。11. 常见问题排查11.1Secrets页面是空的通常两种原因还没执行flyctl secrets set打开的是另一个应用例如oroute不是omniroute。11.2flyctl deploy报app not found先创建应用flyctl apps create omniroute11.3fly.toml解析失败重点检查注释里是否有乱码字符TOML 引号和缩进是否正确。11.4 数据没有持久化检查两点fly.toml中是否存在destination /dataDATA_DIR是否设置为/data。11.5 不设置INITIAL_PASSWORD是否能跑可以运行但会回退到默认密码CHANGEME对应 scripts/build/bootstrap-env.mjs 的启动警告。生产环境建议尽快在后台修改密码。12. 新项目复用建议如果是新项目照着这份文档部署最少改这几项修改fly.toml里的app修改NEXT_PUBLIC_BASE_URL保持DATA_DIR/data重新生成API_KEY_SECRET、JWT_SECRET、MACHINE_ID_SALT、STORAGE_ENCRYPTION_KEY生产环境还需重新生成OMNIROUTE_WS_BRIDGE_SECRET首次部署后检查日志是否写入/data。不要直接复用旧项目的密钥。13. 当前项目最小发布清单后续最常用的命令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 omniroute14. 结语Fly.io 为 OmniRoute 提供了理想的托管形态fly.tomlDockerfile开箱即用Volume 挂载解决 SQLite 与运行时密钥的持久化问题flyctl secrets set一条命令完成全部敏感参数注入。只要遵循本文的挂载点\data与DATA_DIR一致、密钥全部走 Secrets、首次部署后核对日志落盘三条原则就能获得一个数据可持久、可滚动升级、可长期维护的自托管 AI 网关节点。相关配置与源码可继续在仓库内查阅fly.toml、Dockerfile、scripts/dev/run-standalone.mjs、scripts/build/bootstrap-env.mjs。【免费下载链接】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），仅供参考
