Komari 探针部署与运维指南

本文记录探针 Komari 的部署、配置与常见问题排错。

1. 资源占用实测数据#

监控环境共三台节点。Agent 部署于 Server A/B/C，Server 端部署于 Server A。持续运行约 8 天 6 小时后的资源消耗如下：

节点	组件	运行时长 (etime)	物理内存 (RES)	虚拟内存 (VIRT)	瞬时 CPU	累计 CPU 时间 (TIME+)
Server C	Agent	8天6小时	17.9 MB	1.23 GB	0.0%	27m37s
Server B	Agent	8天6小时	12.4 MB	1.23 GB	0.0%	23m24s
Server A	Agent	8天6小时	12.6 MB	1.23 GB	0.0%	33m38s
Server A	服务端	8天6小时	34.6 MB	1.34 GB	0.0%	6m34s

原始监测命令与输出片段#

1
# 服务端（Server A）
2
username@ServerA:~$ top -p $(pgrep -d',' komari)
3
    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
4
  49316 komari    20   0 1343280  34636  11980 S   0.0   1.7   6:34.61 komari
5

6
username@ServerA:~$ ps -p 49316 -o etime=
7
 8-06:11:49
8

9
# Agent（Server A）
10
username@ServerA:~$ top -p $(pgrep -d',' agent)
11
    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
12
  49459 root      20   0 1234116  12664   5140 S   0.0   0.6  33:38.01 agent
13

14
username@ServerA:~$ ps -p 49459 -o etime=
15
 8-06:04:41
16

17
# Agent（Server B）
18
username@ServerB:~$ top -p $(pgrep -d',' agent)
19
    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
20
2379623 root      20   0 1234116  12400   4992 S   0.0   2.6  23:24.26 agent
21

22
username@ServerB:~$ ps -p 2379623 -o etime=
23
 8-06:05:52
24

25
# Agent（Server C）
26
username@ServerC:~$ top -p $(pgrep -d',' agent)
27
    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
28
  13527 root      20   0 1233860  17940   6520 S   0.0   1.8  27:37.69 agent
29

30
username@ServerC:~$ ps -p 13527 -o etime=
31
 8-06:03:06

注：VIRT 较大为 Go 运行时地址空间预留，不代表物理内存消耗。

2. 拓扑架构#

1
┌─────────────────────────────────────────────────────┐
2
│                  Server A                       │
3
│  Komari Server (使用 SQLite 数据库)               │
4
│  Caddy 反代 -> https://monitor.example.com       │
5
└─────────────────────────────────────────────────────┘
6
         ▲                        ▲
7
         │ 上报数据                │ 上报数据
8
         │                        │
9
┌────────┴──────────┐   ┌─────────┴───────────┐
10
│ Server B         │   │ Server C          │
11
│ Komari Agent     │   │ Komari Agent      │
12
└───────────────────┘   └─────────────────────┘

3. 服务端部署 (Server A)#

3.1 创建隔离用户与数据目录#

1
# 创建无登录权限的系统用户
2
sudo useradd -r -s /usr/sbin/nologin komari
3

4
# 初始化工作目录
5
sudo mkdir -p /opt/komari/data
6
sudo chown -R komari:komari /opt/komari
7
sudo chmod 755 /opt/komari

3.2 部署二进制文件#

自 Komari Releases 下载~~最新发行版~~ v1.25 版本（无后缀名，是裸二进制）：

TIP
近期 1.25 之后的版本存在争议，表现为硬盘占用过大，因此暂不做推荐
see komari #620、komari #612、komari #620

1
cd /opt/komari
2
sudo wget https://github.com/komari-monitor/komari/releases/download/1.2.5/komari-linux-amd64
3
sudo mv komari-linux-amd64 komari
4
sudo chmod +x komari
5
sudo chown komari:komari komari

3.3 配置 Systemd 服务与沙箱权限#

创建服务配置，限制其系统访问权限：

1
sudo nano /etc/systemd/system/komari.service

1
[Unit]
2
Description=Komari Monitor Service
3
After=network.target
4

5
[Service]
6
Type=simple
7
User=komari
8
Group=komari
9
ExecStart=/opt/komari/komari server -l 127.0.0.1:25774
10
WorkingDirectory=/opt/komari
11
Restart=always
12
RestartSec=5
13

14
# 权限沙箱化配置
15
CapabilityBoundingSet=
16
NoNewPrivileges=yes
17
ProtectHome=yes
18
ProtectSystem=strict
19
ReadWritePaths=/opt/komari/data
20
PrivateTmp=yes
21
PrivateDevices=yes
22
ProtectKernelTunables=yes
23
ProtectKernelModules=yes
24
ProtectControlGroups=yes
25

26
[Install]
27
WantedBy=multi-user.target

参数说明：

User=komari：非 root 运行

CapabilityBoundingSet=：丢弃所有特权能力

NoNewPrivileges=yes：禁止提权

ProtectSystem=strict + ReadWritePaths=/opt/komari/data：系统只读，数据目录可写

ProtectHome=yes：无法访问 /home

PrivateDevices=yes：无法访问物理设备

监听 127.0.0.1：不暴露到公网

3.4 启动与初始化#

1
sudo systemctl daemon-reload
2
sudo systemctl enable --now komari.service
3

4
# 获取日志中打印的首次启动随机管理密码
5
sudo journalctl -u komari.service --no-pager -l | tail -30

如未获取到密码，可通过命令行手动重置 admin 密码：

1
sudo -u komari /opt/komari/komari chpasswd -p <YOUR_PASSWORD> -d /opt/komari/data/komari.db

TIP
chpasswd 不支持 -u 参数（默认修改 admin 用户）。
关于修改面板用户名密码：
1.2.5 (e446bee)面板的更新用户功能同时修改用户名和密码时，会清空所有 session 导致当前用户被登出，且前端 401 处理不完善，页面显示裸错误。建议分两步操作：

先只改用户名 → 保存（session 保持有效）

再只改密码 → 保存（会被登出，重新登录即可）

如果已经 401 了，恢复方法：
Terminal window
1
sudo systemctl stop komari
2
sudo -u komari sqlite3 /opt/komari/data/komari.db "DELETE FROM sessions;"
3
sudo systemctl start komari

3.5 Caddy 反代与 DNS 配置#

编辑 /etc/caddy/Caddyfile，配置反代域名：

1
monitor.example.com {
2
    reverse_proxy 127.0.0.1:25774
3
}

重启 Caddy：

1
sudo systemctl restart caddy

接着在域名解析商处将 monitor 子域名指向 Server A 的公网 IP。

添加 A 记录：

类型	名称	值	代理
A	`monitor`	Server A 的公网 IP	开启（CDN 代理）

3.6 生成自动发现密钥#

4. 客户端部署 (Agent)#

在各被监控节点（含服务端节点本机）上执行一键安装

进入 Admin 面板后台，服务器 -> 添加节点

勾选 安装选项

展开列表后：

勾选 禁用远程控制，禁用网页端 SSH 及远程执行命令权限
勾选 禁用自动更新，停用客户端自动更新
勾选 从网卡获取IP地址，通过本地网卡读取 IP
勾选 排除特定网卡，输入 lo 过滤环回网卡数据
勾选 采集间隔(秒)，输入 5 或 10 秒
勾选 网络统计月重置日，输入你的机器账单日

最后点击最底部的 复制，即得到 Agent 的安装命令

【完】

5. Theme#

进入 Admin 面板后台，设置 -> 主题管理，即可更换主题

推荐安装主题：

sanrokamlan-prog

komari-theme-Glassmorphism

Waiting for api.github.com...

00K

Waiting...

6. 常用维护命令#

1
# 服务端生命周期管理
2
sudo systemctl [start|stop|restart|status] komari
3
sudo journalctl -u komari -f
4

5
# 客户端生命周期管理
6
sudo systemctl [start|stop|restart|status] komari-agent
7
sudo journalctl -u komari-agent -f
8

9
# 服务端手动升级
10
cd /opt/komari && sudo systemctl stop komari
11
sudo wget -O komari https://github.com/komari-monitor/komari/releases/latest/download/komari-linux-amd64
12
sudo chmod +x komari && sudo chown komari:komari komari
13
sudo systemctl start komari

客户端卸载与残留清理#

官方卸载命令存在缓存残留，若更换服务端重建数据库，Agent 缓存的旧 token 失效，如果不手动删除，Agent 会一直 401。

1
sudo systemctl stop komari-agent
2
sudo systemctl disable komari-agent
3
sudo rm -f /etc/systemd/system/komari-agent.service
4
sudo systemctl daemon-reload
5

6
# 彻底清理二进制和 token 缓存文件
7
sudo rm -rf /opt/komari/agent
8
sudo rm -f /opt/komari/auto-discovery.json    # 必须清理的旧 Token 缓存
9
sudo rm -f /opt/komari/agent.yml
10
sudo rm -f /opt/komari/net_static.json

7. 排错与问题对照#

7.1 服务端常见问题#

表现	原因	对策
启动报 `read-only file system`	Systemd 沙箱只读限制	确认服务文件包含 `ReadWritePaths=/opt/komari/data`
启动报 `permission denied`	`/opt/komari/data` 目录属主为 root	执行 `chown -R komari:komari /opt/komari/data`
面板修改密码后提示 401	全局 Session 销毁导致登出	建议改用户名与改密码分步保存，或通过 CLI 命令修改
开启“私有站点”新设备无法打开	未登录用户的 `/api/me` 接口被拦截	新设备首次连接前先关闭私有站点，完成登录后再行开启

关于私有站点（Private Site）： 面板设置中的「私有站点」选项开启后，新设备首次访问时不会显示登录框（/api/me 等公开接口被拦截），导致 Error: Failed to fetch node data。已登录的设备不受影响。

不开私有站点也没有实质风险，未登录用户最多只能看到版本号和站点名，节点数据、资源监控等敏感信息均需登录后才能查看

7.2 客户端常见问题#

表现	原因	对策
`bash: /dev/fd/63: No such file...`	`sudo` 状态下不支持 `*<()` 进程替换	采用 `wget -qO- \| sudo bash` 管道连接模式安装
重装或迁移服务端后持续报 401	缓存了已失效的旧 Token 校验文件	停止服务并清理 `rm -f /opt/komari/auto-discovery.json`