Skip to content

Configuration

Jump to bottom
Juwan-Hwang edited this page Apr 12, 2026 · 7 revisions

配置说明

Zephyr 的配置体系涵盖应用设置、内核管理、系统代理、主题定制与高级功能等多个维度。本文档对每一项配置进行详细的技术说明，帮助用户全面掌握 Zephyr 的配置方法与底层机制。

目录

设置页面结构

Zephyr 的设置页面划分为 6 个功能分区，从通用配置到高级选项依次排列，覆盖从基础使用到深度定制的全部配置需求。以下图表展示了完整的设置页面结构：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}}}%%
graph TB
    subgraph SettingsPage["设置页面"]
        direction TB
        A["常规设置<br/>General"] --> B["网络与路由<br/>Network & Routing"]
        B --> C["内核管理<br/>Core Management"]
        C --> D["系统工具集<br/>System Utilities"]
        D --> E["端口转发<br/>Port Forwarding"]
        E --> F["高级设置<br/>Advanced"]
    end

    subgraph GeneralDetail["常规设置详情"]
        G1["语言设置"]
        G2["主题模式"]
        G3["关闭到托盘"]
        G4["DNS 覆写"]
        G5["节点名称滚动"]
        G6["开机自启"]
        G7["主题颜色"]
        G8["应用不透明度"]
        G9["恢复默认"]
    end

    subgraph NetworkDetail["网络与路由详情"]
        N1["统一延迟"]
        N2["IPv6"]
        N3["局域网连接"]
        N4["Geo 数据库更新"]
    end

    subgraph CoreDetail["内核管理详情"]
        C1["当前版本"]
        C2["检查更新"]
        C3["自动检查更新"]
        C4["配置文件夹"]
    end

    subgraph UtilDetail["系统工具集详情"]
        U1["UWP 环回免除 (Windows)"]
        U2["订阅客户端伪装"]
    end

    subgraph PortDetail["端口转发详情"]
        P1["TCP/UDP 隧道配置"]
        P2["监听地址 / 端口"]
        P3["目标地址 / 端口"]
        P4["代理节点选择"]
    end

    subgraph AdvDetail["高级设置详情"]
        A1["自定义启动参数"]
        A2["动态配置引擎"]
        A3["实时 PATCH"]
    end

    A --- GeneralDetail
    B --- NetworkDetail
    C --- CoreDetail
    D --- UtilDetail
    E --- PortDetail
    F --- AdvDetail

    style SettingsPage fill:#f8fafc,stroke:#64748b,color:#1e293b
    style GeneralDetail fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style NetworkDetail fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style CoreDetail fill:#fff3e0,stroke:#e65100,color:#bf360c
    style UtilDetail fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
    style PortDetail fill:#e0f7fa,stroke:#00695c,color:#004d40
    style AdvDetail fill:#fce4ec,stroke:#c62828,color:#b71c1c
Loading

分区总览

分区 核心功能 适用用户
常规设置 语言、主题、窗口行为、DNS、外观定制 所有用户
网络与路由 延迟测试、IPv6、局域网连接、Geo 数据库 需要调整网络行为的用户
内核管理 版本查看、内核更新、配置目录访问 需要管理内核版本的用户
系统工具集 UWP 环回、订阅客户端伪装 Windows 用户 / 订阅管理用户
端口转发 TCP/UDP 隧道创建与管理 需要端口转发的进阶用户
高级设置 自定义启动参数、动态配置引擎 有经验的用户

设置数据结构

Zephyr 的应用设置使用 Rust 结构体 Settings 定义，序列化为 JSON 格式持久化存储。以下是完整的字段说明：

struct Settings {
    close_to_tray: bool,                    // 关闭时最小化到托盘（默认 true）
    auto_update: bool,                      // 自动更新（默认 false）
    autostart: bool,                        // 开机自启（默认 false）
    theme: Option<String>,                  // 主题标识
    last_config: Option<String>,            // 上次使用的配置文件名
    custom_args: Vec<String>,               // 自定义启动参数列表
    dns_nameservers: Option<Vec<String>>,   // DNS 服务器列表
    dns_fallbacks: Option<Vec<String>>,     // DNS 回退服务器列表
}

字段详情

字段 类型 默认值 说明
close_to_tray bool true 关闭窗口时是否最小化到系统托盘而非退出应用
auto_update bool false 是否在启动时自动检查并安装应用更新
autostart bool false 是否在系统启动时自动运行 Zephyr
theme Option<String> None 当前主题标识，None 表示使用默认主题
last_config Option<String> None 上次使用的配置文件名，用于启动时自动加载
custom_args Vec<String> [] 传递给 Mihomo 内核的自定义命令行参数
dns_nameservers Option<Vec<String>> None 自定义 DNS 服务器地址列表
dns_fallbacks Option<Vec<String>> None DNS 回退服务器地址列表

存储位置与权限

属性 值
文件路径 {app_data_dir}/settings.json
文件格式 JSON
Unix 权限 0600（仅文件所有者可读写）
Windows 权限 DACL（自由访问控制列表）限制访问

安全说明：0600 权限确保只有当前用户可以读写设置文件，防止其他用户或进程篡改配置。在 Windows 上通过 DACL 实现等效的访问控制。

数据存储目录

Zephyr 的所有数据文件统一存放在操作系统约定的应用数据目录下，结构如下：

AppData/Zephyr/
├── settings.json          # 应用设置（JSON 格式）
├── profiles/              # 配置文件目录
│   ├── *.yaml             # 订阅配置文件
│   └── metadata.json      # 加密的订阅元数据
├── core/                  # 内核运行时目录
│   └── run_config.yaml    # 运行时配置（注入控制器设置后的最终配置）
├── mihomo/                # Mihomo 内核目录
│   └── mihomo(.exe)       # Mihomo 内核可执行文件
├── cache.db               # Mihomo 缓存数据库
└── logs/                  # 内核日志目录

各文件说明

文件/目录 说明 格式
settings.json 应用全局设置，包含主题、启动参数、DNS 配置等 JSON
profiles/*.yaml 从订阅下载或手动导入的 Mihomo 配置文件 YAML
profiles/metadata.json 订阅元数据（订阅链接、更新时间等），AES-256-GCM 加密 加密 JSON
core/run_config.yaml 运行时实际使用的配置，由原始 profile 注入控制器设置后生成 YAML
mihomo/mihomo(.exe) Mihomo 内核可执行文件 二进制
cache.db Mihomo 运行时缓存（DNS 缓存、Fake-IP 映射等） SQLite
logs/ Mihomo 内核输出的日志文件 文本

各平台数据目录路径

平台 默认路径
Windows C:\Users\{用户名}\AppData\Roaming\Zephyr\
macOS ~/Library/Application Support/Zephyr/
Linux ~/.config/Zephyr/

以下流程图展示了配置文件路径解析的完整安全校验过程：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A["请求配置文件"] --> B{"传入的是绝对路径?"}

    B -->|"是"| C["validate_path_within_dir<br/>(检查是否在profiles_dir内)"]
    C --> D{"通过?"}
    D -->|"是"| E["返回完整路径"]
    D -->|"否"| F["拒绝<br/>(路径遍历攻击)"]

    B -->|"否"| G["拼接profiles_dir + 文件名"]
    G --> H["sanitize_config_file_name<br/>(5轮URL解码 + 9步净化)"]
    H --> I{"通过?"}
    I -->|"是"| E
    I -->|"否"| J["拒绝<br/>(非法文件名)"]

    style A fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style C fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style G fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style H fill:#e3f2fd,stroke:#3B82F6,color:#3B82F6
    style E fill:#c8e6c9,stroke:#10B981,color:#10B981
    style F fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style J fill:#ffcdd2,stroke:#991B1B,color:#991B1B
    style B fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style D fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
    style I fill:#fff3e0,stroke:#F59E0B,color:#F59E0B
Loading

常规设置

常规设置是 Zephyr 最基础的配置区域，涵盖界面语言、主题模式、窗口行为与外观定制等选项。

语言设置

选项 说明
en 英文界面
zh 中文界面

语言设置即时生效，无需重启应用。所有界面文本（包括设置页面、通知消息、托盘菜单等）均会跟随语言切换。

主题模式

模式 说明 适用场景
Light 浅色背景 + 深色文字 日间使用、明亮环境
Auto 跟随操作系统主题自动切换 希望与系统保持一致
Dark 深色背景 + 浅色文字 夜间使用、暗光环境

Auto 模式下，Zephyr 会监听操作系统的主题变化事件，实时切换明暗模式。

关闭到托盘

状态 行为
开启（默认） 点击关闭按钮时窗口最小化到系统托盘，应用继续在后台运行
关闭 点击关闭按钮时直接退出应用

提示：开启此选项后，可通过托盘菜单的 "Quit" 选项完全退出应用。

DNS 覆写

提供独立的 DNS 配置面板，支持覆盖 Mihomo 内核的默认 DNS 设置：

  • Fake-IP 模式：启用后使用 Fake-IP 加速 DNS 解析，减少 DNS 泄露风险
  • 自定义 DNS 服务器：配置独立的 nameserver 列表（如 8.8.8.8、1.1.1.1）
  • DNS 回退服务器：当主 DNS 服务器不可用时使用的备用列表
  • DNS 规则：支持按域名指定解析服务器

配置示例：

dns:
  enable: true
  fake-ip: true
  nameserver:
    - 8.8.8.8
    - 1.1.1.1
  fallback:
    - https://dns.google/dns-query
    - https://cloudflare-dns.com/dns-query

节点名称滚动

状态 行为
开启 节点名称过长时自动启用水平滚动动画，完整展示名称
关闭 节点名称超出容器宽度时直接截断显示省略号

开机自启

基于 Tauri autostart 插件实现，支持 Windows、macOS 和 Linux 三平台。启用后 Zephyr 会在系统启动时自动运行。

平台 实现方式
Windows 注册表 HKCU\...\Run
macOS ~/Library/LaunchAgents/
Linux XDG Autostart (.desktop 文件)

主题颜色

提供 5 种预设主题色，同时支持通过取色器自定义任意颜色。详见 主题颜色 章节。

应用不透明度

支持在 10% - 100% 范围内调节应用窗口不透明度：

范围 效果
100% 完全不透明（默认）
50% - 99% 半透明，可透视桌面背景
10% - 49% 高度透明，仅保留基本可见性

用户可根据个人偏好或桌面壁纸搭配调整透明度，打造个性化的桌面体验。

恢复默认

一键将所有常规设置恢复为默认值。此操作会重置以下设置项：

  • 语言恢复为系统默认
  • 主题模式恢复为 Auto
  • 主题颜色恢复为默认紫色
  • 不透明度恢复为 100%
  • 关闭到托盘恢复为开启
  • 节点名称滚动恢复为开启

注意：恢复默认操作不会影响网络设置、内核配置、端口转发规则和自定义启动参数。

网络与路由

网络与路由设置控制 Mihomo 内核的网络行为，包括延迟测试策略、IPv6 支持、局域网连接和 Geo 数据库管理。

统一延迟

配置延迟测试使用的统一 URL 和超时参数：

参数 默认值 说明
测试 URL http://www.gstatic.com/generate_204 延迟测试目标地址
超时时间 5000ms 单次测试超时阈值

通过 Mihomo RESTful API 发起延迟探测：

GET /proxies/{proxy_name}/delay?url=http://www.gstatic.com/generate_204&timeout=5000

IPv6

状态 行为
开启 允许 Mihomo 处理 IPv6 流量
关闭（默认） 仅处理 IPv4 流量，忽略 IPv6 请求

局域网连接

状态 行为
开启 允许局域网内其他设备通过本机代理端口访问代理
关闭（默认） 仅允许本机（127.0.0.1）连接代理端口

安全提示：开启局域网连接后，同一网络内的其他设备可通过 http://{本机IP}:{端口} 使用你的代理。请确保在可信的网络环境中使用此功能。

Geo 数据库更新

管理 Mihomo 内核使用的 GeoIP 和 GeoSite 数据库：

操作 说明
检查更新 查询 Geo 数据库是否有新版本可用
手动更新 立即下载并替换最新的 Geo 数据库文件

Geo 数据库用于基于地理位置的分流规则（如 GEOIP、GEOSITE 规则类型），保持数据库最新可确保规则匹配的准确性。

内核管理

内核管理页面提供 Mihomo 内核的版本信息查看、更新检查与配置目录访问等功能。

当前版本

显示当前已安装的 Mihomo 内核版本号，格式为 Mihomo v{版本号}。

检查更新

手动触发 Mihomo 内核版本检查，对比远程最新版本与本地版本：

状态 行为
有新版本 显示更新提示，用户确认后自动下载并替换内核文件
已是最新 提示当前版本已是最新

自动检查更新

状态 行为
开启 应用启动时自动检查 Mihomo 内核是否有新版本
关闭（默认） 不自动检查，需手动触发

配置文件夹

提供快速打开配置文件目录的快捷操作：

操作 行为
点击按钮 使用系统文件管理器打开 Zephyr 的数据存储目录

各平台打开方式：

平台 实现方式
Windows explorer {app_data_dir}
macOS open {app_data_dir}
Linux xdg-open {app_data_dir}

系统工具集

系统工具集提供平台特定的系统级配置功能。

UWP 环回免除（Windows 专属）

Windows 的 UWP（通用 Windows 平台）应用默认被禁止访问本地回环地址（127.0.0.1），导致 UWP 应用无法使用系统代理。此功能通过 PowerShell 调用 CheckNetIsolation.exe LoopbackExempt 命令为 UWP 应用添加环回免除规则。

属性 说明
操作方式 通过 PowerShell 调用 CheckNetIsolation.exe LoopbackExempt -a -n="<PackageFamilyName>"，自动豁免所有非框架 UWP 应用（IsFramework -eq $false）
限流间隔 5 分钟（防止频繁操作）
用户确认 操作前弹出确认对话框

订阅客户端伪装

自定义订阅下载请求的 User-Agent 头部，使服务器返回与指定客户端兼容的配置格式。

选项 说明
Clash Verge 模拟 Clash Verge 客户端的 User-Agent
Mihomo Party 模拟 Mihomo Party 客户端的 User-Agent
FlClash 模拟 FlClash 客户端的 User-Agent
Shadowrocket 模拟 Shadowrocket 客户端的 User-Agent
Custom 用户可输入任意自定义 User-Agent 字符串

使用场景：部分订阅服务会根据客户端类型返回不同格式的配置。选择与你的订阅服务兼容的客户端伪装，可确保正确获取配置。

端口转发

Zephyr 支持创建 TCP/UDP 端口转发隧道，将本地端口流量通过指定代理节点转发到目标地址。

配置参数

参数 类型 说明
协议 TCP / UDP 转发隧道使用的传输协议
监听地址 字符串 本地绑定的 IP 地址（如 127.0.0.1）
监听端口 整数 本地监听的端口号
目标地址 字符串 转发目标的 IP 地址或域名
目标端口 整数 转发目标的端口号
代理节点 字符串 使用的代理节点名称

配置示例

以下配置将本地 8080 端口的 TCP 流量通过代理节点 HK-Server-01 转发到 example.com:443：

参数 值
协议 TCP
监听地址 127.0.0.1
监听端口 8080
目标地址 example.com
目标端口 443
代理节点 HK-Server-01

配置完成后，访问 http://127.0.0.1:8080 的流量将通过指定的代理节点转发到 example.com:443。

高级设置

高级设置面向有经验的用户，提供对 Mihomo 内核行为的深度控制。

自定义启动参数

通过文本域（textarea）输入传递给 Mihomo 内核的额外命令行参数。每行一个参数，或以空格分隔。

输入示例：

--log-level debug
--test

安全限制：为防止配置冲突与安全风险，以下参数被禁止使用。详见 自定义启动参数安全过滤 章节。

动态配置引擎

Zephyr 实现了一套递归渲染的动态配置引擎，用于可视化管理 Mihomo 内核的复杂配置结构。

核心特性

特性 说明
递归渲染 根据配置的嵌套结构自动生成对应的编辑控件，支持任意深度的嵌套层级
类型感知控件 根据值的类型自动选择合适的输入控件

类型感知控件映射

值类型 控件类型 说明
字符串 (string) 文本输入框 单行文本输入
数字 (number) 数字输入框 支持整数与浮点数，含步进按钮
布尔 (boolean) Toggle 开关 iOS 风格的开关控件
数组 (array) 列表编辑器 支持添加、删除、排序数组元素
对象 (object) 嵌套面板 递归展开为子面板，包含子字段的控件

实时 PATCH

配置修改通过 HTTP PATCH 请求实时推送至 Mihomo 内核，无需手动保存或重启：

PATCH http://127.0.0.1:{port}/configs?force=true
Content-Type: application/json

{
  "dns": {
    "enable": true,
    "fake-ip": true,
    "nameserver": ["8.8.8.8", "1.1.1.1"]
  }
}

force=true 参数确保配置被强制重载，绕过内部缓存，使修改即时生效。

主题颜色

Zephyr 提供 5 种预设主题色和自定义颜色功能，通过 CSS 变量 --color-accent 全局生效。所有强调色元素（按钮、链接、选中态、进度条等）自动跟随主题色切换。

预设颜色

名称 色值 视觉感受
Purple（薰衣草紫） #8B5CF6 优雅、科技感（默认）
Blue（海洋蓝） #0A84FF 沉稳、专业
Green（翡翠绿） #34C759 自然、清新
Orange（琥珀橙） #FF9500 温暖、活力
Pink（玫瑰粉） #FF2D55 活力、热情

自定义颜色

选择 "Custom" 选项后，系统会弹出取色器（Color Picker），用户可选择任意颜色作为主题色。选定的颜色值会以 HEX 格式存储到设置文件中。

主题色作用范围

主题色通过 CSS 变量注入，影响以下 UI 元素：

元素 说明
按钮背景 主要操作按钮的填充色
链接文字 可点击链接的文字颜色
选中态 列表项、Tab 等的选中高亮色
进度条 流量使用进度、下载进度等
Toggle 开关 开关处于开启状态时的颜色
图标强调色 部分图标的着色
流量图表 下载流量面积图的填充色

运行模式

Zephyr 提供三种代理运行模式，通过 Mihomo RESTful API 实时切换，无需重启内核。

模式说明

模式 API 值 说明 适用场景
Rule（规则分流） rule 根据 Mihomo 配置中的规则集进行智能分流 日常使用，推荐模式
Global（全局代理） global 所有流量均通过代理服务器转发 需要全部流量走代理的场景
Direct（直连） direct 所有流量直接发送，不经过代理 排查问题、访问本地服务

切换方式

通过 PATCH API 实时切换运行模式：

PATCH http://127.0.0.1:{port}/configs
Content-Type: application/json

{
  "mode": "rule"
}

UI 交互

设置页面和托盘菜单均提供模式切换入口。设置页面使用三段式滑块控件，带有平滑动画过渡效果，当前激活模式高亮显示。

系统代理设置流程

Zephyr 针对不同操作系统实现了差异化的系统代理配置方案，确保在各平台上的正确性与一致性。以下流程图展示了从调用 enable_sysproxy 到最终完成系统代理设置的完整决策链路：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A["enable_sysproxy 调用"] --> B["validate_proxy_server<br/>验证代理服务器地址<br/>仅允许 127.0.0.1 / localhost / ::1"]
    B --> C{"地址合法?"}
    C -->|"不合法"| ERR["返回错误<br/>Suspicious Proxy Host"]
    C -->|"合法"| D{"平台检测<br/>cfg!(target_os)"}

    D -->|"Windows"| E["Windows 分支"]
    D -->|"macOS"| F["macOS 分支"]
    D -->|"Linux"| G["Linux 分支"]

    subgraph Win["Windows -- 注册表原子写入"]
        E1["读取当前注册表值<br/>HKCU\\...\\Internet Settings<br/>备份 ProxyEnable / ProxyServer / ProxyOverride"]
        E2["原子写入新值<br/>ProxyEnable = 1<br/>ProxyServer = 127.0.0.1:7890<br/>ProxyOverride = localhost;127.*;10.*;172.16.*;...;192.168.*"]
        E3["InternetSetOptionW 刷新<br/>INTERNET_OPTION_SETTINGS_CHANGED<br/>+ INTERNET_OPTION_REFRESH"]
        E4{"写入成功?"}
        E5["失败时回滚到备份值"]
        E1 --> E2 --> E3 --> E4
        E4 -->|"失败"| E5
    end

    subgraph Mac["macOS -- networksetup 逐服务"]
        F1["获取所有网络服务列表<br/>networksetup -listallnetworkservices"]
        F2["遍历每个活跃服务"]
        F3["跳过 Disabled 状态的服务"]
        F4["设置 Web Proxy<br/>networksetup -setwebproxy 服务名 127.0.0.1 7890"]
        F5["设置 Secure Web Proxy<br/>networksetup -setsecurewebproxy 服务名 127.0.0.1 7890"]
        F6["设置 SOCKS Proxy<br/>networksetup -setsocksfirewallproxy 服务名 127.0.0.1 7890"]
        F7["启用代理开关<br/>-setwebproxystate on<br/>-setsecurewebproxystate on<br/>-setsocksfirewallproxystate on"]
        F1 --> F2 --> F3 --> F4 --> F5 --> F6 --> F7
    end

    subgraph Lin["Linux -- 多桌面环境适配"]
        G1{"检测桌面环境<br/>XDG_CURRENT_DESKTOP"}
        G2["GNOME<br/>gsettings<br/>先设值后切模式<br/>mode = manual"]
        G3["KDE Plasma<br/>kwriteconfig6 + DBus<br/>reparseConfiguration 信号"]
        G4["XFCE<br/>xfconf-query<br/>xfce4-session channel<br/>完整代理地址字符串"]
        G1 -->|"GNOME / gnome"| G2
        G1 -->|"KDE / plasma"| G3
        G1 -->|"XFCE / xfce"| G4
    end

    E --> Win
    F --> Mac
    G --> Lin

    E4 -->|"成功"| DONE["返回 Ok(())"]
    E5 --> DONE
    F7 --> DONE
    G2 --> DONE
    G3 --> DONE
    G4 --> DONE

    style ERR fill:#ffcdd2,stroke:#c62828,color:#b71c1c
    style DONE fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    style Win fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style Mac fill:#fff3e0,stroke:#e65100,color:#bf360c
    style Lin fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
Loading

代理地址验证

所有平台在设置系统代理前均会执行严格的地址验证：

验证规则 说明
仅允许 127.0.0.1 标准 IPv4 回环地址
仅允许 ::1 IPv6 回环地址
仅允许 localhost 回环主机名
拒绝欺骗性主机名 防止使用 127.0.0.1.evil.com 等伪装地址
512 字符限制 代理地址字符串长度上限

Windows 实现

通过 Windows 注册表配置系统代理，采用原子写入策略确保一致性：

注册表路径 说明
HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings Internet Explorer / 系统级代理设置

操作步骤：

  1. 读取当前注册表值作为回滚备份
  2. 原子写入新的代理配置：
    • ProxyEnable = 1（启用）/ 0（禁用）
    • ProxyServer = 127.0.0.1:{port}
    • ProxyOverride = <local>;localhost;127.*;10.*;172.16.*;172.17.*;172.18.*;172.19.*;172.20.*;172.21.*;172.22.*;172.23.*;172.24.*;172.25.*;172.26.*;172.27.*;172.28.*;172.29.*;172.30.*;172.31.*;192.168.*
  3. 调用 InternetSetOptionW 刷新系统代理设置
  4. 写入失败时自动回滚到备份值

macOS 实现

通过 networksetup 命令逐个网络服务设置代理：

# 启用 HTTP 代理
networksetup -setwebproxy "Wi-Fi" 127.0.0.1 7890

# 启用 HTTPS 代理
networksetup -setsecurewebproxy "Wi-Fi" 127.0.0.1 7890

# 启用 SOCKS 代理
networksetup -setsocksfirewallproxy "Wi-Fi" 127.0.0.1 7890

# 关闭代理
networksetup -setwebproxystate "Wi-Fi" off
networksetup -setsecurewebproxystate "Wi-Fi" off
networksetup -setsocksfirewallproxystate "Wi-Fi" off

Zephyr 会自动检测所有活跃的网络服务（Wi-Fi、Ethernet 等），逐一配置代理设置，确保所有网络接口均正确应用代理。

Linux GNOME 实现

通过 gsettings 配置 GNOME 系统代理，采用原子写入策略（先设值再切模式）：

# 步骤 1：设置代理参数
gsettings set org.gnome.system.proxy.http host '127.0.0.1'
gsettings set org.gnome.system.proxy.http port 7890
gsettings set org.gnome.system.proxy.https host '127.0.0.1'
gsettings set org.gnome.system.proxy.https port 7890
gsettings set org.gnome.system.proxy.socks host '127.0.0.1'
gsettings set org.gnome.system.proxy.socks port 7890

# 步骤 2：切换到手动模式（原子操作）
gsettings set org.gnome.system.proxy mode 'manual'

原子性保证：先完成所有参数写入，最后才将模式切换为 manual。如果参数写入过程中发生错误，模式不会被切换，确保系统不会使用不完整的代理配置。

Linux KDE 实现

通过 kwriteconfig5 / kwriteconfig6 修改 KDE 代理配置文件，并通过 DBus 通知相关服务刷新：

# 写入代理配置
kwriteconfig6 --file kioslaverc --group "Proxy Settings" --key "ProxyType" 1
kwriteconfig6 --file kioslaverc --group "Proxy Settings" --key "httpProxy" "http://127.0.0.1:7890"
kwriteconfig6 --file kioslaverc --group "Proxy Settings" --key "httpsProxy" "http://127.0.0.1:7890"
kwriteconfig6 --file kioslaverc --group "Proxy Settings" --key "socksProxy" "socks://127.0.0.1:7890"

# 通过 DBus 通知 KIODaemon 刷新配置
dbus-send --type=method_call --dest=org.kde.KIODaemon /KIODaemon org.kde.KIODaemon.update

# 通知 KWin 刷新环境变量
dbus-send --type=method_call --dest=org.kde.KWin /KWin org.kde.KWin.reconfigure
DBus 目标 说明
org.kde.KIODaemon / /KIODaemon KDE I/O 守护进程，通过 org.kde.KIODaemon.update 方法调用刷新代理配置
org.kde.KWin / /KWin KDE 窗口管理器，通过 org.kde.KWin.reconfigure 方法调用刷新环境变量

Linux XFCE 实现

通过 xfconf-query 配置 XFCE 代理设置，使用 xfce4-session channel 直接设置完整代理地址：

# 设置代理地址（完整 URL 形式）
xfconf-query -c xfce4-session -p /proxies/HTTP -s "127.0.0.1:7890" -n -t string
xfconf-query -c xfce4-session -p /proxies/HTTPS -s "127.0.0.1:7890" -n -t string
xfconf-query -c xfce4-session -p /proxies/SOCKS -s "127.0.0.1:7890" -n -t string

各平台实现对比

平台 配置方式 原子性保证 刷新机制
Windows 注册表写入 备份 + 回滚 InternetSetOptionW
macOS networksetup 命令 逐服务顺序执行 系统自动生效
Linux GNOME gsettings 先设值后切模式 系统自动生效
Linux KDE kwriteconfig6 + DBus 配置文件写入 DBus 信号通知
Linux XFCE xfconf-query（xfce4-session channel） 直接设置完整代理地址 系统自动生效

托盘菜单

Zephyr 的系统托盘菜单提供了快速访问常用功能的入口，支持状态双向同步。以下图表展示了完整的托盘菜单层级结构：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}}}%%
graph TD
    ROOT["托盘菜单根节点"]

    SHOW["Show<br/>显示主窗口"]
    SEP1["--- 分隔线 ---"]
    SYSP["System Proxy<br/>系统代理开关<br/>● 启用 / ○ 禁用"]
    TUN["TUN Mode<br/>TUN 虚拟网卡开关<br/>● 启用 / ○ 禁用"]
    SEP2["--- 分隔线 ---"]
    RULE["Rule<br/>规则分流模式<br/>● 选中 / ○ 未选中"]
    GLOBAL["Global<br/>全局代理模式<br/>● 选中 / ○ 未选中"]
    DIRECT["Direct<br/>直连模式<br/>● 选中 / ○ 未选中"]
    SEP3["--- 分隔线 ---"]

    subgraph SUB["Subscriptions 子菜单"]
        SUB_A["Config A<br/>切换到配置 A"]
        SUB_B["Config B<br/>切换到配置 B"]
        SUB_C["Config C<br/>切换到配置 C"]
        SUB_D["... 更多配置"]
    end

    subgraph PROX["Proxies 子菜单"]
        subgraph PG1["代理组 1"]
            N1A["Node A"]
            N1B["Node B"]
            N1C["... (每组最多 15 个)"]
        end
        subgraph PG2["代理组 2"]
            N2A["Node X"]
            N2B["Node Y"]
        end
        PG3["... 更多代理组"]
    end

    SEP4["--- 分隔线 ---"]
    QUIT["Quit<br/>退出应用"]

    ROOT --> SHOW
    ROOT --> SEP1
    ROOT --> SYSP
    ROOT --> TUN
    ROOT --> SEP2
    ROOT --> RULE
    ROOT --> GLOBAL
    ROOT --> DIRECT
    ROOT --> SEP3
    ROOT --> SUB
    ROOT --> PROX
    ROOT --> SEP4
    ROOT --> QUIT

    style ROOT fill:#f8fafc,stroke:#64748b,color:#1e293b
    style SHOW fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style SYSP fill:#fff3e0,stroke:#e65100,color:#bf360c
    style TUN fill:#fce4ec,stroke:#c62828,color:#b71c1c
    style RULE fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style GLOBAL fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style DIRECT fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style SUB fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
    style PROX fill:#e0f7fa,stroke:#00695c,color:#004d40
    style QUIT fill:#ffcdd2,stroke:#c62828,color:#b71c1c
    style SEP1 fill:#f1f5f9,stroke:#cbd5e1,color:#94a3b8
    style SEP2 fill:#f1f5f9,stroke:#cbd5e1,color:#94a3b8
    style SEP3 fill:#f1f5f9,stroke:#cbd5e1,color:#94a3b8
    style SEP4 fill:#f1f5f9,stroke:#cbd5e1,color:#94a3b8
Loading

菜单项说明

菜单项 类型 说明
Show 按钮 显示并聚焦主窗口
System Proxy Toggle 开关系统代理，带启用/禁用状态指示
TUN Toggle 开关 TUN 虚拟网卡，带启用/禁用状态指示
Rule / Global / Direct Radio 三选一，切换运行模式，当前模式以圆点标记
Subscriptions 子菜单 列出所有已导入的配置文件，点击切换
Proxies 子菜单 按代理组分类列出节点，每组最多显示 15 个
Quit 按钮 完全退出应用（含内核）

图标状态

托盘图标通过颜色变化直观反映当前网络状态：

状态 图标颜色 说明
默认 默认色 无代理或直连模式
系统代理激活 黄色 系统代理已启用
TUN 激活 红色 TUN 虚拟网卡已启用

双向同步机制

托盘菜单与主窗口之间通过 Tauri Event 系统实现双向状态同步，确保两端的 UI 状态始终一致。

事件名称 触发场景 同步内容
tray-sysproxy-changed 通过托盘菜单切换系统代理 系统代理开关状态
tray-tun-changed 通过托盘菜单切换 TUN TUN 开关状态
tray-mode-changed 通过托盘菜单切换运行模式 当前运行模式（Rule/Global/Direct）
tray-subscription-changed 通过托盘菜单切换配置 当前使用的配置文件
tray-proxy-changed 通过托盘菜单切换代理节点 当前选中的代理节点 
+------------------+    Tauri Event    +------------------+
|   主窗口 UI       | <--------------> |   托盘菜单        |
|                  |   双向状态同步      |                  |
| - 设置页面        |                    | - Toggle 状态     |
| - 节点面板        |                    | - Radio 选中      |
| - 模式滑块        |                    | - 子菜单高亮      |
+------------------+                    +------------------+

配置热重载

Zephyr 支持在不重启 Mihomo 内核的情况下实时更新配置，通过 update_config 机制实现安全、高效的配置热重载。以下时序图展示了从前端发起配置变更到最终生效的完整交互过程：

%%{init: {'themeVariables': {'fontSize': '10px', 'actorTextColor': '#ccc', 'signalColor': '#666', 'labelTextColor': '#999', 'labelBoxBkgColor': '#333', 'labelBoxBorderColor': '#555', 'lineColor': '#666', 'actorBkg': '#333', 'actorBorder': '#555', 'actorTextColor': '#ccc', 'signalTextColor': '#ccc', 'noteBkgColor': '#333', 'noteTextColor': '#ccc', 'noteBorderColor': '#555'}}}%%
sequenceDiagram
    participant FE as 前端 UI
    participant IPC as Tauri IPC
    participant CM as config_manager<br/>(Rust 后端)
    participant FS as 文件系统<br/>(run_config.yaml)
    participant API as Mihomo API<br/>(PATCH /configs)

    FE->>IPC: invoke("update_config", {patch})
    IPC->>CM: update_config(patch) 调用

    Note over CM: Step 1: 读取运行时配置
    CM->>FS: 读取 run_config.yaml
    FS-->>CM: YAML 内容

    Note over CM: Step 2: JSON 转 YAML
    CM->>CM: serde_json::Value<br/>转为 serde_yaml::Value

    Note over CM: Step 3: 保存安全键
    CM->>CM: 备份 external-controller<br/>备份 secret<br/>备份 TUN 状态

    Note over CM: Step 4: 递归合并
    CM->>CM: merge_yaml(existing, new, depth=0)
    Note over CM: 深度限制 50 层<br/>null 值表示删除键<br/>数组整体替换

    Note over CM: Step 5: 恢复安全键
    CM->>CM: 写回 external-controller = 127.0.0.1:{port}
    CM->>CM: 写回 secret = 应用管理的密钥
    CM->>CM: 写回 TUN 状态

    Note over CM: Step 6: 写入文件
    CM->>FS: write_file_secure<br/>序列化为 YAML 写入 run_config.yaml
    FS-->>CM: 写入成功

    Note over CM: Step 7: 同步到订阅文件
    CM->>FS: 同步更新原始 profile 文件

    Note over CM: Step 8: PATCH 热重载
    CM->>API: PATCH /configs?force=true
    API-->>CM: 200 OK

    CM-->>IPC: Ok(ConfigUpdateResult)
    IPC-->>FE: resolve

    Note over FE: UI 刷新配置显示
Loading

以下时序图展示了配置写入的完整流程：

%%{init: {'themeVariables': {'fontSize': '10px', 'actorTextColor': '#ccc', 'signalColor': '#666', 'labelTextColor': '#999', 'labelBoxBkgColor': '#333', 'labelBoxBorderColor': '#555', 'lineColor': '#666', 'actorBkg': '#333', 'actorBorder': '#555', 'actorTextColor': '#ccc', 'signalTextColor': '#ccc', 'noteBkgColor': '#333', 'noteTextColor': '#ccc', 'noteBorderColor': '#555'}}}%%
sequenceDiagram
    participant FE as 前端 UI
    participant IPC as Tauri IPC
    participant CM as config_manager<br/>(Rust 后端)
    participant FS as 文件系统
    participant API as Mihomo API<br/>(PATCH /configs)

    FE->>IPC: invoke("write_config_file", {name, content})
    IPC->>CM: write_config_file 调用

    Note over CM: Step 1: 写入文件
    CM->>FS: write_file_secure<br/>直接写入目标文件
    FS-->>CM: 写入成功
    Note over CM: 设置安全权限<br/>Unix 0o600 / Windows DACL

    Note over CM: Step 2: 同步到运行时配置
    CM->>FS: 同步到 run_config.yaml

    Note over CM: Step 3: 推送到内核
    CM->>API: PATCH /configs
    API-->>CM: 200 OK

    CM-->>IPC: Ok(String)
    IPC-->>FE: resolve
Loading

JSON 到 YAML 转换

前端通过动态配置引擎收集用户修改，以 JSON 格式提交到后端。后端将 JSON 转换为 YAML 格式后与现有配置进行合并。

递归合并策略

参数 值 说明
深度限制 50 层 防止配置嵌套过深导致的栈溢出
合并策略 深度合并 嵌套对象递归合并，标量值直接覆盖
数组处理 整体替换 数组类型不进行元素级合并，直接替换
null 值语义 删除键 overlay 中的 null 值表示从 base 中移除该键

安全键保护

在配置合并过程中，以下关键配置项受到特殊保护，防止意外或恶意修改：

保护键 保护策略 说明
external-controller 强制设为 127.0.0.1 防止外部网络访问内核 API
secret 恢复为应用管理的值 防止 API 密钥被篡改
TUN 状态 保护当前 TUN 配置 防止配置合并意外修改 TUN 状态

PATCH 请求

配置合并完成后，通过 Mihomo RESTful API 推送新配置：

PATCH http://127.0.0.1:{port}/configs?force=true
Content-Type: application/json

{
  "mode": "rule",
  "dns": {
    "enable": true
  }
}

force=true 参数确保配置被强制重载，绕过 Mihomo 内部的配置缓存机制。

原始 Profile 同步

热重载不仅更新运行时配置（run_config.yaml），还会同步修改原始的 profile 文件，确保下次启动时加载的配置与当前运行配置一致。

自定义启动参数安全过滤

用户可通过高级设置向 Mihomo 内核传递自定义启动参数。为防止配置冲突与安全风险，Zephyr 实现了严格的参数过滤机制。

禁止使用的参数

以下参数会被安全过滤器拦截，即使用户输入也会被自动移除：

禁止参数 等价形式 禁止原因
-d -- 指定工作目录，可能指向恶意路径
--directory -d 的长格式 同上
-f -- 指定配置文件路径，与 Zephyr 的配置管理冲突
--config -f 的长格式 同上
-ext-ctl -- 指定外部控制器地址，可能暴露内核 API
--external-controller -ext-ctl 的长格式 同上
-secret -- 指定 API 密钥，与 Zephyr 的安全管理冲突
--secret -secret 的长格式 同上

过滤规则

过滤器同时匹配以下形式：

形式 示例 说明
短参数 -f, -d 以单短横线开头的参数
长参数 --config, --secret 以双短横线开头的参数
等号形式 -secret=xxx, --secret=xxx 参数与值通过等号连接的形式

允许的参数示例

以下为合法的自定义启动参数：

--log-level debug
--test
--profiling

安全说明：安全过滤在参数传递给 Mihomo 内核之前执行，确保禁止参数不会到达内核进程。过滤日志会记录被移除的参数，便于排查配置问题。

返回 Home

导航

外部链接

Clone this wiki locally