> 免责声明：本项目仅供 Go TUI 工具的学习与交流。这是一个非营利开源项目，现在及未来均不接受任何赞助或捐赠。
>
> 本应用目前处于非正式开发阶段，bug 多是普遍的。

# Mihari — Mihomo / Clash 的 CLI 与 TUI 管理器

[English](README.md) · [简体中文](README.zh-CN.md)

出口网卡覆盖可在 **System → Network → Outbound Interface Override** 中选择，或使用 `mihari egress list|status|set <网卡名>|auto`。System 主行以亮黄色显示当前选择。弹窗以 ↑/↓ 浏览滚动列表，PgUp/PgDn 查看详情，回车使用当前行。界面上的 No-Override 表示不写入 Mihari 覆盖。失效的已保存网卡仍会显示，不自动回退。详细语义见[出口网卡](docs/commands.md#egress--出口网卡)。

[![license](https://img.shields.io/github/license/mihari-proxy/mihari)](LICENSE)
[![ci](https://img.shields.io/github/actions/workflow/status/mihari-proxy/mihari/ci.yml?branch=main)](https://github.com/mihari-proxy/mihari/actions)
[![go version](https://img.shields.io/github/go-mod/go-version/mihari-proxy/mihari)](go.mod)
[![release](https://img.shields.io/github/v/release/mihari-proxy/mihari)](https://github.com/mihari-proxy/mihari/releases)

[官网](https://mihari-proxy.github.io/mihari/zh/) · [Releases](https://github.com/mihari-proxy/mihari/releases)

Mihari 是面向 Windows 和 Linux 的跨平台 [mihomo](https://github.com/MetaCubeX/mihomo)（Clash Meta）管理器。它提供 CLI、终端界面（TUI）、订阅管理、系统代理、TUN 模式、mihomo 核心管理与 Web 面板。macOS 系统暂不支持；现有 Unix 安装通道与 darwin 发行二进制仍会保留。

它是 Clash Party、Sparkle 等图形化 Mihomo / Clash 客户端的开源终端替代，CLI、TUI 与浏览器面板共享同一个守护进程控制面。

![Overview](assets/overview.png)

Overview 的 Core 卡片会缩短流量趋势图，为速度值及其单位保留同一行的显示空间。

## 这是什么?

**TLDR**:Mihari 是 mihomo 的终端管理器——和 Clash Party、Sparkle 等 mihomo GUI 是同类工具,但它运行在终端里,并由一个守护进程在后台托管,CLI、TUI 和浏览器面板共享同一个控制面。

具体功能:

- **订阅管理**:添加、刷新、切换订阅配置,支持离线切换、独立刷新间隔与按订阅的拉取代理
- **核心管理**:安装、更新、重装和重启 mihomo 核心。在线更新使用官方 stable/alpha 最新版，本地已有核心不要求官方来源凭据；更新 Mihari 保留核心与通道。核心更新中断后阻止不确定启动，可通过 **System → Reinstall core** 或 `mihari core reinstall` 按原通道重装最新版，保留订阅和配置。
- **服务监控**:以 OS 服务方式在后台运行,崩溃自动重启
- **系统代理 / TUN**:开启系统代理或 TUN;若其他产品已占用系统代理或存在其他 TUN/mihomo 实例,需确认或传入 `--force`
- **Web 面板**:一键安装并打开 zashboard / MetaCubeXD 面板
- **连接与规则**:实时查看连接、代理组与规则,本地 GeoIP 解析

## 快速开始

**安装**

macOS 系统暂不支持。下方 Unix 安装命令仍包含保留的 darwin 通道。

**main release 通道**（GitHub）

```sh
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/mihari-proxy/mihari/main/scripts/install/install.sh | bash
```

```powershell
# Windows (PowerShell)
irm https://raw.githubusercontent.com/mihari-proxy/mihari/main/scripts/install/install.ps1 | iex
```

**dev release 通道**（GitHub）

```sh
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/mihari-proxy/mihari/dev/scripts/install/install.sh | bash -s -- --channel dev
```

```powershell
# Windows (PowerShell)
$env:MIHARI_CHANNEL = 'dev'
irm https://raw.githubusercontent.com/mihari-proxy/mihari/dev/scripts/install/install.ps1 | iex
```

或从 [Releases 页面](https://github.com/mihari-proxy/mihari/releases) 下载对应平台的二进制。

**国内 / 无 GitHub 访问（离线）**

整合包（mihari 二进制 + mihomo 核心 + GeoIP,含 sha256 校验）镜像在自建 AList 网盘上,安装全程不触碰 GitHub。下载器始终从稳定 AList 根目录获取。

**main release 通道**（AList / 离线）

```sh
# Linux / macOS
curl -fsSL https://cloud.xn--30q18ry71c.com/p/public/mihari-release/mihari/install-aio-remote.sh | bash
```

```powershell
# Windows (PowerShell)
& ([scriptblock]::Create((irm https://cloud.xn--30q18ry71c.com/p/public/mihari-release/mihari/install-aio-remote.ps1)))
```

**dev release 通道**（AList / 离线）

```sh
# Linux / macOS
curl -fsSL https://cloud.xn--30q18ry71c.com/p/public/mihari-release/mihari/install-aio-remote.sh | bash -s -- --channel dev
```

```powershell
# Windows (PowerShell)
& ([scriptblock]::Create((irm https://cloud.xn--30q18ry71c.com/p/public/mihari-release/mihari/install-aio-remote.ps1))) -Channel dev
```

离线分发设计见 [docs/distribution.md](docs/distribution.md)。

**首次运行**

```console
mihari
```

交互式设置沿用现有 TUI 主题和分步布局，长任务显示当前动作、动态等待指示与耗时。失败时显示安全的具体原因和下一步建议，按 F2 可打开可滚动、可复制的诊断详情。

Setup 按每一步明确提交的目标执行，正常后台初始化不会使该步失效。新导入的订阅会成为当前订阅，其他订阅条目仍然保留；跳过保留现状，可用资源直接复用，后续失败保留此前成功步骤。单步成功后的其他修改正常生效，完成引导不会重新应用之前各步。旧 daemon 不支持这套 setup 行为时，需要更新并重启 daemon 后继续。若订阅配置步骤失败且无法确认回滚成功，引导会阻止继续修改并停止核心。按 F2 查看诊断，解决报错原因后重启 Mihari daemon；底层问题未解决时，重启不保证恢复。

端口修改经确认后立即由 daemon 保存，已保存资源不会因中断丢失。重新进入时检查必需的端口与核心，继续未完成的设置；可选订阅、GeoIP 缺失不会强制进入向导。Core 分别展示本地可用性、版本、通道和运行状态，GeoIP 分别展示 Country/ASN 可用性及更新时间。已有订阅时保留概览步骤，展示数量、各项状态及当前使用项，按 Enter 继续且不修改已有订阅；继续添加或管理请进入 Subscriptions 页面。新订阅先获取并校验，首次导入失败且回滚成功时不留下条目。

操作中按 Esc 会先确认取消，再核对 daemon 执行是否收尾及实际保存结果。“结果待确认”不代表没有保存，此时可重新检查或退出，不盲目重复提交。Ctrl+Q 确认退出。已确认的启动端口冲突会通过认证本地 IPC 开放受限端口恢复，其他业务变更仍不可用。改端口后需重启 daemon，再重新检查或等待重连；当前服务接口不能验证服务是否属于所连接的实例，因此向导不会自动重启可能不相干的服务。

**添加订阅并启用系统代理**

```console
mihari sub add 我的订阅 https://example.com/subscribe
mihari sub list
mihari sub use <ID>
mihari sysproxy enable
```

## 特性

- **一个守护进程,三种界面**:CLI、TUI 和浏览器面板经本地命名管道 / Unix 域套接字连接同一守护进程控制面,控制 API 从不绑定 TCP 端口。
- **OS 服务托管**:可安装为 Windows 服务 / systemd 单元 / launchd 代理,带崩溃退避重启。
- **订阅配置**:每个订阅独立缓存、离线切换、按配置独立的刷新间隔、按订阅的拉取代理(`direct` / `proxy` / `auto`;`auto` 在可回退的代理网络错误后尝试直连),以及经过校验的原子化配置生成与回滚。
- **Web 面板**:一键安装 / 更新 / 激活 / 回滚 zashboard 与 MetaCubeXD,置于带独立访问凭据的回环 Web 网关之后。
- **系统代理与 TUN**:跨平台的系统代理控制与托管 TUN,均由守护进程持有并持久化。若其他产品已持有系统代理(`system_proxy_conflict`),或检测到其他 TUN / mihomo 实例(`tun_conflict`),enable 会失败,除非传入 `--force`(TUI 会要求确认)。
- **端口配置**:System 页面可修改 Mixed / Controller / Web 端口;占用显示 `Owned` 或 `Occupied by name (pid)`。启动期间尚未收到核心身份时，已检测到监听进程的端口显示中性的 `Checking owner…`。在 Linux 上，未提权的 TUI 无法确认占用者时显示 `Needs admin`。重启后，归属判断随守护进程/核心 PID 更新，无需重新进入页面。应用后通常需要重启守护进程。
- **TUI 内更新 Mihari**：导航栏选中 System、按 Enter 进入之前检查 GitHub Releases，显示 `当前版本 -> 最新版本 available` 或 `当前版本 · Up to date`；以管理员/root 权限启动时可替换二进制、同步并重启已安装的系统服务副本、验证 daemon 版本，并自动进入更新后的 TUI。更新确认会将安全的非标准已安装构建标识显示为 `Unknown[标识]`，兼容性仍为未知；长内容可用 ↑/↓ 或 PgUp/PgDn 滚动，默认选择 Cancel。
- **内核通道**:System 页面可在 mihomo 的 `stable` / `alpha` 通道之间切换。核心安装、更新、重装、切换通道或重启期间，mihomo core 信息行和操作行都会显示盲文运行动画与进度状态。动画标记添加在原有信息之前，操作成功或失败后消失；窄窗口优先显示动画，其余信息按可用宽度裁剪。
- **自动版本检查**：导航栏选中 System、按 Enter 进入之前，每次都会检查 Mihari 和 core 当前通道。按 Enter 进入页面不会再次发起这两项检查，也不会取消已经在进行的检查。进入 Web GUI 时逐项检查所有支持的面板，包括尚未安装的面板。Core 与 Mihari 检查会显示带动画的 `Checking`，随后显示 `当前版本 -> 最新版本 available`、`Up to date` 或 `Check failed`；这些 System 检查不会阻断其他 System 操作。Web GUI 面板检查进行时，Latest 使用同一个 badge。面板的成功结果在本次 TUI 会话内缓存 5 分钟。Mihari 或 core 检查失败时，下次用导航栏再次选中 System 会重试。core 安装/通道切换，以及面板安装/更新/回滚/重装/卸载成功后，立即刷新对应版本检查。检查只获取元数据，安装仍需确认。

Mihari 更新下载与校验期间显示 `Preparing` 盲文动画，并保留当前版本和通道。确认后恢复终端，在替换二进制和同步安装期间显示 `Updating Mihari` 盲文动画；进入新版 TUI 前报告成功、失败或需要恢复。输出重定向时使用普通状态行。

Windows 更新可使用同一用户的非管理员令牌查询用户目录中的安装版本，包括默认的 AppData 安装位置。若降权 UAC 令牌只能识别身份，Mihari 会在核验同一用户、同一登录会话和非管理员权限后，使用桌面 Shell 的令牌。目录权限不安全或无法取得通过核验的令牌时，版本仍显示 unknown；版本查询不会以管理员权限执行用户可写的文件。

单个无 CGO 的静态二进制(< 15 MB)即包含全部功能,内置 GitHub Releases 自动更新与本地 GeoIP 解析。

本地 YAML 使用 `mihari sub add NAME --file PATH` 添加，使用 `mihari sub set ID --file PATH` 修改同类型来源。PATH 必须为绝对路径或规范 `file://` URI，支持 Windows 盘符与 Linux/macOS POSIX 路径。Subscriptions 和 Setup 表单提供 **Source ‹ URL / Local file ›** 开关；切换清空来源输入，文件模式隐藏 HTTP 代理配置。已有条目类型固定。

daemon 使用自身权限读取普通文件，最多 16 MiB，仅缓存原始主 YAML；Mihari 设置覆盖另行生成的运行配置，不修改原文件。支持手动更新、定时刷新和关闭自动刷新，不监听主 YAML。本地相对输入引用按上次成功读取的实际文件目录解析（符号链接使用目标目录）；修改来源后旧缓存保留旧目录，成功刷新才替换。

URL provider 继续由 mihomo 下载。本地文件引用直接交给 mihomo，不复制或备份；原生 watcher 可能在关闭订阅自动刷新时仍改变运行，文件移动、删除或权限变化可能导致运行/重启失败，主 YAML 回滚不能恢复引用文件，部分原生操作可能写入引用文件。核心校验和运行通过 `SKIP_SAFE_PATH_CHECK=true` 允许任意引用路径，但仍受 daemon/核心 OS 权限限制；核心身份校验与 loopback controller 边界保留。

本地或远程创建新订阅时，先校验，再对文件引用列出位置/路径和后果，默认取消。非交互/JSON 必须提供 `--allow-file-references`，否则退出码为 2 并提示该 flag。后续编辑、更新、切换和启动不重复询问。初次获取或校验失败不创建条目；响应丢失仍须检查服务器状态再决定重试。普通响应仅增加派生 `source_type=file`，完整来源沿用认证 reveal 接口。本地 catalog 含 `cache-base-dir`，旧版本无法加载，降级前需移除本地条目或恢复兼容备份。

代理节点测速会读取 provider 节点，并在需要时调用 mihomo 的 provider 专用接口。同名节点在每个组内合并显示、共享测速结果：优先全局普通节点，否则按 provider 名排序选择首个匹配项。TUI 启动后的首次成功检查会对重名弹窗提示，测速来源可能与组实际选中的来源不同。provider 读取对瞬时故障最多尝试三次；持续失败时保留旧列表，显示 **Stale data** 和关键原因，恢复后自动清除提示。CLI/TUI 与 daemon 应配套升级。

TUI 节点测速进行中时，卡片在协议名称旁仅显示盲文加载动画。

**Proxies** 支持 **PgUp/PgDn** 在分组标题和已展开节点卡片之间按约一屏快速移动，保持焦点可见，并尽量保留当前列。翻页距离随窗口尺寸和固定 Basic 区域调整；焦点在 Basic 控件时，PgDn 也可进入分组列表。翻页不改变代理选择或分组展开状态。

每次进入 **Proxies** 都开始新一轮自动测速。展开后的节点卡片内容首次进入视口时触发；视口内组头的当前选择和顶部 **Basic → GLOBAL** 也会沿选择关系找到最终节点并测速。同名项每轮只自动测一次，滚出视口后已排队任务继续执行；离页或关闭自动测速时取消自动任务。重新进入、重新开启、切换订阅或核心重启后开始新一轮。新测速状态和结果直接覆盖原显示；失败本轮不自动重试，可手动测速或下次进入再测。GLOBAL 与组头当前选择旁的额外延迟复用节点卡片的结果和配色。

任一主页面按 **F4** 打开统一 **Page Settings**，也可访问 Proxies 的 **Basic** 第一行第二列入口。弹窗左侧是 Section 目录，右侧保留完整、可滚动的配置列表；打开时全部 Section 展开，并聚焦来源页面。展开状态每次打开都恢复为全部展开。左侧 Enter 跳转并展开右侧对应标题，不改变其他 Section 的折叠状态；右侧光标跨组移动时，左侧高亮同步跟随。其他页面暂显示 **No settings available yet**。Proxies 提供默认开启的 **Extra latency display** 和 **Automatic latency test**，以及 **Test concurrency**（测速并发数，范围 **1–50**，默认 **5**）。选中并发数后用 ←/→ 调整；每个 TUI 的自动与手动测速共用此上限。保存后调高会立即补充排队任务，调低则让已开始的请求完成，再按新上限调度。这些设置由 daemon 保存，同一 daemon 的 TUI 客户端共享，重启 TUI 后保留，不覆盖 Conns 列设置。

↑/↓ 在列表内移动，Enter/Space 展开标题或切换开关；Tab/Shift+Tab 在左侧目录、右侧配置区、Cancel、Save 之间切换。标题下方显示 `Tab to switch: Sections · settings · Cancel · Save`。这四个区域按 **]** 展开全部 Section，按 **[** 折叠全部 Section，底栏显示 `] Expand all` 与 `[ Collapse all`；折叠不改变草稿。底部按钮固定可见。任意位置按 **Ctrl+S** 或 Save 开始保存，弹窗保持打开：先播放橙色 **Saving** 动画 badge，结束后显示绿色 **Done** badge，或红色 **Failed** badge 加错误详情。Esc 或 Cancel 才关闭弹窗。没有改动时不会请求 daemon，Ctrl+S 同样留在弹窗并显示 **Done**。保存成功后生效。TUI 与 daemon 应配套升级；旧版不能读取包含非默认 Proxies 设置的偏好文件，旧版 daemon 也不能读取非默认测速并发数，降级前应先恢复为 5；两个开关和并发数都恢复默认后会移除该可选块。

TUI 订阅表格的 Name 和 Traffic 列按内容分配宽度，分别最多占 40 和 24 个终端字符格；多余空间留在右侧，窄屏优先隐藏次要字段。

本地文件读取传递取消并限制内容大小，但文件系统元数据查询/打开可能阻塞在 OS 内，尤其是不可达的 UNC/SMB 共享或网络挂载。取消及执行预算无法强行中断这些同步系统调用。

订阅下载 Mode 将 `auto` 显示为 **PROXY w Fallback to DIRECT**。回退覆盖主订阅 YAML 的连接超时和成功响应正文读取超时等可重试网络错误；HTTP 错误、无效文档不触发回退。每次代理/直连尝试保留 30 秒预算，daemon 的 Add/Refresh 整次执行上限为 120 秒，CLI/TUI 每条等待最多 180 秒以容纳有界回滚和响应。更短的调用方 deadline 与主动取消仍优先，批量刷新逐条计时。窄列表必要时整列隐藏 Mode，进入详情可查看完整值。Provider 下载策略及 Proxies 页 Routing Mode 独立于此设置。

**System → Network** 在 daemon 启动时应用保存的系统代理或 TUN 状态期间显示橙色 **Applying…** 动画 badge，开启与关闭目标均适用。该次启动应用完成、失败或取消后停止动画。页面导航和手动操作保持可用；此标记不代表自动修复状态漂移。

mihomo HTTP 失败的原始报错与上游状态会写入诊断日志，范围包括 gateway 和 WebSocket 握手。日志、导出及本地 CLI/TUI 错误汇报均不脱敏，保留错误自带的凭据、URL、路径与配置片段。CLI 分段展示概要、错误分类和原始详情，JSON 增加可选诊断和 warnings，业务退出码保持不变。TUI 所有页面均可按 F2 打开统一诊断历史，滚动查看详情并复制原文。终端控制字符仅在显示时转义。

F2 每次发生保留独立记录，以级别颜色和选中高亮帮助浏览。宽终端左右显示列表和详情，窄终端上下排列。Tab 切换窗格，方向键、PgUp/PgDn、Home/End 导航，c 复制原始详情，Esc 返回；新记录不会抢走当前选择。Web gateway 允许来自 mihomo 的单条消息最大 1 MiB，与 mihomo 流客户端一致；浏览器发送方向仍限制为 32 KiB。

F2 的剪贴板写入在后台执行，保持弹窗可操作。OSC 52 仅表示请求已交给终端，不确认复制成功，并保留历史不可用等提示。在 Linux 使用 sudo 启动时，Wayland 复制优先使用发起会话指定的可用显示 socket；未找到时，自动发现要求只有一个可用 socket。提权 helper `runuser` 只从固定的绝对系统路径查找，包括系统 profile。其他本地会话使用系统剪贴板工具。

更新后保留已退役的 Mihari/mihomo 二进制及已完成事务残留，留到后续启动尝试清理。daemon 清理其管理的核心文件；daemon 与 TUI 启动还会尝试清理当前 Mihari 程序旁的残留。占用或其他清理失败保留到下次启动重试，并在 **F2** 显示 warning，不影响更新或启动成功。同次运行可连续更新核心。普通 CLI 查询不触发删除；中断事务的恢复材料和用户备份会保留。

## 常用命令

| 场景 | 命令 |
|------|------|
| 查看状态 | `mihari status` |
| 核心管理 | `mihari core status` · `mihari core restart` |
| 代理组 | `mihari proxy groups` · `mihari proxy select <GROUP> <PROXY>` |
| 运行模式 | `mihari proxy mode [rule\|global\|direct]` · `mihari proxy select GLOBAL <PROXY>` |
| 订阅管理 | `mihari sub add <NAME> <URL>` · `mihari sub set <ID> --proxy auto` · `mihari sub use <ID>` |
| 系统代理 / TUN | `mihari sysproxy enable` · `mihari sysproxy enable --force` · `mihari tun enable` · `mihari tun enable --force` |
| Web 面板 | `mihari panel list` · `mihari panel open` |
| 服务控制 | `mihari service status` · `mihari service stop` |
| 全量卸载 | System 页 `Completely Uninstall Mihari` · `mihari service uninstall --purge --yes` · `mihari service uninstall --purge --yes --force` · `mihari service uninstall --purge --yes --delete-unmatched-command` |
| 更新 mihari | System 页 `Update Mihari` · `mihari self update` |

完整命令参考见 [docs/commands.md](docs/commands.md),架构与安全机制见 [docs/architecture.md](docs/architecture.md)。

**Connections** 为 Chain 分配更多宽度，窄窗口中优先于 Source、Destination、Rule 保留。Traffic 使用固定宽度的上下行紧凑速率，`K/M/G/T/P/E` 按 1024 进制表示字节每秒；连接详情仍显示完整速率与代理链。**Rules** 用居中弹窗展示规则或 provider 的完整详情，↑/↓ 或 PgUp/PgDn 滚动，Enter/Esc 关闭后返回原行。

**Conns、Rules、Logs** 支持 Ctrl+F 从侧栏或页面内容区直接聚焦检索框，保留已有文字并将光标移到末尾；页面内容区仍支持 `/`。弹窗打开时不抢走焦点。焦点位于列表行时，**PgUp/PgDn** 按当前窗口高度移动一页行数，在筛选结果的首尾停住；Rules 的 provider 列表同样支持。Logs 翻页后停止自动跟随，按 **G** 返回最新记录并恢复跟随。Conns 在当前 TUI 会话中保留最新 **5000 条已关闭连接记录**，切页保留，重连或退出后清空；活动连接不占此配额。

**Logs** 中选中 **Level** 后按 Enter 打开多选小窗。↑/↓ 移动，Space 勾选 DEBUG、INFO、WARNING、ERROR；**Select all** 用于全选或清空。Enter 应用、Esc 放弃，至少勾选一个级别。连续选到 ERROR 的组合显示为 `DEBUG+`、`INFO+` 或 `WARNING+`，其他组合完整列出，例如 `DEBUG, WARNING`。这只是显示摘要，筛选按所选精确级别匹配，再与文字检索取交集。Enter 确认改动后异步保存，Level 旁显示 **Saving…**，不阻断导航和操作。保存失败保留当前筛选，显示 **Unsaved**，错误进入 F2；不重试、不在重连时补交，退出也不等待保存。新 TUI 恢复同一 daemon 最后成功保存的选择；已打开的窗口各自保留当前选择，切页和重连不覆盖。尚无已保存选择时默认全选；全选也保留未知级别记录。筛选不修改 System 日志设置或实时流订阅。TUI 与 daemon 须同步升级；旧版 daemon 无法读取含新增 `log_levels` 字段的偏好文件。

连接详情采用单个居中页面，以 **Application → Routing → Outbound → Destination** 纵向展示处理链路，字段归入对应阶段。Routing 合并显示入站名称／类型／协议和 **Rule Matched**，并从外层代理组到出站逐级展开上报的选择链；Outbound 展示 **Remote** 及其 GeoIP，Destination 保留自己的目标地址及 GeoIP，选择树不代表完整网络中转拓扑。上传速率与累计量为绿色，下载为蓝色；拒绝出站以断线连接灰色的请求目标节点。长字段自动换行，深层选择树保留层级序号，面板最大 88 个终端字符列。↑/↓ 滚动，Enter/Esc 返回选中行。**Paused** 表示观测数据已冻结；已关闭连接显示最后观测速率与累计流量，**Closed observed** 是 TUI 发现连接消失的时间，不是内核报告的精确关闭时间。

**Web GUI** 面板卡片宽屏并排、窄屏纵排。Tab/Shift+Tab 或 ←/→ 选择 Open/Install 或 Manage，Enter 执行，↑/↓ 切换面板。顶部以三行对齐展示 Gateway、Default panel 和 Browser sessions。安装、重装或更新期间，橘色 Installing／Reinstalling／Updating 动画 badge 显示在 Manage 后（首次安装在 Install 后）；窄卡片中 badge 整体换到按钮下方，操作结束后清除。Update available 保留在 Latest 版本后，更新成功后刷新版本状态；原有面板快捷键保留。Manage 包含更新、设为默认、重装、回滚及卸载，不可用项标明原因。黄色 **Ctrl+Shift+R** 刷新提示始终保留在卡片上方，网关保护说明移至 `?` 帮助。**System** 的 Network 分区移至 Ports Config 之后。

TUI **Proxies** 页顶部的 **Basic** 卡片包含 **Mode**、**GLOBAL** 和 **Page Settings**。**Mode** 按 Enter 打开 Rule / Global / Direct 选择弹窗，↑/↓ 选择、Enter 应用、Esc 取消；**GLOBAL** 入口展开 mihomo 返回的候选组，并自动滚动到整个 section 完整可见；超过一屏时从列表视口顶部展示，继续用方向键浏览候选。Mihari 全局保存模式、按订阅保存 GLOBAL 出口，支持面板发起的相同操作。默认使用 Rule，切换模式和出口保留已有连接。保存的出口消失时，有 DIRECT 候选则保存 DIRECT，否则保存 Rule；内核停止时保存的模式显示为 pending，待启动应用。

Basic 标签为白色、值为绿色。仅焦点行在值后紧跟显示 `· Press Enter to Change` 或 `· Press Enter to Select`；窄屏优先保留值，空间不足时隐藏操作提示。状态说明不随失焦隐藏。

已选代理卡片使用蓝色 **●** 标记，颜色与日志 **INFO** 一致。候选节点的长名称在卡片内自动换行，不再截断；同一排卡片统一采用该排最高卡片的高度，各排独立计算。Proxies 每个组（含 GLOBAL）的当前选择右侧都有 **→ Jump to Selected**（窄窗口缩短为 **→ Selected**）。在组标题上按 → 聚焦按钮，再按 Enter 自动展开并定位到当前选中的卡片；← 返回组标题。定位只移动键盘焦点，后续刷新改变选中项时不自动跟随。保留的 **Last selected** 数据仍可定位；选中项为空或不在候选列表中时按钮置灰。

TUI **Subs** 页按 Enter 打开可编辑详情，`a` 添加订阅。Tab/Shift+Tab 或 ↑/↓ 切换字段和操作，←/→/Space 在 **Auto refresh** 和 **Mode** 行循环选择；设置字段上的 Enter 进入下一项，**Save** 上的 Enter 提交设置。**Enabled** 操作可立即启用或停用订阅；**InUse → Use this subscription** 可将已启用且有有效缓存的订阅设为当前使用，已选中的订阅显示 **In use**。停用会同时清除其 InUse；重新启用不会自动选中。操作后详情保持打开，未保存的设置草稿保留。PgUp/PgDn 滚动正文，长 URL 单行横向滚动。所有 TUI 内置文案均为英文。列表显示 **InUse**、**Enabled**、**Status**、**Mode**，`p` 循环切换拉取模式。

列表各列保持紧凑，**Name** 随内容扩展，最多占 40 个终端显示单元，超长名称以省略号截断。表头分隔线和焦点行高亮延伸至区域右侧内边距。窄窗口会按需缩短名称并隐藏优先级较低的列。

添加和编辑共用居中紧凑表单，详情按运行状态和设置分组；没有错误时隐藏错误行，时间显示为本地时间并精确到分钟。窗口较矮时正文滚动，**Save** 始终可见。Auto refresh、Mode、Enabled、InUse 仅对当前选项值反色高亮，标签和行尾空白保持原样；文本框使用浅色输入底和白色光标。快捷键仅在终端底部显示一份并随焦点变化。**Interval** 输入值旁用浅灰色显示支持的单位（`ns/us/ms/s/m/h`）；留空时以占位文字显示当前全局间隔，保存空值仍表示继承。

修改 URL 会保留旧缓存和 InUse，不立即下载或 reload；**Outdated** 表示缓存来自旧 URL，仍可离线 Use。修改单条 interval 会重置下次刷新时间，并持久标记 **Expired**，直到刷新成功（包括有效 304）；Disabled、Failed、Missing、Outdated 等更高优先级状态仍优先显示。关闭 Auto refresh 时 Next 显示 **Manual**。

保存等待结果后关闭。revision 冲突会询问是否仅覆盖本次实际修改的字段。结果未知时先只读查询操作和当前状态，不自动重放保存；**Submit again** 需要再次确认，添加场景可能产生重复条目。关闭界面不代表撤销保存。首次获取或校验失败不创建条目；已有订阅刷新失败时保留旧缓存，可按 `r` 重试。

TUI 与 daemon 必须配套升级，不保证混用版本。升级前停止 daemon，按实际布局备份完整业务数据（Unix B/D，或 Windows/私有 P），将 catalog、缓存、settings/state、运行配置作为一致整体保存。旧二进制无法读取新增 catalog 字段，不支持直接降级；回退二进制时应停机恢复兼容的完整备份，不通过单独删除 YAML 字段降级。

## 平台目标

- Windows amd64 与 arm64
- Linux amd64 与 arm64

macOS 系统暂不支持。Unix 安装通道仍会发布 darwin amd64 与 arm64 二进制。

所有发行二进制均为无 CGO。

## 数据路径

| 平台 | 默认机器入口 B | 业务数据 D | 本用户诊断 U |
| --- | --- | --- | --- |
| Windows | `%USERPROFILE%\.mihari` | 同左 | 同左 |
| Linux | `/var/lib/mihari` | `B/data` | 绝对 `XDG_STATE_HOME/mihari`，否则可信 home 的 `.local/state/mihari` |
| macOS（暂不支持） | `/Library/Application Support/mihari` | `B/data` | 可信 home 的 `Library/Logs/mihari` |

Unix 的 E/C/channel 分别为 `B/control.sock`、`B/control.token`、`B/mihari-channel`；I 默认 `/usr/local/lib/mihari`。B 为 root0711，D 为 root0700，C/channel 为 root0644，E 为 root0666。普通用户无需 sudo 即可认证并管理同一代理及读取受控机器诊断；不能直接读取 D 或其他用户的 U。Windows 继续使用 `\\.\pipe\mihari-control`。

显式 `MIHARI_DATA=P` 保留 P 本身的私有单根语义与 0700/0600 权限，不是 P/data，也不能与默认 B/D 重叠。root 不信 HOME/SUDO_USER/XDG；默认共享发现不使用 XDG_RUNTIME_DIR。root 安装与迁移采用停机、校验、原子提交和可重复恢复；旧数据树及旧日志保留。各平台统一保留订阅配置，仅覆盖 Mihari 托管参数；TUN 开关只覆盖 `tun.enable`，保留其余字段。配置语义和原生 provider 由 mihomo 处理，Mihari 保留候选校验与 reload 回滚。Unix root 仍要求内置可信核心 v1.19.30，二进制身份校验与配置生成相互独立。具体覆盖项、I/FS 限制、停机 credential 轮换和恢复入口见 [Unix 布局与安装恢复](docs/unix-layout.md)。

## 文件日志

Unix 机器日志写入 D，本用户 TUI 日志写入 U；Windows/显式私有 P 保持单根。日志采用 JSONL（每行一个 JSON 对象）：

| 来源 | 路径 |
| --- | --- |
| Mihari 守护进程 | `D/logs/mihari-daemon.log` |
| TUI（当前 UID 的实例共享） | `U/logs/mihari-tui.log` |
| 捕获的 mihomo 输出 | `D/logs/mihomo.log` |

守护进程与捕获的 mihomo 文件日志默认级别为 `info`，每个活跃文件到 10 MiB 时轮转，并保留三份文件（活跃文件加最多两份归档）。TUI 启动时使用 bootstrap 配置——级别 `debug`、100 MiB、10 份文件——以便在守护进程设置可用前也能记录日志；在后续控制面同步前会保持该 bootstrap 配置。TUI 的 System 页面可修改由守护进程持有的级别、单文件最大大小和保留数量，变更无需重启守护进程。捕获 mihomo 输出时会识别文本/JSON 中的真实级别并保留原行；无法识别时，stdout 回退为 `INFO`，stderr 回退为 `WARN`。

System → Logging → Level 同时控制 Mihari 文件日志与 mihomo 全局 `log-level`，生成配置覆盖订阅值但不修改原缓存。主动可选 `debug`、`info`、`warn`、`error`。在线修改经过校验、内核确认、reload 与保存，失败补偿恢复；内核停止时保存到下次启动应用。外部内核变化每 2 秒观察：保存失败保留内核现状、显示未保存并重试最新值。仅被动采纳内核的 `silent`，保留历史文件和操作错误提示，用户可切回四档。旧版本可能拒绝已保存的 `silent`，降级前应切回支持级别或恢复兼容的停机备份。TUI/Web 实时日志筛选独立于文件级别，silent 也不限制实时订阅。网关允许单字段 `PATCH /configs {"log-level":"debug"}`，混合及未知写入仍拒绝。

选中 **Level** 后按 Enter，右侧以 `< INFO >` 整块高亮当前级别。←/→ 在 DEBUG、INFO、WARN、ERROR 间循环选择，再按 Enter 应用；Esc 放弃候选并显示最新实际值。编辑期间 ↑/↓ 和 Tab 不移动焦点；提交时显示 Applying 旋转动画并锁定编辑，成功返回 Level，失败保留候选以便重试。未改变值时直接退出，不发送请求；外部更新不会覆盖候选。从 SILENT 开始编辑时，→ 选 DEBUG、← 选 ERROR，SILENT 不加入主动选项。

`GET /v1/logging` 与 `PATCH /v1/logging` 是供 TUI 使用的稳定 v1 本地控制端点，并非 CLI 命令。日志导出仅在 TUI 提供：可在 Logs 页按 `e`，或在 System → Logging 选择 **Export logs**。对话框支持最近 24 小时、最近 60 分钟、本地时间区间和全部记录。默认输出到 `U/logs-export/`；已有 zip 永不覆盖，自定义目标必须是既有目录中的绝对 `.zip` 路径。没有 CLI 日志导出命令。

Logging 位于 Network 下方、About 上方。Unix 分别显示机器日志目录与本用户日志目录；Windows 的 **Logging Dir** 保持单目录只读路径，选中后按 Enter 复制。Export Logs 中的 **Current Time** 每秒刷新；↑/↓ 选择字段，Enter 进入编辑或应用修改，编辑时 Esc 弹窗确认放弃。Range 编辑支持方向键及 Tab/Shift+Tab 切换模式，自定义区间在行末提示 `Use YYYY-MM-DD HH:MM format`。选中 **Export** 后按 Enter 开始导出。

Windows 私有日志授权给具体的数据用户及 LocalSystem，兼容提权进程创建、owner 为 Administrators 的数据目录；写入器启动时会修复 daemon、TUI、mihomo 的现有日志、保留归档及锁文件的 ACL，不改动内容。运行中的服务创建或加固文件时会重新读取根目录权限策略，避免轮转后恢复旧权限。如果旧版本已经移除了普通用户访问权限，需要更新后的程序以管理员权限运行一次完成修复。TUI 内的提权更新流程会以该权限进入新 TUI；手动替换二进制的用户可能需要首次以管理员权限启动。

Unix 系统模式使用 `mihari-logs-export/v2`，通过认证的机器快照协议组合机器与本用户日志；离线时须明确选择仅本用户日志。Windows/显式私有 P 保持本地 v1。zip 固定包含 `manifest.json`，以及有内容时才出现的 `daemon/mihari-daemon.log`、`tui/mihari-tui.log`、`mihomo/mihomo.log`。记录经过有效性与时间范围筛选，并保留原始 JSON 记录字节；快照及导出均不脱敏。导出前与成功页面以红色文字说明：日志可能包含密码、访问令牌、完整订阅地址及用户配置，分享前请自行检查。

诊断文本、HTTP 失败正文与 mihomo 单个逻辑输出行各限 256 KiB，超限明确标记。JSON 转义使记录超过既有快照限额时，使用带 `record_id`、`fragment_index`、`fragment_count` 的有界分片；轮转或写入中断造成的缺片仍可识别。保留已有堆栈，普通错误不额外采集堆栈。

错误仅使用当前可用的文件 logger；普通 CLI 不创建日志，也不打开历史日志文件。预期拒绝和主动取消为 INFO，可恢复失败及重试尝试为 WARN，最终失败为 ERROR，并遵循配置的级别过滤。同一失败由实际执行 owner 记录，重放同一结果不重复记错。

导出全程持有已打开的目标父目录 identity，生成期间父路径被替换时不会跟随被替换后的路径。Unix 清理以同 UID 与本机 root/管理员为受信主体；若自定义父目录初始为不可信共享目录，即使导出期间收紧权限，内容清理成功后仍可能留下空的私有 workspace，清理 IO 失败则会报告可能存在内容残留。发布成功后若目标目录又被外部改名，界面显示的绝对路径也可能失效。

旧版二进制使用 `KnownFields(true)` 解码 `mihari.yaml`，无法读取自定义 `log:` 块。降级前，请在 System → Logging 恢复 `info` / 10 MiB / 3 份文件，使该块自动移除；或先备份设置文件，再手动删除 `log:`。历史脱敏日志无法恢复原文，旧客户端仍可能对导出内容执行脱敏。

## 开发

```console
go test ./...
go test -race ./...
go vet ./...
```

构建本地二进制:

```console
CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o bin/mihari ./cmd/mihari
```

架构不变量、包边界与贡献指南见 [AGENTS.md](AGENTS.md) 与 [CONTRIBUTING.md](.github/CONTRIBUTING.md),发布流程见 [docs/RELEASE.md](docs/RELEASE.md)。

## 社区

本项目完整开源，认可 [LINUX DO](https://linux.do/) 社区，感谢其对开源项目的支持。

## 许可

[GPL-3.0](LICENSE) © 2026 Mihar1

Mihari 是一个独立项目,与 mihomo 项目或 MetaCubeX 无关联,也不受其背书。

## Star History

[![Star History Chart](https://api.star-history.com/chart?repos=mihari-proxy/mihari&type=date&legend=bottom-right)](https://www.star-history.com/?repos=mihari-proxy%2Fmihari&type=date&legend=bottom-right)