用美国服务器部署Uptime Kuma,如何配置网站监控与故障告警?
要在美国服务器上部署 Uptime Kuma,核心不是单纯把监控面板跑起来,而是让监控节点与被监控网站尽量处于不同故障域,并根据网站类型设置合理的超时、重试、响应码和告警恢复条件。本文以 Ubuntu 22.04/24.04、Docker Compose、Uptime Kuma 1.x 为示例,完成从安装、HTTPS 访问、网站监控、通知渠道配置,到故障注入验证、降噪和回滚的完整流程。
适用环境包括企业官网、独立站、API、后台登录页和部署在其他机房的网站。美国服务器可以作为独立监控点,但它只能代表“美国网络位置看到的可用性”;如果业务用户分布在中国、欧洲或东南亚,建议后续增加其他地区的监控节点,避免把单一区域网络问题误判为源站故障。

A5数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器租用,其中美国常规系列配备Xeon、AMD EPYC及CN2 GIA线路,并提供不同内存、NVMe存储和带宽配置,可为Uptime Kuma监控节点、企业网站、后台与API运行提供独立资源。面向跨地区可用性观察,A5数据还可提供多个地区的服务器资源,支持按业务访问范围布设监控节点,形成更贴近不同网络位置的运行观测基础。
一、部署前确认监控目标
1. 明确监控节点与被监控对象
本文示例中:
| 项目 | 示例值 | 说明 |
|---|---|---|
| 监控服务器 | 美国 VPS,Ubuntu 22.04/24.04 | 部署 Uptime Kuma |
| 监控域名 | status.example.com | 指向美国监控服务器 |
| 被监控网站 | https://www.example.com | 可与监控服务器位于不同地区 |
| Uptime Kuma 监听端口 | 3001 | 仅建议本机或反向代理访问 |
| HTTPS 入口 | 80/443 | 由 Nginx 转发到 3001 |
| 容器数据目录 | /opt/uptime-kuma/data | 保存监控器、通知和用户配置 |
这里的域名均为示例,实际部署时替换为自己的域名。
监控目标至少应区分以下几类:
- 首页可用性:验证网站是否能建立连接并返回正常响应。
- 关键业务页面:例如登录页、商品详情页、订单查询页。
- API 接口:验证状态码、响应时间和返回内容。
- 证书有效期:避免 HTTPS 证书临近过期才发现。
- DNS 解析:确认域名能被监控节点正确解析。
- 服务器资源:CPU、内存、磁盘和进程状态可使用独立的系统监控工具补充,不能仅依赖 Uptime Kuma 的网页探测。
2. 确认服务器基础条件
建议准备:
- Ubuntu 22.04 或 24.04 64 位系统;
- 至少 1 vCPU、1 GB 内存和 10 GB 可用磁盘;
- 一个已解析到监控服务器公网 IPv4 的域名;
- 云平台安全组放行 TCP 80 和 443;
- 具备
sudo权限的系统用户; - 一个可接收故障通知的邮箱、Webhook 或即时通信机器人;
- 监控节点能够访问被监控网站的 80/443 端口。
不要直接把 Uptime Kuma 的 3001 端口长期暴露到公网。更稳妥的方式是让 Docker 只绑定到本机,由 Nginx 负责 HTTPS、访问控制和证书续期。
3. 检查操作系统与网络
先登录美国服务器,确认系统和内核信息:
cat /etc/os-release
uname -a
free -h
df -h /
示例结果可以是:
PRETTY_NAME="Ubuntu 22.04.5 LTS"
Mem: 1.9Gi 180Mi 1.1Gi 2.0Mi 620Mi 1.5Gi
Filesystem Size Used Avail Use% Mounted on
/dev/vda1 20G 3.8G 15G 21% /
如果根分区可用空间低于 2 GB,不建议直接部署。Uptime Kuma 本身占用空间不大,但 Docker 镜像、日志和系统更新仍需要余量。
检查 DNS 和外网连通性:
getent hosts registry-1.docker.io
curl -I --connect-timeout 10 https://www.example.com
预期至少应满足:
getent hosts能返回解析地址;curl能建立 HTTPS 连接;- 被监控站点即使返回 403 或 5xx,也说明网络路径可能可达,后续需要再判断业务状态。
二、安装 Docker 与基础工具
1. 安装 Docker
Ubuntu 可以使用 Docker 官方软件源。先安装依赖:
sudo apt update
sudo apt install -y ca-certificates curl gnupg
创建密钥目录并导入 Docker 软件源密钥:
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
| sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
写入软件源。下面命令会根据当前系统代号生成配置,不要在不同发行版上直接照搬:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
安装 Docker Engine、Compose 插件和常用组件:
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin nginx ufw
检查版本和服务状态:
sudo systemctl enable --now docker
sudo docker version
sudo docker compose version
sudo systemctl is-active docker
预期输出中应看到 Docker 服务为 active,并能显示 Compose 版本。如果 apt update 报软件源或签名错误,应先修复软件源,不要使用来源不明的安装脚本覆盖系统组件。
2. 配置基础防火墙
如果使用 UFW,先确认云平台安全组已经允许 SSH。否则启用防火墙后可能导致远程失联。
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status verbose
确认规则无误后启用:
sudo ufw enable
这里不需要放行 3001,因为 Uptime Kuma 会只监听本机地址。若现有服务器已经有其他服务占用 80 或 443,应先检查:
sudo ss -lntp | grep -E ':(80|443|3001)\b'
如果 80/443 已被现有 Nginx 或其他 Web 服务使用,应将配置合并到现有服务中,不能重复启动监听同一端口的服务。
三、使用 Docker Compose 部署 Uptime Kuma
1. 创建目录与 Compose 文件
创建专用目录:
sudo mkdir -p /opt/uptime-kuma/data
sudo chown -R "$USER":"$USER" /opt/uptime-kuma
cd /opt/uptime-kuma
创建 compose.yml:
services:
uptime-kuma:
image: louislam/uptime-kuma:1
container_name: uptime-kuma
restart: unless-stopped
ports:
- "127.0.0.1:3001:3001"
volumes:
- .//app/data
environment:
TZ: America/Los_Angeles
security_opt:
- no-new-privileges:true
配置说明:

louislam/uptime-kuma:1使用 1.x 稳定大版本标签,避免自动跨到不兼容的大版本;restart: unless-stopped让容器在服务器重启后自动恢复;127.0.0.1:3001:3001仅允许本机访问;.//app/data保存配置和监控数据;TZ示例使用美国太平洋时区,也可以改为UTC或业务团队常用时区;no-new-privileges可减少容器进程获得额外权限的风险。
启动容器:
sudo docker compose up -d
查看容器状态:
sudo docker compose ps
sudo docker logs --tail=50 uptime-kuma
预期状态类似:
NAME IMAGE SERVICE STATUS
uptime-kuma louislam/uptime-kuma:1 uptime-kuma Up 20 seconds
本机验证 3001 端口:
curl -I http://127.0.0.1:3001
如果返回 200、302 或带有 Uptime Kuma 页面特征的响应,说明容器基本启动成功。若提示连接拒绝,先查看日志:
sudo docker logs uptime-kuma
2. 首次初始化账户
在浏览器访问:
http://监控服务器公网IP:3001
如果 3001 未对外放行,公网浏览器无法访问是正常现象。为了安全,建议直接配置 Nginx 和 HTTPS 后再访问。
首次页面会要求创建管理员账户。请使用独立的强密码,不要与服务器 SSH、云平台或业务后台复用。初始化完成后,先确认能够进入监控面板,再继续反向代理配置。
四、配置 Nginx 与 HTTPS 访问
1. 创建 Nginx 站点配置
将 status.example.com 的 DNS A 记录指向美国服务器公网 IP。DNS 生效后检查:
dig +short status.example.com
如果服务器没有 dig,可以安装:
sudo apt install -y dnsutils
创建 Nginx 配置:
sudo nano /etc/nginx/sites-available/uptime-kuma
写入:
server {
listen 80;
listen [::]:80;
server_name status.example.com;
location / {
proxy_pass http://127.0.0.1:3001;
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 60s;
proxy_send_timeout 60s;
}
}
Uptime Kuma 的实时界面依赖长连接,Upgrade 和 Connection 头不能省略。检查配置语法:
sudo nginx -t
预期结果:
nginx: configuration file /etc/nginx/nginx.conf test is successful
启用站点并重载 Nginx:
sudo ln -s /etc/nginx/sites-available/uptime-kuma \
/etc/nginx/sites-enabled/uptime-kuma
sudo systemctl reload nginx
浏览器访问:
http://status.example.com
如果能打开 Uptime Kuma,说明 Nginx 到容器的转发正常。
2. 使用 Certbot 配置证书
安装 Certbot 和 Nginx 插件:
sudo apt install -y certbot python3-certbot-nginx
申请证书:
sudo certbot --nginx -d status.example.com
命令执行过程中会要求填写邮箱、同意条款,并选择是否将 HTTP 重定向到 HTTPS。监控面板包含管理员入口,建议选择重定向到 HTTPS。
验证 HTTPS:
curl -I https://status.example.com
预期应看到 200、302 或其他正常的 HTTP 响应,并且浏览器地址栏显示有效证书。
检查自动续期:
sudo certbot renew --dry-run
如果续期测试失败,常见原因包括:
- DNS 已指向其他服务器;
- 80 端口没有放行;
- Nginx 配置存在语法错误;
- 云平台安全组阻断了验证请求;
- 域名启用了其他代理或 CDN,验证请求没有到达本机。
修复后再次执行 --dry-run,不要直接删除证书目录或手工覆盖 Certbot 配置。
五、在 Uptime Kuma 中创建网站监控
1. 首次添加 HTTP(s) 监控器
登录 https://status.example.com,点击添加监控器,选择 HTTP(s)。
建议先使用以下参数:
| 参数 | 示例值 | 设置目的 |
|---|---|---|
| 监控名称 | 官网首页 | 便于告警识别 |
| URL | https://www.example.com/ | 被监控地址 |
| 间隔 | 60 秒 | 常规网站的基础频率 |
| 重试次数 | 2 | 减少瞬时丢包造成误报 |
| 请求超时 | 10 秒 | 区分慢响应和完全不可达 |
| 最大重定向次数 | 5 | 兼容常见 HTTPS 跳转 |
| 重新通知间隔 | 30 分钟 | 避免持续故障重复轰炸 |
| 反向代理缓存 | 按实际情况 | 防止缓存掩盖源站状态 |
初始配置不宜过于激进。例如把间隔设为 5 秒,会增加监控节点访问量,也可能因网络短暂抖动产生大量告警。对普通企业官网,60 秒间隔、10 秒超时和 2 次重试通常是可操作的起点,之后再根据业务容忍度调整。
2. 按返回状态码判断成功与失败
HTTP 监控至少要明确哪些状态码算正常:
2xx:通常表示请求成功;3xx:若跳转符合预期,可以接受;循环跳转则应判定异常;401、403:可能是接口认证或 WAF 策略,不应简单视为正常;404:页面不存在,通常应告警;429:可能触发限流,需要结合请求频率判断;5xx:一般代表服务端或上游异常;- TLS 握手失败、DNS 失败、连接超时:应分别记录原因。
如果网站首页会根据地区、Cookie 或 User-Agent 返回不同内容,单纯检查状态码可能不够。可以设置关键词检查,例如要求响应正文包含:
Welcome
或业务页面固定存在的标题。关键词不宜选择会随语言、日期、用户状态变化的内容,否则会制造误报。
3. 设置响应内容检查
在 Uptime Kuma 的 HTTP(s) 监控中,启用响应内容或关键词检查,填写一个稳定字符串。例如网站首页源代码中长期存在:
<title>Example Official Website</title>
可以检查:
Example Official Website
验证逻辑应满足:
- HTTP 状态正常且关键词存在:监控器为正常;
- HTTP 状态正常但关键词缺失:页面可能被错误模板、WAF 页面或空白页替换;
- HTTP 状态异常:直接记录失败原因;
- 页面启用了压缩、动态渲染或服务端分流:先确认 Uptime Kuma 能获取到目标内容。
不要把短字符串如 html、OK 作为关键词。这类内容可能在错误页中同样存在,无法识别业务异常。
4. 创建关键页面与 API 监控
不建议只监控首页。至少应补充一个关键业务页面和一个 API:
| 监控对象 | 建议检查内容 | 典型失败信号 |
|---|---|---|
| 首页 | 状态码、关键词、响应时间 | Web 服务停止、首页被替换 |
| 登录页 | 状态码、页面标题 | 前端资源或认证入口异常 |
| API 健康检查 | 状态码、JSON 字段 | 应用进程或数据库连接异常 |
| 静态资源 | CSS/JS 或 CDN 地址 | CDN、对象存储或构建发布问题 |
| 证书 | 到期时间 | 证书续期失败 |
API 最好提供独立的健康检查接口,例如:
https://www.example.com/healthz
接口可以返回:
{
"status": "ok"
}
然后在 Uptime Kuma 中设置:
- 请求方法:
GET; - 预期状态码:
200; - 关键词:
"status":"ok"; - 超时:根据接口实际响应设置;
- 不建议直接监控需要高权限的生产管理接口。
如果健康检查接口始终返回 200,但内部依赖已经异常,监控仍会误判正常。因此健康检查应至少检查应用自身运行状态,并根据风险决定是否检查数据库、缓存或关键第三方依赖。不要把大量外部依赖全部串进一个检查接口,否则任意下游波动都会让主站告警。
六、设置告警通知与降噪策略
1. 先配置通知渠道
在 Uptime Kuma 的通知设置中添加通知方式。可选择邮件、Webhook 或团队协作工具机器人,具体选项取决于当前版本和服务商接口。
告警消息建议包含:
- 监控名称;
- URL 或目标地址;
- 当前状态;
- 错误原因;
- 首次发生时间;
- 最近一次检查时间;
- 监控节点位置;
- 恢复时间和持续时长。
测试通知后,应确认收件人或群组确实收到消息。只看到 Uptime Kuma 页面显示“测试成功”还不够,必须在实际渠道中验证。
2. 使用连续失败和恢复通知
推荐采用“连续失败后告警、恢复后通知”的策略:
- 第一次失败:记录事件,不立即通知;
- 连续 2 次失败:发送故障告警;
- 服务恢复:发送恢复通知;
- 故障持续:每 30 分钟或 60 分钟重复一次;
- 维护窗口:提前暂停相关监控器或屏蔽通知。
如果监控间隔为 60 秒、重试次数为 2,实际告警时间可能约为 2 至 3 分钟,具体取决于重试实现和网络响应时间。这个延迟换取了更低的误报率。对支付入口、登录服务等关键目标,可以设置更短间隔,但应确保目标服务和监控节点能够承受请求量。
3. 区分网络故障与应用故障
美国监控节点观察到的故障可能来自四层位置:

- DNS 无法解析;
- TCP 连接无法建立;
- TLS 握手失败;
- HTTP 返回异常或页面内容错误。
告警内容尽量保留原始错误。例如:
getaddrinfo ENOTFOUND:优先检查 DNS;ECONNREFUSED:目标端口未监听或被防火墙拒绝;ETIMEDOUT:网络丢包、策略阻断或服务响应过慢;certificate has expired:证书过期;HTTP 502/504:反向代理或上游服务异常;- 关键词缺失:页面内容不符合预期。
不要把所有错误都改写为“网站宕机”。准确的错误类型有助于值班人员快速判断责任边界。
4. 配置维护窗口
系统升级、证书切换、DNS 迁移和发布操作期间,建议提前设置维护窗口,否则监控会把已知变更重复告警。
维护操作前记录:
- 受影响的监控器;
- 开始和结束时间;
- 变更负责人;
- 回滚条件;
- 验证 URL。
维护结束后必须恢复监控,并手工执行一次检查。只取消维护模式而不确认业务页面,会留下“监控已恢复但业务未恢复”的盲区。
七、建立响应时间和阈值判断
1. 不要只看 UP/DOWN
网站返回 200 并不代表用户体验正常。建议同时关注:
- DNS 解析耗时;
- TCP 建连耗时;
- TLS 握手耗时;
- 首字节时间;
- 完整响应时间;
- 5xx 比例;
- 超时次数;
- 证书剩余天数。
Uptime Kuma 主要适合做可用性和基础响应监控。更细的分阶段耗时,可以使用 curl、反向代理日志或专门的 APM 工具补充。
2. 使用分层阈值
可按业务重要性制定示例阈值:
| 层级 | 参考条件 | 处理方式 |
|---|---|---|
| 正常 | 响应时间低于 1 秒且状态正常 | 仅记录 |
| 关注 | 连续多次高于 2 秒 | 检查应用、数据库和带宽 |
| 预警 | 连续 3 次高于 5 秒 | 通知技术人员 |
| 故障 | 超时、连接失败或连续返回 5xx | 立即告警 |
| 内容异常 | 状态正常但关键词缺失 | 按业务故障处理 |
这些数值是示例起点,不是所有网站的通用标准。应先观察一段时间的正常分布,再设定阈值。例如一个动态商城首页正常响应就在 2 秒左右,把 1 秒设为故障线会持续产生噪声。
3. 用基线识别故障前兆
建议在非高峰和高峰时段分别观察:
- 平均响应时间;
- P95 或 P99 响应时间;
- 连接失败频率;
- 5xx 类型分布;
- 特定时间段是否重复变慢。
如果平时响应时间约为 600 至 900 毫秒,近期连续上升到 2 至 3 秒,即使尚未超时,也可能说明数据库连接池、CPU、磁盘 IO 或上游接口开始拥堵。此时应结合源站日志和系统指标确认,不要等待完全不可用后才处理。
八、逐项验证监控是否真的有效
1. 验证正常访问
从美国服务器执行:
curl -sS -o /dev/null \
-w 'code=%{http_code} dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s start=%{time_starttransfer}s total=%{time_total}s\n' \
--max-time 15 \
https://www.example.com/
示例输出:
code=200 dns=0.012s connect=0.045s tls=0.091s start=0.238s total=0.312s
这只是命令格式和输出结构示例,不代表任何实际客户网站或实时测试结果。重点检查:
code是否符合预期;total是否低于设定阈值;tls是否异常升高;- 多次执行结果是否稳定。
2. 验证内容关键词
curl -fsSL --max-time 15 https://www.example.com/ \
| grep -F 'Example Official Website'
命令退出状态为 0,说明找到了关键词;没有输出或退出状态非 0,说明关键词检查失败。注意部分网站会使用压缩、JavaScript 渲染或动态接口,命令行拿到的 HTML 可能与浏览器最终页面不同。
3. 模拟连接失败
不要直接停止生产网站来测试。可以使用专用测试域名、临时测试监控器或短时间修改测试目标。
例如把测试监控器 URL 临时改为一个明确不存在的端口:
http://测试域名:65530/
验证步骤:
- 保存监控器;
- 等待超过检查间隔和重试次数;
- 确认状态变为
DOWN; - 确认通知渠道收到故障告警;
- 查看错误原因;
- 恢复原始 URL;
- 确认收到恢复通知。
测试完成后必须检查测试监控器是否已删除或恢复,避免遗留无效目标。
4. 模拟内容异常
准备一个测试页面,让它返回 200,但不包含预期关键词。这样可以验证“状态码正常、业务内容异常”的检测能力。
验证结果应为:
- HTTP 请求本身成功;
- 关键词检查失败;
- Uptime Kuma 将监控器标记为异常;
- 告警消息明确说明内容检查失败,而不是笼统提示连接失败。
5. 验证重启恢复
检查容器是否设置了自动重启:
sudo docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' uptime-kuma
预期输出:
unless-stopped
执行重启测试前,确认当前没有正在进行的维护。重启容器:
cd /opt/uptime-kuma
sudo docker compose restart
观察状态:
sudo docker compose ps
curl -I http://127.0.0.1:3001
如果容器恢复运行且监控配置仍然存在,说明数据卷挂载有效。若配置丢失,应立即停止继续升级,检查 /opt/uptime-kuma/data 是否为空以及 Compose 文件是否在正确目录。
九、常见异常与处理顺序
1. 页面打不开,先区分入口问题
从外部执行:
curl -Iv https://status.example.com
根据结果判断:
- DNS 无记录:检查域名解析;
- 连接超时:检查云安全组、UFW 和服务器公网地址;
- Nginx 返回 502:检查 Uptime Kuma 容器和本机 3001;
- 证书错误:检查 Certbot、域名和系统时间;
- 页面加载但实时状态不更新:检查 WebSocket 反向代理头。
服务器内检查:
sudo systemctl status nginx --no-pager
sudo docker compose -f /opt/uptime-kuma/compose.yml ps
sudo ss -lntp | grep -E ':(80|443|3001)\b'
2. 容器反复重启
查看最近日志:
sudo docker logs --tail=100 uptime-kuma
sudo docker inspect uptime-kuma --format '{{.State.Status}} {{.State.ExitCode}}'
常见原因:
- 数据目录权限不正确;
- 宿主机磁盘空间不足;
- 镜像拉取不完整;
- Docker 服务异常;
- 配置文件或挂载路径错误。
检查:
df -h /opt/uptime-kuma
ls -ld /opt/uptime-kuma /opt/uptime-kuma/data
sudo journalctl -u docker --since "30 minutes ago" --no-pager
不要在未备份数据前删除 /opt/uptime-kuma/data。该目录包含监控器、账户和通知配置,删除后可能无法恢复。
3. 监控一直显示 DOWN,但浏览器正常
浏览器正常不代表美国监控节点正常。按以下顺序执行:
getent hosts www.example.com
curl -Iv --max-time 15 https://www.example.com/
curl -4 -Iv --max-time 15 https://www.example.com/
curl -6 -Iv --max-time 15 https://www.example.com/
重点检查:
- DNS 是否返回了不同地址;
- IPv6 是否可解析但不可连通;
- 网站是否按 IP、地区或 User-Agent 返回不同结果;
- WAF 是否拦截数据中心 IP;
- 源站是否限制美国云服务器访问;
- SNI 和证书是否匹配域名。
如果 curl -4 正常、curl -6 失败,说明 IPv6 路径可能存在问题。可以在 DNS、主机网络或目标站点侧修复,而不是简单提高超时阈值。
4. 告警过多
可以按顺序调整:
- 将间隔从 30 秒调整为 60 秒;
- 增加一次重试;
- 适当延长超时;
- 延长重复通知间隔;
- 删除不稳定或价值较低的关键词;
- 将发布、备份和维护任务纳入维护窗口;
- 将首页、API、登录页拆分为独立告警。
不要通过关闭所有通知解决噪声问题。告警降噪的目标是减少误报,同时保留真正影响用户的事件。
5. 邮件或 Webhook 测试失败
先确认服务器可以访问通知服务:
curl -I --connect-timeout 10 https://通知服务域名
如果是 SMTP,检查:
- 主机名和端口;
- TLS/STARTTLS 模式;
- 用户名和授权码;
- 发件人地址是否被服务商允许;
- 云服务商是否限制 SMTP 端口;
- 系统时间是否准确。
如果通知接口需要签名或 Token,不要将密钥写入公开仓库,也不要把完整 Token 放进工单截图。发生泄露时,应立即在通知服务端撤销并重新生成。
十、数据备份、升级与回滚
1. 备份 Uptime Kuma 数据
备份前停止容器,可以避免数据库文件在写入过程中被复制:
cd /opt/uptime-kuma
sudo docker compose stop
sudo tar -czf /opt/uptime-kuma-data-$(date +%F-%H%M%S).tar.gz data
sudo docker compose start
检查备份文件:
ls -lh /opt/uptime-kuma-data-*.tar.gz
sudo tar -tzf /opt/uptime-kuma-data-*.tar.gz | head
备份文件不要只保存在同一块系统盘。可以复制到受控的备份存储,并限制权限:
sudo chmod 600 /opt/uptime-kuma-data-*.tar.gz
2. 更新镜像
更新前先备份并记录当前镜像:
cd /opt/uptime-kuma
sudo docker image inspect louislam/uptime-kuma:1 \
--format '{{.Id}} {{.Created}}'
拉取并重建:
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker logs --tail=100 uptime-kuma
然后验证:
- 管理员可以登录;
- 监控器数量和状态正常;
- 通知测试正常;
- HTTPS 页面和实时状态正常;
- 数据目录仍然挂载到
/app/data。
3. 使用备份回滚
如果升级后出现配置丢失、页面异常或监控器无法运行:
cd /opt/uptime-kuma
sudo docker compose down
先保留当前异常数据目录,便于后续分析:
sudo mv data data.failed-$(date +%F-%H%M%S)
sudo mkdir data
解压选定的备份:
sudo tar -xzf /opt/uptime-kuma-data-YYYY-MM-DD-HHMMSS.tar.gz \
-C /opt/uptime-kuma
确认目录结构正确:
find /opt/uptime-kuma/data -maxdepth 2 -type f | head
重新启动:
sudo docker compose up -d
sudo docker compose ps
如果回滚镜像版本,需要使用升级前明确记录的镜像标签或镜像 ID,不要随意猜测版本号。若当前 Compose 文件使用浮动标签,回滚前应把标签改为经过验证的固定版本,并保留修改前的 Compose 文件副本。

4. 回滚 Nginx 和证书配置
修改 Nginx 前先备份:
sudo cp -a /etc/nginx/sites-available/uptime-kuma \
/etc/nginx/sites-available/uptime-kuma.bak.$(date +%F-%H%M%S)
回滚时恢复备份文件:
sudo cp -a /etc/nginx/sites-available/uptime-kuma.bak.时间戳 \
/etc/nginx/sites-available/uptime-kuma
sudo nginx -t
sudo systemctl reload nginx
不要直接删除 /etc/letsencrypt。证书目录删除后,自动续期和现有站点配置可能同时失效。
十一、上线验收清单
1. 服务器与容器
- [ ] Docker 服务已设置为开机启动;
- [ ]
docker compose ps显示 Uptime Kuma 正常运行; - [ ]
/opt/uptime-kuma/data已挂载; - [ ] 3001 仅监听
127.0.0.1; - [ ] 云安全组和 UFW 仅开放必要端口;
- [ ] 服务器磁盘仍有足够可用空间;
- [ ] 容器重启后配置未丢失。
2. 域名与 HTTPS
- [ ] 监控域名解析到正确的美国服务器;
- [ ] HTTP 可以跳转到 HTTPS;
- [ ] 浏览器证书有效且域名匹配;
- [ ]
certbot renew --dry-run通过; - [ ] Nginx 配置测试通过;
- [ ] Uptime Kuma 页面和实时状态加载正常。
3. 监控器设置
- [ ] 首页监控已创建;
- [ ] 关键页面或 API 已创建;
- [ ] 状态码范围符合业务预期;
- [ ] 关键词检查使用稳定内容;
- [ ] 间隔、超时和重试值已经记录;
- [ ] 证书到期监控已启用或由其他系统负责;
- [ ] 不同监控器的业务优先级清晰。
4. 告警与恢复
- [ ] 故障通知测试成功;
- [ ] 恢复通知测试成功;
- [ ] 连续失败策略已验证;
- [ ] 重复通知间隔不会造成告警轰炸;
- [ ] 维护窗口流程已记录;
- [ ] 通知密钥没有出现在公开仓库或日志中;
- [ ] 测试监控器和临时目标已经删除或恢复。
5. 回滚准备
- [ ] Uptime Kuma 数据已有可读备份;
- [ ] Compose 文件和 Nginx 配置已有备份;
- [ ] 升级前镜像版本已记录;
- [ ] 已明确数据恢复命令;
- [ ] 已明确容器、Nginx 和证书的回滚边界;
- [ ] 回滚后有一组固定 URL、状态码和通知测试项。
完成这些验收后,美国服务器上的 Uptime Kuma 才算具备可运营的监控能力:既能发现网站不可达,也能识别证书、内容、响应时间和 API 状态异常。后续如果业务用户跨越多个地区,应增加不同网络位置的监控节点,并将“单点观察到的失败”与“多点同时失败”分开处理,避免把区域网络波动误判为源站整体故障。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3680.html
