外观
常见问题与排查
先找到出问题的环节，再改一项、验证一项。面板能打开、Agent 在线、DNS 能回答、网站能访问，是四个不同的检查结果。
打不开管理页面
- 在 NAS 容器管理器查看容器状态，或运行
docker compose ps。没启动时先看容器日志。 - 确认浏览器用的是面板所在设备 IP。手机上的
localhost指向手机自己，不是 NAS。 - 普通安装
5010:80用http://设备IP:5010，不是内部后端的5001。 - Bridge 模式核对端口映射两侧；Host 模式直接使用实际 Web 监听端口，
ports不起作用。 - 看日志是否端口占用或数据目录无法写入，再检查主机防火墙与局域网连通性。
环境变量和 Web 设置谁优先
优先级是 明确设置的 CONFIGFLOW_WEB_PORT → Web 保存的值 → 默认 80。
例如环境变量是 8088，Web 原来保存 8090，会使用 8088，且网页端口输入只读，不会出现后改网页就覆盖环境变量的情况。移除环境变量并重新创建容器后，才恢复使用 8090；从未保存过则回到 80。
“用于首次启动或访问恢复”的意思是：还没进网页，或者改错端口进不去了，可以先在部署文件指定一个空闲端口，重新创建容器恢复访问。单纯重启不能应用改过的环境变量。 Bridge 模式还要同步更新映射右侧。
具体操作见 安装面板：网络与端口 和 系统设置。修改端口不能让一个没有 IPv6 的 Docker 网络自动拥有 IPv6。
安装完成但设备不能正常上网
| 先检查哪里 | 怎么判断 | 下一步 |
|---|---|---|
| Agent 是否在线 | Agent 页面能收到最新心跳 | 离线先核对设备地址、管理端口、面板服务域名和防火墙 |
| 核心是否运行 | Agent 卡片 / 核心面板显示运行 | 安装 Agent 不一定安装了核心；检查“同时安装核心”和已有程序路径 |
| 配置是否已应用 | 发布记录成功；不是“已上传 / 待应用” | 对目标设备完成应用；失败看具体校验与回滚记录 |
| DNS 是否经过 OxiDNS | 发起一次访问后，在查询列表看到对应记录 | 无记录时核对客户端 DNS、路由器下发和设备是否重新联网 |
| 连接是否经过 Mihomo | 运行面板有该次连接 | 没有时核对网关、主路由规则、Linux 转发与接管设置 |
| 节点本身是否可用 | 测试选中的节点并查看连接错误 | 更换可用节点或修复订阅；不能只看策略组名字 |
先在一台测试电脑或手机验证，再让全家设备改用新 DNS/网关。要退回时，用安装前记录的原 DNS、原网关或路由备份恢复，不要在不知道原值时随意填写公共地址。
保存后没有变化
保存常常只是更新面板中的草稿。到 配置生成 或对应页面发布，确认目标 Agent 和配置空间。RouterOS 还需要自己的“预览发布 → 确认发布”。
改设备名称不需要发布；改 DNS 策略通常需要。已存在的远程规则集可能按更新间隔生效，新建规则或改结构通常需要重新发布，详见相应页面。
设为直连后仍然经过代理
客户端设备里的“直连”首先影响 OxiDNS 返回地址的方式。主路由的按目标 IP 路由、Mihomo 本身的规则、浏览器自己的代理仍可能影响连接。沿着 客户端设备 → 上游路由 → Mihomo 面板 检查实际命中。
下载或更新失败
| 现象 | 优先检查 |
|---|---|
| 订阅拉取失败 | 地址是否过期、服务端能否访问、是否需要下载代理；浏览器能打开不代表容器能打开 |
| 规则下载失败 | 来源地址、格式、代理设置和最近错误；有效旧缓存可能仍保留 |
| 安装脚本或 Agent 下载配置失败 | “服务域名”是否写成 localhost、是否漏令牌、设备能否访问该地址 |
| 更新后节点数量没变 | 是否更新了对应订阅，过滤条件是否排除新节点；设备还可能使用旧配置 |
| Sub-Store 显示休眠 | 默认按需启动；首次转换等待唤醒即可，不必马上重装 |
规则库的“批量测试连通性”会对失败来源自动关闭启用状态，可能影响所有空间。不要把它当作完全只读的诊断按钮。具体区别见 规则库。
Docker 安装相关
DNS 的 53 端口被占用
先看宿主机是否已有 DNS 服务。Host 容器共用宿主机端口，普通 bridge 则看映射；macvlan 用容器自己的独立地址。按 安装组合 选择合适方式，不要只把 DNS 随意换成客户端不会使用的端口。
macvlan 容器连不到宿主机上的面板
macvlan 默认隔离容器与所在宿主机的直接通信。先安排实际可达的面板地址或网络，再继续安装；单纯修改 Agent 名称或密码无法解决此问题。支持条件允许时，初次 HA 部署可使用 Host 方案。
有 IPv6，为什么 HA 仍要求 IPv4
当前 OxiDNS 高可用创建的是 IPv4 共用地址。DNS 查询可以包含 IPv6 地址记录，但这与建立 IPv6 VIP 是不同的事。不要用第二套未经安排的 IPv6 DNS 绕过已配置的 VIP。详情见 高可用支持范围。
OxiDNS 双机备用异常
先按 高可用检查失败与常见问题 检查。常见原因是两端不在同一局域网、共用地址已被占用、容器缺少 HA 准备、两台实际上属于同一宿主机，或 OxiDNS 只监听了本机地址。
不要把普通“重启”当作计划切换，也不要在确认备用可用前同时停止两台。Host 辅助容器被强杀后的 VIP 清理、停用和升级顺序见 高可用维护。
升级后配置不见了
先核对挂载目录。挂到新的空目录会像首次安装，不代表旧目录已丢失。保留现有文件，找回原数据目录或备份，再按 备份与升级 恢复。
JSON 导出不等于整个数据目录副本；它不包含全部运行文件、监控历史和 Web 监听端口。迁移前先确认自己需要保留哪些内容。
反馈问题时提供什么
描述“在哪个页面、点哪个按钮、期望什么、实际发生什么”，附上发生时间、面板和 Agent 版本、安装组合、相关错误及已尝试步骤。敏感的订阅地址、令牌、密码要遮住。
优先附 日志 和发布记录中的具体失败项；如果是 HA，分别说明两端 Shell/Host/macvlan 方式。这样比只发“不能用”更容易找到原因。