手里的 VPS 和云主机一旦超过三四台，挨个 SSH 进去查负载和带宽就变得非常繁琐。传统的 Prometheus + Grafana 套件虽然强大，但动辄吃掉几百 MB 内存，小内存 VPS 根本跑不起。

Komari（小鞠探针）是一款极轻量、颜值高、支持多节点汇总的服务器监控面板：主控端一个轻量容器搞定，各受控节点只需跑一个几十 MB 的 Go 编译二进制 Agent，就能实时汇报 CPU、内存、磁盘、上下行流量和在线率。

这篇笔记记录如何用 Docker 部署 Komari 主控端、配置 Nginx 反代与 WebSocket、以及在多台被控机器上一键安装 Agent 守护进程。

Komari 监控面板的架构与优势

传统监控工具（如 Zabbix、Prometheus）动辄吃掉几百兆甚至几 GB 内存，而 Komari（基于 Go 语言单二进制开发） 展现了极具诱惑力的架构优势：

┌─────────────────────────────────────────────────────────────┐
│ 🖥️ 主控面板 (Master)：Docker 极简运行                        │
│    - 单二进制引擎 + 内置 SQLite 数据库，内存仅占 ~50MB；     │
│    - 聚合展示全网所有机器的实时水位、网络延迟与在线状态。     │
├─────────────────────────────────────────────────────────────┤
│ 📡 被控端 (Agent)：主动出站心跳（被控机 0 门槛）              │
│    - 占用内存仅 ~10MB，编译为单个二进制文件；                │
│    - 🔑 核心特性：被控机完全不需要公网 IP、不需要开任何入站端口！│
│    - 哪怕是家里的内网软路由、动态 IP 小鸡，只要能联网，     │
│    - 就能主动顺着 WebSocket 向上汇报数据，安全又稳定！       │
└─────────────────────────────────────────────────────────────┘

准备工作

  • [ ] 一台做主控的 VPS：安装了 Docker 与 Nginx 反代环境；
  • [ ] 一个二级域名：例如将 server.example.com 解析到主控服务器 IP；
  • [ ] 若干台待监控的机器：可以是你手里的任意 Linux 服务器、树莓派或软路由。

在主控服务器启动 Komari 容器

我们将数据持久化在宿主机目录中，保证数据永不丢失。

💻 【你本地的电脑】 打开终端连入主控服务器，进入 🖥️ 【主控窗口】。

整段粘贴执行以下自包含 Compose 部署脚本（绝不需要手动碰 vim）：

# 1. 创建 Komari 专属数据目录
mkdir -p /opt/komari && cd /opt/komari

# 2. 写入干净纯净的 Docker Compose 编排清单
cat << 'EOF' > /opt/komari/docker-compose.yaml
version: "3"
services:
  komari:
    image: ghcr.io/komari-monitoring/komari:latest
    container_name: komari
    restart: unless-stopped
    volumes:
      # 数据持久化挂载
      - /opt/komari/data:/app/data
    ports:
      # 绑定本地 25774 端口，准备供 Nginx 反代接入
      - "127.0.0.1:25774:25774"
EOF

# 3. 后台静默启动面板
docker compose up -d
docker compose ps
  • ✅ 成功标志：终端显示 komari 容器状态为 Up，成功绑定 127.0.0.1:25774。

配置 Nginx 反向代理与 WebSocket 转发

Komari 的节点心跳和前端实时波形图全部走 WebSocket，Nginx 配置必须注入长连接支持。

🖥️ 【主控窗口】 先定义你的监控域名变量：

MONITOR_DOMAIN="server.example.com"

接着，整段执行自包含网关反代脚本：

cat << EOF > /etc/nginx/sites-available/${MONITOR_DOMAIN}.conf
server {
    listen 80;
    listen [::]:80;
    server_name ${MONITOR_DOMAIN};

    location / {
        proxy_pass http://127.0.0.1:25774;

        # 核心标头透传
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;

        # 核心必须：启用 WebSocket 动态长连接升级
        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";

        # 调优长连接保活超时（防止心跳被 Nginx 提前切断）
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}
EOF

# 激活站点并自检重载
ln -sf /etc/nginx/sites-available/${MONITOR_DOMAIN}.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
  • ✅ 成功标志：终端打印 test is successful，网关平滑生效。
  • 💡 小绿锁建议：执行 certbot --nginx -d ${MONITOR_DOMAIN} 顺手为监控域名配上 HTTPS。

在控制面板中添加受控节点

💻 【你本地的浏览器】 打开 https://server.example.com：

  1. 首次打开会引导你设置管理员账号与初始密码（务必牢记）；
  2. 登录进入极其炫酷清爽的探针大盘；
  3. 点击右上角或设置里的 「添加节点 (Add Server)」：
    * 节点名称：例如 香港生产节点 或 家里软路由；
    * 系统架构：选择 Linux；
  4. 点击生成后，面板会给出该节点的专属接入密钥（UUID / Token）！
  • ✅ 成功标志：节点列表中出现新节点卡片，当前状态显示为黄色的「等待连接 (Waiting)」。

在被控端机器安装 Agent 守护进程

现在切换到你想监控的那台机器上（无论是别的 VPS 还是本地的小主机）。

💻 【你本地的电脑】 打开一个新终端连入被控服务器，进入 🖥️ 【被控机器窗口】。

使用官方标准的 Systemd 一键后台守护模式 运行 Agent：

# 1. 自动探测架构并下载官方最新 Agent 二进制
ARCH=$(uname -m)
case $ARCH in
    x86_64)  FILE="komari-agent-linux-amd64" ;;
    aarch64) FILE="komari-agent-linux-arm64" ;;
    *) echo "未知架构: $ARCH"; exit 1 ;;
esac

mkdir -p /opt/komari-agent && cd /opt/komari-agent
curl -sSL "https://github.com/komari-monitoring/komari-agent/releases/latest/download/${FILE}" -o komari-agent
chmod +x komari-agent

# 2. 定义连接主控的信息（填入你在第 3 步获得的面板域名与节点 Token！）
MASTER_URL="https://server.example.com"
NODE_TOKEN="你的节点专属Token"

# 3. 注册为 systemd 开机自启服务
cat << EOF > /etc/systemd/system/komari-agent.service
[Unit]
Description=Komari Monitoring Agent
After=network.target

[Service]
Type=simple
ExecStart=/opt/komari-agent/komari-agent -e ${MASTER_URL} -t ${NODE_TOKEN}
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# 4. 启动 Agent 服务
systemctl daemon-reload
systemctl enable --now komari-agent
systemctl is-active komari-agent
  • ✅ 成功标志：最后一行返回 active。

此时回到你的浏览器刷新 Komari 仪表盘：
– ✅ 大功告成标志：刚才等待连接的卡片瞬间变成充满生机的翠绿色！CPU 动态波动、内存占用条、实时网速曲线一览无余，双向建链成功！🚀🎉

常见报错与排障

异常现场 真实根因 对应一秒救命招式
被控端 Agent 已启动，但面板里永远显示“离线” Nginx 反代配置里漏了 WebSocket Upgrade 标头 检查第 2 步的反代配置，确认包含 proxy_set_header Upgrade $http_upgrade;，重载生效。
Agent 日志提示 x509: certificate signed by unknown authority 主控使用了不被信任的自签证书，或系统缺少 CA 证书 1. 确保主控已绑定正式的 Let’s Encrypt 证书；
2. 在被控机器执行 apt install -y ca-certificates。
Watchtower 自动更新面板后出现 502 报错 镜像升级后，旧数据权限被重置或端口变动 敲 docker logs komari 看日志；确保数据卷挂载的是 /opt/komari/data:/app/data 官方标准路径。
家里内网机器重启后 Agent 没连上 开机时网络尚未就位，服务提前退出 在 systemd 配置里增加 RestartSec=5，Agent 会在网络连通后自动重连自愈。
# Docker # Komari # VPS # 探针 # 监控 # 运维