Docker Compose部署Uptime Kuma与Mieru代理监控一体化方案-平芜编程栈

1. 项目概述与核心价值

最近在折腾一些需要跨网络环境访问的服务时，发现了一个挺有意思的项目，叫Alice39s/kuma-mieru。乍一看这个名字，可能有点摸不着头脑，但如果你对网络代理、隧道工具或者容器化部署有需求，那这个项目很可能就是你一直在找的“瑞士军刀”。简单来说，kuma-mieru是一个将Uptime Kuma监控面板与Mieru代理服务深度集成的容器化解决方案。它的核心价值在于，让你在一个统一的、易于管理的容器里，同时获得一个功能强大的服务可用性监控工具和一个高性能的网络代理服务。

对于个人开发者、小型团队或者需要自建服务监控和网络访问方案的用户来说，这种“二合一”的打包方式极具吸引力。想象一下，你不再需要分别部署和维护两个独立的容器或服务，配置文件散落在各处，更新升级也麻烦。kuma-mieru通过一个精心编排的Docker Compose配置，把这两件事完美地结合在了一起。你只需要docker-compose up -d一下，一个既能监控你所有服务（网站、API、数据库端口等）健康状态，又能提供稳定网络代理能力的服务就启动好了。这大大降低了运维复杂度和入门门槛，尤其适合那些希望快速搭建一套私有、可控的监控和网络基础设施的用户。

从技术栈来看，它底层基于Docker和Docker Compose，这是现代应用部署的事实标准，保证了环境的一致性和可移植性。集成的Uptime Kuma是一个用Node.js写的、界面非常漂亮的现代化监控工具，支持HTTP(s)、TCP、Ping、DNS等多种监控类型，还有漂亮的仪表盘、通知（支持 Telegram、Discord、邮件等十几种方式）。而Mieru则是一个用Go语言编写的高性能代理协议实现，以其效率和抗干扰能力著称。将这两者结合，意味着你不仅拥有了“眼睛”（监控），还拥有了“腿”（代理），可以更灵活地管理和访问你的网络资源。

2. 核心组件深度解析

2.1 Uptime Kuma：你的服务健康守门员

Uptime Kuma是这个组合里的“面子”和“大脑”。它的主要职责是持续不断地检查你指定的服务端点是否存活、响应是否正常。我之所以喜欢用它替代一些老牌的监控方案，比如UptimeRobot的免费版或者自建的Nagios，主要是因为它在易用性、美观度和功能上找到了一个很好的平衡点。

首先，它的部署极其简单。作为一个Node.js应用，它可以通过Docker一键运行，数据存储默认使用SQLite，这意味着你不需要额外配置数据库服务，开箱即用。在kuma-mieru项目里，它被封装在一个容器中，所有的配置都通过环境变量和卷挂载预设好了。

其次，它的监控能力非常全面。你不仅可以监控一个HTTP/HTTPS网址返回的状态码是不是200，还可以：

关键词匹配：检查响应体里是否包含或不包含某个关键词，这对于监控API返回特定数据特别有用。
TCP端口检测：直接检测某个服务器的特定端口（如SSH的22、数据库的3306）是否开放。
Ping监控：监控服务器的网络可达性。
证书过期监控：自动检查HTTPS站点的SSL/TLS证书还有多少天过期，提前预警。

所有这些监控任务，你都可以设置检查间隔（比如每60秒一次）、超时时间和重试次数。监控结果会以直观的时间线图表形式展示在仪表盘上，绿色代表正常，红色代表故障，一目了然。

最后，它的通知系统是亮点。当监控项状态发生变化（从正常到故障，或从故障恢复）时，它可以触发通知。它集成了超过20种通知方式，包括Telegram、Discord、Slack、电子邮件、Gotify、Pushover等等。在kuma-mieru的默认配置中，通常已经预留了这些通知渠道的配置位置，你只需要填入自己的Token、Webhook URL或邮箱信息即可。

注意：Uptime Kuma的监控页面本身是需要被访问的。在kuma-mieru的架构里，通常我们会通过反代（如Nginx Proxy Manager）或者直接暴露端口的方式，让它在公网或内网可访问。同时，要确保运行Kuma的容器本身有网络权限去探测你所要监控的目标。

2.2 Mieru：高效稳定的网络通道

如果说Uptime Kuma是观察外界的“眼睛”，那么Mieru就是主动连接外界的“通道”。Mieru是一个代理协议，设计目标是在复杂的网络环境中提供稳定、高效、低延迟的传输能力。

它的工作原理是在客户端和服务器端之间建立一个加密的隧道。你的本地应用（比如浏览器）将流量发送到本地的Mieru客户端，客户端对流量进行加密和混淆处理，然后通过常规的HTTPS或TCP连接发送到远端的Mieru服务器端。服务器端解密流量后，将其转发到真正的目标网站或服务。这个过程对应用来说是透明的，你只需要在系统或浏览器中配置代理地址为本地Mieru客户端即可。

Mieru有几个技术特点值得一说：

协议混淆：它的流量在表面上看起来像是普通的HTTPS流量，这有助于在一些对代理流量进行深度包检测的网络环境中维持连接的稳定性。
多路复用：单个TCP连接上可以承载多个独立的逻辑数据流，减少了建立新连接的开销，提升了在高延迟或丢包网络下的性能。
拥塞控制：实现了自己的拥塞控制算法，旨在更公平地利用带宽并适应不同的网络条件。
Go语言编写：编译为静态二进制文件，跨平台部署非常方便，依赖极少，性能和资源占用表现都不错。

在kuma-mieru项目中，Mieru通常以服务器端（mieru server）的模式运行在容器内。这意味着，这个容器本身就是一个代理服务器。你可以在其他设备上部署Mieru的客户端，并连接到这个服务器，从而利用服务器所在的网络环境访问资源。

实操心得：Mieru的配置核心在于服务器和客户端的配置文件（通常是JSON格式）。在Docker环境下，这些配置可以通过环境变量注入，或者更常见的是通过将宿主机上的配置文件挂载到容器内的特定路径。务必确保服务器端配置中定义的监听端口、密码、加密方式等，与客户端配置完全匹配，否则连接无法建立。

2.3 Docker Compose：一体化部署的灵魂

kuma-mieru项目的精髓，很大程度上体现在它的docker-compose.yml文件上。这个文件定义了如何将Uptime Kuma和Mieru两个服务组织起来，协调运行。

一个典型的kuma-mieru的docker-compose.yml会包含两个service：

kuma服务：基于louislam/uptime-kuma镜像。它会映射两个端口：一个用于Web管理界面（如3001:3001），另一个可能用于Mieru客户端连接（但这通常属于mieru服务）。它会挂载一个卷到宿主机，用于持久化SQLite数据库和配置，确保容器重启后数据不丢失。
mieru服务：基于mieru的官方Docker镜像或项目自定义镜像。它会映射Mieru协议使用的端口（例如2022:2022）到宿主机。同样，它也需要挂载卷来持久化自己的配置文件。

关键点在于网络模式。为了让Kuma容器能监控到Mieru容器的状态（或者监控其他服务），同时也为了让Mieru容器能正常访问外网作为代理，通常有两种选择：

host网络模式：容器直接使用宿主机的网络栈。这样最简单，容器内应用看到的IP和端口就是宿主机的，但牺牲了一定的隔离性。
自定义桥接网络：创建一个Docker网络，让两个容器都加入进去。这样容器间可以通过服务名互相访问，与宿主机网络隔离，更安全规范。在kuma-mieru中，更推荐这种方式。

此外，Compose文件还会处理好依赖关系（比如确保网络先创建）、设置重启策略（always或unless-stopped以保证服务持续运行）、配置时区等细节。一份好的Compose文件，能让用户真正做到一键部署，无需关心底层细节。

3. 从零开始部署与配置实战

3.1 环境准备与项目获取

在开始之前，你需要一个运行Linux的服务器（VPS或家庭服务器均可），并确保已经安装了Docker和Docker Compose。如果还没有安装，可以参照以下命令（以Ubuntu/Debian为例）：

# 更新软件包索引 sudo apt-get update # 安装 Docker 依赖 sudo apt-get install -y ca-certificates curl gnupg lsb-release # 添加 Docker 官方 GPG 密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 设置 Docker 仓库 echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 Docker Engine 和 Compose 插件 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 验证安装 docker --version docker compose version

接下来，获取kuma-mieru项目。通常项目会托管在GitHub上，使用git克隆是最佳方式：

# 克隆项目仓库（请替换为实际仓库地址） git clone https://github.com/Alice39s/kuma-mieru.git cd kuma-mieru

如果项目没有提供git，你也可以直接下载ZIP包并解压。进入项目目录后，你首先应该查看README.md文件，了解基本的配置要求和步骤。

3.2 配置文件详解与定制

项目根目录下最核心的文件就是docker-compose.yml，以及相关的环境配置文件（如.env文件）或Mieru的config.json。我们的定制化工作主要在这里进行。

首先，打开docker-compose.yml文件，你会看到类似下面的结构：

version: '3.8' services: kuma: image: louislam/uptime-kuma:latest container_name: uptime-kuma restart: unless-stopped volumes: - ./kuma-data:/app/data ports: - "3001:3001" # Web管理界面 environment: - TZ=Asia/Shanghai networks: - kuma-mieru-net mieru: image: xxx/mieru:latest # 具体镜像名需看项目说明 container_name: mieru-server restart: unless-stopped volumes: - ./mieru-config:/config ports: - "2022:2022/tcp" # Mieru协议端口 - "2022:2022/udp" networks: - kuma-mieru-net depends_on: - kuma networks: kuma-mieru-net: driver: bridge

需要修改和注意的地方：

端口映射：
- 3001:3001：这是Uptime Kuma的Web端口。如果宿主机的3001端口已被占用，你可以将前面的端口号改为其他值，例如8080:3001，这样你就要通过http://服务器IP:8080来访问。
- 2022:2022：这是Mieru的默认端口。强烈建议更改，使用一个不常见的端口，能减少被扫描和干扰的风险。例如改为34567:2022。
持久化存储：
- ./kuma-data:/app/data：将容器内的数据目录挂载到宿主机的./kuma-data目录。确保这个目录存在，或者Docker Compose会自动创建。所有监控配置、历史数据都保存在这里。
- ./mieru-config:/config：Mieru的配置目录。里面应该包含server_config.json等文件。你需要根据项目说明或自己创建配置文件。
时区：TZ=Asia/Shanghai设置了容器时区。请根据你所在位置修改，例如America/Los_Angeles，这会影响监控日志的时间戳。
网络：两个服务都加入了自定义的kuma-mieru-net网络，这样在Kuma里监控Mieru服务时，可以直接使用服务名mieru-server和容器内部端口2022作为地址。

接下来是Mieru服务器配置。你需要在./mieru-config目录下创建server_config.json。一个最简配置示例如下：

{ "users": [ { "name": "your_username", "password": "your_strong_password" } ], "portBindings": [ { "port": 2022, "protocol": "TCP_UDP" } ], "loggingLevel": "INFO" }

users：定义连接的用户名和密码。可以定义多个用户。
portBindings：定义服务器监听的端口和协议。这里的端口2022需要与docker-compose.yml中mieru容器内部的端口一致。
loggingLevel：日志级别，DEBUG、INFO、WARN、ERROR。

重要提示：密码请务必设置得足够复杂，并且不要使用与其他账户相同的密码。这是保护你代理服务安全的第一道防线。

3.3 启动服务与初始化

配置完成后，在项目根目录（即docker-compose.yml所在目录）执行启动命令：

# 启动服务（-d 表示后台运行） docker compose up -d

使用docker compose ps或docker ps命令查看容器是否正常运行。如果状态是Up，则表示启动成功。

首次访问Uptime Kuma：打开浏览器，访问http://你的服务器IP:3001（如果你改了端口，则用新端口）。第一次访问会进入初始化页面，让你设置管理员账号和密码。这个账号用于登录Kuma管理后台，务必牢记。

初始化完成后，你就进入了Uptime Kuma的主仪表盘。现在，你可以开始添加你的第一个监控项了。点击左上角的 “Add New Monitor”。

3.4 配置监控与通知

在Uptime Kuma中添加监控项非常直观。我们以监控Mieru服务本身和监控一个外部网站为例。

监控Mieru服务（容器内监控）：

Monitor Type：选择TCP Port。
Friendly Name：填写Mieru Server。
Hostname：由于两个容器在同一个Docker网络，这里可以直接填mieru-server（Compose中定义的服务名）。
Port：填写2022（Mieru容器内部监听端口）。
Heartbeat Interval：检查间隔，例如60秒。
点击Save。

这样，Kuma就会每分钟尝试连接mieru-server容器的2022端口，以此判断Mieru代理服务是否正常。

监控一个外部网站：

Monitor Type：选择HTTP(s)。
Friendly Name：填写My Blog。
URL：填写https://example.com。
Heartbeat Interval：120秒。
关键词检查（可选）：在Advanced Options里，如果希望检查页面包含特定内容，可以在Accepted Status Codes旁展开更多选项，设置Keyword。
点击Save。

配置通知（以 Telegram 为例）：

在Kuma侧边栏点击Settings->Notifications。
点击Setup Notification，选择Telegram。
你需要先给@BotFather发送/newbot指令创建一个Telegram Bot，并获取API Token。
在Kuma界面填入Token。
然后，你需要获取你的Chat ID。最简单的方法是先给你的Bot发送一条消息（比如/start），然后访问这个API地址：https://api.telegram.org/bot<YourBOTToken>/getUpdates。在返回的JSON中找到chat对象的id字段。
将Chat ID填入Kuma。
点击Test发送测试通知，如果收到，则配置成功。

最后，记得在监控项的设置里，关联你刚创建的通知方式。这样当监控状态变化时，你就会收到Telegram消息了。

4. Mieru客户端配置与使用

服务器端部署好后，你需要在需要代理的设备上配置Mieru客户端。Mieru客户端有命令行版本和图形界面版本，这里以Linux命令行版本为例。

下载客户端：从Mieru的GitHub Releases页面下载对应你客户端操作系统和架构的二进制文件。例如，对于Linux AMD64：mieru-client-linux-amd64。
创建客户端配置：创建一个名为client_config.json的文件，内容如下：

{ "profiles": [ { "name": "my_server", "serverAddress": "你的服务器公网IP或域名", "serverPort": 34567, // 注意：这里填你在 docker-compose.yml 中映射到宿主机的端口，不是容器内的2022 "username": "your_username", // 与服务器配置一致 "password": "your_strong_password", // 与服务器配置一致 "tcpFastOpen": false, "mtu": 1400 } ], "activeProfile": "my_server", "socks5Port": 1080, // 本地SOCKS5代理端口 "httpPort": 8088, // 本地HTTP代理端口 "loggingLevel": "INFO" }

启动客户端：

# 赋予执行权限 chmod +x mieru-client-linux-amd64 # 启动客户端，指定配置文件路径 ./mieru-client-linux-amd64 -config ./client_config.json

如果看到mieru client started之类的日志，说明客户端启动成功，并连接到了服务器。

配置系统或应用代理：
- 现在，你的本地1080端口提供了一个SOCKS5代理，8088端口提供了一个HTTP代理。
- 你可以在系统网络设置中配置全局代理，或者仅在浏览器（如使用SwitchyOmega插件）、终端（通过export http_proxy）等特定应用中配置使用这些代理。

排查技巧：如果客户端无法连接，首先检查服务器防火墙是否放行了你映射的端口（如34567）。在服务器上运行sudo ufw allow 34567（如果使用UFW）或配置相应的云服务商安全组规则。其次，检查客户端配置中的serverAddress、serverPort、username、password是否与服务器端完全一致。可以在服务器容器内查看Mieru日志：docker logs mieru-server。

5. 安全加固与运维建议

将监控面板和代理服务放在一起，安全尤为重要。以下是一些加固措施：

修改默认端口：如前所述，3001和2022都是常见默认端口，务必修改。Kuma的Web端口可以改为一个高位端口，Mieru的服务端口也改为非标准端口。
强密码与多用户：为Uptime Kuma的管理员和Mieru的用户设置强密码（长、混合大小写、数字、符号）。Mieru可以配置多个用户，并为不同设备分配不同用户，便于管理和吊销。
反向代理与 HTTPS：强烈建议不要将Uptime Kuma的3001端口直接暴露在公网。应该使用Nginx、Caddy或Nginx Proxy Manager这样的反向代理工具，将Kuma服务代理到一个域名下，并配置HTTPS（可以使用Let‘s Encrypt免费证书）。这能加密管理流量，防止窃听和中间人攻击。
防火墙限制：在服务器防火墙或云安全组中，只开放必要的端口：SSH端口（如22）、HTTPS端口（如443，用于反向代理访问Kuma）、以及你自定义的Mieru服务端口。关闭所有其他不必要的入站端口。
定期更新：定期检查并更新Docker镜像。可以设置Watchtower或Diun这样的容器自动更新工具，但更建议在测试后手动更新，因为重大版本更新可能需要调整配置。
```
# 进入项目目录，拉取最新镜像并重启服务 cd /path/to/kuma-mieru docker compose pull docker compose up -d --force-recreate
```
备份数据：定期备份./kuma-data目录。这是你所有的监控配置和历史数据。简单的备份方法可以是使用cron定时任务执行tar压缩并拷贝到其他位置或云存储。

6. 常见问题与故障排查实录

在实际部署和使用kuma-mieru的过程中，你可能会遇到一些问题。下面是我遇到过的一些典型情况及其解决方法。

问题1：Uptime Kuma容器启动失败，日志显示Permission denied或EACCES错误。

原因：这通常是因为Docker容器内进程的用户（通常是node）对挂载的宿主机目录./kuma-data没有写入权限。
解决：在宿主机上，确保该目录存在且权限正确。最直接的方法是更改目录的所有者到Docker容器默认使用的用户UID（对于uptime-kuma镜像，可能是1000），或者直接赋予777权限（安全性较低，仅用于测试）。
```
sudo chown -R 1000:1000 ./kuma-data # 或 sudo chmod -R 777 ./kuma-data
```

问题2：Mieru客户端能连接服务器，但无法访问外网。

排查步骤：
1. 检查服务器端网络：进入mieru容器，测试从容器的网络是否能访问外网。
```
docker exec -it mieru-server ping 8.8.8.8
```
  如果不通，检查宿主机的网络配置、防火墙，以及容器是否以--net=host模式运行（在Compose中通常是自定义网络，需要确保网络配置正确）。
2. 检查客户端配置：确认客户端配置中的serverAddress是公网IP或能正确解析的域名。如果服务器在NAT后或有复杂的网络环境，可能需要额外的端口转发。
3. 检查Mieru服务器日志：查看服务器容器日志，看是否有客户端的连接记录和错误信息。
```
docker logs --tail 50 mieru-server
```
4. 检查客户端本地代理设置：确保你的浏览器或系统正确配置了代理地址（127.0.0.1）和端口（1080或8088）。可以用curl命令测试：
```
curl --socks5 127.0.0.1:1080 https://httpbin.org/ip
```
  如果返回了你的服务器IP，说明代理工作正常。

问题3：Uptime Kuma监控TCP端口一直显示“Down”，但手动测试端口是通的。

原因：Kuma容器可能无法解析你在监控项中填写的主机名（特别是使用容器服务名时），或者网络策略限制。
解决：
1. 确保Kuma容器和监控目标容器在同一个Docker网络中（在Compose中已配置）。
2. 尝试在Hostname字段直接使用目标容器的IP地址。你可以进入Kuma容器，使用ping或nslookup测试。
```
docker exec -it uptime-kuma ping mieru-server
```
3. 检查目标服务的防火墙，确保它允许来自Docker网络网段（如172.20.0.0/16）的连接。

问题4：如何查看Mieru的流量使用情况？

Mieru服务器端默认日志不会详细记录每个用户的流量。如果需要流量统计，可以考虑以下方案：
1. 服务器级监控：在宿主机上使用iftop、nethogs等工具监控Docker虚拟网卡或物理网卡的流量，但这无法区分用户。
2. 应用级日志分析：调整Mieru的日志级别到DEBUG（不推荐长期开启，日志量巨大），然后从日志中解析流量信息。
3. 第三方插件或修改：目前Mieru官方未提供详细的流量统计API。这是一个进阶需求，可能需要自行开发或寻找社区插件。