服务器一多，状态就乱。内存跑满了不知道，流量用超了没提示，等到应用崩了才发现——这是很多 VPS 玩家的日常痛点。

Komari 是一款开源的轻量级服务器监控探针，界面简洁、部署简单，支持多节点汇聚展示，适合个人玩家和小团队使用。不需要复杂配置，一个 docker-compose.yml 就能跑起来。本文记录在 VPS 上用 Docker Compose 完整部署 Komari 的过程，包括反向代理绑定域名，以及后续更新的操作。

项目地址：https://github.com/komari-monitor/komari

环境要求

  • Linux VPS，已安装 Docker 和 Docker Compose

  • 有 root 权限

  • （可选）Nginx Proxy Manager，用于绑定域名和申请 SSL

第一步：创建目录

以 root 身份操作，避免后续的权限问题。

sudo -i
mkdir -p /root/data/docker_data/Komari
sudo chmod -R 755 /root/data/docker_data/Komari
cd /root/data/docker_data/Komari

第二步：编写 docker-compose.yml

新建配置文件：

nano docker-compose.yml

填入以下内容，Ctrl+X → Y → Enter 保存退出：

services:
  komari:
    image: ghcr.io/komari-monitor/komari:latest
    container_name: komari
    restart: unless-stopped
    ports:
      - "25774:25774"
    volumes:
      - ./data:/app/data

restart: unless-stopped 的作用是让容器在服务器重启后自动拉起，无需手动干预。数据通过 ./data 目录持久化，重建容器不会丢失历史数据。

第三步：启动容器并获取初始密码

docker compose up -d

启动后查看日志，获取系统自动生成的初始账号密码：

docker logs komari

在输出中找到 username 和 password 字段，记下来。登录后建议立即修改密码。

第四步：访问面板

直接通过 IP + 端口访问，确认面板能正常打开：

http://服务器IP:25774

第五步：配置反向代理（NPM）

如果你使用 Nginx Proxy Manager，新增一条代理主机：

配置项

值

Domain Names

your-domain.com

Forward Hostname

127.0.0.1

Forward Port

25774

Websockets Support

✅ 必须开启

SSL

申请 Let's Encrypt 证书

⚠️ Websocket 一定要开 ，否则节点状态无法实时推送，面板数据会停滞不更新。

配置保存后，通过域名访问，SSL 正常则部署完成。

后续更新

Komari 迭代较活跃，建议定期更新：

cd /root/data/docker_data/Komari
docker compose pull && docker compose up -d
docker image prune

最后一条命令用于清理旧版本镜像，释放磁盘空间，养成习惯。

常见问题

Q：国内服务器 docker compose pull 拉取镜像失败或很慢？

ghcr.io 在国内访问不稳定，可以换用南京大学的镜像加速站：

# 将镜像地址替换为加速源
ghcr.nju.edu.cn/komari-monitor/komari:latest

在 docker-compose.yml 里把 image: 那行改成上面的地址，再重新 docker compose up -d 即可。

Q：延迟监控显示"暂无延迟数据"，该怎么排查？

延迟监控不显示数据的原因有多种，按顺序逐项排查：

  1. 刚添加还没到时间：延迟检测是定时任务，添加后需要等几分钟才会出现第一批数据，不是实时生效。

  2. 检测协议选错了：Komari 支持 ICMP、TCP、HTTP 三种协议。ICMP（ping）在很多环境下会被屏蔽——NAT 鸡、部分 IDC、云厂商默认禁 ping 都会导致为空。建议优先选 TCP 或 HTTP 类型的检测节点，成功率更高。

  3. 服务端出方向被防火墙拦截：延迟检测由 Komari 服务端主动发起，不是 Agent 端。如果服务端所在机器出方向的 ICMP 或对应端口被 iptables、云厂商安全组拦截，检测包发不出去自然没结果。

  4. Docker 部署未用 host 网络：Docker 默认桥接网络对 ICMP 有限制，可以在 docker-compose.yml 加上 network_mode: host 绕过，或改用 TCP/HTTP 类型检测。

  5. 检测节点地址填错：确认填入的 IP 或域名本身可达，可以在服务端机器上手动 ping 或 curl 验证。

Q：面板显示的 CPU、内存、硬盘等硬件信息和实际不符？

这是容器化环境（LXC/OpenVZ）的常见现象，不是 Komari 的 bug：

  • LXC/OpenVZ 容器：Agent 通过读取 /proc 获取数据，而 LXC 容器共享宿主机内核，/proc 里看到的是宿主机的硬件规格，不是你购买的套餐规格。CPU 核数、内存大小偏大都属于这个原因，目前没有完美解决方案。

  • 磁盘路径识别错误：多块磁盘挂载时 Komari 可能读取了非预期的路径，可以检查 Agent 启动参数或挂载点配置。

  • KVM 机器数据正常：KVM 完全虚拟化，/proc 数据是隔离的，通常显示正确。如果 KVM 机也出现硬件信息异常，优先检查 Agent 版本是否过旧。

Q：我的 VPS 无法运行官方二进制 Agent（虚拟主机、限制执行权限），怎么办？

官方 Agent 是 Go 编译的二进制文件，无法在部分限制性环境中运行。社区有现成的替代方案，用解释型语言实现了相同的上报协议：

使用第三方 Agent 时，远程控制等高级功能可能不完整，以各项目文档为准。

Q：Agent 安装后一段时间自动掉线，面板显示离线？

按以下几点逐一排查：

  1. 反代未正确配置 WebSocket：Komari 使用 WebSocket 长连接，NPM 需勾选 Websockets Support；Nginx 手动配置需确保有 proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "Upgrade" 这三行，缺一会导致连接被断开。

  2. 代理超时时间过短：Nginx 默认 proxy_read_timeout 是 60 秒，WebSocket 长连接会被强制切断。建议设置为 proxy_read_timeout 3600;。

  3. 面板地址用了 IP 而不是域名：安装 Agent 时如果通过 http://IP:25774 打开面板，生成的安装命令里连接地址也是 IP，VPS 重启后 IP 不变没问题，但如果面板迁移或换 IP 就会断联。建议始终通过域名访问面板再复制安装命令。

  4. Agent 内存不足被 OOM Kill：极低内存的机器（如 64MB 的 LXC）可能因内存耗尽导致 Agent 进程被杀。配置 Swap 可以有效缓解，Alpine 系统下执行：dd if=/dev/zero of=/swapfile bs=1M count=512 && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile。

Q：使用 Cloudflare 反代时，NAT 鸡的 Agent 无法上线？

这是一个已知 bug：当面板启用了 CF Argo 隧道反代，且 Agent 安装时使用了 --auto-discovery 参数，NAT 鸡的共享 IP 会触发 Cloudflare 的自动程序攻击模式（Bot Fight Mode），Agent 被 JS 质询拦截导致无法连接。

解决方法：卸载 Agent 后，用面板 Argo 域名重新安装（去掉 --auto-discovery 参数），同时在 CF 面板中为该 IP 添加"跳过质询"规则。

Q：在同一台机器上同时装了面板和 Agent，卸载 Agent 时把面板也删了？

这是官方文档旧版卸载命令的已知 bug，旧命令 rm -rf /opt/komari 会把面板目录一起删掉。正确的 Agent 卸载命令应当只删 Agent 子目录：

sudo systemctl stop komari-agent && \
sudo systemctl disable komari-agent && \
sudo rm -f /etc/systemd/system/komari-agent.service && \
sudo systemctl daemon-reload && \
sudo rm -rf /opt/komari/agent /var/log/komari

注意末尾是 /opt/komari/agent，而不是 /opt/komari，后者会把面板数据一并删除。

Q：延迟检测数据越积越多，磁盘占用越来越大？

Komari 默认保存 24 小时的延迟检测历史，检测节点多、间隔短的情况下数据量增长较快。可以在后台 设置 → 通用 中调整保存时长，或适当拉长检测间隔（建议 60 秒以上）。如果磁盘已经占满，直接删除 data/ 目录下的数据库文件会清空所有历史记录，谨慎操作。

Q：macOS 上安装 Agent 后 ping 监控不正常，或提示 zsh: no such file or directory？

macOS 默认使用 zsh，官方生成的一键安装命令用了 bash 的进程替换语法 bash <(...) 在 zsh 下不兼容。解决方法是把命令改成：

curl -sL https://raw.githubusercontent.com/komari-monitor/komari-agent/refs/heads/main/install.sh | sudo bash -s -- -e https://你的面板地址 -t 你的Token

此外，macOS 上 ping 需要 root 权限，安装时必须加 sudo，否则 ICMP 延迟检测会静默失效。

小结

Komari 的整个部署流程非常干净，没有繁琐的依赖和配置，适合快速上手。如果你同时管理多台 VPS，它能提供一个统一的状态视图，省去逐台 SSH 查看的麻烦。

目前我把它部署在一台专用的监控机上，稳定运行中。如果你也在用 Komari，或者有其他推荐的探针方案，欢迎在评论区交流。