Docker Compose 部署 Uptime Kuma：配置 HTTPS、QQ 邮箱告警与数据备份

网站部署完成后，还需要回答一个问题：如果凌晨访问失败，谁来发现？

手动打开网页只能确认某个时刻的访问情况。要持续了解网站是否可用，需要定时检测、保留记录，并在故障发生时发送通知。

本文使用 Docker Compose 部署 Uptime Kuma，通过 Caddy 提供 HTTPS 访问，再配置 QQ 邮箱告警。最后用一个独立的 Nginx 测试容器，验证故障和恢复通知是否真正送达。

封面为 AI 概念插画，并非 Uptime Kuma 后台截图。

一、先明确各个服务的作用

这套配置包含三个服务：

服务	用途	是否默认启动
Uptime Kuma	检查网站状态、记录结果、发送通知	是
Caddy	提供 HTTPS 入口，管理证书	是
demo-web	模拟网站故障，验证告警	否

浏览器通过 HTTPS 访问 Caddy，Caddy 再通过 Docker 内部网络连接 Uptime Kuma。

因此，宿主机只需要为这套服务开放 TCP 80、443，无需额外开放 Uptime Kuma 的 3001 端口。

需要注意，本文配置的是网站可用性监控。一个页面能够返回正常 HTTP 状态，不代表登录、支付、数据库等业务功能全部正常。后续应根据业务增加更有针对性的检测项。

二、准备服务器、域名和 Docker

本文适用于新建部署，以 Debian 12 或 Ubuntu 24.04 为例。

服务器可以选择莱卡云等提供的 Linux 云主机，具体资源根据监控数量和检测频率调整。更值得优先考虑的是部署位置：尽量让监控服务与被监控网站分开，减少一台机器故障导致两者同时停止的情况。

开始之前，需要满足以下条件：

• 已安装 Docker Engine 和新版 Compose 插件。

• 有一个可以修改 DNS 解析的域名。

• 宿主机 TCP 80、443 没有被其他服务占用。

• 安全组和系统防火墙允许访问这两个端口。

• 准备好发送通知的 QQ 邮箱，以及接收告警的邮箱。

以下服务器命令按 root 用户编写。

先检查 Docker：

docker --version
docker compose version
systemctl is-active docker
docker run --rm hello-world

版本命令应正常输出，Docker 服务应显示 active，测试容器应能正常运行。

如果尚未安装，可以按系统选择官方安装说明：

• Docker Engine：Debian 安装说明

• Docker Engine：Ubuntu 安装说明

本文使用的是带空格的 docker compose 命令。

三、为监控面板解析域名

假设计划使用：

status.example.com

在 DNS 管理页面添加 A 记录，将其指向监控服务器的公网 IPv4 地址。

这里的域名只是示例，后面的配置必须替换成自己的真实域名。

如果服务器没有配置可用的 IPv6，不要给这个子域名保留错误的 AAAA 记录，否则可能出现部分请求或证书验证访问到错误地址的情况。

同时确认服务器上的 80、443 端口可以交给 Caddy 使用。已经运行 Nginx、宝塔或其他反向代理的机器，需要先处理端口冲突，不能直接叠加这份配置。

四、编写 Compose 配置

创建项目目录：

mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

在目录中创建 compose.yaml，内容如下。已有部署请先备份，不要直接覆盖原文件。

将 status.example.com 替换为自己的监控域名：

name: uptime-kuma

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.6-slim
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
      UPTIME_KUMA_DB_TYPE: sqlite
    volumes:
      - ./data:/app/data

  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    command:
      - caddy
      - reverse-proxy
      - --from
      - status.example.com
      - --to
      - uptime-kuma:3001
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./caddy-data:/data
      - ./caddy-config:/config
    depends_on:
      - uptime-kuma

  demo-web:
    image: nginx:alpine
    profiles: [demo]
    restart: unless-stopped

这里沿用原教程的 2.5.6-slim 版本，便于对照配置，并不表示它始终是最新版本。后续更新应先查看版本说明。

几个容易忽略的地方：

./data:/app/data 用于持久化监控数据。重建容器时，应继续使用原来的数据目录。

UPTIME_KUMA_DB_TYPE: sqlite 指定使用 SQLite，本次部署不需要额外运行数据库服务。

uptime-kuma:3001 是 Caddy 在 Compose 网络中访问的服务地址。不要改成 localhost:3001，因为 Caddy 容器中的 localhost 指向它自身。

caddy-data 保存证书等持久化数据，不能把它当成随时可以删除的缓存。

demo-web 带有 demo profile，普通启动时不会一起运行，后面测试通知时再启用。

五、启动并检查 HTTPS 访问

在项目目录执行：

cd /opt/uptime-kuma
docker compose config -q && docker compose up -d

其中，config -q 用于检查 Compose 配置能否正确解析。没有错误后，才会执行启动命令。

查看容器和应用日志：

docker compose ps
docker compose logs --tail=100 uptime-kuma
docker compose logs --tail=100 caddy

首次启动需要拉取镜像、初始化数据和申请证书。容器显示运行，并不意味着这些步骤已经全部完成。

等待初始化完成后，在浏览器访问：

https://你的监控域名

及时创建管理员账户，设置独立的高强度密码，并根据需要启用双重验证。

如果浏览器提示证书错误，先检查 DNS 解析、端口访问和 Caddy 日志，处理后再登录。

本配置由 Caddy 自动申请和续期证书。长期运行时，仍需保持域名解析正确、验证所需端口可达，以及证书目录可持久保存。

六、添加真实网站监控

登录后新增一个 HTTP(s) 监控项：

设置项	示例
显示名称	官网首页
监控类型	HTTP(s)
URL	自己网站的完整 HTTPS 地址
检测间隔	60 秒
重试次数	1 次
重试间隔	60 秒

只检测自己拥有或获得授权的网站。

保存后，等待页面出现实际检测结果，再确认状态和响应时间是否持续更新。

检测间隔不等于邮件到达时间。一次故障还可能经历请求超时、重试、状态确认和邮件投递，不应把"每 60 秒检测"理解为"故障发生后必定在 60 秒内收到邮件"。

七、配置 QQ 邮箱通知

登录 QQ 邮箱网页版，在账号相关设置中开启 SMTP 服务，并按页面提示生成授权码。

这里需要的是邮箱授权码，不是 QQ 登录密码。

随后在 Uptime Kuma 中新增 Email（SMTP）通知：

设置项	填写内容
通知名称	网站邮件告警
SMTP 主机	smtp.qq.com
SMTP 端口	465
安全连接	SSL/TLS
用户名	完整 QQ 邮箱地址
密码	QQ 邮箱授权码
发件人	与用户名一致的邮箱地址
收件人	实际接收告警的邮箱

保持证书校验开启，不要通过忽略证书错误来处理连接失败。

配置后，依次完成三件事：

1. 点击测试，并到收件箱确认收到邮件。

2. 保存这条通知配置。

3. 编辑网站监控项，勾选这条通知并保存。

测试邮件验证的是通知通道；监控项关联通知后，网站状态变化才能触发对应告警。

如果服务器限制出站连接，还需要检查能否连接 smtp.qq.com:465。这里是服务器向外发送邮件，不需要开放服务器入站 465 端口。

八、验证故障邮件和恢复邮件

不要用正在提供服务的业务网站做停机实验。前面的配置已经准备了一个独立测试容器。

先启动它：

cd /opt/uptime-kuma
docker compose --profile demo up -d demo-web

在 Uptime Kuma 中新增测试监控：

设置项	填写内容
显示名称	Nginx 告警测试
监控类型	HTTP(s)
URL	http://demo-web
检测间隔	20 秒
重试次数	1 次
重试间隔	20 秒
通知	勾选"网站邮件告警"

demo-web 是 Docker 网络内的服务名称。这个地址填在 Uptime Kuma 中即可，不需要在个人电脑浏览器中打开。

先等监控状态正常，再停止测试容器：

docker compose --profile demo stop demo-web

等监控完成检测与重试、正式进入故障状态后，检查邮箱是否收到故障通知。

然后恢复测试容器：

docker compose --profile demo start demo-web

再次确认监控恢复正常，并实际收到恢复邮件。

阶段	应确认的结果
启动测试服务	监控显示正常
停止测试服务	进入故障状态，收到故障邮件
恢复测试服务	恢复正常状态，收到恢复邮件

整个测试过程中，只操作 demo-web。不要执行整个项目的 docker compose down，否则监控服务本身也会停止。

测试结束后，先暂停或删除测试监控项，再停止测试容器，避免产生预期之外的告警。

这次演练验证了容器内部 HTTP 检测与邮件通知流程。实际网站的公网域名、HTTPS 和外部访问情况，仍要通过真实网站监控项单独确认。

九、为配置和数据做备份

这套部署需要保留四部分内容：

文件或目录	内容
compose.yaml	部署配置
data	监控数据及应用配置
caddy-data	证书等数据
caddy-config	Caddy 配置数据

为了避免直接复制正在写入的 SQLite 文件，可以在短暂停机窗口内完成备份。

下面的命令会暂停监控和网页访问，打包结束后尝试重新启动服务：

(
  set -e
  cd /opt/uptime-kuma
  umask 077
  mkdir -p /opt/uptime-kuma-backups

  trap 'docker compose start uptime-kuma caddy' EXIT
  docker compose stop uptime-kuma caddy

  tar -czf "/opt/uptime-kuma-backups/kuma-$(date +%Y%m%d-%H%M%S).tar.gz" \
    compose.yaml data caddy-data caddy-config
)

执行后检查服务：

cd /opt/uptime-kuma
docker compose ps

再打开 HTTPS 页面，确认监控恢复工作。

备份文件包含通知配置和证书私钥，应限制访问，并复制到其他设备保存。只把备份放在同一台服务器上，无法应对整机或磁盘故障。

正式升级前，除了生成备份，还应确认它能在隔离环境中恢复。恢复演练时注意控制通知发送，避免测试实例重复告警。

十、遇到问题时从哪里查

1. 域名打不开，或者证书申请失败

先检查域名 A/AAAA 记录、安全组、系统防火墙和端口占用，再查看：

cd /opt/uptime-kuma
docker compose logs --tail=100 caddy

2. HTTPS 页面出现 502

先确认 Uptime Kuma 是否完成初始化：

docker compose ps
docker compose logs --tail=100 uptime-kuma

配置中的 depends_on 不代表应用已经准备好接受请求。首次启动可以等待初始化完成；持续报错则应按日志定位。

3. 面板显示故障，但没有邮件

先区分两个问题：

• 测试邮件也收不到：检查 SMTP 设置、授权码、出站连接和收件箱。

• 测试邮件能收到，故障邮件收不到：检查监控项是否关联了通知，以及是否已经进入最终故障状态。

4. 容器反复重启

查看应用日志和磁盘空间：

docker compose logs --tail=100 uptime-kuma
df -h

不要把删除数据目录当成常规排错步骤。先保留数据，再根据报错处理。

这套部署是否完成，可以用三个实际结果判断：HTTPS 面板可以正常登录，故障与恢复邮件都能收到，备份能够恢复。后续再根据业务需求增加监控项、调整检测频率，比一开始堆叠大量配置更容易维护。

原始搭建教程：Docker搭建Uptime Kuma网站监控

项目地址：Uptime Kuma

HTTPS 配置参考：Caddy Automatic HTTPS