OmniRoute 故障排查清单doctor 命令快速诊断端口、提供商与原生依赖【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90 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 450 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 是一个开源 AI 网关AI gateway把 350 提供商、1200 模型Kimi、Claude、GPT、Gemini、GLM、DeepSeek 等聚合到一个 OpenAI 兼容端点并支持配额感知的自动故障转移auto-fallback与 RTK 上下文压缩。当它突然连不上、端口被占用或原生依赖损坏时不必逐个环境变量排查——内置的omniroute doctor命令可以一次性体检配置、端口、数据库、原生依赖与服务器存活状态是新手排障的第一站。为什么排障要先跑一遍 doctor网关类项目的问题往往不在模型而在环境端口被占用、.env缺失、SQLite 数据库迁移落后、better-sqlite3原生二进制与当前平台不匹配……这些故障现象各不相同但根源都能被同一次诊断覆盖。doctor 命令把所有检查项聚合为OK / WARN / FAIL三档结果并输出汇总统计几项通过、几项警告、几项失败让你 30 秒内定位问题所在。 源码入口CLI 的 doctor 命令实现位于bin/cli/commands/doctor.mjsCLI 工具提供商相关健康检查位于src/lib/cli-helper/doctor/checks.ts。一键运行omniroute doctor 基础用法安装完成后在终端直接执行omniroute doctor终端会打印数据目录Data dir、数据库路径然后逐项输出检查结果最后给出汇总行Summary: 8 ok, 1 warning(s), 0 failure(s)只要存在 FAIL 项命令的退出码就是 1方便在脚本或 CI 中做健康门禁全部通过则返回 0。9 大检查项doctor 体检清单逐项拆解1. 配置Config.env 文件与端口合法性检查DATA_DIR、数据目录与当前工作目录下的.env是否存在并验证PORT、API_PORT、DASHBOARD_PORT是否为 1–65535 的合法端口值。.env缺失只是 WARN会回退到默认值端口值非法则是 FAIL。2. 数据库DatabaseSQLite quick_check 与迁移对 SQLite 数据库执行PRAGMA quick_check完整性检查并把磁盘上的迁移文件与数据库已应用的迁移版本做比对发现待执行迁移pending migrations时给出警告。3. 存储加密Storage/encryption密钥与密文一致性如果数据库中存在已加密的凭证样本doctor 会用STORAGE_ENCRYPTION_KEY实际解密抽样验证——密钥缺失或解密失败都是 FAIL这能在数据看起来正常但实际已不可恢复之前提前报警。4. 端口可用性Port availability在127.0.0.1上尝试监听 Dashboard 与 API 端口若返回EADDRINUSE说明端口被其他进程占用——这是启动即失败最常见的原因。5. Node 运行时Node runtime校验当前 Node 版本是否落在官方支持策略内本项目要求 Node 22.22.2 或 24不支持 23。6. 原生依赖Native binarybetter-sqlite3 兼容性查找node_modules、dist/node_modules等位置下的better-sqlite3预编译二进制如linux-x64.node并校验它与当前平台/架构是否兼容。Linux musl 与 glibc 会被区分处理。二进制缺失通常是升级 Node 后启动崩溃的元凶。7. 内存Memory校验OMNIROUTE_MEMORY_MB默认 512配置值合法且不超过机器总内存。8. 服务器存活Server liveness请求健康端点/api/health/degradation2 秒超时若因需要管理令牌而拿不到 200会自动退化为探测静态资源/favicon.ico来确认服务进程是否真的活着。9. CLI 机器令牌与工具健康CLI machine token / CLI Tools验证本地机器令牌machine token能否被服务端接受——跨主机或容器边界部署被拒绝时doctor 会直接提示你用omniroute connect host --key oma_live_...建立连接随后继续执行提供商相关的 CLI 工具检查帮助定位具体提供商的连接问题。常见故障速查表症状对应检查项典型处理启动报错、端口监听失败Port availability换端口修改PORT/API_PORT或结束占用进程升级 Node 后无法启动Native binary重新安装依赖让 better-sqlite3 生成匹配的预编译二进制面板打不开、CLI 却正常Server liveness检查服务进程与 Dashboard 端口部分提供商连接失败CLI Tools检查对应提供商凭证与配额网关会自动切换到备用提供商数据库打不开Database备份后删除损坏库让 doctor 重建或检查迁移状态实用参数跳过存活探测与 JSON 输出--no-liveness跳过 HTTP 健康端点探测适合离线或纯配置检查场景--host host/--liveness-url url指定存活探测的目标主机或完整 URL远程部署时非常有用--output json输出结构化 JSON 结果方便脚本解析或存档。omniroute doctor --no-liveness --output json写在最后把omniroute doctor当作 OmniRoute 的日常体检工具升级运行时、迁移主机、或遇到玄学故障时先跑一遍再动手改配置能省掉大部分盲目试错的时间。配合仪表盘上的健康页面与提供商列表端口、数据库、原生依赖、服务器与提供商五类问题都能在一处闭环处理。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90 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 450 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OmniRoute 故障排查清单：doctor 命令快速诊断端口、提供商与原生依赖
OmniRoute 故障排查清单doctor 命令快速诊断端口、提供商与原生依赖【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90 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 450 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 是一个开源 AI 网关AI gateway把 350 提供商、1200 模型Kimi、Claude、GPT、Gemini、GLM、DeepSeek 等聚合到一个 OpenAI 兼容端点并支持配额感知的自动故障转移auto-fallback与 RTK 上下文压缩。当它突然连不上、端口被占用或原生依赖损坏时不必逐个环境变量排查——内置的omniroute doctor命令可以一次性体检配置、端口、数据库、原生依赖与服务器存活状态是新手排障的第一站。为什么排障要先跑一遍 doctor网关类项目的问题往往不在模型而在环境端口被占用、.env缺失、SQLite 数据库迁移落后、better-sqlite3原生二进制与当前平台不匹配……这些故障现象各不相同但根源都能被同一次诊断覆盖。doctor 命令把所有检查项聚合为OK / WARN / FAIL三档结果并输出汇总统计几项通过、几项警告、几项失败让你 30 秒内定位问题所在。 源码入口CLI 的 doctor 命令实现位于bin/cli/commands/doctor.mjsCLI 工具提供商相关健康检查位于src/lib/cli-helper/doctor/checks.ts。一键运行omniroute doctor 基础用法安装完成后在终端直接执行omniroute doctor终端会打印数据目录Data dir、数据库路径然后逐项输出检查结果最后给出汇总行Summary: 8 ok, 1 warning(s), 0 failure(s)只要存在 FAIL 项命令的退出码就是 1方便在脚本或 CI 中做健康门禁全部通过则返回 0。9 大检查项doctor 体检清单逐项拆解1. 配置Config.env 文件与端口合法性检查DATA_DIR、数据目录与当前工作目录下的.env是否存在并验证PORT、API_PORT、DASHBOARD_PORT是否为 1–65535 的合法端口值。.env缺失只是 WARN会回退到默认值端口值非法则是 FAIL。2. 数据库DatabaseSQLite quick_check 与迁移对 SQLite 数据库执行PRAGMA quick_check完整性检查并把磁盘上的迁移文件与数据库已应用的迁移版本做比对发现待执行迁移pending migrations时给出警告。3. 存储加密Storage/encryption密钥与密文一致性如果数据库中存在已加密的凭证样本doctor 会用STORAGE_ENCRYPTION_KEY实际解密抽样验证——密钥缺失或解密失败都是 FAIL这能在数据看起来正常但实际已不可恢复之前提前报警。4. 端口可用性Port availability在127.0.0.1上尝试监听 Dashboard 与 API 端口若返回EADDRINUSE说明端口被其他进程占用——这是启动即失败最常见的原因。5. Node 运行时Node runtime校验当前 Node 版本是否落在官方支持策略内本项目要求 Node 22.22.2 或 24不支持 23。6. 原生依赖Native binarybetter-sqlite3 兼容性查找node_modules、dist/node_modules等位置下的better-sqlite3预编译二进制如linux-x64.node并校验它与当前平台/架构是否兼容。Linux musl 与 glibc 会被区分处理。二进制缺失通常是升级 Node 后启动崩溃的元凶。7. 内存Memory校验OMNIROUTE_MEMORY_MB默认 512配置值合法且不超过机器总内存。8. 服务器存活Server liveness请求健康端点/api/health/degradation2 秒超时若因需要管理令牌而拿不到 200会自动退化为探测静态资源/favicon.ico来确认服务进程是否真的活着。9. CLI 机器令牌与工具健康CLI machine token / CLI Tools验证本地机器令牌machine token能否被服务端接受——跨主机或容器边界部署被拒绝时doctor 会直接提示你用omniroute connect host --key oma_live_...建立连接随后继续执行提供商相关的 CLI 工具检查帮助定位具体提供商的连接问题。常见故障速查表症状对应检查项典型处理启动报错、端口监听失败Port availability换端口修改PORT/API_PORT或结束占用进程升级 Node 后无法启动Native binary重新安装依赖让 better-sqlite3 生成匹配的预编译二进制面板打不开、CLI 却正常Server liveness检查服务进程与 Dashboard 端口部分提供商连接失败CLI Tools检查对应提供商凭证与配额网关会自动切换到备用提供商数据库打不开Database备份后删除损坏库让 doctor 重建或检查迁移状态实用参数跳过存活探测与 JSON 输出--no-liveness跳过 HTTP 健康端点探测适合离线或纯配置检查场景--host host/--liveness-url url指定存活探测的目标主机或完整 URL远程部署时非常有用--output json输出结构化 JSON 结果方便脚本解析或存档。omniroute doctor --no-liveness --output json写在最后把omniroute doctor当作 OmniRoute 的日常体检工具升级运行时、迁移主机、或遇到玄学故障时先跑一遍再动手改配置能省掉大部分盲目试错的时间。配合仪表盘上的健康页面与提供商列表端口、数据库、原生依赖、服务器与提供商五类问题都能在一处闭环处理。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90 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 450 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考