Komari 安装教程

1. 架构说明

Komari 分两块：

• 面板（Panel）：只装在一台主机上，Web 看监控、管理节点 token。
• 探针（Agent）：每台要监控的机器都装，向面板上报 CPU / 内存 / 流量等。

2. 官方项目与下载（GitHub）

所有镜像 / 二进制请优先从官方仓库获取：

• 面板仓库： https://github.com/komari-monitor/komari
• 探针仓库： https://github.com/komari-monitor/komari-agent
• 面板 Docker 镜像： ghcr.io/komari-monitor/komari:latest （见面板仓库 / GHCR）
• 探针 Release 页： https://github.com/komari-monitor/komari-agent/releases

常用 Linux 探针直链（示例版本，建议始终点 latest）

Release 资产名固定，版本号随更新变化。可用 latest 跳转：

• komari-agent-linux-amd64
• komari-agent-linux-arm64
• komari-agent-linux-arm
• komari-agent-linux-386

3. 主机安装面板（Docker）

需要 Docker + Compose。目录可自定，示例用 /opt/komari-panel。

3.1 compose 示例

mkdir -p /opt/komari-panel/data
cd /opt/komari-panel

cat > .env <<'EOF'
ADMIN_PASSWORD=CHANGE_ME_STRONG_PASSWORD
EOF

cat > docker-compose.yml <<'EOF'
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: ${ADMIN_PASSWORD}
    volumes:
      - ./data:/app/data
    # 若与 Caddy 同 Docker 网络，取消下面注释并加入 caddy 网络
    # networks:
    #   - caddy_default

# networks:
#   caddy_default:
#     external: true
EOF

docker compose up -d
docker compose ps
docker compose logs --tail=50

3.2 本机验证

curl -I http://127.0.0.1:25774
# 期望 HTTP 200 / 3xx

4. Caddy 反代（HTTPS + WebSocket）

探针与面板通信依赖 WebSocket。反代需转发 Upgrade / Connection，并关闭响应缓冲。

4.1 Caddyfile

monitor.yourdomain.com {
	# 面板在同一 Docker 网络时用服务名：
	# reverse_proxy komari:25774 { ... }

	# 面板只监听宿主机 127.0.0.1:25774 时用：
	reverse_proxy host.docker.internal:25774 {
		header_up Host {host}
		header_up X-Real-IP {remote_host}
		header_up Connection {http.request.header.Connection}
		header_up Upgrade {http.request.header.Upgrade}
		flush_interval -1
	}
}

若 Caddy 非 Docker、直接装在宿主机：

monitor.yourdomain.com {
	reverse_proxy 127.0.0.1:25774 {
		header_up Host {host}
		header_up X-Real-IP {remote_host}
		header_up Connection {http.request.header.Connection}
		header_up Upgrade {http.request.header.Upgrade}
		flush_interval -1
	}
}

4.2 Nginx 参考（可选）

server {
    listen 443 ssl http2;
    server_name monitor.yourdomain.com;

    # ssl_certificate     /path/fullchain.pem;
    # ssl_certificate_key /path/privkey.pem;

    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";
        proxy_read_timeout 3600s;
        proxy_buffering off;
    }
}

4.3 重载

# Caddy Docker 示例
docker compose exec -T caddy caddy reload --config /etc/caddy/Caddyfile

# 或宿主机
# systemctl reload caddy
# nginx -t && systemctl reload nginx

浏览器打开 https://monitor.yourdomain.com，用 compose 里的管理员账号登录。

5. DNS 解析

给面板域名加 A 记录，指向主机公网 IP。

• 类型：A
• 名称：monitor（完整即 monitor.yourdomain.com）
• 内容：your.server.public.ip
• 代理：若用 Cloudflare，建议先 DNS only；若开代理需允许 WebSocket。

6. 探针机安装

探针机只跑 agent。二进制从 GitHub Releases 下载。

6.1 在面板拿 token

1. 登录 https://monitor.yourdomain.com
2. 添加节点 / 创建探针，复制该节点的 token
3. 每台机器用自己的 token，不要混用

6.2 一键安装（systemd 机器）

# 1) 选架构下载（示例 amd64）
mkdir -p /opt/komari
curl -fL -o /opt/komari/agent \
  "https://github.com/komari-monitor/komari-agent/releases/latest/download/komari-agent-linux-amd64"
# arm64:
# curl -fL -o /opt/komari/agent \
#   "https://github.com/komari-monitor/komari-agent/releases/latest/download/komari-agent-linux-arm64"
chmod +x /opt/komari/agent

# 2) 写入服务（替换 YOUR_TOKEN）
cat > /etc/systemd/system/komari-agent.service <<'EOF'
[Unit]
Description=Komari Agent
After=network.target

[Service]
Type=simple
ExecStart=/opt/komari/agent -e https://monitor.yourdomain.com -t YOUR_TOKEN --disable-web-ssh --exclude-nics lo,docker0,br-,veth
WorkingDirectory=/opt/komari
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now komari-agent
systemctl status komari-agent --no-pager

6.3 无 systemd（部分容器 / 精简系统）

# 若提示 Text file busy：先停旧进程
pkill -f /opt/komari/agent || true
sleep 1

# 前台测试
/opt/komari/agent -e https://monitor.yourdomain.com -t YOUR_TOKEN --disable-web-ssh

# 后台 + 开机（crontab）
nohup /opt/komari/agent -e https://monitor.yourdomain.com -t YOUR_TOKEN --disable-web-ssh \
  --exclude-nics lo,docker0,br-,veth \
  >/var/log/komari-agent.log 2>&1 &

(crontab -l 2>/dev/null | grep -v 'komari/agent'; \
  echo '@reboot sleep 15; /opt/komari/agent -e https://monitor.yourdomain.com -t YOUR_TOKEN --disable-web-ssh --exclude-nics lo,docker0,br-,veth >/var/log/komari-agent.log 2>&1') | crontab -

6.4 参数说明

• -e：面板地址，如 https://monitor.yourdomain.com
• -t：该节点 token（面板生成）
• --disable-web-ssh：关闭远程终端（推荐）
• --exclude-nics：排除 lo / docker 网卡，流量统计更干净

7. Token 说明

• token 由面板为节点生成，不是随便编的字符串。
• 每台探针应使用自己的 token。
• 换 token：改 systemd 的 ExecStart -t ... 后 daemon-reload && restart。
• 装探针时把命令里的 YOUR_TOKEN / yourdomain.com 换成你的真实值。

nano /etc/systemd/system/komari-agent.service
systemctl daemon-reload
systemctl restart komari-agent
journalctl -u komari-agent -n 30 --no-pager

8. 常见问题

Q：探针不上线？

• 探针机：curl -I https://monitor.yourdomain.com
• token 是否完整、无空格
• ps aux | grep komari 进程是否在跑
• 反代是否正确转发 WebSocket

Q：GitHub 下载失败？

• 用代理，或在能访问 GitHub 的机器下载后 scp
• Release 页： komari-agent/releases

Q：Text file busy

agent 正在运行无法覆盖。先 pkill -f /opt/komari/agent，下到 agent.new 再 mv。

Q：探针机要装 Caddy 吗？

不用。 面板 + 反代只在主机；探针只上报。

Q：官方文档入口

• github.com/komari-monitor/komari
• github.com/komari-monitor/komari-agent