常见问题

添加或刷新订阅失败

1. 在服务器上直接访问订阅 URL，确认不是过期、限 IP 或需要特殊请求头。
2. 检查系统时间和 DNS；HTTPS 时间错误也会表现为下载失败。
3. Docker/RouterOS 检查容器是否有默认互联网出口。
4. 查看应用日志中的 HTTP 状态码和解析错误。

自动刷新间隔在“节点与订阅”页面设置，0 表示关闭。临时失败时先保留已有节点，不要反复删除订阅。

sing-box 一直重启

通常是生成配置不被当前内核接受、端口冲突或自定义 JSON 错误。看 sing-box 日志中的第一条 ERROR，停用最近的高级配置，确认 53/2080/9090 未被同一 IP 上其他程序占用，再重新应用。

连接代理后出现 HTTP 错误

• 407：代理认证已开启，使用代理用户名密码，不是后台密码。
• 502 或连接失败：当前节点不可用、规则选错出站或订阅已失效。
• 部分站点失败：检查 DNS 分流、IPv6、纯 IP 目标及最终出站。

先用显式代理访问一个 IP 查询站点，再到控制台看连接走向；这样能区分“代理入口问题”和“路由规则问题”。

HTTP/SOCKS5 开关刷新后又关闭

切换后必须点击设置页保存按钮，再应用配置。若保存仍回退，查看应用日志是否有字段校验或写入错误。混合代理默认应开启，密码不是强制项；关闭认证时不要把 2080 暴露到公网。

代理控制台打不开或要求手填信息

先确认 sing-box 已运行、9090 正在监听。入口应使用当前访问后台的 IP，而不是 127.0.0.1；可直接访问 http://CMSingBox-IP:9090/ui/。修改 Clash API 端口或密钥后必须重新应用配置。

DNS 在哪里开启

进入“设置 → DNS”，开启“独立 DNS 服务”，监听地址设为 0.0.0.0、端口默认 53，保存并应用配置。然后还要在 DHCP 或终端中把 DNS 指向 CMSingBox IP。代理 DNS 上游的 127.0.0.1:1053 是同机内部地址，不是客户端要填写的地址，也不要替换成部署机器的局域网 IP。Docker/RouterOS 使用独立 IP，不占宿主机的 53。

Docker 内核无法下载

镜像已经集成基础内核，不下载也能启动。在线更新失败时检查容器 egress 网络、DNS、GitHub 连通性和设置中的 GitHub 代理。确认 Compose 同时有 egress 与 lan 网络。

docker exec cmsingbox sh -c 'ip route; cat /etc/resolv.conf'
docker compose logs --tail=200 cmsingbox

Docker 宿主机打不开容器，但手机能打开

这是 macvlan 默认隔离。局域网其他设备能访问说明服务正常。若所有设备都不通，检查 parent 物理网卡、独立 IP 冲突、交换机或云平台是否允许多个 MAC。

RouterOS 配置 DNS 后断网

只配置 DNS 而没有 FakeIP 路由会断网；把 CMSingBox 自己加入代理设备列表也会环回。先按 断网回滚停用 mangle 和 DNS NAT，再逐项检查透明代理、路由表和计数。

授权中心离线会影响已授权设备吗

授权由客户端使用内置公钥校验签名。已签发、仍在有效条件内的授权不依赖授权中心实时在线；授权中心故障会影响新授权签发和管理。未授权状态只限制订阅链接最多 1 条，节点数量不限。

迁移或升级前备份什么

优先在“设置 → 数据管理”导出备份。原生部署另备份数据目录 /var/lib/cmsingbox；Docker 备份 Compose 目录下的 data；RouterOS 备份挂载的 cmsingbox-data。恢复后重新检查端口、IP 与证书路径。

如何提供有效故障信息

请同时提供部署方式、CPU 架构、CMSingBox 与 sing-box 版本、问题发生时间、相关页面截图，以及应用日志和 sing-box 日志中从第一条 ERROR 开始的片段。授权码、订阅 URL、密码和证书私钥应先打码。