Mihomo Web UI 打不开怎么办:从访问地址到后端连接逐层恢复
简答:Mihomo Web UI 打不开时,先区分页面无法访问、面板资源缺失与后端连接失败,再分别核对访问路径、控制器地址和浏览器报错;不要先改节点或重装内核。
定义:Mihomo Web UI 是通过控制 API 管理 Mihomo 内核的网页界面,网页资源可与内核一起托管,也可独立部署。
先试这一步:按眼前现象选择排查入口
先确认控制器地址是否能响应,再判断是否需要修复面板文件,不要一开始就修改代理配置。本文为第三方使用指南,非官方;只处理管理面板无法访问或连接不上内核,不处理所有外部网页打不开的问题。
| 眼前现象 | 先核对什么 | 正常结果与下一步 |
|---|---|---|
| 页面连接被拒绝或一直等待 | 实际地址、监听端口、内核进程与容器映射 | 控制器应返回 HTTP 响应;没有响应时先查服务和访问路径 |
| 页面显示 hello JSON | 是否访问了控制 API 根路径 | 这不等于面板损坏;使用内核托管面板时继续访问 /ui/ |
| /ui/ 返回 404 | external-ui 指向的目录及面板构建资源 | 应加载面板页面;继续检查实际目录、挂载与路径权限 |
| 页面白屏或样式缺失 | 浏览器 Network 中脚本、样式的请求结果 | 资源应成功加载;记录失败资源后再检查部署路径或缓存 |
| 页面能开,但后端连接失败 | 后端 URL、secret、CORS 与浏览器 Console | 应能读取内核状态;按实际请求失败原因继续处理 |
内核托管面板的路径依据 Mihomo 全局配置文档;根路径显示 hello JSON 的现象见 项目问题记录。后端连接与跨域排查可对照 metacubexd 项目说明。表中结论仅作分流判断,不凭一个现象直接认定故障原因。
先分清面板地址、后端地址和浏览器所在设备
面板地址用于加载网页,后端地址用于让网页连接内核,两者不一定相同。控制 API 是供管理界面读取状态、执行管理操作的接口;它不是浏览器上网使用的混合代理端口。部署形态及接口区别可核对 metacubexd 部署说明。
- 记录浏览器地址栏中的完整地址,包括协议、主机、端口和路径。
- 打开面板的后端连接设置,记录它实际保存的内核地址;入口名称以当前版本界面为准。
- 确认浏览器、面板文件、Mihomo 内核分别在哪台设备上运行,不要默认三者在同一台机器。
- 从实际运行配置或启动日志确认控制器端口,不把教程中的示例端口当成自己的端口。
特别注意:浏览器中的 127.0.0.1 指向浏览器所在设备。手机访问 NAS 上的面板时,后端若仍填写这个地址,通常不是在连接 NAS。应填写浏览器能够访问的内核地址,并同时确认内核的监听范围。监听字段的含义见 外部控制配置。
如果后端 URL 字段要求填写 Mihomo 控制器地址,不要把面板的 /ui/ 页面路径直接当成后端地址。若仍分不清代理端口与控制器端口,可先阅读 代理端口与外部控制端口的区别;该文用于理解概念,具体数值仍以本次运行实例为准。
页面完全无法访问:核对进程、监听和生效配置
先在内核运行设备上测试,再从其他设备测试,能减少同时排查多个网络环节的干扰。建议先备份实际配置、服务启动参数和容器部署文件,之后每次只调整一项;尚未确认原因前,不更换订阅或批量修改规则。
- 确认进程持续运行。在实际使用的服务管理器、客户端或容器管理页查看状态,并阅读启动日志。若程序启动后立即退出,先处理日志中提示大意为配置解析失败、端口占用或路径访问失败的问题,不要先修改浏览器。
- 确认正在使用哪份配置。核对服务启动参数、客户端生成的运行配置或容器挂载路径。你编辑的订阅原文件不一定就是内核实际读取的文件。
- 确认控制器监听。检查顶层
external-controller的实际值。仅监听127.0.0.1时,应先在内核所在设备测试;需要局域网管理时,再有针对性地调整监听和访问控制。 - 在浏览器单独访问控制器根地址。返回 JSON 或鉴权相关 HTTP 响应,说明这个地址有服务响应,但还不能证明面板文件与鉴权都正常。没有响应则继续核对端口、服务和网络路径。
控制器监听与 secret 的配置依据见 Mihomo 全局配置。不要把开启 allow-lan 当成开放管理面板的通用修复:该字段针对其他设备经过代理端口访问网络,与控制 API 的监听不是同一项设置。
如果本机可访问而其他设备不可访问,依次核对控制器是否只监听回环地址、目标局域网地址是否正确、防火墙是否允许指定来源访问该端口。不要为测试关闭全部防火墙,也不要直接将控制 API 暴露到公网;需要远程管理时,应使用受保护的管理通道并限制来源。相关安全边界见 控制器保护说明。
显示 hello JSON 或 /ui/ 返回 404:检查面板资源
根路径显示 hello JSON 时,先试面板路径;面板路径不存在时,再查静态资源。Mihomo 项目问题记录展示了根路径返回 {"hello":"mihomo"}、已配置面板通过 /ui/ 访问的情形。这个现象不能单独证明代理功能异常,也不能证明已经安装了面板。
- 确认是否采用内核托管方式。只有配置了相应面板资源,才应期待控制器地址下出现面板;独立面板服务应访问它自己的地址。
- 检查顶层 external-ui。它应指向实际面板资源目录。相对路径是相对于 Mihomo 工作目录,不应按你当前打开文件管理器的位置推算。
- 检查目录内容。确认存在面板构建后的入口页面及其引用资源,例如
index.html与对应脚本文件;不要把只有源代码的目录当成可直接托管的构建目录。metacubexd 的预构建资源获取方式见 项目部署说明。 - 检查目录限制。若资源位于工作目录之外,按文档核对运行进程的
SAFE_PATHS环境变量。Windows 的路径列表使用分号分隔,其他系统使用冒号分隔;设置后还要确认服务进程实际继承了该变量。 - 核对下载或更新结果。配置下载地址不等于已成功取得资源。检查下载日志、解压后的目录层级;使用
external-ui-name时还要核对更新资源的实际落点。
上述路径、环境变量和更新目录行为依据 外部用户界面配置,字段适用性以实际运行版本文档为准。若目录无误但页面白屏,打开浏览器开发者工具的 Network,刷新后查看脚本与样式是否加载成功;先保存失败请求地址和状态,再尝试强制刷新,避免直接删除整个配置目录。
面板能开却连不上内核:分别检查密钥、跨域和协议
页面能打开只证明前端资源可访问,不代表浏览器已获准访问控制 API。先打开开发者工具的 Network 和 Console,刷新面板并重试连接,记录失败请求的地址、状态与提示;以下关键词用于辅助定位,不代表所有版本都会显示完全相同的报错。
- 地址或端口不符:比较失败请求的目标与实际控制器地址,尤其检查旧的面板连接记录。正常结果应是请求发往正在运行的控制 API,而不是混合代理端口或已经变更的旧端口。
- 鉴权失败:若请求返回鉴权失败,先确认请求确实发往 Mihomo 控制 API,再核对面板保存的密钥与生效配置中的
secret。不要通过清空密钥来掩盖问题。接口范围可查 Mihomo API 文档。 - Console 出现 CORS 相关提示:CORS 即跨源资源共享,是浏览器对跨来源请求的访问控制机制。协议、主机或端口不同都可能构成不同来源,详见 MDN 跨源说明。
- Console 出现 Mixed Content 相关提示:混合内容指安全页面加载不安全资源的情形。HTTPS 面板请求 HTTP 后端可能受到浏览器限制,但不能只凭协议不同就断定失败,应以实际控制台记录为准,参见 MDN 混合内容说明。
确认是 CORS 后,先备份配置,再在顶层 external-controller-cors 对应的 allow-origins 中加入面板的准确来源,即协议、主机和实际端口,不附页面路径。不要直接加入通配来源。局域网场景涉及 allow-private-network 时,再结合浏览器报错与运行版本支持情况核对;它不是所有连接失败的万能开关。字段用法与排查方法见 metacubexd 跨域排查说明。
确认是混合内容限制后,优先考虑通过内核托管本地面板,减少不必要的跨来源访问;需要 HTTPS 管理时,正确配置 HTTPS 后端与证书。不要关闭浏览器安全机制。Mihomo 的 external-controller-tls 还需要对应的 tls 证书配置,具体要求见 HTTPS API 配置。每次改动后复测同一请求,未改善就恢复该项原值。
Docker、NAS 与路由器部署:额外核对映射和目录
容器里的服务已启动,不等于浏览器能通过宿主机地址访问它。如果通过 Docker 部署,先在管理界面分别查看面板容器和内核容器,不要把面板容器运行正常当成内核也运行正常。
- 查看容器的网络模式。使用桥接网络时,核对控制 API 的宿主机端口是否已发布,并确认没有只发布面板端口。
- 浏览器应连接可达的宿主机地址与已发布端口;不能直接照搬仅在容器内部有效的地址。
- 检查发布端口绑定的宿主机地址。仅绑定回环地址的端口不能按普通局域网入口使用;需要改变绑定时,同时设置来源限制。
- 核对面板资源与配置卷的挂载位置。配置中的路径必须在内核进程所在的文件系统内存在,不能只在宿主机上存在。
- 在 NAS 或路由器插件中,查看其生成配置和实际进程日志;没有核实具体插件版本前,不套用统一菜单路径。
端口发布与绑定行为依据 Docker 端口发布文档。纯面板容器、桌面应用和一体化服务的职责不同,部署区别可查 metacubexd 部署形态说明;实际端口以部署文件、应用显示及日志为准。
修复后怎样确认完成,失败时怎样回滚
修复完成的标准是面板资源加载正常、后端状态可读取,并且原有网络使用未因本次调整而退化。建议按下面顺序验收,而不是看到首页出现就停止排查。
- 重新打开预期面板地址,确认不再停留在错误页面或白屏。
- 查看开发者工具,确认关键页面资源没有继续加载失败。
- 在面板读取一次内核状态,并确认失败请求没有继续出现;API 的作用范围见 Mihomo API 文档。
- 保存配置并按部署方式重载或重启后,再打开面板,确认修改没有被客户端生成配置或容器部署流程覆盖。
- 若修改后出现新问题,先恢复最近改动的字段、环境变量或端口映射;仍不能恢复时,使用备份还原,再核对服务启动结果。
需要求助时,提供部署方式、实际版本、面板地址结构、后端地址结构、失败请求状态、脱敏后的控制台信息和启动日志。删除密钥、订阅地址及其他凭据,不上传整份含敏感信息的配置。
如果面板已恢复,但外部网页依然无法访问,下一步阅读 Mihomo 连接成功但打不开网页的排查方法;如果发现修改的配置一直没有生效,阅读 Mihomo 配置文件切换与生效核对。不要把管理面板问题与代理流量问题继续混在一起测试。
参考资料
- Mihomo 全局配置:控制器、密钥、面板目录与 HTTPS
- Mihomo API 文档
- Mihomo 根路径与 /ui/ 行为的问题记录
- metacubexd 部署与连接排查说明
- MDN:跨源资源共享
- MDN:混合内容
- Docker:端口发布与映射
常见问题
Mihomo Web UI 只显示 hello JSON,是内核坏了吗?
不能这样判断。项目问题记录展示过控制器根路径返回 hello JSON、面板位于 /ui/ 的情况。先确认已配置并部署面板资源,再访问相应面板路径;有 JSON 响应不等于面板已经安装,也不等于代理功能异常。
为什么电脑本机能打开,手机却打不开?
先检查手机是否错误地使用了 127.0.0.1,再核对控制器是否仅监听回环地址,以及宿主机端口绑定、防火墙来源限制。不要直接关闭防火墙或无保护地公开控制 API。
浏览器能直接访问后端,为什么面板仍提示连接失败?
直接打开地址与网页脚本跨来源请求不是同一种测试。先在开发者工具中查看实际失败请求,分别判断密钥、CORS、混合内容或目标端口是否有问题,不要仅凭后端页面能打开就排除浏览器限制。
Mihomo Web UI 的后端应该填写混合代理端口吗?
不应该。管理面板连接的是控制 API,混合代理端口用于代理流量。填写实际运行的控制器地址;具体端口从生效配置、应用显示或日志确认,不机械照抄教程示例。
/ui/ 返回 404,必须重新安装 Mihomo 吗?
不必先重装。先确认采用内核托管面板,再检查 external-ui 的实际目录、构建资源、工作目录、挂载位置与 SAFE_PATHS。若使用独立面板服务,应访问其自身地址,而不是默认要求控制器提供 /ui/。
排查面板时需要修改 DNS 或更换节点吗?
通常不应作为第一步。先分清页面加载、资源读取、控制 API 连接与浏览器限制;只有证据指向相关网络环节时才继续处理。面板恢复后外部网页仍无法访问,应另行排查代理流量路径。