MIHOMO / CONFIGURATION REFERENCE

Clash 配置进阶

从配置引用关系到流量接管路径,按章节修改,按连接记录验证。

本页用于完成基础连接后的系统查阅。首次安装、导入订阅和开启系统代理,请先阅读使用文档。以下参数以 mihomo 配置结构为主;客户端界面的同名选项可能通过覆写生成最终值,应以实际运行配置为准。

模式与配置基线

进阶配置首先需要一条已经验证可用的连接路径。保留当前能访问的订阅、一个手动选择的节点和系统代理设置,记录客户端名称、内核类型、混合端口以及当前 Profile。不要同时替换订阅、启用 TUN 和修改 DNS;多处变化叠加后,网页能否打开只能说明最终结果,无法定位是哪一层改变了行为。

区分配置来源与运行结果

客户端通常把订阅文件、本地设置和覆写内容组合后交给内核。订阅编辑器里写着一个端口,不代表内核最终监听同一个端口。检查客户端提供的运行配置、内核配置预览或启动日志,确认实际值。若文件保存成功但行为未变,先确认编辑的是当前激活的 Profile,再确认是否需要重新加载,而不是反复添加相同字段。

配置中的名称引用也属于运行依赖。规则末尾的策略名称必须能在节点或策略组中找到,策略组引用的 provider 必须已经定义。YAML 能被解析,只能证明语法成立,不能证明这些对象存在。使用空格缩进,避免制表符;名称含逗号、冒号或特殊符号时使用引号,并在重命名后检查所有引用位置。

规则、全局与直连的用途

mode: rule 按规则列表从上到下决定出站;全局模式通常把需要代理决策的连接交给全局策略;直连模式用于绕过代理出站。模式选择不会凭空修复节点、解析或路由问题,也不等于已经接管所有应用。系统代理之外的程序是否进入内核,仍由应用设置、TUN 或网关转发决定。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

这段基线把混合代理端口固定为 7890,关闭局域网访问,并保留信息级日志。混合端口可以接受 HTTP 与 SOCKS 代理请求,但应用仍需使用正确的代理协议。端口被占用时应先停止另一个监听进程,或统一修改客户端与应用设置;只修改应用中的数字会让连接指向不存在的监听器。

模式适合检查不能据此推断
规则域名、地址与规则顺序所有应用均已接管
全局当前代理路径是否可用规则内容正确
直连本地网络与直接访问路径DNS 一定绕过内核

建立可以重复的验证过程

每次只改变一个设置,然后用同一个应用发起新连接。已有长连接可能继续使用旧策略,因此需要关闭对应连接或重新启动测试应用。先在连接面板确认请求是否进入内核,再看命中的规则与实际出站。如果没有连接记录,应回到接管层检查;如果有记录但选错策略,再检查规则与策略组。

全局可用而规则模式失败,通常意味着两种模式选取了不同出站,或规则模式把目标交给了不适用的直连路径。比较实际出站名称后再下结论。直连能够访问某个站点,也不能说明整个订阅失效;目标地址、解析结果和服务端行为都可能不同。保留同一目标的对照结果,才能避免把局部现象当成整体故障。

如果需要区分客户端界面与内核行为,可先阅读名词解释中的配置结构与网络接管概念。更换客户端时优先从下载中心选择 Clash Plus,再按平台和所需内核能力比较其他客户端。不同界面的开关位置可以变化,本页采用的验证顺序保持一致:配置加载、请求进入、规则匹配、出站连接。

策略组类型与实战

策略组把规则与具体节点隔离。规则可以长期引用“业务出口”,而组内节点随订阅更新替换。设计时先明确选择目标:需要人工指定、优先保持某条线路、自动选择响应较快的候选,还是把独立连接分散到不同出口。不要把所有组类型堆在同一配置里;层级越多,排查时需要展开的引用链越长。

手动选择与自动选择

select 适合人工固定出口,结果容易解释。url-test 根据探测结果自动选择候选;fallback 按列表顺序使用可用项,适合主备关系;load-balance 按策略分配不同连接,不会把单个下载连接的带宽相加。需要稳定出口身份的登录、支付或会话服务,通常应避免频繁自动切换。

下面的片段假设当前配置已经定义了名为“线路甲”和“线路乙”的两个节点。实际使用时应替换成订阅中的准确名称。顶层手动组可以选择自动组,也可以直接选节点;规则只引用顶层组,后续调整候选列表时不必逐条修改规则。

proxy-groups:
  - name: 自动出口
    type: url-test
    proxies:
      - 线路甲
      - 线路乙
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: 业务出口
    type: select
    proxies:
      - 自动出口
      - 线路甲
      - 线路乙

rules:
  - DOMAIN-SUFFIX,example.com,业务出口
  - MATCH,业务出口

理解探测参数的含义

interval 是探测间隔,单位为秒;tolerance 是切换容差,避免候选之间的小幅波动触发频繁切换。探测 URL 应在候选线路上稳定可达。探测值反映的是这条线路到指定测试服务的请求过程,不等于到所有网站的速度,也不能直接推导视频吞吐、丢包水平或目标平台的可用性。

当多个组共享同一批候选并采用很短的间隔时,健康检查会增加后台请求。先采用适中的间隔,再根据线路变化频率调整。启用延迟探测相关的惰性行为时,未被使用的组可能不会立即产生新的结果;面板显示的旧值需要结合最近探测时间理解,不能把它当作持续运行的实时监控。

嵌套、订阅引用与业务分层

节点由 proxy-providers 提供时,组可以使用 use 引用 provider,而不是复制整份节点名称。这样订阅新增或删除节点后,候选集合可以随加载结果变化。名称筛选适合缩小候选范围,但地区标签通常只是提供者命名习惯,不代表实际出口属性。筛选表达式写错时可能得到空组,应检查展开后的候选列表。

常见的稳定结构是一个手动总出口,加少量按用途划分的组。业务规则引用用途组,用途组再引用自动组或固定节点。避免让甲组引用乙组、乙组再引用甲组;循环依赖会让配置加载失败。也不要让自动组内部包含会回到自身的选择链,即使界面能够显示名称,最终出站仍可能无法解析。

如果自动组频繁切换,先检查候选是否稳定、测试服务是否受到限制,再增加容差或改为主备组。若只有特定服务异常,固定同一节点复测,避免测试期间出口不断变化。组选择发生变化后,旧连接可能保留原出站;需要观察新连接,而不是只看策略组按钮是否已经显示新名称。

节点质量还涉及流量倍率、地区与协议,不应只按一个探测数值排序。可结合节点选择与延迟判断方法建立候选集合。进阶配置的目标不是让所有业务使用同一条自动路径,而是让每条规则的选择理由清楚,并在故障时有可手动切换的出口。

规则集订阅化管理

规则列表负责决定匹配顺序,规则集负责管理一批匹配条件。把经常变化的域名或地址拆入 rule-providers 后,主配置可以保持简短,但规则集不是另一套独立优先级系统。内核依然沿着 rules 自上而下检查,第一次命中的规则决定出站;一个覆盖面过大的集合放在前面,会遮住后面的精细规则。

先确定行为类型,再确定文件格式

behavior: domain 用于域名集合,ipcidr 用于地址网段,classical 可以包含多种完整规则条件。行为类型与文件格式是两个维度:format 说明文件如何编码,行为类型说明内容如何解释。不能因为文件扩展名都是 YAML,就把完整的 DOMAIN-SUFFIX 条目塞进只接受域名条目的集合。

下面使用本地 classical 规则集,便于先验证结构。把第二段保存到内核工作目录的 rules/work.yaml,并把第一段合并进当前配置。示例假设“业务出口”策略组已经存在。文件式 provider 的改动通常需要重新加载;如果客户端把文件复制到另一工作目录,应检查实际读取位置。

rule-providers:
  work:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/work.yaml

rules:
  - RULE-SET,work,业务出口
  - GEOIP,CN,DIRECT
  - MATCH,业务出口
payload:
  - DOMAIN-SUFFIX,example.com
  - DOMAIN,example.org

安排例外、常规匹配与兜底

建议先放必须覆盖其他条件的少量例外,再放业务域名集合,随后处理需要的地址规则,最后保留 MATCH。这里的 GEOIP,CN,DIRECT 只是常见结构示例,不意味着所有目标都适合按地区直连。地址归属数据、跨地区服务与共享基础设施都会影响结果,应按实际业务要求调整。

域名规则通常不需要为了匹配而立即解析地址;地址规则可能触发解析。给支持该参数的地址规则添加 no-resolve,可避免仅为匹配而主动解析,但也可能让只有域名、没有目标地址的请求无法命中该条。它不是普遍的性能开关,而是在匹配准确性与解析行为之间作出的明确取舍。

行为类型内容侧重点常见检查项
domain域名及其匹配形式是否符合域名集合语法
ipcidrIPv4、IPv6 网段掩码与地址族是否正确
classical完整规则条件是否误带了出站策略名称

把远程更新当作配置依赖

切换到 HTTP 类型时,需要提供可访问的实际规则地址、缓存路径和更新间隔。更新间隔单位为秒,不能套用客户端订阅界面的分钟或小时数值。缓存路径应保持唯一,避免两个 provider 共用同一文件。首次启动尚无缓存时,下载规则的连接路径必须已经可用,否则会出现配置依赖尚未建立就等待自身完成的循环。

远程更新失败与规则匹配失败应分开排查。先看 provider 是否加载、条目是否存在,再检查请求是否命中集合。已有缓存可能允许继续运行,但不能据此认定更新成功;反过来,下载成功也不证明内容符合指定行为类型。日志中的解析错误、空集合和下载异常应分别处理,不要统一归因于节点不可用。

维护规则集时记录来源、用途与回退文件,保留上一份能加载的内容。新增集合后用一个应命中的域名和一个不应命中的域名做正反测试,再观察是否改变其他业务。若命中结果不符合预期,先把相关规则临时移到前面验证覆盖关系,确认原因后恢复有意设计的顺序,而不是长期依赖不断追加的例外。

DNS 解析路径优化

DNS 配置首先是路径设计,其次才是服务器选择。需要区分应用向谁提问、内核向谁提问,以及内核如何解析代理服务器自身的域名。浏览器可能启用独立加密 DNS,操作系统可能缓存旧答案,路由器还可能转发查询。只改 nameserver 并不能保证所有应用查询都经过内核,也不能保证代理节点的域名使用同一解析路径。

分清引导解析与业务解析

default-nameserver 主要为 DNS 上游自身的域名解析提供引导,应选择在当前网络能够直接访问的地址;nameserver 处理通常的业务查询;proxy-server-nameserver 用于代理节点域名解析。把这几种用途混在一起,可能出现“必须先连代理才能解析代理地址”的依赖环,表现为启动后长时间无法建立任何出站。

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - 223.5.5.5
  fake-ip-filter:
    - "*.lan"
    - "*.local"

这段示例假设当前网络可以访问所列解析服务。它没有把系统 DNS 自动改成 1053 端口,也没有启用 TUN 劫持。多数系统的常规 DNS 设置不能填写自定义端口,因此验证监听与接管必须分开。可以用支持指定端口的查询工具测试内核,再检查系统请求是否真的被重定向到它。

按域名选择解析上游

nameserver-policy 可以让特定域名使用指定上游,适合内部域名、专用解析环境或确实存在差异的业务。它决定解析器选择,不直接决定最终连接出站。不要把“某域名用某 DNS”与“某域名一定走代理”画等号;连接仍要经过规则匹配,必要时还受 DNS 请求自身的路由配置影响。

使用 respect-rules 让 DNS 请求遵守规则时,需要特别检查代理服务器域名解析与引导路径。DNS 请求也进入规则后,错误的兜底策略可能让查询依赖尚未建立的代理。先明确哪些查询必须能够直接完成,再增加策略约束。单纯看到加密 DNS 地址,并不足以证明其传输路径符合预期。

缓存、IPv6 与结果对照

修改 DNS 后,应分别考虑应用缓存、系统缓存和内核缓存。直接重开网页可能复用已有连接,不能作为新解析的证据。关闭相关连接,清理适当层级的缓存,再查看查询和连接日志。不要一开始就清空全部状态;保留一次修改前的结果,比较返回地址、响应类型和实际出站,才有助于判断问题发生在哪一层。

顶层 ipv6 与 DNS 下的 ipv6 作用范围不同,前者涉及内核的 IPv6 使用,后者影响解析响应中的 IPv6 结果。若网络没有可用 IPv6 路由,却向应用提供可优先使用的 IPv6 地址,可能出现连接等待后回落的现象。反过来,直接禁用 IPv6 也不是所有网络的通用答案,应先确认设备路由与服务要求。

解析正常而连接失败时,不要继续盲换 DNS。检查目标地址是否能经选定出站访问、规则是否误判、证书与系统时间是否正常。解析失败而节点仍可连通时,则重点检查查询路径和上游可达性。把“解析到地址”和“应用完成请求”视为两个验收点,能够显著减少在 DNS 层反复试错的范围。

TUN 与 Fake-IP 配合

TUN 是流量进入内核的方式,Fake-IP 是保留域名关联的一种 DNS 工作方式。二者经常一起使用,但不是同一个功能。TUN 创建虚拟网络接口并配合路由接管数据包;Fake-IP 向应用返回保留地址,再由内核把该地址关联回原域名。只开 Fake-IP 不会自动接管应用,只开 TUN 也不保证内核知道每条连接对应的域名。

从最小接管范围开始

桌面客户端启用 TUN 通常需要服务模式、管理员权限或系统网络扩展授权,具体机制随平台不同。先保持原有 DNS 与规则基线,确认客户端成功创建接口,再开启自动路由。其他 VPN、虚拟机网络和安全软件也可能安装路由或过滤器;同时启用时应记录默认路由变化,避免把争用误认为配置语法问题。

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
    - tcp://any:53

示例劫持常规 UDP 与 TCP 的 DNS 端口,不会透明接管所有加密 DNS。浏览器的独立 HTTPS DNS 请求看起来仍是普通 HTTPS 连接,不能仅凭端口劫持恢复其查询内容。验证时先让测试应用使用系统解析路径,确认域名映射正常,再考虑是否保留应用自身的加密 DNS 设置。

选择 stack 与接口策略

system、gvisor、mixed 对应不同网络栈处理方式,支持情况与平台、内核构建有关。不要把某一种 stack 当作固定最优值。遇到特定协议不兼容时,在其他设置不变的前提下逐个对照,并查看日志是否明确报告该选项不受支持。能够保存设置不代表内核已经采用该值。

自动检测出口接口适合常见单出口设备,但多网卡、热点共享、容器或路由器环境可能需要明确的接口和路由设计。接口名在系统更新、重连或设备变更后可能不同。出现流量不断回到虚拟接口、连接数量异常增长或全网中断时,应先关闭 TUN 恢复网络,再检查是否形成了路由回环,而不是持续重试目标站点。

维护 Fake-IP 映射与例外

应用拿到 Fake-IP 后,后续连接必须再次经过保存映射的同一个内核。若 DNS 由设备甲返回,而连接被设备乙处理,乙可能不知道该保留地址对应哪个域名。局域网共享代理时尤其要明确 DNS 与连接的归属,不能把 Fake-IP 解析结果直接暴露给未经过该代理的设备或其他网络路径。

fake-ip-filter 用于让指定域名不走 Fake-IP 分配,但过滤后仍要有可用的真实解析上游。对依赖真实地址的应用,应从具体异常域名开始添加例外,而不是把大范围公共后缀全部过滤。过滤范围过大,会减少内核通过映射获得域名的机会,并把部分判断重新推给地址规则或嗅探。

如果应用缓存了旧的 Fake-IP,而内核重启后映射丢失,新连接可能无法还原域名。可在理解存储行为后使用 profile.store-fake-ip 保留映射,同时检查客户端是否保留对应数据目录。排查时清理应用缓存并重新解析,通常比直接扩大过滤列表更有针对性;切换回不使用该内核的网络后,也要避免沿用这些保留地址。

验收应包含普通网页、一个不遵从系统代理的应用,以及局域网服务访问。分别查看是否进入内核、是否显示域名和是否命中预期规则。若系统代理正常而 TUN 异常,把故障范围缩小到路由、权限、DNS 劫持和网络栈。两种方式的详细差异可继续阅读TUN 模式与系统代理原理对比,不必为了覆盖面同时开启所有接管功能。

域名嗅探与匹配边界

当连接只有目标 IP、没有可靠域名信息时,域名规则可能无法参与预期的决策。域名嗅探尝试从部分协议握手或请求信息中提取主机名,为规则匹配补充线索。它不是解密 HTTPS 内容,也不能保证识别每条连接。先修复正常 DNS 接管与 Fake-IP 映射,再考虑用嗅探补齐边界情况,通常比完全依赖嗅探更容易维护。

按协议与端口限定范围

HTTP 可以从请求主机信息提取域名,TLS 通常可以从可见的握手信息提取服务器名称,QUIC 的识别则依赖内核支持与具体流量。应用使用自定义协议、直接访问 IP、复用既有连接或隐藏相关握手信息时,嗅探可能无法得到域名。结果为空并不等于内核失效,应先确认这条流量是否提供了可识别素材。

sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true
  override-destination: false
  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
    TLS:
      ports:
        - 443
        - 8443
    QUIC:
      ports:
        - 443

这份片段把范围限制在常见业务端口,并保留原目标地址。启用 parse-pure-ip 允许尝试识别只有 IP 的连接;force-dns-mapping 涉及 DNS 映射场景下的嗅探行为。参数名称相近,但不能替代正常的 DNS 工作流程。若内核报告不支持某字段,应核对实际内核,而不是只看客户端名称。

区分补充域名与覆盖目标

override-destination 决定是否允许嗅探结果影响连接目标。改变目标可能帮助某些需要重新按域名建立连接的场景,也可能破坏应用原先选择的地址。对于依赖专用 IP、内部服务、内容分发调度或证书绑定的业务,应先保持关闭,只观察域名补充与规则结果,再决定是否需要启用覆盖。

同一 IP 可以承载多个域名,同一域名也可以返回多组地址。嗅探得到域名后再次解析,结果可能与应用原先使用的地址不同。因此“识别出了正确域名”和“最终连到了正确服务”仍是两个验收点。若启用覆盖后只有某一应用失败,可以关闭覆盖进行对照,再针对对应域名设置跳过策略。

处理例外与隐私边界

对不适合嗅探的域名,可以根据内核支持使用 skip-domain 等排除设置。例外应根据明确的兼容性问题添加,并保留原因;不建议复制来源不明的大型排除列表。范围过大时,嗅探基本不再工作,排查者却容易误以为功能仍全面生效,最后在规则层不断添加补丁。

嗅探无法保证穿透加密客户端问候等机制,也无法替代应用日志。看到的域名可能是连接层主机名,不一定等于用户正在访问的页面标题或完整业务归属。共享基础设施上的服务尤其如此。规则设计应以稳定、能够验证的主机名为依据,避免根据一次抓到的域名就把整个基础设施划入同一出站。

调试时先固定一个目标,关闭旧连接后重新请求,比较嗅探关闭与开启两种状态下的目标域名、规则名称和出站。若请求在嗅探前已经命中明确的地址规则,应同时检查规则顺序和内核处理行为。不要在一次测试中改端口范围、目标覆盖和分流集合,否则无法判断哪项设置造成了差异。

日志可能包含访问域名、目标地址和应用信息。临时提高日志级别后,只记录完成定位所需的一段时间,分享前移除订阅地址、认证信息与个人访问记录。确认故障消失后恢复常规日志级别,保留最小的有效设置。嗅探应作为可解释的辅助机制,而不是用来掩盖解析、接管与规则引用之间尚未解决的结构问题。

本地覆写与多订阅合并

订阅更新通常会替换远程 Profile 的内容,直接修改下载文件容易在下一次更新后丢失。本地覆写用于保存属于设备或用户的长期设置,例如监听端口、DNS 策略、少量业务规则和控制接口。具体入口可能叫覆写、合并、扩展或脚本,但这些名称不保证合并语义相同,应先查清客户端是替换字段、深度合并对象,还是拼接数组。

把配置分成三类所有权

远程订阅负责节点与其配套结构,本地设备设置负责权限、监听和接管方式,用户策略负责业务分流与长期例外。尽量不要让三层同时维护同一个字段。比如界面固定了端口,覆写又设置另一个端口,订阅还带第三个值,最终结果就只能依赖隐含加载顺序,迁移客户端后很容易改变。

先选择一个容易观察、影响较小的字段测试合并行为,例如 log-level。加载后检查最终配置,再测试规则数组如何处理。若新规则覆盖了整份 rules,说明该入口不是预想的追加机制;应使用客户端明确提供的前置、后置或规则编辑功能,而不是假设所有 YAML 合并都能保留原数组。

# 合并片段:使用前确认客户端的对象与数组处理方式
log-level: info

profile:
  store-selected: true
  store-fake-ip: true

合并节点,不直接拼接完整文件

两份完整订阅都可能包含端口、DNS、策略组和兜底规则,直接拼接文本会产生重复键或相互覆盖。更稳定的做法是由一个主配置负责规则与组结构,多个 proxy-providers 分别提供节点。前提是这些来源提供内核能接受的节点 provider 格式;完整客户端配置不能仅改文件名就当成节点集合使用。

proxy-providers:
  source-a:
    type: file
    path: ./providers/source-a.yaml
  source-b:
    type: file
    path: ./providers/source-b.yaml

proxy-groups:
  - name: 多源出口
    type: select
    use:
      - source-a
      - source-b

两个本地文件应各自包含 proxies 节点列表,并使用合法协议字段。示例只展示引用关系,不提供节点凭据。节点名称最好保持可辨识,避免不同来源使用相同名称时难以区分。需要重命名或加来源前缀时,确认客户端或转换流程明确支持,不要在更新生成的文件上进行无法重复执行的手工替换。

更新间隔、转换与失败回退

客户端的 Profile 更新间隔与内核 provider 更新间隔是不同任务,单位也可能不同。前者重新获取主配置,后者更新某个节点或规则来源。应记录每一层由谁触发、缓存在哪里,以及更新失败后是否继续使用旧文件。设备休眠、移动网络限制和后台任务策略都可能推迟更新,不能只凭间隔数值推断实际执行时间。

订阅地址常包含访问凭据,不要把完整链接写进公开截图、日志或示例仓库。需要格式转换时,先确认转换过程是否会把原地址交给第三方服务。优先使用可信客户端内置能力或本地处理方式,并检查转换后是否丢失节点选项。配置能够加载只是第一步,协议字段被简化后,实际连接仍可能发生变化。

为一次合并准备三份内容:当前可用主配置、新的覆盖片段,以及恢复方法。应用后先检查节点数量是否符合预期,再确认策略组非空、规则引用存在、DNS 和端口保持原计划。更新后异常时,先停用新增覆写回到基线;若恢复成功,再逐段启用,而不是直接重装客户端并丢失定位线索。

不同客户端对多 Profile 的切换与合并支持不同,切换一份配置并不等于同时使用多份节点。需要先厘清管理模型,可阅读Profile 结构与多订阅管理。长期维护时,把规则意图和来源关系写成简短记录,比依赖复杂且没有说明的合并脚本更容易迁移,也更容易在更新后验证。

外部控制与维护流程

外部控制接口用于读取内核状态、切换策略、查看连接和触发部分管理操作;它不是供应用上网的代理端口。常见配置使用 9090,混合代理端口则可能是 7890。把浏览器或系统代理指向控制端口不会得到正常代理服务。部署前应分别列出两个端口的用途、监听地址和允许访问的设备。

优先只监听本机

单机客户端通常不需要让局域网直接访问控制接口,使用回环地址可以缩小访问范围。若客户端已经管理控制接口和认证值,不要在覆写里强行覆盖,否则内置面板可能失去连接。下面采用教学用认证值,仅说明字段位置;实际环境应自行生成独立的高强度值,并妥善保存。

external-controller: 127.0.0.1:9090
secret: "your-password"

控制接口的认证能力不能替代网络边界。若确实需要远程维护,先设计可信网络、加密传输与防火墙限制,再考虑改变监听地址。不要仅为方便把接口暴露到所有地址,也不要直接做公网端口映射。能够调用该接口的主体可能改变出站策略或读取连接信息,权限范围应与系统管理接口同等对待。

用 API 区分接口问题与面板问题

先在运行内核的设备上检查接口,再处理浏览器面板。下面命令中的认证值与前段教学配置对应;使用实际环境时同步替换。认证失败、连接被拒绝和返回内容不符合预期是三种不同故障:分别对应认证设置、监听或进程状态,以及端口或服务选错,不能统一通过重新下载面板解决。

curl --fail --silent --show-error \
  -H "Authorization: Bearer your-password" \
  http://127.0.0.1:9090/version

curl --fail --silent --show-error \
  -H "Authorization: Bearer your-password" \
  http://127.0.0.1:9090/proxies

在 Windows PowerShell 中需要注意 curl 可能受命令别名或版本行为影响,可明确使用 curl.exe,并按对应终端调整换行方式。接口能返回数据后,再检查面板填写的地址、协议和认证值。面板页面通过 HTTPS 打开却连接普通 HTTP 接口时,还可能受到浏览器混合内容策略限制。

静态面板与连接历史的边界

external-ui 用于指定本地面板静态文件目录,目录相对内核工作位置解析。静态文件存在不代表它已经连到正确内核;打开面板后仍需确认控制地址与身份验证。内置面板通常已经处理这层关系,普通桌面用户优先使用客户端提供的入口,避免同时维护多个来源不明的管理页面。

面板中的连接列表通常用于观察当前连接,不应把它当作永久审计记录。重启内核、关闭连接或切换配置后,可见数据可能变化。排错需要保留必要日志,但不应长期公开连接详情。分享问题时描述目标类别、命中规则和错误类型即可;订阅链接、认证值和完整访问历史应先移除。

建立更新后的验收清单

每次更新客户端、替换订阅或调整覆写后,按相同顺序验收:确认内核启动,检查实际监听端口,确认 provider 加载,测试规则命中,再验证 DNS 与 TUN。最后才检查外部面板。这样即使面板暂时无法使用,也能通过日志和基础连接判断代理链路是否正常,避免把管理界面故障误判为整个网络不可用。

回退应恢复上一个已验证的配置组合,而不是只还原最后编辑的单个文件。订阅缓存、覆写、策略选择和客户端开关共同决定最终行为。保留一份恢复记录,注明需要停用哪些覆写、选择哪个 Profile、是否关闭 TUN,以及何时清理缓存。恢复完成后重新发起连接,确认旧会话没有掩盖结果。

本页各章可以独立查阅,但修改顺序仍应遵循依赖:先稳定入口与节点,再建立策略组和规则,随后调整 DNS、TUN 与嗅探,最后配置远程管理。基础连接问题返回系统代理设置检查;需要迁移客户端时返回下载中心。每次留下可观察的结果和可执行的回退步骤,比持续增加配置字段更有维护价值。