2026-10-19

喵星之旅-狂奔的兔子-Komari 监控面板全流程操作手册

项目概述

Komari 是一个轻量级的服务器监控面板，支持 Docker 部署，提供服务器监控、远程控制、流量统计、计费管理等核心功能。适合中小规模服务器集群管理。

架构设计

┌─────────────────────┐        WebSocket v2         ┌──────────────────────┐
│  Komari 面板（服务端）  │ ◄──────────────────────► │  Komari Agent（客户端） │
│  Docker 容器          │        带 token           │  每台服务器一个         │
│  nginx 反代 + CF 代理  │                          │  上报 CPU/内存/磁盘/流量  │
└─────────────────────┘                          └──────────────────────┘

服务端：Docker 容器（内部端口 127.0.0.1:<端口>），nginx 反代对外端口，可套 Cloudflare
Agent 端：每台被监控服务器装一个轻量二进制，通过 WebSocket v2 长连面板
监控内容：CPU / 内存 / 磁盘 / 网络流量 / 在线状态；额外能力：网页终端、命令剪切板、离线通知
数据存储：默认 SQLite，历史默认 30 天

服务端部署

1. 部署前选择

决策项	建议	原因
面板放置	选带宽稳定、24h 在线的机器	面板挂了所有节点都失联
对外端口	独立端口（如 8443）	Komari 前端用绝对路径 `/`，不支持子路径部署
域名	独立子域名（推荐）或独立端口	关系应用构建层

2. Docker 部署

docker run -d --name komari \
  -p 127.0.0.1:25774 \
  -v /opt/komari/data:/app/data \
  --restart unless-stopped \
  ghcr.io/komari-monitor/komari:1.5.x

面板只绑 127.0.0.1，所有外部访问走 nginx 反代。

3. Nginx 反向代理配置

server {
    listen 443 ssl;
    server_name komari.example.com;

    ssl_certificate     /path/to/cert.crt;
    ssl_certificate_key /path/to/cert.key;

    location / {
        proxy_pass http://127.0.0.1:25774;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }
}

4. Cloudflare 配置要点

开启橙云（代理）
确保 Bot Fight Mode 关闭（避免误判）
若访问出现 403，在面板「设置」中关闭 CORS 检查
证书建议用通配符或域名级，避免 IP 直连导致证书校验失败

客户端 Agent 安装

1. 正确下载方式

✅ 从 GitHub 官方下载：

1 2	curl -fsSL https://raw.githubusercontent.com/komari-monitor/komari-agent/refs/heads/main/install.sh \ -o /tmp/install-komari.sh

❌ 不要从面板下载：https://<面板>/assets/install.sh 返回的是 HTML 首页

2. 标准安装命令

1
2
3

sh /tmp/install-komari.sh \
  --endpoint https://komari.example.com:443 \
  --token <从面板获取的Token>

3. 证书校验失败处理

如果使用 IP 直连，证书只签域名不包含 IP，需要添加 -u 跳过校验：

sh /tmp/install-komari.sh \
  -u \
  --endpoint https://<面板IP>:25774 \
  --token <Token>

4. 服务管理

1
2
3

systemctl restart komari-agent
systemctl status komari-agent
journalctl -u komari-agent -n 20

面板日常操作

1. 节点管理

添加节点：面板 → 「节点/Clients」→ 添加节点 → 复制安装命令
编辑节点：修改价格、计费周期、流量上限、到期时间
远程控制：在 Dashboard 点击「WebSSH」直接操作服务器
删除节点：注意路由是 /api/admin/client/<UUID>/remove

2. 工具提示

节点名称建议用服务器简称
年付机器 billing_cycle = 365 + traffic_limit = 月流量值
如果不需要远程控制，安装时加 --disable-web-ssh

API 操作示例

1. 获取认证 Token

BASE=https://komari.example.com:443
TOKEN=$(curl -sk $BASE/api/login -X POST \
  -H "Content-Type: application/json" \
  -d '{"username":"<管理员>","password":"<密码>"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['set-cookie']['session_token'])")

2. 添加客户端

curl -sk "$BASE/api/admin/client/add" -X POST \
  -H "Cookie: session_token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"<节点名称>","expired_at":"2028-03-20T00:00:00Z","price":50,"currency":"USD"}'

常见问题

1. 浏览器访问 403

检查 CF Bot Fight Mode 是否关闭
在面板设置中关闭 CORS 检查

2. 日志查看

journalctl -u komari-agent -n 20
期望看到：Get IPV4 Success → Basic info uploaded successfully → WebSocket connected using v2 protocol

3. 主题兼容性

第三方主题与特定面板版本可能不兼容，切换时注意版本匹配。

本文档基于 Komari 官方文档整理，版本：1.5.x

更新记录

2026-10-19：整理 Komari 监控面板全流程操作手册