Docker 一键部署 Clash Meta (mihomo) + metacubexd 面板教程（2026 年最新版）

目标：使用最新 MetaCubeX/mihomo 内核 + 官方 metacubexd Web 面板，实现稳定、高性能的代理服务
适用环境：Linux 服务器 / NAS（推荐 Ubuntu/Debian），已安装 Docker + Docker Compose
核心特点：

使用 network_mode: host（TUN/透明代理最稳）
容器别名统一为 clash（核心） + dashboard（面板），操作更友好
提前处理 Country.mmdb 避免经典报错

1. 准备工作

安装 Docker & Docker Compose（如果未安装，一键执行）

# Ubuntu/Debian 推荐方式（2026 年最新）
curl -fsSL https://get.docker.com | sudo sh
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
sudo usermod -aG docker $USER   # 加当前用户到 docker 组，重启终端生效

创建项目目录
```
mkdir -p ~/mihomo && cd ~/mihomo
```

2. 提前下载 GeoIP 数据库（必须！避免 not a directory 错误）

mihomo 需要 Country.mmdb（文件，不是文件夹）

mkdir -p config
cd config

# 强烈推荐：轻量版 country-lite.mmdb（体积小 ≈1-2MB，只含国家信息，规则足够用）
curl -L https://github.com/MetaCubeX/meta-rules-dat/releases/latest/download/country-lite.mmdb \
     -o Country.mmdb

# 如果需要完整版（包含城市/ASN 等更多信息，文件较大 ≈10MB+）
# curl -L https://github.com/MetaCubeX/meta-rules-dat/releases/latest/download/country.mmdb \
#      -o Country.mmdb

关键：启动前这个路径必须存在文件，否则 Docker 会自动创建成目录导致启动失败。

3. docker-compose.yml（完整配置，已加别名）

在 ~/mihomo 目录下创建文件 docker-compose.yml：

version: '3.8'

services:
  clash:                     # 服务名（内部引用用）
    container_name: clash    # 对外别名！以后 docker logs clash / docker exec -it clash sh
    image: metacubex/mihomo:Alpha   # Alpha = 最新功能版；如需更稳可用 :latest 或具体版本如 :v1.19.18
    restart: unless-stopped
    network_mode: host              # 必须 host（TUN、全局路由最稳定）
    pid: host
    ipc: host
    cap_add:
      - ALL
    volumes:
      - ./config:/root/.config/mihomo   # 所有配置、订阅、数据库都在这里
      - /dev/net/tun:/dev/net/tun       # TUN 模式必需
      - /etc/localtime:/etc/localtime:ro  # 可选：同步主机时间

  dashboard:                 # metacubexd 面板
    container_name: dashboard  # 对外别名！docker logs dashboard
    image: ghcr.io/metacubex/metacubexd:latest
    restart: unless-stopped
    network_mode: host              # 推荐 host，端口冲突少
    # 如果想用自定义端口，可改成 bridge 模式 + ports（示例）：
    # network_mode: bridge
    # ports:
    #   - "12345:80"                 # 浏览器访问 http://IP:12345

别名说明：

核心容器统一叫 clash（更符合大家习惯）

面板叫 dashboard（清晰好记）

操作示例：docker compose restart clash、docker compose logs -f clash

4. 准备 mihomo 主配置文件 config.yaml

在 ./config 目录下创建 config.yaml（最小可用模板，替换订阅链接）：

# 基本端口与访问
mixed-port: 7890
allow-lan: true
external-controller: 0.0.0.0:9090   # 面板必须用 0.0.0.0:9090 连接
secret: ""                          # 建议设置一个密码，增强安全

# 模式与日志
mode: rule
log-level: info

# GeoIP 设置（已提前下载文件，所以关闭自动下载或保留）
geodata-mode: false
geo-auto-update: true
geo-update-interval: 24

# 可选：如果网络通，可开启自动更新（但已手动下载可关闭）
# geox-url:
#   mmdb: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/country-lite.mmdb"

# 订阅示例（可加多个）
proxy-providers:
  my-sub: #这个名称是代理别名
    type: http
    url: "https://你的机场订阅链接"
    path: ./subscriptions/my-sub.yaml
    interval: 86400
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300

# 基础分组（面板里可自由编辑）
proxy-groups:
  - name: "自动选择"
    type: url-test
    include-all: true
    url: "http://www.gstatic.com/generate_204"
    interval: 300

rules:
  - MATCH,自动选择

更多高级配置参考：https://wiki.metacubex.one/

5. 启动与常用命令

# 首次启动（自动拉镜像）
docker compose up -d

# 查看核心日志（**强烈建议第一次看！**）
docker compose logs -f clash

# 查看面板日志
docker compose logs dashboard

# 重启核心
docker compose restart clash

# 更新镜像并重启
docker compose pull && docker compose up -d

# 停止+删除容器（数据保存在 config 文件夹）
docker compose down

6. 访问方式

Web 面板（metacubexd）：
http:// 你的服务器 IP （host 模式默认 80 端口）
或 http:// 你的服务器 IP:12345 （如果用了 ports 映射）
连接后端（首次打开面板时）：
Endpoint URL：http://127.0.0.1:9090 （或 http:// 服务器 IP:9090）
Secret：config.yaml 中设置的密码（无则留空）
代理端口：HTTP/SOCKS5 混合端口 7890（局域网设备可用）