韩国服务器部署Uptime Kuma时,如何设置监控探针与告警验证
要在韩国服务器上首次运行 Uptime Kuma,关键是让监控页面可安全访问、让探针从正确的位置检查业务地址,并用一次可控的故障确认告警确实会送达。下面以已安装 Docker 和 Docker Compose 插件的 Ubuntu 22.04/24.04 服务器为例:Uptime Kuma 运行在韩国服务器上,主动检查指定的 HTTP 服务,通过邮件发送告警;另设一个仅用于演练的目标验证 Down 与恢复通知。
A5数据提供韩国首尔物理服务器资源,可为 Uptime Kuma 及业务健康检查提供贴近韩国访问环境的部署基础。不同方案覆盖多种处理器、内存、存储与国际线路配置,既能承载监控服务和历史数据,也可配合网站、接口及业务后台进行独立监测,满足不同规模业务的资源需求。
准备条件:先确认监控位置和访问方式
准备一台能通过 SSH 登录的韩国服务器,并确认它可以向被监控地址发起请求,也能连接所用邮件服务的 SMTP 地址。示例需要 Docker、Compose 插件,以及足够存放监控历史记录的磁盘空间。先核对环境:
docker --version
docker compose version
df -h /opt
前两条应分别显示版本信息;若提示找不到命令,应先按当前 Ubuntu 版本安装 Docker Engine 与 Compose 插件,不要直接执行后面的部署命令。/opt 所在文件系统也应有可用空间。本文使用 sudo docker,不要求把登录用户加入 Docker 用户组。
探针的位置决定了结果的含义。 安装在韩国服务器上的 Uptime Kuma,检查的是“从该服务器到目标”的连通性。如果目标也是本机业务,整台服务器断电或完全失联时,本机上的 Kuma 无法继续发出告警。需要判断韩国服务器是否从外部可达时,应另用独立服务器或外部监控点检查它的公网业务地址;本机探针不能代替外部探针。

首次部署只把 Uptime Kuma 的 Web 端口绑定到服务器本机回环地址,通过 SSH 转发访问,不必为管理页面开放公网端口。还要准备一个实际可访问的业务健康检查地址,例如 https://service.example.com/healthz;文中的域名只是占位示例,操作时须换成自己的地址。
部署并确认 Uptime Kuma 可以访问
创建独立目录,并确认其中没有待保留的同名配置文件:
sudo install -d -m 700 /opt/uptime-kuma
sudo test ! -e /opt/uptime-kuma/compose.yaml
第二条命令没有输出且退出码为 0,表示可以新建配置;若返回非 0,应先检查已有文件,不要覆盖。写入 Compose 配置:
sudo tee /opt/uptime-kuma/compose.yaml > /dev/null <<'YAML'
services:
uptime-kuma:
image: louislam/uptime-kuma:2
container_name: uptime-kuma
restart: unless-stopped
ports:
- "127.0.0.1:3001:3001"
volumes:
- kuma_/app/data
check-target:
image: nginx:stable-alpine
profiles:
- drill
restart: "no"
volumes:
kuma_
name: uptime-kuma-data
YAML
sudo docker compose -f /opt/uptime-kuma/compose.yaml config
config 应正常输出解析后的配置,不能出现 YAML 缩进或字段错误。check-target 带有 drill 配置组,日常启动不会运行;它只用于后面的告警演练。/app/data 挂载到 Docker 命名卷,后续重建应用容器时不会随容器一起丢失。
启动应用并查看状态:
sudo docker compose -f /opt/uptime-kuma/compose.yaml up -d
sudo docker compose -f /opt/uptime-kuma/compose.yaml ps
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001/
预期 uptime-kuma 处于运行状态,curl 返回可访问页面的 HTTP 状态码,例如 200。这只能证明本机 Web 入口有响应,还不能证明监控和邮件配置有效。若容器未启动,先查看日志,不要反复删除数据卷重装:
sudo docker logs --tail 80 uptime-kuma
在自己的电脑上建立 SSH 转发,并保持该终端连接:
ssh -N -L 13001:127.0.0.1:3001 <登录用户>@<韩国服务器IP>
浏览器访问 http://127.0.0.1:13001/,按首次运行页面提示创建管理员账号。此处的 127.0.0.1:13001 是自己电脑上的转发入口;服务器端的 Kuma 仍只监听回环地址。完成后重新打开页面确认能登录,并妥善保存管理员凭据。若浏览器无法连接,分别检查 SSH 会话是否仍在、服务器上的 curl 是否成功,以及自己电脑的 13001 端口是否已被占用。
设置实际业务探针并逐项验证
在 Uptime Kuma 页面添加一个 HTTP(s) 监控项,示例名称为“韩国业务健康检查”,URL 填入实际的 https://service.example.com/healthz。首次配置可按以下口径设置,再根据业务特性调整:
| 设置项 | 示例设置 | 验证重点 |
|---|---|---|
| 检查间隔 | 60 秒 | 页面是否按间隔产生新记录 |
| 请求方式 | GET | 健康检查接口是否允许 GET |
| 可接受状态码 | 200–299 | 不能只因首页跳转就把业务判为正常 |
| 请求超时 | 10 秒 | 目标正常响应时间应明显低于超时值 |
| 重试次数 | 2 次 | 短暂抖动与告警时效之间是否符合需求 |
保存后等待探针实际执行,而不是只看配置是否提交成功。状态显示 Up、近期检查有响应时间,才说明 Kuma 从韩国服务器发出的这类请求成功了。如果健康检查接口需要鉴权,应在监控项中按接口要求配置请求头等信息;不要把含凭据的完整 URL 随意发给他人。
注意容器网络边界:在 Kuma 监控项中填写 127.0.0.1,指向的是 Kuma 容器自身,不是韩国服务器宿主机。 若要检查宿主机上的业务,应使用从容器可达的宿主机地址或业务域名,并核对服务监听地址与访问控制;不能把宿主机执行 curl 127.0.0.1 成功,直接当作容器探针成功。

如果探针显示 Down,按影响较小的顺序检查:
- 核对 URL、端口、路径和健康检查接口预期状态码;应用返回
404或500与网络连接失败不是一类问题。 - 在韩国服务器上请求同一地址,观察 DNS、TLS 和 HTTP 返回。宿主机请求成功但 Kuma 失败时,继续检查容器网络、目标地址是否仅绑定宿主机回环地址,以及目标服务的访问规则。
- 若只有 HTTPS 失败,检查域名是否与证书匹配、证书是否有效;不要为求显示 Up 就长期关闭证书校验。
- 若请求偶发超时,先核对接口耗时和目标负载,再调整超时或重试;单纯放宽阈值可能掩盖真实故障。
例如可在服务器上执行:
curl -v --max-time 10 https://service.example.com/healthz
把域名替换为实际地址。命令结果用于辅助定位,但最终仍应以 Kuma 监控项自身恢复 Up 作为该探针配置通过的依据。
配置邮件通知,不把“测试成功”等同于告警成功
进入 Uptime Kuma 的通知设置,新增邮件通知。填写实际 SMTP 主机、端口、加密方式、登录凭据、发件人与收件人;加密方式应与邮件服务商提供的端口要求一致,例如使用 587 端口时核对是否要求 STARTTLS,不能只按端口号猜测。保存前确认韩国服务器允许向该 SMTP 地址发起连接。
先使用页面中的测试通知功能,检查收件箱和垃圾邮件目录。测试消息到达,说明这组通知配置具备基本发送能力;它并不能证明某个监控项进入 Down 后一定会触发邮件。接着编辑“韩国业务健康检查”,将该邮件通知关联并启用,保存后再核对一次监控项设置。通知已创建但未关联到监控项,是首次部署时常见的漏项。
测试失败时,优先核对 SMTP 地址与端口是否可达、账号是否允许 SMTP 登录、凭据及加密方式是否匹配,再看 Kuma 日志中的发送错误。不要把邮件密码写进公开命令或工单;邮件配置和监控数据也会保存在 Kuma 数据卷中,后续备份应按敏感数据管理。
用可控目标演练 Down 与恢复
不要为了验证告警而停止正式业务。配置中预留的 check-target 可以在同一 Compose 网络中提供一个临时 HTTP 目标。先启动它:
sudo docker compose -f /opt/uptime-kuma/compose.yaml --profile drill up -d check-target
sudo docker compose -f /opt/uptime-kuma/compose.yaml --profile drill ps
确认 check-target 处于运行状态后,在 Kuma 中新增一个 HTTP(s) 监控项,名称设为“告警演练”,URL 使用 http://check-target/,检查间隔可设为 60 秒,并关联刚配置的邮件通知。这里的 check-target 是 Compose 网络内的服务名,只供 Kuma 容器访问,不是公网域名。等演练监控项显示 Up,再人为制造故障:
sudo docker compose -f /opt/uptime-kuma/compose.yaml --profile drill stop check-target
停止的范围仅是演练用 Nginx 容器,不应影响正式业务。等待探针经历检查及所设重试,核对演练项是否变为 Down、事件时间是否合理,以及收件人是否收到对应的故障邮件。60 秒间隔、10 秒超时和重试配置下,告警不会在停止容器的瞬间到达;应给检查周期、重试和邮件投递留出时间。

如果页面已显示 Down 却没有邮件,先确认演练项确实启用了该通知,再检查通知发送结果和 SMTP 错误;如果页面一直显示 Up,确认停止的是 check-target、监控 URL 确为 http://check-target/,并等待下一次检查。演练完成后恢复目标:
sudo docker compose -f /opt/uptime-kuma/compose.yaml --profile drill start check-target
预期演练项重新显示 Up;若相应通知设置包含恢复消息,还应核对恢复邮件。完成验证后,可在页面删除“告警演练”监控项,再停止演练容器,避免留下无用途的检查记录和资源占用:
sudo docker compose -f /opt/uptime-kuma/compose.yaml --profile drill stop check-target
验收与回滚检查项
上线验收时,逐项确认以下结果:
- 韩国服务器上的
uptime-kuma容器持续运行;管理页面可经 SSH 转发登录,3001 端口没有按本文配置对公网开放。 - 正式 HTTP(s) 监控项检查的是实际业务地址,显示 Up,状态码与响应时间符合该接口的预期。
- 邮件测试消息已收到;演练目标停止后出现 Down 告警,恢复后监控项重新显示 Up。两项验证应分别记录,不能互相代替。
- 如需发现韩国服务器整机失联,已另行安排独立监控点检查其公网业务地址,而不是仅依赖本机 Kuma。
若决定撤销本次部署,先通知依赖这些告警的人员:停止 Kuma 后,新故障将不再由它检测。确认不再需要当前监控后执行:
sudo docker compose -f /opt/uptime-kuma/compose.yaml --profile drill down
sudo docker compose -f /opt/uptime-kuma/compose.yaml --profile drill ps
down 会停止并移除本次 Compose 的容器及网络,不会删除名为 uptime-kuma-data 的数据卷;不要附加 -v。检查容器已停止,并确认原有监控由其他方式接管。若只是要撤回一次错误的监控或通知设置,优先在页面修改该监控项,而不是停止整套服务。数据卷中可能含管理员信息、邮件凭据和历史记录;决定长期保留、备份或删除前,应先按自身的数据保留要求核对,不要把删除数据卷当作普通回滚步骤。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5393.html
