mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4mobile wallpaper 5mobile wallpaper 6
Profile Image of the Author
黎明
公告
欢迎来到黎明的小站。本站用于堆叠平时的技术痕迹，记录一些值得留存的想法。
标签
2398 字
6 分钟
搭建“黎明の鸡窝”：基于 Komari 的轻量级服务器监控接入指南
2026-05-23
2026-05-24
运维记录
Komari Monitor
/
探针
/
Nginx
/
Ops

最近给手头几台小服务器补了一套统一监控。之前每台机器各跑各的服务，状态靠临时 SSH 上去看：有的跑博客，有的跑 Docker 服务，有的跑机器人，有的跑 API 网关。机器数量不多，但一旦分散到不同云厂商、不同架构、不同端口策略里，就会很容易出现一种尴尬局面：明明都是自己的机器，却没有一个一眼能看到全局健康状态的地方。

这次最后选了 Komari。它的思路比较简单：一个自托管面板，加若干轻量 agent。面板负责展示，agent 负责上报 CPU、内存、磁盘、网络、在线状态等指标。整体足够轻，适合塞进 1G 内存级别的小机器里。

本文记录一下这次部署的完整流程。所有真实域名、IP、SSH 用户、密钥名和 token 都会做脱敏处理，只保留架构、命令形态和踩坑过程，方便以后自己复盘，也给类似场景的人一个参考。

最终效果#

部署完成后的形态大概是这样：

监控面板：https://monitor.example.com
面板部署：Docker Compose
公网入口：Nginx + Let's Encrypt HTTPS
后端端口：127.0.0.1:25774
Agent 数量：5 台服务器
Agent 权限：禁用 web ssh，只做监控上报

被监控节点覆盖了几类环境：

节点系统架构用途
Node AUbuntu 24.04amd64Docker 服务
Node BUbuntu 24.04amd64Blog / Komari 面板
Node CUbuntu 24.04arm64Bot 服务
Node DUbuntu 24.04amd64API / Docker 服务
Node EAlibaba Cloud Linux 3amd64额外云服务器

真实 IP 和 SSH 信息没有写进文章。实际运维时我另外保存在本地私有记录里，和公开博客分开。

预览地址:黎明の鸡窝

image-20260524200841421

部署时间线#

这次过程不算复杂，但中间有几个坑比较典型：DNS 刚开始没解析、Nginx Basic Auth 会影响 agent、自动发现 key 的配置格式、固定 token 启动方式、以及某台国内云服务器下载 GitHub release 卡住。

gantt title Komari 监控部署时间线 (2026-05-23) dateFormat YYYY-MM-DD HH:mm axisFormat %H:%M section 面板准备 服务器资源与端口检查 :done, p1, 2026-05-23 18:03, 8m Docker 与 Compose 安装 :done, p2, 2026-05-23 18:13, 4m Komari 容器部署 :done, p3, 2026-05-23 18:17, 3m section HTTPS 暴露 子域名 DNS 解析 :done, n1, 2026-05-23 18:18, 1m Nginx 反代配置 :done, n2, 2026-05-23 18:19, 2m Certbot 证书签发 :done, n3, 2026-05-23 18:19, 2m section Agent 接入 自动发现批量注册 :done, a1, 2026-05-23 18:27, 3m 修复 AD Key JSON 格式 :done, a2, 2026-05-23 18:28, 2m 固定 token 启动 :done, a3, 2026-05-23 18:35, 3m 新增额外云服务器 :done, a4, 2026-05-23 18:40, 6m section 收尾 清空自动发现 Key :done, s1, 2026-05-23 18:44, 1m 本地文档记录 :done, s2, 2026-05-23 18:50, 8m

架构设计#

最终的流量关系非常朴素：

flowchart TD User[浏览器访问 monitor.example.com] --> DNS[DNS A 记录] DNS --> Nginx[Nginx 443 / HTTPS] Nginx --> Komari[Komari 容器<br>127.0.0.1:25774] Komari --> DB[(SQLite<br>/opt/komari/data)] NodeA[Node A Agent] -->|HTTPS + token| Nginx NodeB[Node B Agent] -->|HTTPS + token| Nginx NodeC[Node C Agent] -->|HTTPS + token| Nginx NodeD[Node D Agent] -->|HTTPS + token| Nginx NodeE[Node E Agent] -->|HTTPS + token| Nginx

核心原则是：

  1. Komari 后端不直接暴露公网端口：容器只绑定 127.0.0.1:25774。
  2. 公网只开放 80/443：统一由 Nginx 接入和终结 TLS。
  3. Agent 走 HTTPS 上报：每个 agent 使用自己的 token。
  4. 禁用 web ssh：面板不承担远程命令入口，只做监控。
为什么不直接暴露 25774？

监控面板本身不应该裸露在公网随机端口上。即使应用有登录鉴权，也建议通过 Nginx 统一处理 HTTPS、日志、限流、证书续期和未来可能的访问控制。后端监听 127.0.0.1 是一个很低成本但很有效的边界。

一、选择部署方式：Docker#

Komari 支持源码、二进制和 Docker 部署。这里选 Docker，理由很直接：

  • 面板所在机器已经有 Nginx，Docker 可以把 Komari 和博客环境隔离开；
  • 升级时只需要 docker compose pull && docker compose up -d；
  • 数据目录明确，备份只需要盯住 /opt/komari/data；

源码部署不是不行，但需要关心 Go、Node、构建产物和 systemd 服务。我的目标是稳定跑面板，不是开发 Komari 本体，所以 Docker 更合适。

二、部署 Komari 面板#

面板目录放在：

/opt/komari

Compose 文件形态如下，密码处用占位符代替：

services:
  komari:
    image: ghcr.io/komari-monitor/komari:latest
    container_name: komari
    restart: unless-stopped
    ports:
      - "127.0.0.1:25774:25774"
    environment:
      ADMIN_USERNAME: "admin"
      ADMIN_PASSWORD: "<INITIAL_ADMIN_PASSWORD>"
    volumes:
      - ./data:/app/data

启动：

cd /opt/komari
sudo docker compose pull
sudo docker compose up -d

验证本机访问：

curl -s -D - http://127.0.0.1:25774/ -o /tmp/komari.html
head -20 /tmp/komari.html

此时公网还访问不到 25774，这是预期行为。

三、Nginx 反代与 HTTPS#

DNS 里添加一个子域名，例如：

monitor.example.com -> 面板服务器公网 IP

Nginx 配置大致如下：

server {
    server_name monitor.example.com;


    location ^~ /.well-known/acme-challenge/ {
        root /var/www/html;
    }


    location / {
        proxy_pass http://127.0.0.1:25774;
        proxy_http_version 1.1;
        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;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

启用站点并签证书：

sudo ln -s /etc/nginx/sites-available/komari /etc/nginx/sites-enabled/komari
sudo nginx -t
sudo systemctl reload nginx


sudo certbot --nginx -d monitor.example.com --redirect

签完后确认：

curl -I https://monitor.example.com/
curl -I http://monitor.example.com/

预期结果：

HTTPS：200
HTTP：301 -> HTTPS

Basic Auth 最后为什么去掉了#

一开始我在 Nginx 外层加了 Basic Auth，思路是“面板登录前再挡一层”。这对浏览器访问没问题，但会让 agent 上报和 WebSocket 连接多一层认证适配成本。

后来考虑到 Komari 本身已经有登录，agent 也使用 token 鉴权，而这个面板不是公众注册服务，最后去掉了 Nginx Basic Auth，只保留：

HTTPS + Komari 登录 + Agent token + 后端端口不公网暴露

如果未来要再加强，可以考虑只对管理后台路径加访问控制，或使用 Tailscale / WireGuard 做内网访问。

四、批量接入 Agent#

Komari agent 的基本安装方式是下载二进制，然后用 systemd 常驻运行。为了批量接入多台服务器，我先临时启用了自动发现 key。

第一次注册时的启动参数类似：

/opt/komari-agent/agent \
  -e https://monitor.example.com \
  --auto-discovery <TEMP_AD_KEY> \
  --disable-web-ssh \
  --interval 5.0 \
  --info-report-interval 15

注册成功后，agent 会在本地生成：

/opt/komari-agent/auto-discovery.json

里面包含该节点自己的 uuid 和 token。这个文件需要保护好，恢复 agent 时很有用。

之后我把 systemd 改成固定 token 启动：

ExecStart=/opt/komari-agent/agent -e https://monitor.example.com -t <NODE_TOKEN> --disable-web-ssh --interval 5.0 --info-report-interval 15

并清空服务端的自动发现 key。这样以后即使临时注册 key 泄露，也不能再新增节点。

不要长期保留自动发现 Key

自动发现 key 是为了快速注册节点，不适合作为长期开放入口。批量接入完成后，应该清空服务端 key，并让每个 agent 使用自己的固定 token 启动。

五、踩坑记录#

坑 1：DNS 还没解析，证书不能急着签#

刚开始子域名还没有解析到面板服务器。这个时候如果直接跑 Certbot，会因为 ACME 验证失败而中断。

比较稳的顺序是：

  1. 先部署 Komari 容器，只监听 127.0.0.1；
  2. 配好 Nginx 站点模板；
  3. 等 DNS 查询能返回正确 IP；
  4. 再启用站点并签证书。

检查命令：

getent hosts monitor.example.com

Windows 本地也可以：

Terminal window
Resolve-DnsName monitor.example.com

坑 2：Nginx Basic Auth 文件权限导致 500#

外层 Basic Auth 初次配置后，浏览器带认证访问却返回 500。Nginx 错误日志显示：

open() "/etc/nginx/.htpasswd-komari" failed (13: Permission denied)

原因是 .htpasswd 文件权限太紧，Nginx worker 用户读不到。

修复方式：

sudo chgrp www-data /etc/nginx/.htpasswd-komari
sudo chmod 640 /etc/nginx/.htpasswd-komari
sudo nginx -t
sudo systemctl reload nginx

后来我移除了 Basic Auth，这个坑也就不再影响最终架构。但它很典型：Nginx 配置正确不等于运行时权限正确。

坑 3：自动发现 Key 写进数据库时必须是 JSON 字符串#

为了临时启用自动发现，我直接改了 Komari SQLite 里的配置项。第一次把 key 写成了裸字符串：

auto_discovery_key = abcdef...

结果 agent 注册时报错：

Failed to get AutoDiscovery Key: invalid character 'x' after top-level value

后来发现 Komari 的 configs.value 存的是 JSON 字面量，字符串值应该带 JSON 引号：

auto_discovery_key = "abcdef..."

如果通过脚本写入，应该使用 json.dumps() 之类的方法，而不是手搓字符串。

坑 4：移除 auto-discovery 参数后，Agent 变成空 token#

注册完成后，我一开始想“把启动参数里的自动发现 key 删掉，更安全”。于是直接移除了：

--auto-discovery <TEMP_AD_KEY>

结果面板里所有节点都显示离线。服务端日志里全是：

GET /api/clients/report?token= 401
POST /api/clients/uploadBasicInfo?token= 401

也就是说，agent 没有自动读取本地 auto-discovery.json 里的 token，而是用空 token 上报。

正确做法是从本地配置取出 token，然后显式写进 systemd：

-t <NODE_TOKEN>

修完后，日志恢复为：

Basic info uploaded successfully
WebSocket connected

面板在线数也恢复正常。

坑 5：国内云服务器下载 GitHub Release 卡住#

其中一台国内云服务器直连 GitHub 下载 agent release 时卡住，只下载了几 MB 就一直不动。

解决思路不是硬等，而是复用已经下载好的同架构二进制：

已有 amd64 节点 /opt/komari-agent/agent
  -> scp 到本地
  -> scp 到下载困难的节点
  -> chmod +x
  -> 手动创建 systemd service

这个办法很适合小规模自用环境。agent 是单文件二进制，只要架构一致，就很方便迁移。

六、常用运维命令#

面板状态：

cd /opt/komari
sudo docker compose ps
sudo docker compose logs -f
sudo docker stats komari

Nginx 检查：

sudo nginx -t
sudo systemctl reload nginx

证书检查：

sudo certbot certificates

Agent 状态：

systemctl is-active komari-agent
journalctl -u komari-agent -n 80 --no-pager
grep '^ExecStart=' /etc/systemd/system/komari-agent.service

检查面板端口是否只监听本机：

ss -tulpn | grep 25774

预期：

127.0.0.1:25774

七、备份重点#

面板所在机器需要重点备份：

/opt/komari/docker-compose.yml
/opt/komari/data
/etc/nginx
/etc/letsencrypt

每个 agent 节点建议备份：

/etc/systemd/system/komari-agent.service
/opt/komari-agent/auto-discovery.json

其中最关键的是面板的 SQLite 数据和每台 agent 的 token 配置。agent 二进制本身可以重新下载或从同架构机器复制。

恢复优先级

真正重要的是数据和身份：面板数据库、证书、Nginx 配置、agent token。Docker 镜像、agent 二进制、安装脚本都可以重建。

总结#

这次 Komari 部署本身并不难，真正容易出问题的是“边界条件”：

  • 面板端口应该只绑定本机；
  • Nginx 反代 WebSocket 需要保留 Upgrade 和 Connection 头；
  • DNS 生效前不要急着签证书；
  • 自动发现 key 注册后要及时关闭；
  • agent 最终最好用固定 token 启动；
  • 国内云服务器下载 GitHub release 不稳定时，可以复制已有二进制。

最终这套监控系统的复杂度很低，但带来的收益很直接：几台机器的在线状态、资源负载、磁盘空间、网络流量都能在一个页面里看到。对个人小规模服务器来说，这已经足够实用。

以后再加机器时，流程也很明确：临时开自动发现，注册成功，改固定 token，清空自动发现 key，最后补进备份文档。这样既方便扩容，也不会把长期入口留在外面。

分享

如果这篇文章对你有帮助，欢迎分享给更多人！

搭建“黎明の鸡窝”：基于 Komari 的轻量级服务器监控接入指南
https://github.com/example/blog
作者
黎明
发布于
2026-05-23
许可协议
CC BY-NC-SA 4.0

部分信息可能已经过时

“如果今天服务器炸了怎么办？”：我的五台服务器 Restic 自动备份落地记
博客国内外双节点部署与全链路架构解耦
相关文章 智能推荐
1
“如果今天服务器炸了怎么办？”：我的五台服务器 Restic 自动备份落地记
运维记录 记录如何为五台个人服务器搭建基于 Restic 与 DigitalOcean Spaces 的自动备份体系，包括 SQLite/PostgreSQL 一致性快照、systemd timer、Telegram HTML 通知、阿里云 SSH 中继、恢复验证与成本控制。
2
用 Restic 备份本地却在疯狂吃磁盘？一次去重备份的本地瘦身实录
运维记录 记录在使用 Restic 对多台个人服务器进行定时增量备份的过程中，如何发现并清理本地冗余 of 日期后缀备份文件，探讨“快照型备份工具”与“传统打包备份”的思想碰撞，并彻底排查由于环境变量错配导致的第一台机器误报异常问题。
3
博客国内外双节点部署与全链路架构解耦
运维记录 记录如何将个人博客重构为国内外双服务器部署、通过阿里云 DNS 智能解析分流、解耦 Cloudflare R2 静态资源以及使用 GitHub Actions 实现双端自动化投递的完整实操细节。
4
数据结构：栈和队列的互相转化
Algorithm 用两个栈实现队列，用一个队列实现栈：重点不是背代码，而是理解顺序如何被翻转、保存和维护。
5
数据结构：最小栈
Algorithm 最小栈的核心不是多会一个 API，而是给栈的每一层保存一份最小值快照，让所有操作都在 O(1) 时间内完成。
随机文章 随机推荐
1
算法学习
Algorithm 2026-04-28
2
博客国内外双节点部署与全链路架构解耦
运维记录 2026-05-19
3
链表：分隔链表
Algorithm 2026-05-11
4
“如果今天服务器炸了怎么办？”：我的五台服务器 Restic 自动备份落地记
运维记录 2026-05-24
5
克制的艺术：Claude 设计语言网页拆解
Frontend 2026-02-14
豫ICP备2026007336号
© 2026 黎明. All Rights Reserved. / RSS / Atom / Sitemap
Powered by Astro & Mizuki  Version 9.0

目录