教程合集
Komari 部署教程
Komari · Caddy · Cloudflare

Komari 监控面板部署教程

Docker 部署 Komari 主控,用自编译 Caddy(Cloudflare DNS 插件)反代, 配合 Cloudflare DNS-01 签发证书——全程不用关闭小黄云,源站真实 IP 全程隐藏。

适用Komari 监控面板
难度入门
阅读—
更新2026-10-17

用 Docker 跑 Komari 主控,前面架一台自编译 Caddy(带 Cloudflare DNS 插件)做反代,证书走 DNS-01 挑战签发——全程不用关闭小黄云,源站 IP 自始至终藏在 Cloudflare 后面。

整体架构

架构
访客 / Agent
   │  https://monitor.232777.xyz(443)
   ▼
Cloudflare CDN(小黄云 · 完全严格)
   │  回源 → 源站 :8443
   ▼
Caddy(自编译 · Cloudflare DNS 插件)
   │  reverse_proxy → 127.0.0.1:25774
   ▼
Komari 主控(Docker 容器)

为什么 HTTPS 端口是 8443

443 通常已经被 sing-box(VLESS Reality)这类代理占用,Caddy 不能再绑。而 Cloudflare 代理只认这几个 HTTPS 端口:443 / 2053 / 2083 / 2087 / 2096 / 8443。随手写个 1234 之类的端口,小黄云一点亮网站就打不开——证书倒是能签下来(DNS-01 不依赖入站端口),但访客流量根本到不了源站,现象会非常迷惑。8443 是不需要任何额外配置就能用的选择。

不要用 1234 这类任意端口 caddy validate 通过、有证书,不代表网站能打开。端口不在 Cloudflare 支持列表里,小黄云开启后访客只会看到连接失败,Agent 也连不上。

开工清单

本教程里凡是要你填自己信息的地方,都用 高亮 标出,例如面板域名 monitor.232777.xyz、API Token YOUR_CF_TOKEN。看到就替换,不要原样复制。

不用先粘到别处改:代码框可以直接编辑 每个代码框右上角有编辑 / 还原 / 复制三个按钮。点编辑,框里就变成可以打字的状态,把高亮占位符换成你的域名、Token、密码,再点复制拿到的就是改好的内容,直接粘进服务器就能跑。改完按 Esc(或 Ctrl/⌘ + Enter)退出编辑态。
改动只存在当前这个浏览器标签页里:点还原回到教程原文,关掉页面再打开一律是原始内容。终端输出示例(浅色的那种框)不给编辑,那些是给你对照结果的。

先确认端口和解析,别等 Caddy 装完才发现 8443 被占了。

确认端口空闲

bash
# 8443 应该没有任何输出(空闲);443 被 sing-box 占用是正常的
sudo ss -lntp | grep -E ':(443|8443)'

域名解析

去 Cloudflare → DNS → 记录,给面板域名加一条 A 记录指向源站公网 IP(小黄云先保持灰色也可以,下一节会点亮),然后验证解析已生效:

bash
nslookup monitor.232777.xyz 1.1.1.1
两层防火墙都要处理 云服务器控制台的安全组和系统里的 ufw 是两道门,只开一道,8443 照样不通。第 6 节会给出只放行 Cloudflare 回源的 ufw 规则,安全组里对应放行 8443/tcp 即可。

先把域名侧准备好:给 Caddy 办一个只能改 DNS 的 API Token,点亮小黄云,把加密模式调到完全(严格)。

创建 API Token

登录 Cloudflare 后台 → 右上角头像 → 我的个人资料 → API 令牌 → 创建令牌 → 找到 编辑区域 DNS 点"使用模板" → 区域资源选 包括 → 特定区域 → 你的域名 → 继续并创建。

Token 只显示一次 创建完立刻复制保存到本地,后面写 Caddyfile 要用。模板自带的 Zone:DNS:Edit 权限刚好够签发证书,不要用 Global API Key。
DNS 记录点亮小黄云

回到域名管理 → DNS → 记录,面板域名(如 monitor)的 A 记录指向源站 IP,把云朵点成橙色(已代理)。从这一步起,访客看到的都是 Cloudflare 的 IP。

加密模式设为完全(严格)

SSL/TLS → 概述 → 选择 完全(严格)/ Full (Strict)。这要求源站也必须有受信证书——Caddy 稍后会自动申请 Let's Encrypt 证书,正好满足,Cloudflare 到源站这一段同样是加密的。

为什么小黄云可以全程开着 传统 HTTP-01 挑战需要 Let's Encrypt 直接访问源站 80 端口,会被 CDN 挡住。本教程用 DNS-01:Caddy 拿着 API Token 去 Cloudflare 加一条 TXT 记录完成验证,签发过程完全不碰入站流量,所以代理开着也不影响。

Docker 一把梭。注意端口只绑 127.0.0.1——面板只允许本机 Caddy 反代,这是整套"隐藏源站"设计的前提。

创建目录并编写 compose.yaml
bash
# 1. 建目录并进入
mkdir -p /opt/komari && cd /opt/komari

# 2. 写配置(nano / vim 均可)
nano compose.yaml
yamlcompose.yaml
services:
  komari:
    image: ghcr.io/komari-monitor/komari:latest
    container_name: komari
    restart: unless-stopped
    ports:
      # 只绑本机!写成 25774:25774 会把登录页直接暴露在公网
      - "127.0.0.1:25774:25774"
    volumes:
      - ./data:/app/data
    environment:
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=YourSecurePassword123
      - TZ=Asia/Shanghai
启动并验证
bash
docker compose up -d && docker compose ps
docker logs komari | tail -n 5
终端输出
[INFO] Komari is running on http://0.0.0.0:25774
[INFO] Application timezone is set to 'Asia/Shanghai'.
25774 必须只绑 127.0.0.1 写成 25774:25774 会监听所有网卡,任何人用 http://源站IP:25774 就能直达登录页——Cloudflare 和 Caddy 全被绕过。注意 Docker 的端口映射不受 ufw 管控,绑回环地址是唯一的根本解法。
账号密码只在首次初始化时生效 ADMIN_USERNAME / ADMIN_PASSWORD 是"初始"账号,容器第一次启动后就不再读取。以后想改密码去面板里改,改环境变量没用。
到这里应该 docker compose ps 显示 komari 为 Up,日志里有 Komari is running。先别登录,域名和反代配好之后再进。

官方 Caddy 不带 Cloudflare DNS 插件。正确顺序:先按官方方式装 Caddy(拿到 systemd 服务和配置目录),再把二进制换成带插件的版本。

添加官方仓库并安装 Caddy

这一步会创建 caddy 系统服务、/etc/caddy/Caddyfile 和 caddy 运行用户,后面都要用。

bash
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install -y caddy
下载带 Cloudflare 插件的二进制
bash
# 先停掉刚装好的官方版(后面要替换它的二进制)
sudo systemctl stop caddy

# -L 跟随重定向;p 参数指定要打进的插件
curl -L -o caddy "https://caddyserver.com/api/download?os=linux&arch=amd64&p=github.com/caddy-dns/cloudflare"
ARM 机器 把 arch=amd64 换成 arch=arm64,其余不变。
检查文件大小,确认下载成功

这一步不能省:官方接口偶发报错,只会返回几 KB 的错误页。

bash
ls -lh caddy
终端输出
-rw-r--r-- 1 root root 44M 10月 16 23:30 caddy
# 正常应在 40MB–50MB 之间;只有几 KB 说明下载失败,重试或稍后再试
替换系统里的 Caddy 二进制
bash
chmod +x caddy && sudo mv caddy /usr/bin/caddy
/usr/bin/caddy version
apt upgrade 会覆盖它 以后系统升级 Caddy 时,/usr/bin/caddy 会被官方包刷回不带插件的版本。升级后重做本节第 2–4 步,或者用 apt-mark hold caddy 把版本锁住。
编写 Caddyfile
caddyfile/etc/caddy/Caddyfile
{
    # 443 被 sing-box 占用,改用 Cloudflare 支持的 8443
    https_port 8443
}

monitor.232777.xyz {
    # DNS-01 挑战:调 Cloudflare API 验证,小黄云开着也不影响
    tls {
        dns cloudflare YOUR_CF_TOKEN
    }

    # 反代到本机 Komari;WebSocket 由 Caddy 自动处理
    reverse_proxy 127.0.0.1:25774
}
收紧权限、校验语法、启动
bash
# Caddyfile 里躺着 API Token,只让 root 可读
sudo chmod 600 /etc/caddy/Caddyfile

# 先校验,通过再启动
sudo caddy validate --config /etc/caddy/Caddyfile && sudo systemctl start caddy
sudo systemctl status caddy | head -n 5
不需要 setcap 官方包的 systemd 服务自带 CAP_NET_BIND_SERVICE,且 8443 高于 1024 本来就不需要特权,老教程里的 setcap 可以省了。
到这里应该 systemctl status caddy 显示 active (running)。等 1–2 分钟让 Caddy 走 DNS-01 签发证书,然后浏览器打开 https://monitor.232777.xyz,地址栏出现小锁即成功。以后每 60 天左右 Caddy 会自动续签。

主控就绪后,把要监控的机器接进来。Agent 通过 WebSocket 连主控域名,走 Cloudflare 回源,和访客是同一条路。

在面板添加节点并复制命令

登录面板 → 侧边栏 服务器 → 添加节点,填个别名保存,页面会给出该节点的一键安装命令,原样复制。

核对命令的三个要素 正确的命令从 raw.githubusercontent.com/komari-monitor/komari-agent 拉安装脚本,-e 后面是你的面板公网域名,-t 后面是刚生成的节点 Token。如果看到脚本地址是面板域名下的 /install.sh,那是错的,执行会 404。
追加禁用网页终端参数

如果只需要监控指标、不需要从面板开网页 SSH 到被控机,在命令末尾加上 --disable-web-ssh,攻击面小一截。

到被控机上执行
bash
bash <(curl -sL https://raw.githubusercontent.com/komari-monitor/komari-agent/refs/heads/main/install.sh) \
  -e https://monitor.232777.xyz \
  -t YOUR_AGENT_TOKEN \
  --disable-web-ssh
国内机器拉 GitHub 慢 安装脚本支持 --install-ghproxy 参数指定代理,例如 --install-ghproxy https://ghfast.top,加在命令末尾即可。
到这里应该 回到面板的服务器列表,新节点状态变为在线,CPU / 内存曲线开始有数据。

小黄云藏 IP 有个前提:源站只接受 Cloudflare 的回源。否则源站 IP 一旦泄露(DNS 历史记录、Agent 直连都可能漏),等于没藏。

先放行 SSH,防止把自己锁在门外
bash
sudo ufw allow 22/tcp
8443 只对 Cloudflare 回源 IP 段放行
bash
# IPv4 段(以 cloudflare.com/ips 公布的为准)
for ip in $(curl -s https://www.cloudflare.com/ips-v4); do
  sudo ufw allow proto tcp from $ip to any port 8443
done
# IPv6 段
for ip in $(curl -s https://www.cloudflare.com/ips-v6); do
  sudo ufw allow proto tcp from $ip to any port 8443
done
默认拒绝入站并启用
bash
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw --force enable && sudo ufw status numbered
顺序不能反 一定先放行 SSH 再 enable。如果这台机器已经开了 ufw 但没放 22,先补上再继续。
25774 和 80 都不需要放行 25774 只绑了 127.0.0.1,本来就进不来;证书走 DNS-01,不需要 80 端口做 HTTP 挑战。源站对外只需要 22(自己用)和 8443(仅 Cloudflare)。
验证 域名照常能打开;在另一台机器上 curl -vk --max-time 10 https://源站IP:8443/ 应该连接超时或被拒绝——直连源站走不通,正是我们要的效果。

升级走 compose,别用裸 docker run;Caddy 记得它的插件二进制会被 apt 刷掉。

升级 Komari

bash
# 进目录 → 拉新镜像 → 按 compose.yaml 重建并启动;数据在 ./data 卷里,不会丢
cd /opt/komari && docker compose pull && docker compose up -d
数据不会丢 监控数据在 ./data 卷里,拉新镜像重建容器不影响。Agent 自带自动更新机制,主控升级后不用逐台手动更新 Agent。

升级 Caddy(带插件版)

apt upgrade 会把 /usr/bin/caddy 刷回官方不带插件的版本。升级系统后重做第 4 节的第 2–4 步(停服务 → 下载 → 检查大小 → 替换 → 启动);或者提前 apt-mark hold caddy 锁住版本,手动升级时再放开。

常用命令

操作是干什么,命令点右边的复制直接粘进终端就能跑,说明讲什么时候用、执行完看什么。

操作命令说明
启动容器
docker compose -f /opt/komari/compose.yaml up -d
按 compose.yaml 创建并启动;改了配置后用这个重建
停止容器
docker compose -f /opt/komari/compose.yaml down
停掉并删除容器,数据卷保留。别加 -v:会连监控数据一起删
重启容器
docker restart komari
配置没改、服务卡住时用这个
查看状态
docker compose -f /opt/komari/compose.yaml ps
看是否为 Up;PORTS 列应为 127.0.0.1:25774
资源占用
docker stats komari --no-stream
CPU / 内存快照,不刷屏
实时日志
docker logs -f --tail 100 komari
出问题第一时间看这里;Ctrl + C 退出
近一小时日志
docker logs --since 1h komari
排查"刚才发生了什么",不被旧日志淹没
进入容器
docker exec -it komari sh
查容器内文件、手动跑命令;exit 退出
数据目录大小
du -sh /opt/komari/data
监控数据增长心里有数
Caddy 状态
systemctl status caddy
看是否为 active (running),顺带看最近几行日志
Caddy 快速状态
systemctl is-active caddy
只输出 active / inactive
Caddy 实时日志
sudo journalctl -u caddy -f
含 ACME 签发证书全过程;Ctrl + C 退出
Caddy 今日日志
sudo journalctl -u caddy --since today
翻历史问题,配合 grep 过滤关键字
校验配置
sudo caddy validate --config /etc/caddy/Caddyfile
每次改完先跑,输出 Valid configuration 再 reload
重载配置
sudo systemctl reload caddy
平滑重载,不断现有连接
重启 Caddy
sudo systemctl restart caddy
换过二进制、reload 不生效时用,会短暂断连
证书有效期
echo | openssl s_client -connect 127.0.0.1:8443 -servername monitor.232777.xyz 2>/dev/null | openssl x509 -noout -dates
看 notAfter(到期);Caddy 到期前 30 天自动续签,没续上就去查 Caddy 日志

排错

域名打不开 / Cloudflare 报错 高频

按顺序查:

bash
# 1. Caddy 在不在 8443 上监听
sudo ss -lntp | grep 8443

# 2. 本机直连 8443 通不通(绕过 CF)
curl -vk --max-time 10 https://127.0.0.1:8443/ | head -n 5

# 3. 证书签下来没有,看 ACME 日志
sudo journalctl -u caddy | grep -i certificate | tail -n 10

第 2 步不通先看 Caddy 状态和 Caddyfile;第 3 步报错多半是 API Token 权限不对(必须用"编辑区域 DNS"模板)。

Agent 一直离线 网络

Agent 走的是和访客同一条路(域名 → CF → 源站 8443),先确认域名本身能打开。再到被控机上查:

bash
# 被控机能否连上主控域名
curl -sI --max-time 10 https://monitor.232777.xyz | head -n 3

# Agent 服务状态与日志
sudo systemctl status komari-agent | head -n 8
sudo journalctl -u komari-agent | tail -n 20

常见原因:-e 域名写错、-t Token 复制不全、被控机出网受限(安装脚本拉不下来时可加 --install-ghproxy 参数指定代理)。

改完 Caddyfile 没生效 配置

改完必须 reload(或 restart)才会加载,且 validate 通过不代表语义正确。检查三步:sudo caddy validate --config /etc/caddy/Caddyfile → sudo systemctl reload caddy → sudo journalctl -u caddy 看有没有报错。