#Zephyr

基于 Tauri v2 的现代化 Mihomo GUI 客户端 —— 轻量、安全、跨平台

Zephyr 是一款基于 Tauri v2 框架与原生 Web 技术构建的跨平台桌面代理管理客户端，专为 Mihomo（Clash Meta）内核设计。项目采用 Rust 后端 + 原生 JavaScript 前端的极简架构，在保持功能完备的同时实现了极低的资源占用与良好的运行时性能。

本 Wiki 描述的是 v2.5.0 版本的代码。

#截图预览

更多截图

设置页面	深色模式

#功能亮点

#代理与内核

• 一键模式切换 —— 规则 / 全局 / 直连，系统代理与 TUN 可直接在首页切换；托盘同步显示状态（TUN 红橙色图标、系统代理绿色图标）
• TUN 模式 —— Windows 上通过 UAC 以管理员身份重启整个应用来开启 TUN（仅对 UAC 拆分令牌的管理员账户提供；未提升启动时 TUN 自动保持关闭）；macOS 通过 osascript 以 root 运行内核；Linux 通过 pkexec + setcap + polkit 规则授权
• 系统代理守护 —— 带归属标记，被外部关闭时每 10 秒重新应用，崩溃后可恢复；Linux 同时作用于检测到的 GNOME / KDE / XFCE 桌面环境
• 节点管理 —— 自适应网格布局，支持默认 / 名称（按地区分组）/ 延迟 / 智能排序；节点轮盘支持悬停、点击或键盘打开与方向键导航，切换节点时关闭已有连接
• 自动切换 —— 故障转移、节点评分、定时测速三个独立开关（定时测速需开启节点评分）
• DNS 防泄漏 —— 仅通过内核 API 应用，不写入配置文件

#订阅与规则

• 订阅三层下载 —— 直连（DNS Pinning）→ 内核 mixed 端口代理 → 临时全局模式（自动恢复）；从不使用系统 / 环境代理
• 订阅管理 —— 带实时 URL 校验的链接对话框、拖拽手柄与 Alt+↑/↓ 排序、"下次更新"时间、更新失败徽标；自动更新间隔：关闭 / 12 小时 / 1 天 / 3 天
• 配置清洗 —— 自动移除 script、cfw-*、各类外部控制器键（含 << 合并展开）等危险配置；Prism YAML 覆写同样经过清洗
• 规则库 —— 启用 / 禁用规则文件、从配置提取规则、从文本 / 文件 / URL 导入；保存前清洗，不可解析的 YAML 会被拒绝；内置插入规则表单与行内编辑器（12 种规则类型）
• Deep Link 导入 —— 支持 clash://install-config?url=…&name=…，导入前弹出确认框

#界面与体验

• 首页统计条 —— 总流量、活动连接数（TCP / UDP 拆分）、节点延迟；控制台首页优先显示缓存延迟
• 进程图标 —— 连接列表显示真实应用图标（Windows 可执行文件图标、macOS .app 图标、Linux .desktop / hicolor 图标）
• 实时流量图表 —— 原生 Canvas 2D 绘制，下载蓝色、上传珊瑚色
• 统一日志页 —— 应用日志与内核日志共用一个筛选栏（全部 / Info+ / Warn+ / 仅错误），支持暂停、跳到最新、结构化行与搜索高亮
• 设置页 —— 外观 / 通用 / 代理 / 网络 / 订阅与规则 / 数据与安全 / 关于 7 个分区，另有独立的高级配置页；分区索引栏 + 设置搜索；"恢复默认"会列出重置与保留的内容；关于页内置第三方许可证查看器
• 主题与缩放 —— 4 种预设主题色 + 自定义十六进制颜色，深色模式，窗口不透明度调节；界面缩放 100% / 110% / 125% / 150%
• 无障碍 —— 完整键盘导航（标签页方向键、节点列表 roving tabindex、对话框焦点陷阱），仅在键盘操作时显示焦点环，导航栏提示
• 多语言 —— 14 种语言，含 RTL 语言支持
• 空状态与错误提示 —— 无订阅引导页，内核错误在页面内以错误卡片展示

#更新

• 新版更新对话框 —— 一个对话框同时处理内核与客户端更新：检查中 / 已是最新 / 有新版本（安全渲染的更新说明）/ 安装中 / 完成 / 失败；两者都有更新时先装内核
• 完整性校验 —— 客户端安装包需通过 SHA-256 + Minisign 签名双重校验；内核与 Geo 数据均校验 SHA-256，内核替换失败时自动回滚
• 自动检查 —— 开启后在启动 5 秒后检查并通知，不会自动安装；便携版提供发布页链接，仅支持内核更新

完整功能说明见 Features。

#支持平台

每个平台提供两种版本：

• Full —— 内置 Mihomo 内核与 Geo 数据，开箱即用
• Lite —— 不含内核，需要自行放置内核文件

Windows 另提供便携版。下载与安装方式见 Installation。

#技术栈架构

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}}}%%
graph TB
    subgraph Frontend["前端层 (UI Layer)"]
        JS["原生 JavaScript<br/>104 个 ES Module"]
        UNO["UnoCSS presetWind4<br/>原子化样式"]
        CV["Canvas 2D API<br/>流量图表渲染"]
        CM["CodeMirror 6<br/>配置 / 脚本编辑器"]
    end

    subgraph IPC["Tauri IPC 桥接层"]
        CMD["Command Registry<br/>180 个 Tauri Commands"]
        EVT["Event System<br/>15 个后端 → 前端事件"]
        STATE["托管状态<br/>MihomoState / SettingsState / TrayState<br/>RateLimiter / PrismState / SchedulerState 等"]
    end

    subgraph Backend["Rust 后端层"]
        TAURI["Tauri v2<br/>应用框架"]
        REQ["reqwest<br/>HTTP 客户端"]
        AES["aes-gcm + pbkdf2<br/>AES-256-GCM 加密"]
        MS["minisign<br/>更新签名校验"]
    end

    subgraph Core["Mihomo 内核层"]
        MIHOMO["Mihomo (Clash Meta)<br/>代理引擎"]
        REST["RESTful API 127.0.0.1:9090"]
        STREAM["HTTP Streaming /traffic"]
        TUN["TUN 虚拟网卡"]
    end

    Frontend -->|invoke / listen| IPC
    IPC -->|Rust Command Handlers| Backend
    Backend -->|进程管理 / REST API| Core

详见 Architecture。

#安全纵深防御

%%{init: {'themeVariables': {'fontSize': '10px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '10px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 15, 'rankSpacing': 25}}}%%
graph LR
    A["CSP<br/>script-src 'self'"] --> B["Tauri 最小权限<br/>无 fs / shell / http 插件"]
    B --> C["SSRF 防护<br/>DNS 预检 + IP 校验<br/>DNS Pinning + 重定向校验"]
    C --> D["加密存储<br/>AES-256-GCM<br/>可选订阅文件加密"]
    D --> E["路径遍历防护<br/>文件名净化"]
    E --> F["危险配置清除<br/>script / 外部控制器键"]
    F --> G["更新完整性<br/>SHA-256 + Minisign"]
    G --> H["特权提升<br/>UAC / osascript / polkit"]
    H --> I["CI/CD 扫描<br/>security.yml 14 个 Job<br/>+ CodeQL / Snyk / GitGuardian"]

完整的十三层防御说明见 Security。

#设计理念

• 安全优先 —— 多层纵深防御，从 CSP 策略到 CI/CD 自动化扫描。Fail-closed 设计：安全检查失败时拒绝操作，而非降级放行
• 极简依赖 —— 无前端框架（无 React / Vue / Svelte），无图表库（原生 Canvas 2D）。pnpm monorepo（apps/desktop + packages/shared），前端共 104 个 ES Module
• 跨平台一致 —— Windows / macOS / Linux 统一代码库，按平台精准适配（Windows 注册表代理与 UAC 提权、macOS osascript 提权、Linux 多桌面环境检测与 polkit）
• 配置即代码 —— 安全策略通过 CI/CD 流水线强制执行，确保不会被意外绕过

#技术栈

#项目规模

#Wiki 页面索引

链接：GitHub 仓库 · 问题反馈 · MIT 许可证