OmniRoute 在 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导读本文基于 OmniRoute 仓库中已实测验证的 Fly.io 部署文档原文见 docs/i18n/id/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md英文原版见 docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md系统讲解如何将 OmniRoute单端点接入 350 提供方、1200 模型的统一 AI 网关发布到 Fly.io。指南覆盖两大核心场景项目首次部署、以及后续代码更新的滚动发布同时给出可复用到新项目的完整部署流程参考。读完本文你将掌握flyctl发布、Fly Volume 持久化挂载、Secrets 一次性配置、fork 仓库同步上游更新并保留自定义fly.toml以及用启动日志验证部署成败的完整技能。1. 部署目标与环境概览当前仓库针对 Fly.io 的部署方案已实测验证目标环境如下项目值平台Fly.io发布方式本地使用flyctl直接发布运行载体仓库内已就绪的Dockerfile与 fly.toml数据持久化Fly Volume 挂载到/data访问地址https://omniroute.fly.dev/这套方案的特点是开箱即用不需要额外编写 Docker 编排或构建脚本仓库根目录的 fly.toml 与 Dockerfile 已经包含完整的发布配置本地只需登录账号后执行flyctl deploy即可。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各字段的实际含义与仓库佐证app omniroute指定部署目标是哪个 Fly 应用flyctl系列命令与 Fly 控制台均以此名定位应用。实际仓库文件第一行还标注了它由oroute于 2026-03-20 生成因此历史遗留应用中可能存在oroute与omniroute并存的情况操作时务必区分。destination /dataFly Volume 挂载到容器的/data目录这是数据库与密钥的持久化落点。[processes] app node run-standalone.mjs应用入口。对应 scripts/dev/run-standalone.mjs该脚本首先调用bootstrapEnv()完成密钥引导再以转发信号的方式启动真正的服务进程且优先选择带 WebSocket 包装的server-ws.mjs具备可信对端 IP 戳记缺失时才回退到裸的server.js。internal_port 20128容器内 HTTP 服务端口。与 Dockerfile 中ENV PORT20128及EXPOSE 20128一致。此外仓库实际fly.toml还包含了指南之外但同样值得了解的增强配置当前仓库即为佐证见 fly.tomlVolume 自动扩容auto_extend_size_threshold 80、auto_extend_size_increment 1GB、auto_extend_size_limit 10GB当卷使用率超过 80% 时自动扩容 1GB上限 10GBHTTP 服务加固force_https true、auto_stop_machines stop无流量时停机省额度、auto_start_machines true、min_machines_running 1VM 规格memory 1gb、cpu_kind shared、cpus 1。关键前提本项目必须设置DATA_DIR/data。若缺失数据库和密钥会被写入容器临时目录容器重建即丢失全部数据详见第 6、7 节。3. 前置工具准备3.1 安装 Fly CLIflyctlWindows PowerShell 一键安装pwsh -Command iwr https://fly.io/install.ps1 -useb | iex如果当前环境的安装脚本执行失败也可以手动下载flyctl二进制文件并放置到PATH目录中。3.2 登录 Fly 账号flyctl auth login3.3 验证登录状态flyctl auth whoami flyctl versionauth whoami应输出当前登录账号version输出 flyctl 版本号二者均正常即说明 CLI 环境就绪。4. 首次部署完整流程4.1 拉取代码并进入目录git clone OmniRoute 仓库地址 cd OmniRoute4.2 确认应用名称打开fly.toml关注这一行app omniroute若计划部署到自己新建的应用应改为全局唯一的名字例如app omniroute-yourname注意两点在 Fly 控制台确认你看到的应用与fly.toml中app的值一致若之前曾用过其他名字如oroute不要与omniroute混淆flyctl命令与 Secrets 均按app名定向。4.3 创建应用若尚不存在flyctl apps create omniroute如果你已经改名把omniroute替换成你自己的应用名。4.4 执行首次部署flyctl deployflyctl 会自动读取仓库根目录的 Dockerfile 构建镜像并创建第一个 Machine。构建链路的关键环节在 Dockerfile 中有明确体现采用npm ci --ignore-scripts缩减供应链攻击面随后针对better-sqlite3直接调用 node-gyp 重建原生绑定并做内存库冒烟测试最后以非 root 用户nodeUID/GID 1000运行并通过ENTRYPOINT中的check-permissions.sh检查挂载卷的属主。5. 必配参数清单以下是本项目在 Fly.io 上运行的最低推荐参数集合。5.1 已实测验证的参数以下参数已在当前omniroute应用上真实使用API_KEY_SECRETDATA_DIRJWT_SECRETMACHINE_ID_SALTNEXT_PUBLIC_BASE_URLSTORAGE_ENCRYPTION_KEY5.2 关于INITIAL_PASSWORD当前项目部署未设置INITIAL_PASSWORD因为本次部署场景不需要它。其影响如下未设置时启动日志会提示默认密码为CHANGEME部署完成后应尽快在系统设置中修改登录密码若希望首次部署时自动初始化管理面板密码可后续补加INITIAL_PASSWORD。这一行为在仓库的引导逻辑中得到了源码级印证 scripts/build/bootstrap-env.mjs 会在INITIAL_PASSWORD缺失或等于CHANGEME时输出警告⚠️ INITIAL_PASSWORD is not set — using default CHANGEME. Change it in Settings!。6. 推荐参数逐项说明6.1 建议存入 Fly Secrets 的参数变量名推荐程度作用说明API_KEY_SECRET必需用于 API Key 的生成与校验签名JWT_SECRET必需用于登录会话与 JWT 签名STORAGE_ENCRYPTION_KEY强烈推荐加密敏感连接信息provider 凭据字段MACHINE_ID_SALT推荐生成稳定的机器标识INITIAL_PASSWORD可选指定管理面板首次部署时的初始密码各平台 OAuth/API 凭据按需配置各外部平台的认证6.2 当前项目推荐值变量名推荐值DATA_DIR/dataNEXT_PUBLIC_BASE_URLhttps://omniroute.fly.dev说明DATA_DIR/data至关重要必须与 fly.toml 中 Fly Volume 的挂载点destination /data保持一致NEXT_PUBLIC_BASE_URL用于调度器回调和前端回调等场景需指向应用的公网地址。源码级原理补充DATA_DIR的解析逻辑定义在 src/lib/dataPaths.ts优先读取process.env.DATA_DIR未配置时才回退到默认目录Linux 下为~/.omnirouteWindows 下为%APPDATA%\omniroute。引导脚本 scripts/build/bootstrap-env.mjs 复刻了同样的解析顺序。而密钥的持久化在 scripts/build/bootstrap-env.mjs首次启动时自动生成缺失的密钥并写入{DATA_DIR}/server.env确保重启、卷重挂载与升级后密钥不丢失。若DATA_DIR指向容器临时目录server.env与 SQLite 数据库都会随之蒸发。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_PASSWORDkata-sandi-kuat-anda -a omniroute随机值的位数与仓库引导逻辑的期望吻合JWT_SECRET在缺失时由randomBytes(64)生成128 位十六进制STORAGE_ENCRYPTION_KEY与API_KEY_SECRET由randomBytes(32)生成见 scripts/build/bootstrap-env.mjs。即使不手动设置这些 Secret首次启动也会自动生成并持久化手动预置的意义在于部署前锁定密钥值保证多实例/跨环境一致性。顺序提示flyctl secrets set会触发 Machine 滚动重启所以最佳实践是先设置 Secrets 再首次flyctl deploy避免先启动后又重启。8. 查看当前参数flyctl secrets list -a omniroute如果 Fly 控制台的Secrets页面没有显示你预期的变量请依次排查当前查看的应用是否为omniroutefly.toml中app的值是否与控制台中的应用一致。9. 后续更新与滚动发布9.1 常规代码更新代码更新后的发布流程非常简单git pull flyctl deploy若只是更新参数而不改代码flyctl secrets set KEYvalue -a omnirouteFly 会自动以滚动更新方式重启 Machine 使参数生效。9.2 Fork 仓库同步上游更新并保留自定义fly.toml如果当前仓库是 fork且希望同步上游的更新可以遵循以下流程。先确认现有 remotegit remote -v应至少包含origin指向你自己的 forkupstream指向原仓库。若没有upstream先添加git remote add upstream 上游仓库地址同步前先拉取上游最新的 commit 与 taggit fetch upstream --tags查看当前版本与上游 taggit describe --tags --always git show --no-patch --oneline v3.4.7若要合并最新upstream/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从合并前的提交恢复你自己的fly.toml若上游未改动fly.toml该步骤不会产生额外差异若上游改动了fly.toml该步骤能确保 fork 自定义的部署配置应用名、Volume 挂载、region 等不被覆盖。如果只想对齐某个特定发布 tag如v3.4.7先确认该 tag 已包含在upstream/main中git merge-base --is-ancestor v3.4.7 upstream/main命令成功退出码 0即说明upstream/main已包含该版本可以直接合并upstream/main。9.3 同步后的标准发布顺序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时采用的就是这套流程。10. 部署后检查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即说明站点正常响应。注意请求经历了 HTTP→HTTPS 跳转fly.toml中force_https true因此这里显式设置了-MaximumRedirection 5。11. 部署成功的判定指标部署成功后启动日志中应当出现以下两行[bootstrap] Secrets persisted to: /data/server.env [DB] SQLite database ready: /data/storage.sqlite这两点至关重要/data/server.env运行时密钥已持久化到卷中说明DATA_DIR生效且卷挂载正确/data/storage.sqliteSQLite 数据库已写入持久卷业务数据不会随容器销毁而丢失。如果看到的是/app/data/...说明DATA_DIR配置不正确需要立即修复。仓库源码与这两条日志一一对应Secrets persisted to: ...输出于 scripts/build/bootstrap-env.mjs路径由join(dataDir, server.env)计算dataDir即DATA_DIR解析结果[DB] SQLite database ready:输出于 src/lib/db/core.ts其路径由path.join(DATA_DIR, storage.sqlite)生成见 src/lib/db/core.ts。值得说明的是镜像内默认DATA_DIR/app/dataDockerfile这正是看到/app/data即配置错误的根源——必须用 Fly Secrets 里的DATA_DIR/data覆盖默认值使其落到 Volume 挂载点。12. 常见问题排查12.1Secrets页面为空通常有两种原因还没有执行过flyctl secrets set打开的是错误的应用例如oroute而不是omniroute。12.2flyctl deploy报app not found先创建应用flyctl apps create omniroute12.3fly.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。切勿复用旧项目的密钥——STORAGE_ENCRYPTION_KEY一旦与已加密凭据不匹配引导阶段会直接拒绝自动生成并提示恢复原密钥见 scripts/build/bootstrap-env.mjs且运行时解密探测会输出STORAGE_ENCRYPTION_KEY does not match的告警见 scripts/build/bootstrap-env.mjs。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附进一步阅读fly.toml —— 本仓库的 Fly.io 部署配置文件含 Volume 自动扩容与机器生命周期策略Dockerfile —— 多阶段构建镜像含 CVE 修补、原生模块重建、非 root 运行、健康检查scripts/dev/run-standalone.mjs —— 运行时入口引导密钥 启动 WebSocket 包装服务scripts/build/bootstrap-env.mjs —— 零配置引导密钥自动生成、server.env持久化、密钥不匹配探测src/lib/dataPaths.ts ——DATA_DIR解析与默认目录回退逻辑src/lib/db/core.ts —— SQLite 数据库初始化与就绪日志docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md —— 英文原版部署指南docs/i18n/zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md —— 简体中文版部署指南【免费下载链接】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），仅供参考 OmniRoute 在 Fly.io 上的生产级部署指南：从首次部署到滚动更新与数据持久化
OmniRoute 在 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导读本文基于 OmniRoute 仓库中已实测验证的 Fly.io 部署文档原文见 docs/i18n/id/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md英文原版见 docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md系统讲解如何将 OmniRoute单端点接入 350 提供方、1200 模型的统一 AI 网关发布到 Fly.io。指南覆盖两大核心场景项目首次部署、以及后续代码更新的滚动发布同时给出可复用到新项目的完整部署流程参考。读完本文你将掌握flyctl发布、Fly Volume 持久化挂载、Secrets 一次性配置、fork 仓库同步上游更新并保留自定义fly.toml以及用启动日志验证部署成败的完整技能。1. 部署目标与环境概览当前仓库针对 Fly.io 的部署方案已实测验证目标环境如下项目值平台Fly.io发布方式本地使用flyctl直接发布运行载体仓库内已就绪的Dockerfile与 fly.toml数据持久化Fly Volume 挂载到/data访问地址https://omniroute.fly.dev/这套方案的特点是开箱即用不需要额外编写 Docker 编排或构建脚本仓库根目录的 fly.toml 与 Dockerfile 已经包含完整的发布配置本地只需登录账号后执行flyctl deploy即可。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各字段的实际含义与仓库佐证app omniroute指定部署目标是哪个 Fly 应用flyctl系列命令与 Fly 控制台均以此名定位应用。实际仓库文件第一行还标注了它由oroute于 2026-03-20 生成因此历史遗留应用中可能存在oroute与omniroute并存的情况操作时务必区分。destination /dataFly Volume 挂载到容器的/data目录这是数据库与密钥的持久化落点。[processes] app node run-standalone.mjs应用入口。对应 scripts/dev/run-standalone.mjs该脚本首先调用bootstrapEnv()完成密钥引导再以转发信号的方式启动真正的服务进程且优先选择带 WebSocket 包装的server-ws.mjs具备可信对端 IP 戳记缺失时才回退到裸的server.js。internal_port 20128容器内 HTTP 服务端口。与 Dockerfile 中ENV PORT20128及EXPOSE 20128一致。此外仓库实际fly.toml还包含了指南之外但同样值得了解的增强配置当前仓库即为佐证见 fly.tomlVolume 自动扩容auto_extend_size_threshold 80、auto_extend_size_increment 1GB、auto_extend_size_limit 10GB当卷使用率超过 80% 时自动扩容 1GB上限 10GBHTTP 服务加固force_https true、auto_stop_machines stop无流量时停机省额度、auto_start_machines true、min_machines_running 1VM 规格memory 1gb、cpu_kind shared、cpus 1。关键前提本项目必须设置DATA_DIR/data。若缺失数据库和密钥会被写入容器临时目录容器重建即丢失全部数据详见第 6、7 节。3. 前置工具准备3.1 安装 Fly CLIflyctlWindows PowerShell 一键安装pwsh -Command iwr https://fly.io/install.ps1 -useb | iex如果当前环境的安装脚本执行失败也可以手动下载flyctl二进制文件并放置到PATH目录中。3.2 登录 Fly 账号flyctl auth login3.3 验证登录状态flyctl auth whoami flyctl versionauth whoami应输出当前登录账号version输出 flyctl 版本号二者均正常即说明 CLI 环境就绪。4. 首次部署完整流程4.1 拉取代码并进入目录git clone OmniRoute 仓库地址 cd OmniRoute4.2 确认应用名称打开fly.toml关注这一行app omniroute若计划部署到自己新建的应用应改为全局唯一的名字例如app omniroute-yourname注意两点在 Fly 控制台确认你看到的应用与fly.toml中app的值一致若之前曾用过其他名字如oroute不要与omniroute混淆flyctl命令与 Secrets 均按app名定向。4.3 创建应用若尚不存在flyctl apps create omniroute如果你已经改名把omniroute替换成你自己的应用名。4.4 执行首次部署flyctl deployflyctl 会自动读取仓库根目录的 Dockerfile 构建镜像并创建第一个 Machine。构建链路的关键环节在 Dockerfile 中有明确体现采用npm ci --ignore-scripts缩减供应链攻击面随后针对better-sqlite3直接调用 node-gyp 重建原生绑定并做内存库冒烟测试最后以非 root 用户nodeUID/GID 1000运行并通过ENTRYPOINT中的check-permissions.sh检查挂载卷的属主。5. 必配参数清单以下是本项目在 Fly.io 上运行的最低推荐参数集合。5.1 已实测验证的参数以下参数已在当前omniroute应用上真实使用API_KEY_SECRETDATA_DIRJWT_SECRETMACHINE_ID_SALTNEXT_PUBLIC_BASE_URLSTORAGE_ENCRYPTION_KEY5.2 关于INITIAL_PASSWORD当前项目部署未设置INITIAL_PASSWORD因为本次部署场景不需要它。其影响如下未设置时启动日志会提示默认密码为CHANGEME部署完成后应尽快在系统设置中修改登录密码若希望首次部署时自动初始化管理面板密码可后续补加INITIAL_PASSWORD。这一行为在仓库的引导逻辑中得到了源码级印证 scripts/build/bootstrap-env.mjs 会在INITIAL_PASSWORD缺失或等于CHANGEME时输出警告⚠️ INITIAL_PASSWORD is not set — using default CHANGEME. Change it in Settings!。6. 推荐参数逐项说明6.1 建议存入 Fly Secrets 的参数变量名推荐程度作用说明API_KEY_SECRET必需用于 API Key 的生成与校验签名JWT_SECRET必需用于登录会话与 JWT 签名STORAGE_ENCRYPTION_KEY强烈推荐加密敏感连接信息provider 凭据字段MACHINE_ID_SALT推荐生成稳定的机器标识INITIAL_PASSWORD可选指定管理面板首次部署时的初始密码各平台 OAuth/API 凭据按需配置各外部平台的认证6.2 当前项目推荐值变量名推荐值DATA_DIR/dataNEXT_PUBLIC_BASE_URLhttps://omniroute.fly.dev说明DATA_DIR/data至关重要必须与 fly.toml 中 Fly Volume 的挂载点destination /data保持一致NEXT_PUBLIC_BASE_URL用于调度器回调和前端回调等场景需指向应用的公网地址。源码级原理补充DATA_DIR的解析逻辑定义在 src/lib/dataPaths.ts优先读取process.env.DATA_DIR未配置时才回退到默认目录Linux 下为~/.omnirouteWindows 下为%APPDATA%\omniroute。引导脚本 scripts/build/bootstrap-env.mjs 复刻了同样的解析顺序。而密钥的持久化在 scripts/build/bootstrap-env.mjs首次启动时自动生成缺失的密钥并写入{DATA_DIR}/server.env确保重启、卷重挂载与升级后密钥不丢失。若DATA_DIR指向容器临时目录server.env与 SQLite 数据库都会随之蒸发。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_PASSWORDkata-sandi-kuat-anda -a omniroute随机值的位数与仓库引导逻辑的期望吻合JWT_SECRET在缺失时由randomBytes(64)生成128 位十六进制STORAGE_ENCRYPTION_KEY与API_KEY_SECRET由randomBytes(32)生成见 scripts/build/bootstrap-env.mjs。即使不手动设置这些 Secret首次启动也会自动生成并持久化手动预置的意义在于部署前锁定密钥值保证多实例/跨环境一致性。顺序提示flyctl secrets set会触发 Machine 滚动重启所以最佳实践是先设置 Secrets 再首次flyctl deploy避免先启动后又重启。8. 查看当前参数flyctl secrets list -a omniroute如果 Fly 控制台的Secrets页面没有显示你预期的变量请依次排查当前查看的应用是否为omniroutefly.toml中app的值是否与控制台中的应用一致。9. 后续更新与滚动发布9.1 常规代码更新代码更新后的发布流程非常简单git pull flyctl deploy若只是更新参数而不改代码flyctl secrets set KEYvalue -a omnirouteFly 会自动以滚动更新方式重启 Machine 使参数生效。9.2 Fork 仓库同步上游更新并保留自定义fly.toml如果当前仓库是 fork且希望同步上游的更新可以遵循以下流程。先确认现有 remotegit remote -v应至少包含origin指向你自己的 forkupstream指向原仓库。若没有upstream先添加git remote add upstream 上游仓库地址同步前先拉取上游最新的 commit 与 taggit fetch upstream --tags查看当前版本与上游 taggit describe --tags --always git show --no-patch --oneline v3.4.7若要合并最新upstream/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从合并前的提交恢复你自己的fly.toml若上游未改动fly.toml该步骤不会产生额外差异若上游改动了fly.toml该步骤能确保 fork 自定义的部署配置应用名、Volume 挂载、region 等不被覆盖。如果只想对齐某个特定发布 tag如v3.4.7先确认该 tag 已包含在upstream/main中git merge-base --is-ancestor v3.4.7 upstream/main命令成功退出码 0即说明upstream/main已包含该版本可以直接合并upstream/main。9.3 同步后的标准发布顺序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时采用的就是这套流程。10. 部署后检查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即说明站点正常响应。注意请求经历了 HTTP→HTTPS 跳转fly.toml中force_https true因此这里显式设置了-MaximumRedirection 5。11. 部署成功的判定指标部署成功后启动日志中应当出现以下两行[bootstrap] Secrets persisted to: /data/server.env [DB] SQLite database ready: /data/storage.sqlite这两点至关重要/data/server.env运行时密钥已持久化到卷中说明DATA_DIR生效且卷挂载正确/data/storage.sqliteSQLite 数据库已写入持久卷业务数据不会随容器销毁而丢失。如果看到的是/app/data/...说明DATA_DIR配置不正确需要立即修复。仓库源码与这两条日志一一对应Secrets persisted to: ...输出于 scripts/build/bootstrap-env.mjs路径由join(dataDir, server.env)计算dataDir即DATA_DIR解析结果[DB] SQLite database ready:输出于 src/lib/db/core.ts其路径由path.join(DATA_DIR, storage.sqlite)生成见 src/lib/db/core.ts。值得说明的是镜像内默认DATA_DIR/app/dataDockerfile这正是看到/app/data即配置错误的根源——必须用 Fly Secrets 里的DATA_DIR/data覆盖默认值使其落到 Volume 挂载点。12. 常见问题排查12.1Secrets页面为空通常有两种原因还没有执行过flyctl secrets set打开的是错误的应用例如oroute而不是omniroute。12.2flyctl deploy报app not found先创建应用flyctl apps create omniroute12.3fly.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。切勿复用旧项目的密钥——STORAGE_ENCRYPTION_KEY一旦与已加密凭据不匹配引导阶段会直接拒绝自动生成并提示恢复原密钥见 scripts/build/bootstrap-env.mjs且运行时解密探测会输出STORAGE_ENCRYPTION_KEY does not match的告警见 scripts/build/bootstrap-env.mjs。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附进一步阅读fly.toml —— 本仓库的 Fly.io 部署配置文件含 Volume 自动扩容与机器生命周期策略Dockerfile —— 多阶段构建镜像含 CVE 修补、原生模块重建、非 root 运行、健康检查scripts/dev/run-standalone.mjs —— 运行时入口引导密钥 启动 WebSocket 包装服务scripts/build/bootstrap-env.mjs —— 零配置引导密钥自动生成、server.env持久化、密钥不匹配探测src/lib/dataPaths.ts ——DATA_DIR解析与默认目录回退逻辑src/lib/db/core.ts —— SQLite 数据库初始化与就绪日志docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md —— 英文原版部署指南docs/i18n/zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md —— 简体中文版部署指南【免费下载链接】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），仅供参考