Docker容器栈统一监控利器Maintenant

发表于 分类于 Waline： 阅读次数： 本文字数： 5k 阅读时长 ≈ 5 分钟
Maintenant 是一个开源的 Docker 容器栈统一监控工具，自动发现容器、端点、SSL证书并集成状态页面。

简介

什么是 Maintenant ？

Maintenant 是一个开源的容器栈统一监控工具，只需部署一个容器，就能自动发现你的整个容器栈，集容器监控、端点检查、SSL 证书跟踪、资源指标、更新检测和安全洞察于一体。它用单个二进制替代了 Uptime Kuma、Portainer、Dozzle 等多个工具的组合，真正做到 “Monitor everything. Manage nothing.”

主要特点

  • 零配置容器自动发现：自动发现 Docker 和 Kubernetes 容器，跟踪状态变化、健康检查、重启循环和日志，Compose 项目自动分组
  • HTTP/TCP 端点监控：通过 Docker 标签即可定义 HTTP 或 TCP 检查，无需编辑 YAML 配置文件，支持响应时间、可用率历史和可配置阈值
  • SSL/TLS 证书跟踪：自动检测 HTTPS 端点的证书信息，在过期前 30、14、7、3、1 天发出警报，支持完整证书链验证
  • 资源指标监控：实时采集 CPU、内存、网络 I/O 和磁盘 I/O 数据，提供历史趋势图表，支持每个容器的阈值告警
  • 更新智能检测：扫描 OCI 镜像仓库，对比镜像摘要，在有新版本时主动通知
  • 网络安全洞察：自动发现容器中的危险网络配置，如端口暴露、特权模式、主机网络模式等
  • 统一告警引擎：支持 Webhook 和 Discord 通知，Pro 版额外支持 Slack、Teams、邮件以及升级策略
  • 公共状态页面：内置实时状态页面，支持 SSE 实时更新，Pro 版还包含事件时间线和订阅者通知
  • 内置 MCP 服务器：支持 Model Context Protocol，可从任何 MCP 兼容的 AI 助手查询基础设施状态
  • 开源免费：基于 AGPL-3.0 协议开源，可免费使用和修改

应用场景

  • 家庭服务器/实验室监控：自托管用户只需一个容器，即可监控 NAS 上运行的所有 Docker 服务状态
  • 端点可用性检测：为每个服务定义 HTTP 健康检查端点，当服务宕机时第一时间接收通知
  • SSL 证书到期预警：自动跟踪所有 HTTPS 服务的证书到期时间，避免证书过期导致服务中断
  • 定时任务/心跳监控：为定时脚本或 Cron 作业创建一个唯一的 Ping URL，作业未按时执行时自动告警
  • 公共状态页面：为你的用户或客户提供一个实时状态页面，展示各服务的运行状态

Maintenant 是一个将多种监控能力融合到一个容器中的利器，从容器状态到 HTTP 端点，从 SSL 证书到系统资源，一个仪表盘尽收眼底。

安装

在群晖上以 Docker 方式安装。

由于镜像托管在 ghcr.io，群晖 Docker 套件无法直接搜索注册表，需要通过命令行或 docker-compose 部署。

本文写作时，latest 版本对应为 v1.2.13。

docker cli 安装

如果你熟悉命令行，可能用 docker cli 更快捷

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 新建文件夹 maintenant 和 子目录
mkdir -p /volume1/docker/maintenant/data

# 进入 maintenant 目录
cd /volume1/docker/maintenant

# 修改目录权限
chmod a+rw data

# 运行容器
docker run -d \
  --name=maintenant \
  --restart=unless-stopped \
  -p 6524:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /proc:/host/proc:ro \
  -v $(pwd)/data:/data \
  -e MAINTENANT_ADDR="0.0.0.0:8080" \
  -e MAINTENANT_DB="/data/maintenant.db" \
  ghcr.io/kolapsis/maintenant:latest

环境变量说明：

  • MAINTENANT_ADDR 指定 HTTP 监听地址
  • MAINTENANT_DB 指定 SQLite 数据库文件路径。
  • 更多环境变量（如 MAINTENANT_BASE_URL、MAINTENANT_ORGANISATION_NAME 等）可根据需要添加。

docker-compose 安装

也可以用 docker-compose 安装，将下面的内容保存为 docker-compose.yml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
services:
  maintenant:
    image: ghcr.io/kolapsis/maintenant:latest
    container_name: maintenant
    restart: unless-stopped
    ports:
      - "6524:8080"
    read_only: true
    security_opt:
      - no-new-privileges:true
    # group_add:
    #   - "${DOCKER_GID:-983}"  # match host's docker group   see note below
    tmpfs:
      - /tmp:noexec,nosuid,size=64m
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /proc:/host/proc:ro
      - ./data:/data
    environment:
      MAINTENANT_ADDR: "0.0.0.0:8080"
      MAINTENANT_DB: "/data/maintenant.db"

关于 DOCKER_GID： 群晖 DSM 的 Docker 套件并不是通过 Linux 的 docker 组来管理，所以 /etc/group 里 可能没有 docker 这个组

然后通过 SSH 登录到您的群晖，执行下面的命令：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 新建文件夹 maintenant 和 子目录
mkdir -p /volume1/docker/maintenant/data

# 进入 maintenant 目录
cd /volume1/docker/maintenant

# 修改目录权限
chmod a+rw data

# 将 docker-compose.yml 放入当前目录

# 一键启动
docker-compose up -d

运行

在浏览器中访问 http://<群晖IP>:6524 即可进入主界面

首次启动后，Maintenant 会自动发现宿主机上运行的所有 Docker 容器，无需任何额外配置。

基本使用流程

  1. 查看仪表盘：首页展示所有容器的运行状态、资源使用情况和健康检查结果
  2. 添加端点监控：在其他服务的 Docker 标签中添加 maintenant.endpoint.http 或 maintenant.endpoint.tcp，Maintenant 会自动检测并开始监控

任何容器上添加标签：

1
2
3
4
5
6
services:
  api:
    image: myapp:latest
    labels:
      maintenant.endpoint.http: "http://api:3000/health"
      maintenant.endpoint.interval: "15s"

一旦容器启动，Maintenant 就会每 15 秒检查一次 http://api:3000/health

  1. 配置告警：进入 Settings → Alert Triggers，配置 Webhook 或 Discord 通知渠道
  2. 启用状态页面：进入 Status Page 设置，选择要在公共页面展示的组件

直接访问 http://<群晖IP>:6524/status 可以看到运行状态

MCP 服务

Maintenant 嵌入了一个 MCP 服务器，提供涵盖所有监控维度的 18 个工具。AI 助手可以使用这些工具诊断问题、关联数据并提出解决方案，而无需离开编辑器。

修改 docker-compose.yml

需要启用 MCP 服务器并配置 OAuth2 凭证

1
2
3
4
MAINTENANT_MCP: "true"
MAINTENANT_MCP_CLIENT_ID: "maintenant-mcp-client"
MAINTENANT_MCP_CLIENT_SECRET: "laosu123"
MAINTENANT_BASE_URL: "http://<群晖IP>:6524"

opencode 中配置

以 opencode 为例，把参数丢给它，直接让它自己配置。应该包含下面这些要素：

其中 192.168.0.197 为老苏安装 Maintenant 的群晖主机的 IP

  • 参考文档地址：https://docs.maintenant.dev/features/mcp/#mcp-server
  • MCP 服务地址： http://192.168.0.197:6524/mcp
  • MAINTENANT_MCP_CLIENT_ID ：maintenant-mcp-client
  • MAINTENANT_MCP_CLIENT_SECRET：laosu123

接下来 opencode 就开始自己忙活了

  • 第一步、会在 opencode.json 中添加了 maintenant MCP 服务配置：
1
2
3
4
5
6
7
8
9
"maintenant": {
  "type": "remote",
  "url": "http://192.168.0.197:6524/mcp",
  "enabled": true,
  "oauth": {
    "clientId": "maintenant-mcp-client",
    "clientSecret": "laosu123"
  }
}

  • 第二步、服务器端配置 OAuth 回调地址

按照说明需要在 docker-compose.yml中配置MAINTENANT_MCP_ALLOWED_REDIRECT_URIS=http://localhost:19876/mcp/oauth/callback，但是实际上老苏并没有配置

  • 第三步、运行 opencode mcp auth maintenant

这一步完成 mcp 的 OAuth2 认证，可以直接在 opencode 中让它执行 opencode mcp auth maintenant，会看到页面跳转并显示认证成功，只是一闪而过，所以没截屏

  • 第四步、开始使用

例如：列出所有容器的状态

注意事项

  1. Docker 套接字权限：Maintenant 以 nobody 用户运行，必须通过 group_add 将容器加入宿主机 Docker 组才有权限读取 Docker 套接字，如果在群晖上运行遇到权限问题，可以尝试使用 root 用户运行
  2. 数据持久化：SQLite 数据库存放在 /data 目录，务必挂载持久化卷，否则容器重启后所有配置将丢失
  3. 反向代理：Maintenant 不内置认证机制，建议通过 Traefik、Nginx 等反向代理配合 Authelia、Authentik 等认证中间件使用
  4. 安全建议：Docker 套接字以只读方式挂载（:ro），Maintenant 只做观测不会修改容器，但仍建议限制外部访问
  5. 资源占用：官方数据显示运行时仅需约 17MB 内存，非常轻量，适合在低配置设备上运行

参考文档

kOlapsis/maintenant: Drop a container. Your stack is monitored.
地址：https://github.com/kOlapsis/maintenant

Maintenant 官方网站
地址：https://maintenant.dev

Maintenant 官方文档
地址：https://docs.maintenant.dev

ghcr.io/kolapsis/maintenant
地址：https://github.com/kOlapsis/maintenant/pkgs/container/maintenant