Docker容器里怎么部署Clash？

选择合适镜像：metacubex/mihomo是首选

官方镜像与社区分支的选择

在Docker中部署Clash时，最推荐的镜像是metacubex/mihomo，这是Clash Meta（mihomo）核心的官方容器镜像，由MetaCubeX团队维护并持续更新。该镜像基于Alpine构建，体积轻量且包含了运行所需的所有依赖。相比使用原版Clash核心的镜像，mihomo镜像在协议支持范围上更全面，支持VLESS、Hysteria2、TUIC等新一代协议，同时社区活跃度更高，遇到问题更容易获得帮助。

镜像拉取加速的技巧

由于Docker Hub在国内网络环境下访问可能不稳定，直接docker pull metacubex/mihomo时可能出现超时或速度极慢的情况。可以通过配置Docker镜像加速器来解决，例如使用阿里云容器镜像服务提供的加速地址，在/etc/docker/daemon.json中添加"registry-mirrors": ["https://<你的加速地址>.mirror.aliyuncs.com"]，然后重启Docker服务使配置生效。如果服务器完全无法访问Docker Hub，也可以在有网络的环境下载镜像后导出为tar文件，再上传到目标服务器通过docker load导入。

其他辅助镜像的用途

除了mihomo核心镜像，还可以搭配Web管理面板镜像使用。mrxianyu/metacubexd-ui是一个专门用于提供Clash Web UI的容器镜像，与mihomo配合使用可以实现浏览器端的可视化节点管理和流量监控。如果不希望额外运行一个UI容器，也可以将面板的静态文件挂载到mihomo容器的external-ui目录中，由mihomo自身托管UI页面。两种方式在管理体验上基本相同，区别在于独立UI容器的资源开销稍大但更新更方便。

创建配置目录与准备配置文件

在宿主机上创建工作目录

在启动容器之前，需要先在宿主机上创建一个目录用于存放Clash的配置文件。推荐在用户目录下创建~/mihomo文件夹，或者放在/etc/mihomo等系统目录中。目录创建完成后，将代理服务商提供的Clash订阅文件或手动编写的config.yaml文件放入该目录。需要特别注意的是，文件必须命名为config.yaml，因为容器内的mihomo进程默认从/root/.config/mihomo/config.yaml读取配置，挂载时容器内的路径应保持一致。

从订阅链接获取配置文件

如果已经有代理服务商提供的Clash订阅链接，最简单的方式是用浏览器访问该链接，将返回的YAML内容保存为config.yaml文件。部分订阅返回的是Base64编码格式，需要先解码再保存。如果订阅链接本身需要代理才能访问（常见于国内服务器环境），可以先在本地电脑上通过Clash客户端下载配置文件，再通过SCP或文件管理工具上传到服务器的工作目录中。直接使用订阅链接的优势在于节点列表和规则会自动保持同步，但初次下载时可能遇到网络问题。

配置文件中的关键参数设置

在config.yaml中，有几个与Docker部署密切相关的参数需要正确配置。allow-lan: true必须设置为true，因为容器需要监听宿主机的网络接口而非仅限容器内部。bind-address: '*'让代理服务监听所有网卡接口。如果打算开启TUN模式接管宿主机所有流量，还需要添加tun段落并设置enable: true，但启动前务必在rules中添加SSH端口直连规则（如- DST-PORT,22,DIRECT），否则容器启动后可能导致SSH连接断开。

编写docker-compose编排文件

基础配置结构详解

使用Docker Compose部署mihomo是最推荐的方式，便于管理容器参数和后续更新。在~/mihomo目录中创建docker-compose.yml文件，写入服务定义。基础配置包括指定镜像metacubex/mihomo:latest、容器名称mihomo、重启策略restart: always，以及通过volumes将宿主机上的./config.yaml挂载到容器内的/root/.config/mihomo/config.yaml。配置完成后在目录下执行docker-compose up -d即可启动容器。

网络模式的选择：host还是bridge

network_mode是Docker部署中需要重点考虑的参数。选择network_mode: "host"时，容器直接使用宿主机的网络栈，代理端口（如7890）会直接暴露在宿主机上，内网其他设备可以直接通过宿主机IP加端口访问代理服务。选择network_mode: bridge（默认模式）时，容器拥有独立的网络命名空间，需要通过ports映射将容器端口暴露到宿主机，例如- "7890:7890"。如果计划开启TUN模式接管宿主机所有流量，必须使用host模式；如果仅提供代理端口供其他容器或设备使用，两种模式皆可，bridge模式在隔离性上稍好。

开启TUN模式所需的额外权限

如果配置文件中开启了TUN模式，容器需要获得额外的系统权限才能操作虚拟网卡。在docker-compose中需要添加cap_add字段，包含NET_ADMIN和SYS_MODULE两项能力，同时设置privileged: true以获取完整的设备访问权限。此外还需要在容器的设备列表中挂载/dev/net/tun，在docker-compose中添加devices: - /dev/net/tun:/dev/net/tun。这些权限是TUN模式能够正常接管流量的必要条件，缺少任何一个都会导致TUN初始化失败。

启动容器并处理常见错误

首次启动与日志监控

运行docker-compose up -d启动容器后，建议立即通过docker logs mihomo查看启动日志，确认容器是否正常运行。如果日志中出现Parse config error或can't download MMDB等错误，通常是因为配置文件中引用了需要下载的GeoIP数据库但网络不通导致。解决方法是手动下载geoip.dat和geosite.dat文件，放置在配置文件同目录下，并在配置文件中将数据库路径指向本地文件而非远程URL。如果日志显示level=fatal且错误信息明确指向某个配置字段，需要检查YAML格式是否缩进正确。

配置文件解析失败的处理

配置文件解析失败是Docker部署中最常见的问题之一，通常表现为容器启动后立即退出或处于不断重启的状态。可以通过在宿主机上使用mihomo -t -d /path/to/config命令测试配置文件的语法有效性（前提是宿主机已安装mihomo二进制）。如果宿主机没有mihomo，也可以将config.yaml内容粘贴到在线YAML验证工具中检查缩进和语法。常见的错误包括port和mixed-port字段重复定义、代理节点名称中包含特殊字符（如Emoji）导致解析异常、rules部分缺少MATCH兜底规则等。

容器启动后SSH断连的紧急修复

如果在配置文件中开启了TUN模式而未正确设置SSH直连规则，容器启动后可能导致SSH会话立即断开且无法重新连接。这种情境下的修复方法是通过服务器控制台（如云服务商的VNC或IPMI）登录，停止mihomo容器，修改配置文件添加- DST-PORT,22,DIRECT规则，然后再重新启动容器。如果无法通过控制台登录，可能需要重启服务器并在启动过程中暂停容器自动启动，或者在docker-compose中临时将restart: always改为restart: no后重启服务器。

配置Web管理面板：可视化运维

部署Metacubexd面板

Clash Meta生态提供了Metacubexd这一现代化的Web管理面板，可以通过两种方式部署。一种是在docker-compose中单独添加UI服务容器，与mihomo并行运行，通过nginx反向代理或直接访问UI容器的端口进行管理。另一种方式是下载Metacubexd的静态文件压缩包，解压后挂载到mihomo容器的/root/.config/mihomo/ui目录中，然后在config.yaml中设置external-ui: ui，mihomo会自动托管这些静态文件。

通过浏览器连接管理端

面板部署完成后，在浏览器中访问http://<宿主机IP>:9090/ui即可进入管理界面。如果使用独立UI容器，需要根据UI容器的端口映射访问对应的地址。首次进入时，面板会要求配置API连接信息——API Base URL填写http://<宿主机IP>:9090，Secret字段填入config.yaml中secret参数设置的密钥。连接成功后可以在Web界面中查看节点列表、切换代理模式、查看实时流量和连接状态，无需登录服务器即可完成日常运维操作。

面板访问的安全配置

将Clash的管理端口暴露在公网存在安全风险。建议在配置文件中为external-controller设置强密码作为Secret密钥，同时通过防火墙或云服务商安全组限制9090端口的访问来源IP，仅允许管理员IP连接。如果服务器位于内网或没有公网暴露需求，也可以将external-controller绑定到127.0.0.1:9090而非0.0.0.0:9090，仅允许本机访问面板页面。

容器间代理互通：让其他容器走Clash

配置其他容器的环境变量

在同一台宿主机上运行的其他Docker容器，可以通过设置环境变量来使用mihomo代理。在启动这些容器时添加-e HTTP_PROXY=http://<宿主机IP>:7890和-e HTTPS_PROXY=http://<宿主机IP>:7890，容器内支持代理的应用就会自动走Clash通道。如果mihomo容器使用了network_mode: "host"，宿主机IP可以直接使用127.0.0.1或宿主机在局域网中的实际IP；如果使用了bridge模式且做了端口映射，同样使用宿主机IP加映射端口即可。

bridge模式下容器访问宿主机的特殊处理

当mihomo运行在默认的bridge网络模式时，其他容器通过127.0.0.1无法访问到宿主机的服务。此时需要使用宿主机的实际局域网IP（如192.168.1.100），或者在docker-compose中使用特殊的host.docker.internal域名（Linux系统需要在docker run命令中添加--add-host host.docker.internal:host-gateway才能支持）。更简单的方式是让mihomo容器使用host网络模式，这样其他容器可以直接通过127.0.0.1访问代理服务。

TUN模式与容器代理的协同工作

如果mihomo容器开启了TUN模式并使用了network_mode: "host"，宿主机上所有进程的网络流量都会被mihomo接管，包括其他Docker容器内的网络请求。这种情况下，其他容器不需要单独配置代理环境变量，因为它们发出的请求在宿主机网络层面就已经被TUN模式捕获并转发。TUN模式在全局代理场景下最省事，但需要注意规则配置的准确性，避免误代理了内网通信或SSH流量。

常见问题FAQ

Docker部署Clash需要宿主机具备什么条件？

宿主机需要安装Docker和Docker Compose，Linux内核版本建议在4.0以上以支持TUN模式所需的模块。如果计划开启TUN模式，还需要确保/dev/net/tun设备存在且内核已加载tun模块。

mihomo容器启动后立即退出怎么排查？

先用docker logs mihomo查看错误日志。常见原因有config.yaml格式错误、订阅地址无法访问导致解析失败、GeoIP数据库下载超时等。可以在宿主机上用mihomo -t -d /path/to/config测试配置有效性。

如何让容器内其他服务通过mihomo代理？

在启动其他容器时添加环境变量HTTP_PROXY=http://:7890和HTTPS_PROXY=...即可。如果mihomo容器使用host网络模式，代理地址填http://127.0.0.1:7890。部分应用可能不读取环境变量，需要单独配置。

Docker Hub拉取mihomo镜像失败怎么解决？

配置Docker镜像加速器（如阿里云、中科大提供的加速地址），编辑/etc/docker/daemon.json添加registry-mirrors配置后重启Docker。也可以从其他可访问Docker Hub的机器导出镜像再导入。