Docker 部署 Mihomo (Clash Meta) 核心 + WebUI 指南

流程概览#

前言#

Mihomo（原名 Mihomo Meta，亦即 Clash Meta）是目前 Clash 核心最活跃、功能最强大的分支。由于原始 Clash 项目删库，Mihomo 已成为各平台客户端的首选核心。

值得注意的是，Mihomo 本身是一个纯命令行程序（Core），没有图形界面。为了方便日常管理和监控，我们需要为其搭配一个 Web UI（如 Metacubexd）。本文将详细介绍如何在 Docker 环境（包括 Linux 服务器、NAS、飞牛OS等）中优雅地部署 Mihomo + WebUI，并开启 TUN 模式实现更接管更底层的流量。

准备工作#

在开始之前，请确保您的环境满足以下条件：

Docker 环境：已安装 Docker 及 Docker Compose。
基础知识：熟悉基本的命令行操作（创建文件夹、编辑文件）。
网络环境：拥有可用的节点订阅链接。

第一步：编写配置文件 (config.yaml)#

Mihomo 的运行核心在于配置文件。我们需要先在宿主机上准备好这个文件。

新建一个文件夹，命名为 mihomo。
在其中创建一个名为 config.yaml 的文件。
参考以下模板填入内容。

⚠️ 重点修改提示： 请务必修改下方模板中的 第 7 行（API访问密钥）、第 20、21 行（节点订阅信息）与 第 26 行（节点名称前缀）。修改时请去掉尖括号 < >。

1
mixed-port: 7890
2
allow-lan: true
3
bind-address: '*'
4
mode: rule
5
log-level: info
6
external-controller: '0.0.0.0:9090'
7
secret: "<API访问密钥>"
8

9
tun:
10
  enable: false
11
  stack: mixed
12
  dns-hijack:
13
    - "any:53"
14
    - "tcp://any:53"
15
  auto-route: true
16
  auto-redirect: true
17
  auto-detect-interface: true
18

19
proxy-providers:
20
  <节点提供者名称>:
21
    url: "<节点订阅链接>"
22
    type: http
23
    interval: 86400
24
    health-check: {enable: true,url: "https://www.gstatic.com/generate_204", interval: 300}
25
    override:
26
      additional-prefix: "<节点名称前缀>"
27

28
proxies:
29
  - name: "直连"
30
    type: direct
31
    udp: true
32

33
geodata-mode: true
34
geox-url:
35
  geoip: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geoip.dat"
36
  geosite: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat"
37
  mmdb: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/country-lite.mmdb"
38
  asn: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/GeoLite2-ASN.mmdb"
39

40
dns:
41
  enable: true
42
  ipv6: true
43
  respect-rules: true
44
  enhanced-mode: fake-ip
45
  fake-ip-filter:
46
    - "*"
47
    - "+.lan"
48
    - "+.local"
49
    - "+.market.xiaomi.com"
50
  nameserver:
51
    - https://120.53.53.53/dns-query
52
    - https://223.5.5.5/dns-query
53
  proxy-server-nameserver:
54
    - https://120.53.53.53/dns-query
55
    - https://223.5.5.5/dns-query
56
  nameserver-policy:
57
    "geosite:cn,private":
58
      - https://120.53.53.53/dns-query
59
      - https://223.5.5.5/dns-query
60
    "geosite:geolocation-!cn":
61
      - "https://dns.cloudflare.com/dns-query"
62
      - "https://dns.google/dns-query"
63

64
proxy-groups:
65

66
  - name: 默认
67
    type: select
68
    proxies: [自动选择,直连,香港,台湾,日本,新加坡,美国,其它地区,全部节点]
69

70
  - name: Google
71
    type: select
72
    proxies: [默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择,直连]
73

74
  - name: Telegram
75
    type: select
76
    proxies: [默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择,直连]
77

78
  - name: Twitter
79
    type: select
80
    proxies: [默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择,直连]
81

82
  - name: 哔哩哔哩
83
    type: select
84
    proxies: [默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择,直连]
85

86
  - name: 巴哈姆特
87
    type: select
88
    proxies: [默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择,直连]
89

90
  - name: YouTube
91
    type: select
92
    proxies: [默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择,直连]
93

94
  - name: 海外AI
95
    type: select
96
    proxies: [默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择,直连]
97

98
  - name: NETFLIX
99
    type: select
100
    proxies: [默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择,直连]
101

102
  - name: Spotify
103
    type: select
104
    proxies:  [默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择,直连]
105

106
  - name: Github
107
    type: select
108
    proxies:  [默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择,直连]
109

110
  - name: 国内
111
    type: select
112
    proxies:  [直连,默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择]
113

114
  - name: 其他
115
    type: select
116
    proxies:  [默认,香港,台湾,日本,新加坡,美国,其它地区,全部节点,自动选择,直连]
117

118
  #分隔,下面是地区分组
119
  - name: 香港
120
    type: select
121
    include-all: true
122
    filter: "(?i)港|hk|hongkong|hong kong"
123

124
  - name: 台湾
125
    type: select
126
    include-all: true
127
    filter: "(?i)台|tw|taiwan"
128

129
  - name: 日本
130
    type: select
131
    include-all: true
132
    filter: "(?i)日|jp|japan"
133

134
  - name: 美国
135
    type: select
136
    include-all: true
137
    filter: "(?i)美|us|unitedstates|united states"
138

139
  - name: 新加坡
140
    type: select
141
    include-all: true
142
    filter: "(?i)(新|sg|singapore)"
143

144
  - name: 其它地区
145
    type: select
146
    include-all: true
147
    filter: "(?i)^(?!.*(?:🇭🇰|🇯🇵|🇺🇸|🇸🇬|🇨🇳|港|hk|hongkong|台|tw|taiwan|日|jp|japan|新|sg|singapore|美|us|unitedstates)).*"
148

149
  - name: 全部节点
150
    type: select
151
    include-all: true
152

153
  - name: 自动选择
154
    type: url-test
155
    include-all: true
156
    tolerance: 10
157

158
rules:
159
  - GEOIP,lan,直连,no-resolve
160
  - GEOSITE,twitter,Twitter
161
  - GEOSITE,youtube,YouTube
162
  - GEOSITE,category-ai-!cn,海外AI
163
  - GEOSITE,github,Github
164
  - GEOSITE,google,Google
165
  - GEOSITE,telegram,Telegram
166
  - GEOSITE,netflix,NETFLIX
167
  - GEOSITE,bilibili,哔哩哔哩
168
  - GEOSITE,bahamut,巴哈姆特
169
  - GEOSITE,spotify,Spotify
170
  - GEOSITE,CN,国内
171
  - GEOSITE,geolocation-!cn,其他
172

173
  - GEOIP,CN,国内
174
  - MATCH,其他

第二步：构建 Docker Compose#

我们将同时部署 Mihomo 核心 和 Metacubexd (WebUI)。

在 mihomo 文件夹同级或任意位置，创建 docker-compose.yml。

🌟 关键配置说明 (TUN 模式支持)： 为了支持 TUN 模式（虚拟网卡），容器必须拥有网络管理权限。我们在配置中加入了 cap_add: [NET_ADMIN] 和 devices: [/dev/net/tun]，这是实现透明代理的关键。

1
version: '3'
2

3
services:
4
  # Web 管理面板
5
  metacubexd:
6
    container_name: metacubexd
7
    #image: ghcr.io/metacubex/metacubexd
8
    # 国内加速源
9
    image: ghcr.1ms.run/metacubex/metacubexd
10
    restart: always
11
    ports:
12
      - '9097:80' # WebUI 访问端口
13

14
  # Mihomo 核心
15
  mihomo:
16
    container_name: mihomo
17
    #image: docker.io/metacubex/mihomo:latest
18
    # 国内加速源
19
    image: docker.1ms.run/metacubex/mihomo:latest
20
    restart: always
21
    pid: host
22
    ipc: host
23
    network_mode: host # 推荐使用 Host 模式，性能最好且便于处理 IPv6
24

25
    # --- TUN 模式核心配置 ---
26
    cap_add:
27
      - NET_ADMIN      # 赋予网络管理权限
28
    devices:
29
      - /dev/net/tun:/dev/net/tun # 映射宿主机的 TUN 设备
30
    volumes:
31
      # ⚠️ 注意：冒号左边请修改为你 config.yaml 所在的实际绝对路径
32
      - ./mihomo:/root/.config/mihomo

第三步：启动与初始化#

1. 启动容器#

在 docker-compose.yml 所在目录执行：

1
sudo docker-compose up -d

如果是飞牛OS等图形化系统，请直接在 Docker 管理器中”使用现有 Compose 文件”创建项目即可。

2. 解决规则文件下载失败 (Fatal Error)#

初次启动时，查看日志可能会发现如下报错： level=fatal msg="Parse config error... can't download MMDB: context deadline exceeded"

这是因为网络环境导致容器无法自动下载 GeoIP/GeoSite 数据库。

解决方法：

前往 MetaCubeX/meta-rules-dat 下载以下文件：
- geoip.dat
- geosite.dat
- country-lite.mmdb
- GeoLite2-ASN.mmdb
将这4个文件手动上传到宿主机的 mihomo 文件夹（与 config.yaml 同级）。
重启容器：sudo docker-compose restart mihomo

第四步：配置 WebUI#

打开浏览器访问：http://设备IP:9097。
进入设置页面，添加后端：
- API Base URL: http://设备IP:9090
- Secret: 在 config 第 6 行设置的 API 访问密钥
点击添加，连接成功后即可看到流量仪表盘和节点选择界面。

进阶：关于 TUN 模式与透明代理#

TUN 模式允许 Mihomo 创建一个虚拟网卡，接管设备上所有层级的流量（包括不走系统代理的终端命令、游戏等）。

为什么需要特殊权限？#

在 Docker 中，默认容器是没有权限创建网络设备的。要启用 TUN 模式，必须在启动参数中显式声明：

--cap-add=NET_ADMIN：允许容器修改网络堆栈。
--device=/dev/net/tun：允许容器访问 Linux 的 TUN 字符设备。

在本文提供的 docker-compose.yml 中，我们已经默认添加了这两项配置。

如何启用？#

确保 Docker 配置已包含上述权限参数。
在 WebUI 的设置页面中勾选 TUN 模式。
或者在 config.yaml 中将 tun: enable 设置为 true 并重启容器。

此时，配合路由表的设置，Mihomo 即可变身为一个网关，实现透明代理。

Q&A 常见问题#

Q1: “Failed to fetch” 无法连接后端？

A: 检查 WebUI 中填写的后端地址端口是否为 9090（不是 9097），并确保 config.yaml 中 external-controller 监听的是 0.0.0.0:9090。

Q2: 为什么不使用在线版的 WebUI (如 yacd)？

A: 在线版面板（通常是 HTTPS）因浏览器安全策略（混合内容拦截），往往无法连接到你本地的 HTTP 后端（Mihomo）。使用 Docker 自建本地版 WebUI 最稳定。

Q3: 如何在其他设备上使用这个代理？

A: 在其他设备（手机/电脑）的 Wi-Fi 代理设置中，填入 IP: 宿主机IP，端口: 7890。