Docker部署 Clash 代理完整指南

一篇文章讲清 mihomo（原 Clash.Meta）的容器化部署全流程：Docker Compose 编排、Web 控制面板、多订阅管理与日常运维。

一、项目介绍

1.1 什么是 mihomo

mihomo 是 Clash 内核的社区继任项目（原名 Clash.Meta）。2023 年 Clash 官方仓库停止公开维护后，mihomo 成为事实上的标准继任者，持续更新并支持更多现代协议：

协议覆盖：Shadowsocks、VMess、Trojan、Hysteria2、TUIC、VLESS、WireGuard 等；
规则分流：基于域名、GeoIP、规则集（rule-set）的精细分流；
订阅管理：支持 proxy-providers 定时自动更新订阅，无需手工替换节点；
RESTful API：完整的外部控制接口，生态内有丰富的 Web 面板。

github地址：MetaCubeX/mihomo
官网地址：虚空终端 Docs

1.2 为什么使用 Docker 部署

维度	Docker 部署	传统二进制部署
环境隔离	完全隔离，不污染宿主机	依赖宿主机环境
升级回滚	换镜像标签即可	需手动替换文件
配置管理	数据卷挂载，改配置即重启生效	配置文件散落各处
多实例	Compose 复制服务即可	端口/路径易冲突
迁移	整个目录打包带走	需重新安装配置

1.3 方案架构

本文采用 内核 + 面板分离 的双容器架构：

┌─────────────────────────────────────────────┐
│                Docker Compose                │
│                                              │
│  ┌──────────────┐      ┌──────────────────┐  │
│  │   mihomo     │      │   metacubexd     │  │
│  │  （代理内核） │◄─────│  （Web 面板）     │  │
│  │  7890 代理   │ API  │  9097 Web 访问   │  │
│  │  9090 控制   │      │  纯静态、无状态   │  │
│  └──────┬───────┘      └────────▲─────────┘  │
│         │                       │            │
└─────────┼───────────────────────┼────────────┘
          │              浏览器直连 API
     ./data 卷               │
  (config.yaml 等)      用户浏览器

mihomo：代理核心，监听 7890（HTTP/SOCKS5 混合代理）与 9090（外部控制器 API）；
metacubexd：MetaCubeXD 面板，纯静态前端，由浏览器直连内核 API，与内核解耦，可独立升级，甚至可同时管理多个 mihomo 实例。

二、详细部署教程（Linux / Docker 环境）

2.1 前置条件

已安装 Docker Compose 并启用；
docker compose version 可正常输出版本号；

2.2 目录结构

mihomo-deploy/
├── docker-compose.yml    # 编排文件
└── data/                 # 数据卷：配置、Geo 数据库、缓存
    └── config.yaml       # 主配置文件

2.3 编写 docker-compose.yml

services:
  mihomo:
    # mihomo 官方镜像；生产环境建议锁定版本标签，如 metacubex/mihomo:v1.19.0
    image: metacubex/mihomo:latest

    # 自定义容器名称，便于 docker 命令直接引用
    container_name: mihomo

    # 重启策略：
    #   unless-stopped —— 除非手动 stop，否则异常退出或宿主机重启后自动拉起（生产推荐）
    #   可选值：no / always / on-failure[:次数] / unless-stopped
    restart: unless-stopped

    # 容器时区：Asia/Shanghai（东八区），保证日志时间戳与本地一致
    environment:
      - TZ=Asia/Shanghai

    ports:
      # 7890：HTTP/SOCKS5 混合代理端口（与 config.yaml 的 mixed-port 对应）
      - "7890:7890"

      # 9090：外部控制器端口（RESTful API），面板经此与内核通信
      #       ⚠️ 仅本机调试 API 时才需要保留；仅本机使用可改为
      #       "127.0.0.1:9090:9090" 限制外部访问
      - "9090:9090"

      # DNS 端口（可选）：config.yaml 启用 dns.listen 时才需暴露（TCP+UDP）
      # - "1053:1053/tcp"
      # - "1053:1053/udp"

    volumes:
      # 本地 ./data → 容器内 mihomo 配置目录
      # ⚠️ 注意：mihomo 默认配置目录为 /root/.config/mihomo
      #          （与旧版 Clash 的 /root/.config/clash 不同，不可写错）
      # 持久化内容：config.yaml、Geo 数据库（Country.mmdb / geoip.dat /
      # geosite.dat）、cache.db、订阅与规则提供者缓存（providers/）
      - ./data:/root/.config/mihomo

    # 日志驱动限制：防止日志无限增长占满磁盘
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

关键参数说明：

参数	作用	可选值 / 注意点
`restart`	重启策略	`no` / `always` / `on-failure[:次数]` / `unless-stopped`（生产推荐）
`TZ`	容器时区	`Asia/Shanghai`（东八区）
`7890` 映射	混合代理端口	修改时需同步调整 config.yaml 的 `mixed-port`
`9090` 映射	外部控制器 API	仅本机使用改 `127.0.0.1:9090:9090`
`volumes`	配置持久化	⚠️ 容器内路径必须是 `/root/.config/mihomo`，与旧版 Clash 不同
`logging`	日志轮转	防止日志占满磁盘

2.4 编写 config.yaml

# =============================================================================
# Mihomo 主配置文件（示例，部署前请按需修改）
# 文档：https://wiki.metacubex.one/config/
# =============================================================================

# 混合代理端口：HTTP + SOCKS5 同端口监听（与 compose 中 7890 映射对应）
mixed-port: 7890

# 外部控制器监听地址：
#   0.0.0.0:9090 —— 允许宿主机/局域网访问（必须配合 secret）
#   127.0.0.1:9090 —— 仅容器内可访问（面板将无法连接，慎用）
external-controller: "0.0.0.0:9090"

# 外部控制接口访问密钥（⚠️ 生产环境必须设置强密码，勿提交公开仓库）
# 面板登录及所有 RESTful API 请求均需携带该密钥；为空则无任何鉴权
secret: "YOUR_SECRET"

# Web 控制面板（MetaCubeXD）：
#   external-ui 指向数据卷内 ui 目录；
#   external-ui-url 指定面板压缩包地址，首次启动自动下载解压（需可访问 GitHub）
external-ui: ui
external-ui-url: "https://github.com/MetaCubeX/metacubexd/archive/gh-pages.zip"
# 面板访问地址：http://宿主机IP:9090/ui

# 运行模式：rule（规则分流，推荐）/ global（全局代理）/ direct（全部直连）
mode: rule

# 日志级别：silent / error / warning / info / debug
log-level: info

# 允许局域网其他设备使用本代理
allow-lan: true

# mihomo 特性：统一延迟测试与数据库自动更新
unified-delay: true
tcp-concurrent: true

# Geo 数据自动更新（可选）
geo-update-interval: 168   # 单位：小时
geox-url:
  geoip: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geoip.dat"
  geosite: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat"
  mmdb: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/country.mmdb"

# 内置 DNS（可选）：启用后配合 compose 中 1053 端口映射可作为局域网 DNS
# dns:
#   enable: true
#   listen: "0.0.0.0:1053"
#   default-nameserver: [223.5.5.5, 119.29.29.29]
#   nameserver: [https://dns.alidns.com/dns-query, https://doh.pub/dns-query]
#   fallback: [https://1.1.1.1/dns-query]

# =============================================================================
# 订阅与规则提供者（mihomo 推荐用法：proxy-providers + rule-providers，
# 订阅链接更新后内核可定时自动拉取，无需手工替换节点列表）
# =============================================================================

# 订阅节点提供者（将下方 URL 替换为你的订阅链接）
# 支持同时配置多个订阅：每个订阅是一个独立键名（如 sub-a / sub-b），
# 各订阅独立定时更新、独立健康检查，互不影响
proxy-providers:
#   # ---------- 订阅 A ----------
  sub-a:
    type: http
    url: "https://example.com/"
    interval: 7200                # 自动更新间隔（秒），0 = 仅启动时拉取
    path: ./providers/sub-a.yaml   # 本地缓存路径（每个订阅必须用不同文件名）
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300
#     # 可选：按节点名过滤（正则），仅保留匹配节点
#     # filter: "香港|日本|新加坡"
#     # 可选：按节点名排除（正则）
#     # exclude-filter: "到期|剩余流量|官网"
#     # 可选：HTTP 请求头（部分机场要求特定 UA 才返回节点）
#     # header:
#     #   User-Agent: ["clash.meta"]
#
#   # ---------- 订阅 B（复制上面的块并修改键名、URL、path 即可） ----------
  sub-b:
    type: http
    url: "https://example.com/"
    interval: 86400
    path: ./providers/sub-b.yaml
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300
#     # 可选：按节点名过滤（正则），仅保留匹配节点
#     # filter: "香港|日本|新加坡"
#     # 可选：按节点名排除（正则）
#     # exclude-filter: "到期|剩余流量|官网"
#     # 可选：HTTP 请求头（部分机场要求特定 UA 才返回节点）
#     # header:
#     #   User-Agent: ["clash.meta"]

# 代理组
proxy-groups:
  # 主选择组：手动从所有订阅节点中挑选
  - name: "PROXY"
    type: select              # 可选：select / url-test / fallback / load-balance / relay
    proxies:
      - DIRECT                # 无订阅时直连兜底
      # - AUTO                # 启用自动测速组后可在此引用
    use:                      # 启用 proxy-providers 后取消注释，引入全部订阅节点
      - sub-a                 # 多个订阅在此逐个列出，节点会合并进本组
      - sub-b

  # 自动测速组（可选）：从所有订阅节点中自动选择延迟最低的
  # - name: "AUTO"
  #   type: url-test
  #   url: "https://www.gstatic.com/generate_204"
  #   interval: 300           # 测速间隔（秒）
  #   tolerance: 50           # 延迟差在 50ms 内不切换，避免频繁跳动
  #   use:
  #     - sub-a
  #     - sub-b

# 规则提供者（mihomo 社区维护的分流规则集，可选）
# rule-providers:
#   geosite-cn:
#     type: http
#     behavior: domain
#     url: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite-cn.yaml"
#     path: ./providers/geosite-cn.yaml
#     interval: 86400

# 分流规则（自上而下匹配）
rules:
  # - RULE-SET,geosite-cn,DIRECT   # 配合 rule-providers 使用
  - GEOIP,CN,DIRECT,no-resolve     # 中国大陆 IP 直连
  - MATCH,PROXY                     # 其余流量走 PROXY 代理组

2.5 将编写好的`config.yaml`文件放到`./data/` 路径下

2.6 安装 MetaCubeXD UI 面板

GitHub

蓝奏云网盘 · 提取码: egej

将解压后的文件夹名字改为ui放到./data/ 路径下

三、Web 面板使用指南

3.1 访问与登录

浏览器打开 http://宿主机IP:9090/ui（本机部署为 http://127.0.0.1:9090/ui）；
首次进入填写连接信息：
- 后端地址：http://宿主机IP:9090（注意：是内核 API 地址，不含 /ui）
- 密钥（Secret）：config.yaml 中 YOUR_SECRET 的值
连接成功后面板会记住该后端，之后打开直接进入。

3.2 核心功能分区

页面	作用
概览	实时上下行速率、活动连接数、内存占用、运行模式
代理	查看代理组与节点；点击节点即切换；闪电图标做延迟测速
连接	查看每条连接的来源、目标、命中规则、走的节点；排查"某网站走了哪条线"最直接
规则	查看当前生效的分流规则列表
日志	实时内核日志，排障时可在设置中切到 debug 级别
设置	切换运行模式（rule/global/direct）、主题、语言、内核版本

3.3 常用操作

切换节点：代理页 → 点击代理组 → 双击目标节点名；
切换模式：设置页 → Mode → rule（日常推荐）/ global（临时全走代理）/ direct（全直连，用于对照排查）；
测速选节点：代理页 → 代理组右上闪电图标 → 选延迟最低且非超时的节点；
排查分流问题：访问目标网站 → 连接页找到对应连接 → 查看"规则链"列确认命中的规则与节点。

3.4 命令行调用 API（可选）

面板本质是对 RESTful API 的可视化封装，也可直接调用：

# 查看所有代理及延迟
curl -H "Authorization: Bearer 你的secret" http://127.0.0.1:9090/proxies

# 切换 PROXY 组到指定节点
curl -X PUT -H "Authorization: Bearer 你的secret" \
  -d '{"name":"节点名"}' http://127.0.0.1:9090/proxies/PROXY

# 对某节点测速
curl -H "Authorization: Bearer 你的secret" \
  "http://127.0.0.1:9090/proxies/节点名/delay?url=https://www.gstatic.com/generate_204&timeout=5000"

3.5 为什么面板不需要挂载数据卷

这是一个常见疑问。答案是：面板容器完全无状态。

MetaCubeXD 镜像内部只是 Nginx + 静态文件（HTML/JS/CSS），不存储任何服务端数据；
代理数据由浏览器通过 API 直接读写 mihomo 内核，状态在内核侧（已挂载 ./data 卷）；
面板自身设置（后端地址、secret、主题）保存在浏览器 localStorage 中。

因此容器删除重建不会丢失任何配置。副作用是：换浏览器或清除浏览器数据后需重新填写后端地址和 secret，属正常现象。

仅当需要深度定制（如自定义 Nginx 配置、HTTPS 证书）时才需要挂卷，常规场景不需要。

四、多订阅配置详解

mihomo 的 proxy-providers 支持任意数量的订阅并存，是管理多机场订阅的标准做法。

4.1 配置方法

第一步：每个订阅在 proxy-providers 下声明一个独立键名：

proxy-providers:
  sub-a:                        # 键名自定义
    type: http
    url: "https://订阅链接A"
    interval: 86400             # 每 24 小时自动更新
    path: ./providers/sub-a.yaml
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300

  sub-b:                        # 复制整块，改三处：键名、url、path
    type: http
    url: "https://订阅链接B"
    interval: 86400
    path: ./providers/sub-b.yaml
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300

第二步：在代理组的 use 中逐个列出，节点自动合并：

proxy-groups:
  - name: "PROXY"
    type: select
    use:
      - sub-a
      - sub-b

4.2 三个关键注意点

path 必须互不重复——这是订阅的本地缓存文件，同路径会互相覆盖；
扩展方式：加一个订阅 = 复制一个 provider 块 + use 列表加一行；
生效方式：docker restart mihomo，或在面板设置页重载配置。

4.3 进阶可选项

选项	作用	示例
`filter`	按节点名正则保留	`filter: "香港
`exclude-filter`	按节点名正则排除	`exclude-filter: "到期
`header`	自定义请求 UA	部分机场校验 UA 才返回节点
`interval: 0`	关闭定时更新	仅在容器启动时拉取一次

配合 url-test 类型的 AUTO 组（见 2.4 节配置），可实现跨订阅的自动选优：tolerance: 50 表示延迟差 50ms 内不切换，避免节点频繁跳动。

五、日常运维命令

docker compose up -d                              # 启动（后台运行）
docker compose down                               # 停止并移除容器（数据保留在 ./data）
docker compose ps                                 # 查看运行状态
docker compose logs -f                            # 实时查看全部日志（Ctrl+C 退出，不影响容器）
docker compose logs -f mihomo                     # 只看内核日志
docker restart mihomo                             # 修改 config.yaml 后重启生效

# 更新镜像（内核与面板通用）
docker compose pull                               # 拉取最新镜像
docker compose up -d --force-recreate             # 重建容器完成更新

六、安全加固清单

必须设置强 secret：secret 为空时控制接口无鉴权，任何人都能读取节点信息并切换代理；
限制端口暴露：仅本机使用时，将映射改为 127.0.0.1:9090:9090 与 127.0.0.1:9090:80，彻底隔绝外部访问；
勿将 9090 暴露公网：如需远程管理，用 SSH 隧道或反向代理 + HTTPS + 访问控制；
配置文件保密：config.yaml 含 secret 与订阅链接，不要提交到公开 Git 仓库；
生产环境锁定镜像版本：metacubex/mihomo:v1.19.x 而非 latest，升级前先看 release notes。

七、常见问题排查

问题	排查方向
面板页面空白/一直加载	确认 metacubexd ui正常运行；检查浏览器能否访问 9090 端口
面板提示连接失败	后端地址是否为内核 API 地址（`http://IP:9090`）；secret 是否填写正确；9090 端口映射是否存在
代理无流量	`docker logs mihomo` 查看内核报错；确认 config.yaml 语法正确（YAML 对缩进敏感）
订阅拉取失败	容器内需能访问订阅链接；部分机场需配置 `header` 自定义 UA
改配置不生效	需 `docker restart mihomo` 或在面板重载；确认修改的是挂载卷内的 `./data/config.yaml`
容器内时间与本地差 8 小时	确认 `TZ=Asia/Shanghai` 已设置并重建容器

八、总结

本文的部署方案要点回顾：

架构：mihomo 内核 + MetaCubeXD 面板，支持多后端管理；
配置：Compose v3.8 规范，unless-stopped 重启策略，Asia/Shanghai 时区，日志轮转；
持久化：仅需为内核挂载 ./data 卷，面板无状态无需挂卷；
订阅：proxy-providers 多订阅并存，独立更新、独立健康检查，配合 url-test 自动选优；
安全：强 secret + 端口绑定 localhost，是本地/局域网场景的最低安全基线。