OmniRoute Fly.io 部署实战fly.toml 持久卷、flyctl Secrets 与标准发布流程【免费下载链接】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本篇基于 OmniRoute 仓库中经过实际验证的 Fly.io 部署配置整理而成覆盖首次部署、参数Secrets配置、代码更新发布与 fork 同步上游的完整流程。读完后你可以独立地把当前项目或新项目通过flyctl直接发布到 Fly.io理解DATA_DIR/data与 Fly Volume 挂载的一致性要求并掌握从fly.toml到启动日志的逐层验证手段。1. 部署目标部署的整体目标如下平台Fly.io部署方式本地flyctl直接发布运行方式使用仓库内现有的 Dockerfile 和 fly.toml数据持久化Fly Volume 挂载到/data访问地址https://omniroute.fly.dev/这套配置对应的 Fly 应用名为omniroute本文所有命令默认针对该应用。2. 当前项目关键配置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对照仓库实际文件fly.toml 中还有几项对生产行为很关键的配置[[mounts]] source data destination /data auto_extend_size_threshold 80 # 使用率达 80% 触发自动扩容 auto_extend_size_increment 1GB # 每次扩展 1GB auto_extend_size_limit 10GB # 卷容量上限 10GB [http_service] internal_port 20128 force_https true auto_stop_machines stop # 空闲时停机配合 auto_start 按需唤醒 auto_start_machines true min_machines_running 1 processes [app] [[vm]] memory 1gb cpu_kind shared cpus 1各关键项说明app omniroute决定实际部署到哪个 Fly 应用必须与控制台应用名一致destination /data决定持久卷挂载目录本项目必须让DATA_DIR/data否则数据库和密钥会写到容器临时目录。这一点在 Dockerfile 中可以得到印证镜像默认ENV DATA_DIR/app/data如果不通过 Secrets 显式覆盖为/data运行时数据会落在/app临时层里重建实例即丢失[processes]中app node run-standalone.mjs是 Fly 应用进程命令它覆盖镜像默认启动命令Dockerfile 中的CMD [node, dev/run-standalone.mjs]启动脚本即 standalone 构建产物中的 run-standalone.mjsinternal_port 20128与镜像内ENV PORT20128Dockerfile保持一致镜像入口还挂载了 check-permissions.sh 作为ENTRYPOINTDockerfile用于在挂载卷属主不正确时提前告警——排查“数据没有持久化”时值得留意这条日志。3. 必备工具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 version4. 首次部署当前项目4.1 获取代码并进入目录git clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute4.2 确认应用名打开 fly.toml重点看这一行app omniroute如果你准备部署到自己的新应用可改成全局唯一名称例如app omniroute-yourname注意控制台里要看的是与fly.toml里app一致的应用以前如果用过别的名字例如oroute不要和omniroute混淆fly.toml首行注释显示该文件最初是为oroute生成的后来统一到了omniroute。4.3 创建应用如果该应用尚不存在flyctl apps create omniroute如果你已经改成别的应用名把omniroute替换成你的名字。4.4 首次部署flyctl deploy5. 必配参数本项目在 Fly.io 上建议至少配置以下参数。5.1 已验证使用的参数这些参数已经在当前omniroute应用上实际部署API_KEY_SECRETDATA_DIRJWT_SECRETMACHINE_ID_SALTNEXT_PUBLIC_BASE_URLSTORAGE_ENCRYPTION_KEY5.2 关于INITIAL_PASSWORD当前项目没有设置INITIAL_PASSWORD因为本次部署按需求不使用它。如果不设置启动日志会提示默认密码是CHANGEME该警告来自启动引导脚本 bootstrap-env.mjsINITIAL_PASSWORD未设置或为CHANGEME时输出 “using default CHANGEME. Change it in Settings!”部署后应尽快在系统设置中修改登录密码。如果你希望无人值守初始化后台密码也可以后续补INITIAL_PASSWORD5.3 Secrets 推荐设置建议放入 Fly Secrets变量名是否推荐说明API_KEY_SECRET必需API Key 生成与校验使用JWT_SECRET必需登录态和 JWT 签名使用STORAGE_ENCRYPTION_KEY强烈推荐加密存储敏感连接信息MACHINE_ID_SALT推荐生成稳定机器标识INITIAL_PASSWORD可选首次部署时直接指定后台初始密码OAuth/API 私密凭证按需各类外部平台鉴权配置从源码看这三个核心密钥并非“必须手动设置才能启动”bootstrap-env.mjs 在首启时会自动生成缺失的JWT_SECRET64 随机字节 hex、STORAGE_ENCRYPTION_KEY32 字节 hex和API_KEY_SECRET32 字节 hex并持久化到{DATA_DIR}/server.env。但显式通过 Secrets 设置仍是推荐做法原因有二自动生成的密钥写在卷上一旦卷数据损坏或误删卷就无法恢复已加密的凭据加密格式为enc:v1:iv:ct:tagAES-256-GCM scrypt 派生STORAGE_ENCRYPTION_KEY配错时启动引导会做“解密探针”bootstrap-env.mjs日志中出现 “STORAGE_ENCRYPTION_KEY does not match the key used to encrypt your stored credentials” 即表示凭据不可解。5.4 当前项目推荐值变量名推荐值DATA_DIR/dataNEXT_PUBLIC_BASE_URLhttps://omniroute.fly.dev说明DATA_DIR/data非常关键必须与 Fly Volume 挂载点一致仓库 .env.example 中DATA_DIR默认是注释状态不设置时回退到~/.omniroute因此必须在 Fly 上显式指定NEXT_PUBLIC_BASE_URL用于调度器和前端回调等场景。.env.example 也注明在反向代理/公网域名后部署时需要把它设为同一公网 originOAuth 回调 redirect URI 同样依赖它。6. 一键设置参数下面命令会生成安全随机值并把当前项目需要的参数一次性写入 Fly Secrets。说明不包含INITIAL_PASSWORD适用于当前项目omniroute随机值长度与源码自动生成策略对齐JWT_SECRET64 字节、其余 32 字节见 bootstrap-env.mjs。$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 omniroute7. 查看当前参数flyctl secrets list -a omniroute如果控制台Secrets页面没有显示你期待的变量先检查看的应用是不是omniroutefly.toml的app是否和控制台应用一致8. 后续更新发布代码有更新后发布步骤很简单git pull flyctl deploy如果只更新参数不改代码flyctl secrets set KEYvalue -a omnirouteFly 会自动滚动更新机器。8.1 跟踪原仓库更新并保留 fork 的fly.toml如果当前仓库是 fork并且你要同步上游 OmniRoute 仓库的更新推荐按下面流程执行。先确认远程git remote -v应至少包含origin指向你自己的 forkupstream指向原仓库如果没有upstream先添加以上游仓库实际地址为准git remote add upstream 上游仓库地址同步上游前先抓取最新提交和标签git fetch upstream --tags查看当前版本和上游标签git describe --tags --always git show --no-patch --oneline v3.4.7如果你想合并上游最新main并强制保留 fork 当前的fly.toml可按下面流程执行git 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 自定义部署配置不被覆盖。如果你明确只想对齐某个发布标签例如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这就是当前项目升级到v3.4.7时使用的实际流程。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说明运行时密钥落到了持久卷。启动时 run-standalone.mjs 会先调用 bootstrap-env.mjs 的bootstrapEnv()按四层优先级合并环境变量自动生成默认值 server.env 首选.env 进程环境变量缺什么就补什么并把自动生成的密钥写回{DATA_DIR}/server.env——这正是日志中 “Secrets persisted to” 的来源/data/storage.sqlite说明数据库写入持久卷由 migrationRunner.ts 负责建库与迁移。如果你看到的是/app/data/...说明DATA_DIR没配对回退到了镜像内置默认值见 Dockerfile需要立即修正。此外源码还解释了第 5 节提到的一个安全机制从源码结构看STORAGE_ENCRYPTION_KEY会在每次启动时对已存在的enc:v1:密文做“解密探针”密钥不匹配时会明确打印恢复指引而不是静默丢失凭据bootstrap-env.mjs。这意味着一旦有加密凭据入库STORAGE_ENCRYPTION_KEY就成了必须长期保管的密钥更换它之前务必备份server.env。11. 常见问题11.1Secrets页面是空的通常有两种原因你还没执行flyctl secrets set你打开的是另一个应用例如oroute不是omniroute11.2flyctl deploy报app not found先创建应用flyctl apps create omniroute11.3fly.toml解析失败重点检查注释里是否有乱码字符TOML 引号和缩进是否正确11.4 数据没有持久化检查以下两点fly.toml中是否存在destination /data当前仓库为 fly.toml还附带了 80% 阈值、1GB 步进、10GB 上限的自动扩容配置DATA_DIR是否设置为/data同时留意 check-permissions.sh 的入口告警它会在挂载卷属主不正确时给出提示避免权限问题导致的假性“数据丢失”。11.5 不设置INITIAL_PASSWORD是否能跑可以运行但会回退到默认CHANGEMEbootstrap-env.mjs 会打印警告。生产环境建议尽快修改后台密码。12. 新项目复用建议如果以后是新项目照着这份文档部署最少改这几项修改fly.toml里的app修改NEXT_PUBLIC_BASE_URL保持DATA_DIR/data重新生成API_KEY_SECRET、JWT_SECRET、MACHINE_ID_SALT、STORAGE_ENCRYPTION_KEY首次部署后检查日志是否写入/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 omniroute适用前提本流程以当前仓库的 Dockerfile多阶段构建runner-base目标 Turbopack 构建、fly.tomlsin区域、1 vCPU / 1GB 共享内存 VM、20128 端口为验证基础更换 Fly 区域、VM 规格或应用名时需同步调整[env]、[[vm]]与app字段并重新核对NEXT_PUBLIC_BASE_URL与实际域名一致。【免费下载链接】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），仅供参考