Komari 探针安装教程（Cloudflare + Nginx）

xiaoyunhai2025-11-032025-11-03

目标：让 Komari 服务端运行在 https://tz.202221.xyz（Cloudflare 代理），并在服务器上部署 Komari Agent 上报数据。全文逐步解释命令作用，保证照做即可完成部署。

0. 前提与环境

系统：Debian / Ubuntu（示例基于 Debian）
域名：tz.202221.xyz 已托管在 Cloudflare（橙云 = 代理，灰云 = 仅 DNS）
Web：Nginx 负责反代本机后端（Komari 服务端监听 127.0.0.1:25774）
权限：具备 sudo 权限

术语说明

服务端面板：Komari 的 Web 控制台，已经通过 Nginx + HTTPS 部署。

Agent / 探针：安装在被监控节点上的客户端，通过面板签发的 token 建立连接。

1. 核对域名解析与服务器 IP

1	dig +short tz.202221.xyz A

作用：确认 tz.202221.xyz 当前解析到的 IPv4 地址。启用 Cloudflare 代理后通常会返回 Cloudflare Anycast IP。

1	curl -4 ifconfig.co

作用：查看当前服务器的公网 IPv4。若与上一条不同且为真实地址，表示域名已走 Cloudflare 代理，可继续配置 Origin 证书方案。

2. 配置 Nginx 反向代理与 HTTPS

2.1 新建站点配置

1	sudo nano /etc/nginx/sites-enabled/komari

作用：创建或编辑 Nginx 站点配置。

写入以下内容（已适配 Cloudflare Origin 证书与 WebSocket）：

server {
    listen 80;
    listen [::]:80;
    server_name tz.202221.xyz;
    return 301 https://$host$request_uri;  # 强制跳转到 HTTPS
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;  # 建议在 server 块开启 HTTP/2

    server_name tz.202221.xyz;

    # 第 3 节生成的 Cloudflare Origin 证书
    ssl_certificate     /etc/ssl/cf-origin/tz.202221.xyz.crt;
    ssl_certificate_key /etc/ssl/cf-origin/tz.202221.xyz.key;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:25774;  # 反代 Komari 服务端
        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_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;   # WebSocket 支持
        proxy_set_header Connection "upgrade";

        proxy_buffering off;  # 关闭代理缓冲，降低延迟
    }
}

如果看到 listen ... http2 is deprecated，说明应将 http2 写成 http2 on; 并放在 server {} 内，如上所示。

2.2 清理零宽字符（推荐）

1	sudo cp /etc/nginx/sites-enabled/komari /etc/nginx/sites-enabled/komari.bak

作用：备份配置文件。

1	sudo perl -i -pe 's/\x{FEFF}\|\x{200B}\|\x{200C}\|\x{200D}//g' /etc/nginx/sites-enabled/komari

作用：移除 UTF-8 BOM / 零宽字符，避免出现 unknown directive 报错。

1	grep -nP --color=always $'(\x{FEFF}\|\x{200B}\|\x{200C}\|\x{200D})' /etc/nginx/sites-enabled/komari \|\| echo "OK: no zero-width chars"

作用：确认文件已无隐形字符。

2.3 测试并重载

1	sudo nginx -t

作用：检测 Nginx 配置语法。

1	sudo systemctl reload nginx

作用：平滑重载 Nginx，让新配置生效。

3. 使用 Cloudflare Origin 证书（Full Strict）

因域名启用 Cloudflare 代理，推荐使用 Cloudflare Origin Certificate：

浏览器 → Cloudflare：使用 Cloudflare Edge 证书

Cloudflare → 源站：使用 Origin 证书（需在 Cloudflare 控制台把 SSL 模式设为 Full (strict)）

3.1 在 Cloudflare 控制台生成证书

进入 SSL/TLS → Origin Server → Create certificate
Hostnames：填写 tz.202221.xyz
Key type：RSA（默认即可）
有效期：默认（Cloudflare 会提供长期证书）
下载 证书（.pem/.crt） 与 私钥（.key）

3.2 上传到服务器并设定权限

1	sudo mkdir -p /etc/ssl/cf-origin

作用：创建存储 Origin 证书的目录。

1	sudo nano /etc/ssl/cf-origin/tz.202221.xyz.crt

作用：粘贴 Cloudflare 提供的证书内容（以 -----BEGIN CERTIFICATE----- 开头）。

1	sudo nano /etc/ssl/cf-origin/tz.202221.xyz.key

作用：粘贴 Origin 私钥内容（以 -----BEGIN PRIVATE KEY----- 开头）。

1
2
3

sudo chown root:root /etc/ssl/cf-origin/tz.202221.xyz.{crt,key}
sudo chmod 644 /etc/ssl/cf-origin/tz.202221.xyz.crt
sudo chmod 600 /etc/ssl/cf-origin/tz.202221.xyz.key

作用：限制证书与私钥权限，私钥仅 root 可读。

3.3 关联到 Nginx

第 2 步已写入：

1 2	ssl_certificate /etc/ssl/cf-origin/tz.202221.xyz.crt; ssl_certificate_key /etc/ssl/cf-origin/tz.202221.xyz.key;

1	sudo nginx -t && sudo systemctl reload nginx

作用：验证配置并重载 Nginx。

3.4 Cloudflare 端设置

Cloudflare 控制台 SSL/TLS → Overview：切换为 Full (strict)
作用：强制校验证书链与域名匹配，防止伪造证书导致的安全风险。

4. 验证服务端与回源

1	ss -ltnp \| grep 25774 \|\| sudo lsof -iTCP:25774 -sTCP:LISTEN

作用：确认 Komari 服务端监听 127.0.0.1:25774。

1	curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:25774/

作用：检查后端接口是否返回 2xx/3xx 状态码。

1	curl -vk --resolve tz.202221.xyz:443:你的服务器IP https://tz.202221.xyz/

作用：直接连接源站测试 HTTPS 是否可用。由于 Origin 证书仅供 Cloudflare 信任，此处使用 -k 忽略证书校验属正常。

5. 安装 Komari Agent（探针）

需要的参数

-e / --endpoint：Komari 面板地址，如 https://tz.202221.xyz

-t / --token：在面板创建节点后获得的令牌（敏感，安装后建议轮换）

5.1 推荐：管道安装（避免 sudo 与 `<()` 冲突）

1 2	curl -fsSL https://raw.githubusercontent.com/komari-monitor/komari-agent/main/install.sh \ \| sudo bash -s -- -e https://tz.202221.xyz -t '你的TOKEN'

curl -fsSL：静默下载脚本，失败时返回非零状态；-L 支持重定向。
sudo bash -s --：将脚本通过管道交给 root 执行；-s 表示脚本来自标准输入，-- 之后是脚本参数。
-e/-t：传入面板地址与节点 token，脚本会写入 systemd 服务并启动 Agent。

5.2 备选：先保存再执行

1
2
3

curl -fsSL -o /tmp/komari-agent-install.sh \
  https://raw.githubusercontent.com/komari-monitor/komari-agent/main/install.sh
sudo bash /tmp/komari-agent-install.sh -e https://tz.202221.xyz -t '你的TOKEN'

作用：若不习惯管道执行，可先下载到本地再以 root 运行。

5.3 请勿与 `<()` 混用

1 2	# 反例：会出现 “bash: /dev/fd/63: No such file or directory” sudo bash <(curl -sL https://raw.githubusercontent.com/.../install.sh) -e ... -t ...

原因：<( ) 依赖临时文件描述符，sudo 默认会关闭，导致脚本无法读取。

6. 验证 Agent 运行状态

1	sudo systemctl status komari-agent --no-pager -l

作用：查看 Agent systemd 服务是否 active (running)。

1	sudo journalctl -u komari-agent -n 200 --no-pager

作用：检查最近日志，确认已连接到 https://tz.202221.xyz 并开始上报。

若在面板看到节点在线、心跳与信息刷新，则安装成功。

7.（可选）服务端管理与优化

7.1 重置面板管理员密码

1	sudo /opt/komari/komari chpasswd -d /opt/komari/data/komari.db -p '新密码'

作用：修改 admin 管理员密码，执行后需重启服务端生效。

1	sudo systemctl restart komari

作用：重启 Komari 服务端（若运行在 Docker，可使用 docker restart 容器名）。

7.2 统一时区（示例：东京）

1	sudo timedatectl set-timezone Asia/Tokyo

作用：调整系统时区，便于日志与排班阅读。

7.3 在 Cloudflare 代理下保留真实客户端 IP（可选）

在 Nginx 全局 http {} 或站点 server {} 中加入：

real_ip_header CF-Connecting-IP;
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;
set_real_ip_from 103.31.4.0/22;
set_real_ip_from 141.101.64.0/18;
set_real_ip_from 108.162.192.0/18;
set_real_ip_from 190.93.240.0/20;
set_real_ip_from 188.114.96.0/20;
set_real_ip_from 197.234.240.0/22;
set_real_ip_from 198.41.128.0/17;
set_real_ip_from 162.158.0.0/15;
set_real_ip_from 104.16.0.0/13;
set_real_ip_from 104.24.0.0/14;
set_real_ip_from 172.64.0.0/13;
set_real_ip_from 131.0.72.0/22;

1	sudo nginx -t && sudo systemctl reload nginx

作用：让应用记录真实访客 IP，而非 Cloudflare 节点 IP。

8. 常见问题速查

unknown directive "..."：文件夹存在零宽字符或 BOM。按 2.2 步骤清理，或使用 nl -ba /etc/nginx/sites-enabled/komari | sed -n '1,80p' 带行号排查。
listen ... http2 is deprecated：把 listen 443 ssl http2; 拆成 listen 443 ssl; + http2 on;。
invalid number of arguments in "http2"：确认写成 http2 on; 且置于 server {}。
[emerg] cannot load certificate：证书路径错误或权限不足，重新检查 3.2 设置。
Cloudflare 5xx：
- 526：Full (strict) 下证书与域名不匹配。使用正确的 Origin 或公认证书。
- 525：TLS 握手失败，多数是证书/权限/Nginx 443 未启动。
- 521/522：源站拒绝或超时，检查 Nginx、防火墙、后端进程。
bash: /dev/fd/*：使用了 sudo + <() 组合，改用 5.1 / 5.2 的方式。

9. 收尾与快速检查

面板地址：https://tz.202221.xyz（Cloudflare 代理 + Full strict）
默认管理员：admin（若已重置，以新密码为准）
节点名称：仅作备注，建议包含区域/机房配置等信息，随时可改
安全建议：Agent 安装完成后在面板轮换 token；服务器仅放行 80/443

至此，Komari 服务端 + Nginx/Cloudflare + Agent 已全部打通。可将本文作为交接文档或贴到群友/论坛，祝使用顺利。

附录 A：使用 Let’s Encrypt（acme.sh）签发证书（可选）

适用于不使用 Cloudflare Origin 证书，或需要公认浏览器信任的场景。若域名在 Cloudflare 且保持橙云代理，HTTP-01 可能失败，可临时改为灰云或改用 DNS-01。

A. 准备验证目录

1 2	sudo mkdir -p /var/www/letsencrypt sudo chown www-data:www-data /var/www/letsencrypt

作用：为 ACME 挑战准备 webroot 目录。

B. 在 80 端口 server 块中新增验证 location（放在 location / 前）

location ^~ /.well-known/acme-challenge/ {
    root /var/www/letsencrypt;
    default_type "text/plain";
    try_files $uri =404;
}

作用：确保验证文件可被直接访问。

C. 重载 Nginx

1	sudo nginx -t && sudo systemctl reload nginx

作用：让验证路径生效。

D. 安装与初始化 acme.sh

1
2
3

curl https://get.acme.sh | sh -s email=你的邮箱
alias acme.sh=~/.acme.sh/acme.sh
acme.sh --set-default-ca --server letsencrypt

作用：安装 ACME 客户端、设置别名、切换到 Let’s Encrypt CA。

E. 申请证书（替换成你的域名）

1	acme.sh --issue -d tz.202221.xyz -k ec-256 --webroot /var/www/letsencrypt

作用：使用 ECDSA 256 位算法签发证书，挑战文件存放在 webroot。

F. 安装证书并自动重载 Nginx

sudo mkdir -p /etc/ssl/komari
acme.sh --install-cert -d tz.202221.xyz --ecc \
  --key-file       /etc/ssl/komari/privkey.key \
  --fullchain-file /etc/ssl/komari/fullchain.cer \
  --reloadcmd      "systemctl reload nginx"

作用：将证书落到固定路径，并在续期后自动重载 Nginx。

G. 切换 Nginx 证书路径（若从 Cloudflare Origin 改用 LE 证书）

1 2	ssl_certificate /etc/ssl/komari/fullchain.cer; ssl_certificate_key /etc/ssl/komari/privkey.key;

作用：让 Nginx 使用新的公认证书。

若仍希望保持橙云代理，并自动续期，可改用 acme.sh + Cloudflare DNS-01（需要 Cloudflare API Token 并在 ~/.acme.sh/account.conf 配置），流程与 HTTP-01 类似但无需临时改灰云。

附录 B：部署 Komari 面板的替代方式（按需选择）

1）官方一键安装脚本（systemd）

1
2
3

curl -fsSL https://raw.githubusercontent.com/komari-monitor/komari/main/install-komari.sh -o install-komari.sh
chmod +x install-komari.sh
sudo ./install-komari.sh

作用：自动安装 / 升级 / 卸载 Komari，并创建 systemd 服务。

2）Docker 部署

mkdir -p ./data && cd ./
docker run -d \
  -p 25774:25774 \
  -v $(pwd)/data:/app/data \
  --name komari \
  ghcr.io/komari-monitor/komari:latest
# 查看默认账号密码（首次启动会输出）
docker logs komari

作用：使用容器运行面板，数据存放在 ./data 方便备份与迁移。

3）下载二进制 + systemd（进阶）

# 以 amd64 为例，版本号可按需调整
curl -L -o /usr/local/bin/komari \
  https://github.com/komari-monitor/komari/releases/download/1.0.9/komari-linux-amd64
chmod +x /usr/local/bin/komari

sudo tee /etc/systemd/system/komari.service >/dev/null <<'EOF'
[Unit]
Description=Komari Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/komari server -l 127.0.0.1:25774
WorkingDirectory=/opt/komari
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo mkdir -p /opt/komari
sudo systemctl daemon-reload
sudo systemctl enable --now komari

作用：直接运行官方二进制，由 systemd 托管，监听到本机 25774 供 Nginx 反代。

附录 C：在面板创建节点并获取 Agent 命令

打开面板 服务 → 节点，点击 添加节点。节点名称仅作备注，可随时修改。
点击 下载 / 复制命令，获取包含 -e（面板地址）与 -t（节点令牌）的安装命令。
推荐使用第 5.1 节的管道安装方式，避免 sudo 与 <() 造成的文件描述符问题。

1 2	curl -fsSL https://raw.githubusercontent.com/komari-monitor/komari-agent/main/install.sh \ \| sudo bash -s -- -e https://tz.202221.xyz -t '你的TOKEN'

作用：以 root 权限执行官方脚本，自动写入配置并启动 Agent。

验证

1 2	sudo systemctl status komari-agent --no-pager -l sudo journalctl -u komari-agent -n 200 --no-pager

作用：确认服务已连接面板并开始上报。

附录 D：界面美化（Mochi 主题示例，可选）

面板中打开 设置 → 主题管理，选择 上传主题。
从 GitHub 下载第三方主题压缩包（如 Mochi），上传并启用。
（可选）在 设置 → 站点 → 自定义头部 加入额外 JS/CSS。请注意性能与安全。

提醒：第三方主题来自社区，务必选择可信来源，并关注后续升级兼容性。