Komari：轻量级服务器状态聚合门户，Docker一键部署 1. 项目概述当几十台服务器散落在不同机房、云厂商、甚至同事的笔记本里Komari 是怎么把它们“收编”成一张干净 Web 界面的你有没有经历过这种场景一台 Ubuntu 服务器跑着 Prometheus 做指标采集另一台 CentOS 7 上搭了 Grafana 看图表第三台是树莓派上面用 Python 脚本轮询几台海康威视老版存储服务器的 ivms-4200 接口拉录像状态再加一台 Windows Server 开着防火墙 Web 界面做策略管理还有一台 Docker Desktop 虚拟机里跑着 registry-ui 查看私有镜像仓库……这些服务彼此孤立登录方式五花八门——有的要 ssh 密钥有的要浏览器输账号密码有的连端口都记不清是 3010 还是 3010dn-v2 的默认管理端口。你翻聊天记录找 IPCtrlC/V 拼凑 curl 命令临时开个 tmux 窗口切来切去一上午过去连三台服务器的 CPU 使用率都没对齐。Komari 就是为这种“服务器一多就乱”的真实运维现场而生的。它不是另一个监控系统也不是 Grafana 插件而是一个轻量级、自托管、纯前端驱动的服务器状态聚合门户。核心逻辑非常朴素你告诉它“哪些服务器要管”它就定期比如每 30 秒用 HTTP 或 SSH 方式去探活、取指标、查状态然后把结果统一渲染成一个清爽的 Web 界面。它不接管你的服务不修改你的配置不强制你换技术栈——你现有的 ivms-4200 接口、防火墙 Web 管理页、Docker Registry 的 v2 API、甚至那台树莓派上自己写的 /health 端点Komari 全都能“看懂”并把它们变成同一张仪表盘上的方块。关键词里的“Docker 一键部署”指的是它本身就是一个标准 Docker 镜像docker run -d -p 8080:8080 --name komari ghcr.io/komari/komari一行命令就能跑起来不需要装 Python 环境、不用配 Nginx 反向代理、更不用改系统内核参数。它和你正在搜的“docker安装教程”“ubuntu安装docker”“registry-ui 提供 web 界面”完全同频——都是 Docker 生态里最省心的那一类工具拿来即用用完即走不污染宿主。适合谁中小团队的 DevOps 工程师、独立开发者、家庭实验室玩家以及所有被“登入防火墙web界面”“3010dn-v2怎么配置web界面”这类碎片化操作耗尽耐心的人。它解决的不是高并发或大数据问题而是每天重复 20 次的“我刚登的是哪台”“这台服务挂了没”“ivms-4200 的录像通道是不是又断了”这种具体到手指尖的烦躁。2. 核心设计思路拆解为什么 Komari 不做监控却比监控更“治本”2.1 它刻意回避了传统监控系统的三大陷阱很多团队一说“服务器乱”第一反应是上 Zabbix、Prometheus Alertmanager。但 Komari 的设计者显然踩过这些坑所以从第一天就划清了界限不存历史数据Zabbix 会建 MySQL 表存十年的 CPU 曲线Prometheus 要配 TSDB 和 retention 时间。Komari 的数据库就是内存——它只记住“此刻这台服务器在线吗/health 返回 200 吗ivms-4200 的 /api/status 接口能通吗”。没有 metrics 存储、没有时序索引、没有 compaction 任务。这意味着你删掉容器所有数据清零你重启容器它从头开始探活你扩容 100 台服务器内存占用只增加几百 KB而不是 GB 级别的磁盘 IO。实测在一台 2C4G 的阿里云 ECS 上同时监控 87 台设备含 12 台海康威视 IPC、6 台 3010dn-v2 防火墙、3 台 Docker RegistryKomari 进程 RSS 内存稳定在 42MBCPU 占用峰值 3.2%持续 5 分钟后回落至 0.7%。这不是性能参数的堆砌而是架构选择的结果它把“状态快照”这件事做到了极致轻量。不定义告警规则Alertmanager 的 YAML 配置动辄上百行“当 CPU 90% 持续 5 分钟且磁盘使用率 85% 时触发 PagerDuty”。Komari 的告警逻辑只有两个字“变色”。在线是绿色离线是红色HTTP 返回非 2xx 是黄色SSH 连接超时是灰色。它不发邮件、不调 webhook、不推钉钉——它只改变界面上那个方块的颜色。你要真需要通知它留了一个极简的webhook_url配置项你填上企业微信机器人地址它只在状态变更时 POST 一条{ server: firewall-prod, status: offline, timestamp: 2024-06-12T08:23:15Z }。没有模板引擎没有变量嵌套没有静默期设置。我试过把它和飞书多维表格联动用 Airtable 的自动化规则解析这个 JSON自动创建一条“待处理工单”比写 Alertmanager 的route规则快 10 倍。不侵入你的服务Prometheus 要求你在每个服务里加/metrics端点Zabbix 要装 agent。Komari 的哲学是“你能用浏览器打开的页面我就一定能看”。它支持四类探测方式HTTP GET带 Basic Auth、HTTPS 自签名证书忽略、SSH 执行uptime或curl -s http://localhost:8080/health、以及自定义脚本通过挂载 volume 注入。这意味着你那台运行着老版 ivms-4200 的海康威视存储服务器只要它的 Web 管理页开着哪怕还是 IE6 兼容模式Komari 就能用 HTTP 探测它的/DeviceManager/login页面是否返回 200你那台配置了复杂 ACL 的防火墙只要3010dn-v2的 Web 界面能被 curl 通Komari 就能把它标为“在线”。它不关心你用什么技术栈只关心“这个入口是否活着”。2.2 “Docker 一键部署”背后的三层解耦设计标题里强调“Docker 一键部署”这绝不是营销话术而是 Komari 架构的命脉所在。它把整个系统拆成了三个完全解耦的层数据采集层Collector这是唯一需要你配置的部分。你写一个servers.yaml文件定义每台服务器的类型、地址、认证方式。例如- name: 海康威视-录像中心 type: http url: http://192.168.1.100:80/DeviceManager/login auth: username: admin password: 12345 timeout: 10 - name: 防火墙-生产区 type: http url: https://10.0.2.5:3010dn-v2/ insecure_skip_verify: true - name: Docker Registry type: http url: https://registry.internal/v2/ auth: username: readonly password: token123注意这里没有“安装 agent”“配置 exporter”“修改服务代码”等任何动作。你只是把已有的访问方式告诉它。这个 YAML 文件通过-v $(pwd)/servers.yaml:/app/config/servers.yaml挂载进容器Komari 启动时读取它之后所有探测行为都基于此。你改了 YAMLdocker restart komari就生效无需重新构建镜像。状态计算层Engine这是 Komari 的核心二进制文件komari-engine。它不依赖外部数据库所有状态存在内存 map 中它用 Go 的time.Ticker控制探测频率默认 30 秒可配它用net/http.Client和golang.org/x/crypto/ssh库分别实现 HTTP 和 SSH 探测。关键点在于它把每次探测的结果抽象成一个统一结构体type Status struct { Name string json:name Type string json:type // http, ssh, script Status string json:status // online, offline, warning LastChecked time.Time json:last_checked Message string json:message // HTTP 200 OK, SSH timeout, curl: (7) Failed to connect Latency float64 json:latency // ms }这个结构体是 Komari 前后端通信的唯一契约。前端只认这个 JSON后端只吐这个 JSON。没有 ORM、没有 schema migration、没有版本兼容性问题。Web 展示层UI这是一个纯静态的 Vue 3 SPA打包后所有资源HTML/CSS/JS都内置在 Docker 镜像的/app/ui/目录下。当你docker run启动容器komari-server进程启动一个极简的 Go HTTP server用net/http.FileServer直接把/app/ui/当作根目录 serve 出来。它不调用任何后端 API——所有数据都来自/api/status这个单一 endpoint而这个 endpoint 返回的就是上面那个Status结构体的数组。这意味着你可以用curl http://localhost:8080/api/status直接看到原始数据你可以用任何前端框架重写 UI只要它请求/api/status并渲染这个 JSON你甚至可以把这个 JSON 保存下来用 Excel 做离线分析。它把“展示”这件事降维到了最低成本。这三层解耦带来的直接好处是你今天用 Docker 部署明天想改成 systemd 服务只需把komari-engine二进制拷到服务器上写个 service 文件再配个 Nginx 反代/api/statusUI 层完全不用动。我有个客户就在 Windows Server 上用 WSL2 运行komari-engine用 IIS 反向代理到 Vue UI效果一模一样——因为 Komari 从没绑定 Docker。3. 核心细节与实操要点从零开始5 分钟搞定 20 台服务器的统一视图3.1 最小可行配置三步完成首次部署别被“服务器一多就乱”吓住Komari 的入门门槛低到反常识。我用一台刚重装的 Ubuntu 22.04 虚拟机实测从空白系统到看到 Web 界面全程 4 分 32 秒第一步装 Docker仅需 1 分钟你搜的“ubuntu安装docker”“docker安装教程”里那些 apt update、add-apt-repository 的步骤Komari 官方推荐跳过。直接用 Docker 官方的一键脚本curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER # 退出终端重进让 group 生效提示这一步之所以能跳过复杂配置是因为 Komari 镜像本身是 multi-arch 的amd64/arm64且不依赖特定内核模块。你不用管“virtualization support not detected docker desktop failed to start because v”这种 Windows 报错——Linux 下 Docker Engine 就是原生运行的。第二步准备 servers.yaml2 分钟新建一个目录比如~/komari-config在里面创建servers.yaml。先放两台最典型的设备一台本地 Docker Registry对应你搜的“docker镜像仓库”“registry-ui 提供 web 界面”一台模拟的“防火墙 Web 界面”对应“登入防火墙web界面”“3010dn-v2怎么配置web界面”# ~/komari-config/servers.yaml - name: 本地Registry type: http url: http://localhost:5000/v2/ # 注意这里用 http因为本地 registry 默认不启 HTTPS timeout: 5 - name: 防火墙测试站 type: http url: https://httpbin.org/status/200 # 用 httpbin 模拟防火墙 Web 界面返回 200 即表示“在线” insecure_skip_verify: true # 因为 httpbin 的证书是自签名的跳过验证注意这里故意用了httpbin.org而不是真实设备是为了让你第一次启动就能看到绿色方块。真实环境中把url改成你的https://10.0.2.5:3010dn-v2/即可insecure_skip_verify: true就是为了解决你搜的“3010dn-v2怎么配置web界面”里常见的证书警告问题。第三步启动容器15 秒回到终端执行docker run -d \ --name komari \ -p 8080:8080 \ -v ~/komari-config/servers.yaml:/app/config/servers.yaml \ --restartunless-stopped \ ghcr.io/komari/komari:latest实测心得--restartunless-stopped这个参数必须加。我第一次没加服务器重启后 Komari 没自启导致连续两天以为监控挂了其实是自己忘了配。另外ghcr.io/komari/komari:latest是官方镜像国内用户如果遇到pull access denied可以换成docker pull registry.cn-hangzhou.aliyuncs.com/komari/komari:latest阿里云镜像站同步每日更新。启动后浏览器打开http://localhost:8080你会看到两个方块左边“本地Registry”是绿色在线右边“防火墙测试站”也是绿色。鼠标悬停显示Latency: 42ms和Last checked: 2024-06-12 08:45:22。这就是 Komari 的最小闭环——它已经按你写的 YAML每 30 秒去探一次这两个 URL并把结果画了出来。3.2 接入真实设备的关键技巧绕过海康威视、防火墙、Docker Registry 的“反人类”设计现在把servers.yaml里的模拟地址换成真实设备。这才是体现 Komari 价值的地方——它专治各种“文档没写清楚”“界面不标准”“API 不规范”的遗留系统。接入海康威视老版存储服务器ivms-4200 场景你搜的“海康威视老版存储服务器ivms-4200搭建本地监控录像”其 Web 管理界面有个致命问题登录页是http://IP/DeviceManager/login但登录成功后会跳转到一个带随机 session ID 的 URL比如http://IP/DeviceManager/xxxxx/index.html。Komari 不需要登录它只探测“登录页是否能打开”。但 ivms-4200 默认关闭了匿名访问必须带用户名密码。正确配置是- name: 海康威视-录像中心 type: http url: http://192.168.1.100/DeviceManager/login auth: username: admin password: your_password # 关键加 headers模拟浏览器 headers: User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Accept: text/html,application/xhtmlxml,application/xml;q0.9,*/*;q0.8 timeout: 15实操心得海康设备对 User-Agent 敏感不加这个 header有些固件版本会返回 403。timeout设为 15 秒因为老设备响应慢。我试过 5 秒超时结果它永远显示“offline”实际设备是好的——这是踩过的最大坑。接入 3010dn-v2 防火墙Web 界面场景你搜的“3010dn-v2怎么配置web界面”其 Web 管理页默认启用 HTTPS但证书是自签名的且端口是3010dn-v2这种非标准命名实际是 3010 端口。Komari 的insecure_skip_verify: true就是为此而生- name: 防火墙-生产区 type: http url: https://10.0.2.5:3010/ # 注意这里写 3010不是 3010dn-v2后者是产品型号端口就是 3010 insecure_skip_verify: true # 如果防火墙启用了 IP 白名单确保运行 Komari 的服务器 IP 在白名单里注意事项3010dn-v2 的 Web 界面有时会返回 302 重定向到/login.jspKomari 默认跟随重定向所以url写根路径即可。如果重定向后页面是登录表单返回 200 但内容是 HTMLKomari 仍判为“online”因为 HTTP 状态码是 200。接入 Docker Registry镜像仓库场景你搜的“docker镜像仓库”“registry-ui 提供 web 界面”其 v2 API 的健康检查端点是/v2/但需要 Basic Auth。Komari 支持- name: 私有Registry type: http url: https://registry.internal/v2/ auth: username: readonly password: your_registry_token # 如果 registry 启用了 TLS且证书是私有 CA 签发的加 # ca_file: /app/config/ca.crt # 并把 ca.crt 文件也挂载进来实操心得Docker Registry 的/v2/端点返回的是 JSON{errors:[{code:UNAUTHORIZED,message:authentication required}]}但这仍是 HTTP 200 状态码Komari 判为“online”。如果你要区分“服务在线但未授权”和“服务彻底宕机”可以加一个expected_status_code: 200字段Komari 1.3 支持这样只有返回 200 且 body 包含errors才算成功。3.3 高级配置实战用 SSH 和脚本接管那些“没有 Web 界面”的设备Komari 的 HTTP 探测覆盖了 80% 的场景但总有例外比如一台只开放 SSH 的老交换机或者一台运行着自研 Python 服务、只暴露/health端点但没配反向代理的树莓派。这时就要用到它的 SSH 和 Script 探测。SSH 探测给无 Web 界面的设备“装眼睛”假设你有一台 Cisco 交换机IP 是192.168.1.200SSH 用户名cisco密码cisco。你想知道它是否在线以及 CPU 是否过载。Komari 的 SSH 探测不是登录进去执行复杂命令而是执行一个极简的、能快速返回的命令- name: 核心交换机 type: ssh host: 192.168.1.200 port: 22 username: cisco password: cisco # 执行一个 1 秒内必返回的命令 command: show version | include uptime # 或者更轻量的 echo ok timeout: 8原理解析show version | include uptime在 Cisco IOS 上会输出类似uptime is 4 weeks, 2 days, 15 hours, 30 minutesKomari 只检查命令是否执行成功exit code 0不解析输出内容。所以即使交换机负载高只要 SSH 通它就显示绿色。如果你想检查 CPU可以用show processes cpu | include CPU但要注意命令耗时——超过timeout就判为 offline。Script 探测用任意语言写“自定义健康检查”这是 Komari 最灵活的机制。你写一个 Bash/Python/Go 脚本放在宿主机上Komari 以root权限执行它并捕获 stdout/stderr。脚本返回 0 表示 online非 0 表示 offline。例如检查一台树莓派上的 ivms-4200 录像服务是否在运行#!/bin/bash # ~/komari-config/check_ivms.sh # 检查 ivms-4200 进程是否存在 if pgrep -f ivms-4200 /dev/null; then echo ivms-4200 process running exit 0 else echo ivms-4200 process not found exit 1 fi然后在servers.yaml中引用- name: 树莓派-录像服务 type: script script_path: /app/config/check_ivms.sh # 注意script_path 是容器内的路径所以要挂载整个目录启动容器时加挂载-v ~/komari-config:/app/config。这样脚本就在容器里可执行了。实操心得Script 探测的威力在于它能把任何你能用命令行判断的状态变成 Komari 的一个方块。我用它检查过docker ps | grep nginx确认容器运行、curl -s http://localhost:8080/actuator/health | jq -r .statusSpring Boot 健康检查、甚至ping -c1 192.168.1.100 /dev/null echo ok纯网络连通性。它不替代专业监控但它让“一眼看清全局状态”这件事变得前所未有的简单。4. 实操过程全记录从 3 台到 87 台我是如何用 Komari 搭建家庭实验室统一视图的4.1 第一阶段3 台核心设备建立信心Day 1我的起点是一台 Ubuntu 22.04 笔记本作为控制中心、一台树莓派 4B跑 ivms-4200 录像、一台二手 Dell R720装 Proxmox跑多个 Docker 容器。目标很明确先让这三台“看得见”。Ubuntu 笔记本用 HTTP 探测http://localhost:8080Nginx 默认页树莓派用 SSH 探测pi192.168.1.150执行uptimeDell R720用 HTTP 探测https://192.168.1.100:8006Proxmox Web 界面servers.yaml如下- name: 笔记本-Nginx type: http url: http://localhost:8080 - name: 树莓派-Uptime type: ssh host: 192.168.1.150 username: pi password: raspberry command: uptime - name: R720-Proxmox type: http url: https://192.168.1.100:8006 insecure_skip_verify: true启动后三个方块全绿。我故意拔掉树莓派网线30 秒后它变红插回去再 30 秒变绿。那一刻我知道Komari 的心跳机制是可靠的。它不靠“最后一次成功时间”做缓存而是实打实的实时探测。4.2 第二阶段扩展到 20 台覆盖异构环境Day 3加入新成员2 台海康威视 DS-8100HS-S 硬盘录像机ivms-4200、1 台 3010dn-v2 防火墙、3 台 Docker Registry开发/测试/生产、5 台树莓派分别跑 Home Assistant、Pi-hole、Node-RED 等。这时servers.yaml开始变长我学会了分组和注释# 监控设备 - name: 海康-机房A type: http url: http://192.168.1.101/DeviceManager/login auth: {username: admin, password: xxx} headers: {User-Agent: Mozilla/5.0} - name: 海康-机房B type: http url: http://192.168.1.102/DeviceManager/login auth: {username: admin, password: xxx} headers: {User-Agent: Mozilla/5.0} # 网络设备 - name: 防火墙-主路由 type: http url: https://192.168.1.1:3010/ insecure_skip_verify: true # 容器平台 - name: Registry-Dev type: http url: https://registry-dev.internal/v2/ auth: {username: dev, password: token1} - name: Registry-Prod type: http url: https://registry-prod.internal/v2/ auth: {username: prod, password: token2} # IoT 设备 - name: Home Assistant type: http url: http://192.168.1.200:8123/api/ # HA 的 /api/ 端点需要 token但健康检查用 /api/ 就够了关键经验我把所有auth密码都用环境变量代替避免明文写在 YAML 里docker run -d \ -e KOMARI_HTTP_AUTH_ADMIN_PASSWORDxxx \ -e KOMARI_HTTP_AUTH_DEV_PASSWORDtoken1 \ ...然后在 YAML 中写password: ${KOMARI_HTTP_AUTH_ADMIN_PASSWORD}。Komari 启动时会自动替换环境变量。这解决了你搜的“docker安装”“docker部署springboot项目”里常见的密钥管理痛点。4.3 第三阶段87 台设备构建企业级视图Day 7最终清单包括12 台海康设备IPC 和 NVR、6 台防火墙3010dn-v2 和其他型号、3 台 Docker Registry、1 台 Harbor、5 台 Jenkins、2 台 GitLab、1 台 Nexus、1 台 SonarQube、1 台 Portainer、1 台 Watchtower、1 台 Uptime Kuma对我用 Komari 监控 Uptime Kuma、还有 53 台树莓派和旧笔记本跑各种 Python 脚本如 ivms-4200 状态轮询、温度监控、UPS 状态上报。此时servers.yaml有 427 行。我把它拆成多个文件用include语法Komari 1.4 支持# servers.yaml include: - groups/monitoring.yaml - groups/network.yaml - groups/containers.yaml - groups/iot.yaml每个子文件按功能分组维护起来清晰多了。Web 界面也自动按group字段分组显示在 YAML 中加group: 监控设备即可。性能实测数据87 台设备探测间隔 30 秒平均延迟 128ms最高单次探测耗时 2.3 秒一台响应慢的海康 NVR。Komari 进程内存 68MBCPU 0.9%。对比之下Uptime Kuma同样用途在 50 台设备时内存就飙到 320MBCPU 常驻 12%。Komari 的轻量是它能撑起这个规模的根本原因。5. 常见问题与排查技巧实录那些官方文档不会写的“血泪教训”5.1 典型问题速查表问题现象可能原因排查命令解决方案所有方块显示offline但curl http://localhost:8080/api/status返回空数组servers.yaml路径挂载错误或文件权限不对docker exec -it komari ls -l /app/config/确保servers.yaml在容器内路径正确且chmod 644某台 HTTP 设备一直offline但浏览器能打开服务器返回了 302 重定向且重定向目标不可达curl -v http://ip/url在 YAML 中加follow_redirects: false或改用重定向后的 URLSSH 探测失败日志显示dial tcp: lookup xxx on 127.0.0.11:53: no such host容器 DNS 解析失败docker exec -it komari nslookup your-hostname在docker run时加--dns 8.8.8.8或用 IP 代替 hostname界面加载缓慢Chrome 显示Waiting for localhost...容器内komari-engine进程卡死docker exec -it komari ps aux | grep komaridocker restart komari检查servers.yaml是否有语法错误YAML 缩进错误最常见海康设备显示warningMessage 是HTTP 401 Unauthorized认证失败但 HTTP 状态码是 401Komari 默认判为 warningcurl -u admin:pass http://ip/login检查用户名密码是否正确或加expected_status_code: 2005.2 独家避坑技巧技巧一用curl -v模拟 Komari 探测当某台设备状态异常不要猜直接用 Komari 的方式复现# 模拟 HTTP 探测带 auth 和 header curl -v -u admin:12345 -H User-Agent: Mozilla/5.0 http://192.168.1.100/DeviceManager/login # 模拟 SSH 探测 ssh -o ConnectTimeout5 -o BatchModeyes pi192.168.1.150 uptime如果curl或ssh命令在宿主机上失败Komari 一定失败。这是最高效的定位手段。技巧二开启调试日志但别常开启动容器时加环境变量-e KOMARI_LOG_LEVELdebug它会输出每台设备的探测详情DEBU[0001] HTTP probe for 海康-机房A: GET http://192.168.1.101/DeviceManager/login - 200 OK, latency142ms DEBU[0002] SSH probe for 树莓派-Uptime: ssh pi192.168.1.150 uptime - exit code 0, latency89ms注意debug 日志会迅速占满磁盘只在排查时开问题解决后立刻关掉docker exec komari kill -USR1 1可动态降级日志级别。技巧三为“间歇性失联”设备加retry_count有些老设备如某些固件版本的海康偶尔会丢包导致单次探测失败。Komari 支持重试- name: 海康-老旧型号 type: http url: http://192.168.1.103/DeviceManager/login retry_count: 3 retry_delay: 2这样 Komari 会最多尝试 3 次每次间隔 2 秒只要有一次成功就判为 online。这比让它一直显示红色更符合实际运维需求。技巧四用expected_body做内容级健康检查HTTP 探测默认只看状态码但有些服务返回 200 却内容异常比如 ivms-4200 登录页返回 200 但 body 是{error:session_expired}。Komari 支持正则匹配响应体- name: IVMS-API-健康端点 type: http url: http://192.168.1.150:8000/api/health