Uptime Kuma Docker Compose 部署指南

Ubuntu 22.04 上以 Docker Compose 部署 Uptime Kuma 1.23.17 的完整实测：compose.yml（数据卷/自动重启/健康检查）、初始化、反代 HTTPS、升级与常见问题。

Uptime KumaUptime Kuma2026/10/17

Uptime Kuma Docker Compose 部署指南

‍‍​​‌​‍‍​​‌​> 目标：用 Docker Compose 在 Ubuntu 22.04 上完成 Uptime Kuma 1.23.17 的生产级部署——带数据卷持久化、自动重启与健康检查，覆盖初始化、反代 HTTPS、升级与常见问题排查，全部命令实测回显。

一、环境信息

项目值
操作系统Ubuntu 22.04（x86_64）
Docker29.8.1
Docker Composev5.5.1
镜像louislam/uptime-kuma:1（实测内含版本 1.23.17，2025-07-15 发布）
服务端口3001
数据目录/opt/data/uptime-kuma（宿主机路径，挂载到 /app/data）
编排目录/opt/data/quzuo/uptime-kuma-compose
验证日期2026-10-17

镜像内实际版本可通过一次性运行核实，避免「标签 ≠ 版本」的误会：

$ docker run --rm --entrypoint /bin/sh louislam/uptime-kuma:1 \
    -c "node -e 'console.log(require(\"/app/package.json\").version)'"
1.23.17

二、部署前提

  1. Docker 与 Compose 就绪：docker version 与 docker compose version 均能正常输出（本机实测 29.8.1 / v5.5.1）；
  2. 端口 3001 未被占用：ss -tlnp | grep 3001 无输出即可；
  3. 数据目录已创建：mkdir -p /opt/data/uptime-kuma，宿主机目录由容器进程自动写入，无需预先设置属主；
  4. 镜像可拉取：海外网络不畅时先配置镜像加速或代理，docker pull louislam/uptime-kuma:1 成功后再继续。

三、编写 compose.yml

在编排目录创建 compose.yml（本篇实测文件，与《Uptime Kuma 配置参数详解》中提到的环境变量可自由组合）：

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma-1.23.17-monitor
    restart: always
    ports:
      - "3001:3001"
    volumes:
      - /opt/data/uptime-kuma:/app/data
    healthcheck:
      test: ["CMD-SHELL", "extra/healthcheck"]
      interval: 60s
      timeout: 30s
      retries: 5
      start_period: 180s

逐项说明：

字段取值说明
imagelouislam/uptime-kuma:1:1 为滚动标签，自动跟随 1.x 最新版；追求确定性可固定为 :1.23.17
container_nameuptime-kuma-1.23.17-monitor固定容器名，日志排查与脚本引用都依赖它
restartalways宿主机重启、进程崩溃后自动拉起
ports3001:3001宿主端口:容器端口；若只走反向代理，可改为 127.0.0.1:3001:3001 收紧暴露面
volumes/opt/data/uptime-kuma:/app/data全部业务数据（SQLite 数据库与上传文件）落在宿主机目录，升级与重建不丢数据
healthcheckextra/healthcheck官方镜像自带探针脚本，检测数据库可写与服务响应（与镜像内置定义一致，此处显式声明便于按环境调参）

用 docker compose config 校验文件语法，确认渲染结果无告警：

$ docker compose config --no-interpolate | head -12
name: uptime-kuma-compose
networks:
  default:
    name: uptime-kuma-compose_default
services:
  uptime-kuma:
    container_name: uptime-kuma-1.23.17-monitor
    healthcheck:
      interval: 60s
      retries: 5
      start_period: 180s
      test:
        - CMD-SHELL
        - extra/healthcheck

四、启动与初始化流程

启动：

$ docker compose up -d
[+] Running 1/1
 ✔ Container uptime-kuma-1.23.17-monitor  Started

观察首次启动日志（确认版本、数据库与监听）：

$ docker compose logs --no-log-prefix 2>&1 | head -30
==> Performing startup jobs and maintenance tasks
==> Starting application with user 0 group 0
Welcome to Uptime Kuma
Your Node.js version: 18.20.3
2026-10-17T08:44:45Z [SERVER] INFO: Welcome to Uptime Kuma
2026-10-17T08:44:45Z [SERVER] INFO: Node Env: production
2026-10-17T08:44:45Z [SERVER] INFO: Inside Container: true
2026-10-17T08:44:45Z [SERVER] INFO: Importing Node libraries
2026-10-17T08:44:46Z [SERVER] INFO: Creating express and socket.io instance
2026-10-17T08:44:46Z [SERVER] INFO: Server Type: HTTP
2026-10-17T08:44:46Z [NOTIFICATION] INFO: Prepare Notification Providers
2026-10-17T08:44:46Z [SERVER] INFO: Version: 1.23.17
2026-10-17T08:44:46Z [DB] INFO: Data Dir: ./data/
2026-10-17T08:44:46Z [DB] INFO: Connecting to the Database
2026-10-17T08:44:46Z [DB] INFO: SQLite config:
[ { journal_mode: 'wal' } ]
[ { cache_size: -12000 } ]
2026-10-17T08:44:46Z [DB] INFO: SQLite Version: 3.41.1
2026-10-17T08:44:46Z [SERVER] INFO: Connected
2026-10-17T08:44:46Z [DB] INFO: Your database version: 10
2026-10-17T08:44:46Z [DB] INFO: Latest database version: 10
2026-10-17T08:44:46Z [DB] INFO: Database patch not needed
2026-10-17T08:44:46Z [SERVER] INFO: Load JWT secret from database.
2026-10-17T08:44:46Z [SERVER] INFO: Listening on 3001

关键行解读：Version: 1.23.17 确认版本；journal_mode: wal 说明数据库工作在 WAL 模式；Your database version: 10 / Database patch not needed 表示库结构就绪；Listening on 3001 即服务可访问。日志出现 No user, need setup 表示尚未创建管理员。

初始化管理员：浏览器访问 http://<服务器IP>:3001，进入设置向导，依次填写用户名、密码（两次）后提交。完成后自动登录并跳转监控面板。初始化只此一次：首次之后 setup 接口自动失效，重复请求只会返回 Added user. We don't need more users.，不存在「公网被抢先初始化」的持续风险，但仍建议初始化完成后再向公网开放端口。

确认运行状态：

$ docker compose ps
NAME                           IMAGE                     COMMAND                  SERVICE      CREATED         STATUS                   PORTS
uptime-kuma-1.23.17-monitor   louislam/uptime-kuma:1   "/usr/bin/dumb-init …"   uptime-kuma  2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:3001->3001/tcp, [::]:3001->3001/tcp

STATUS 列出现 healthy 即健康检查通过，可对外提供服务。

五、数据卷与目录结构

首次启动后宿主机数据目录内容：

$ ls -la /opt/data/uptime-kuma/
drwxr-xr-x  5 root root    4096 10月 17 16:05 .
drwxr-xr-x  2 root root    4096 10月 17 16:05 docker-tls
-rwxr-xr-x  1 root root  262144 10月 17 16:45 kuma.db
-rwxr-xr-x  1 root root   32768 10月 17 16:45 kuma.db-shm
-rwxr-xr-x  1 root root 1219552 10月 17 16:45 kuma.db-wal
drwxr-xr-x  2 root root    4096 10月 17 16:05 screenshots
drwxr-xr-x  2 root root    4096 10月 17 16:05 upload
  • kuma.db（及 -wal / -shm）：SQLite 数据库三件套，存储用户、监控项、心跳、通知与状态页，是备份的核心（详见《Uptime Kuma 运维手册》）；
  • upload：界面收集的自定义图标、证书等文件；
  • screenshots：浏览器监控的截图缓存；
  • docker-tls：监控其他 Docker 宿主机时的证书目录。

验证持久化最直接的方式：删除容器再按同一编排启动，登录态与监控项原样保留——数据全部在宿主机目录，容器本身无状态，这也是升级无所畏惧的原因。

六、健康检查机制

官方镜像内置健康检查定义，实测读取：

$ docker inspect louislam/uptime-kuma:1 --format '{{json .Config.Healthcheck}}'
{"Test":["CMD-SHELL","extra/healthcheck"],"Interval":60000000000,"Timeout":30000000000,"StartPeriod":180000000000,"Retries":5}

即每 60 秒执行一次镜像内的 extra/healthcheck 脚本（内部做数据库连通与服务响应探测），超时 30 秒，启动宽限期 180 秒（首次启动要做数据库初始化，较慢属正常），连续 5 次失败标记 unhealthy。compose.yml 中显式声明同样参数的意义：让编排文件自描述，且可按环境放宽（例如低配设备把 start_period 加到 300s）。

人工排查时可直接看最近一次探针结果：

$ docker inspect --format '{{json .State.Health}}' uptime-kuma-1.23.17-monitor | python3 -m json.tool
{
  "Status": "healthy",
  "FailingStreak": 0,
  "Log": [ ... ]
}

FailingStreak 大于 0 时，Log 数组里会携带探针脚本的输出与退出码，是最快的定位入口。

七、反向代理与 HTTPS 提示

Uptime Kuma 界面重度依赖 WebSocket（心跳实时刷新），反代配置必须放行 Upgrade 头。Nginx 参考片段：

server {
    listen 443 ssl;
    server_name status.example.com;
    # ssl_certificate / ssl_certificate_key 按你的证书路径配置

    location / {
        proxy_pass http://127.0.0.1:3001;
        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;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400s;
    }
}

Caddy 更简单，自动签发证书并默认透传 WebSocket：

status.example.com {
    reverse_proxy 127.0.0.1:3001
}

两个提示：

  • TLS 终结在代理层是推荐姿势，监控进程保持 HTTP，证书轮换不触碰服务；若坚持让服务直接 HTTPS，《Uptime Kuma 配置参数详解》第三节给出的 UPTIME_KUMA_SSL_KEY / UPTIME_KUMA_SSL_CERT 变量可在编排文件中用 environment 段传入；
  • 初始化完成前不要把代理端口暴露到公网，防止向导被陌生人抢先完成；确有需要时，在数据目录放置 setup.json（内容 {"setup": false}）可关闭向导。

八、版本升级方法

标准升级三步（先读《Uptime Kuma 运维手册》第五节，升级前完成一次备份）：

$ docker compose pull
Image louislam/uptime-kuma:1 Pulling
Image louislam/uptime-kuma:1 Pulled

$ docker compose up -d
[+] Running 1/1
 ✔ Container uptime-kuma-1.23.17-monitor  Started

pull 拉取 :1 标签指向的最新 1.x 版本，up -d 用新镜像重建容器；数据在宿主机目录，重建无损。首次启动新版本时日志会出现 Database Patch 2.0 Process 与补丁脚本执行记录，迁移自动完成。

当前镜像元信息（升级前后对比体积与创建时间）：

$ docker compose images
CONTAINER                      REPOSITORY             TAG      PLATFORM    IMAGE ID        SIZE     CREATED
uptime-kuma-1.23.17-monitor   louislam/uptime-kuma   1        linux/amd64 70233f4acb51    724MB    4 weeks ago

标签策略：:1 省心但升级时间不可控；:1.23.17 完全受控但需手动改标签滚动。折中方案是编排文件固定小版本标签，由你按节奏修改后 up -d。

两条红线：

  • 不要从 2.x 降回 1.x，库结构不兼容，只能靠备份回退；
  • 升级后若界面白屏或数据异常，先强制刷新浏览器（旧前端缓存与新版接口不匹配），再查日志。

九、常见问题

1. 端口 3001 被占用。ss -tlnp | grep 3001 找出占用进程；无法让出时改编排文件映射（如 3002:3001），界面改从新端口访问，反向代理目标同步修改。

2. 容器反复重启（Restarting）。先看日志：docker compose logs --tail 50。最常见原因是数据目录权限异常或目录挂载路径写错（宿主路径不存在时 Compose 会自动创建空目录，表现为初始化向导再次出现）——初始化页重现几乎总是数据卷没挂对，先核对 volumes 段再动手。

3. 状态一直 starting / unhealthy。启动宽限期 180 秒内属正常；超时后仍 starting，用 docker inspect --format '{{json .State.Health}}' 看 FailingStreak 与探针输出，多为宿主机资源耗尽或数据库文件损坏（恢复路径见《Uptime Kuma 运维手册》）。

4. 升级后界面显示旧版本。浏览器缓存所致，强制刷新（Ctrl+F5）即可；确认实际版本以日志中 Version: 行为准。

5. 页面能打开但心跳不实时刷新。反向代理未放行 WebSocket，按第七节补齐 Upgrade 头，或临时直连 3001 端口验证差异。

6. 想让监控数据落在指定磁盘。把编排文件的宿主侧路径改为目标盘路径（如 /data1/uptime-kuma）并整体迁移目录内容，docker compose up -d 重建后生效。

十、参考链接