KuvaszUptime 4.6.0 Docker Compose 部署指南

目标：使用 Docker Compose 在 Linux 服务器上从零部署一个生产可用的 KuvaszUptime（项目名 Kuvasz）可用性与 SSL 证书监控服务，覆盖镜像选型、部署目录规划、配置文件挂载、数据持久化、等价 docker run 与常见故障排查。已在 Ubuntu 26.04.1 LTS（x86_64，Kuvasz 4.6.0 官方发行镜像）实测通过，Web 与 API 服务映射宿主机 8141 端口。软件的定位、功能全景与同类对比见《KuvaszUptime 介绍与选型指南》。

一、环境信息

本篇所有部署命令均在以下环境实测，回显逐条照抄：

• 操作系统：Ubuntu 26.04.1 LTS（x86_64）
• Docker：Docker version 29.9.2, build a82e528（docker --version 实测）
• Docker Compose：Docker Compose version v5.6.1（docker compose version 实测）
• Kuvasz 版本：4.6.0（官方最新稳定版，2026-10-25 发布；来源：官网 Changelog https://kuvasz-uptime.dev/changelog/，查询日期 2026-11-01；应用内「设置」页的版本自检接口 GET /api/v2/settings 实测返回 versionInfo.installedVersion: 4.6.0、isUpToDate: true，双向印证）
• 数据库：PostgreSQL 18（pgautoupgrade/pgautoupgrade:18-alpine 发行镜像；Kuvasz 官方最低实测版本为 PostgreSQL 14，来源：官方文档 Deployment 页，查询日期 2026-11-01）
• 服务端口：宿主机 8141 → 应用 8080
• 部署目录：/opt/data/kuvasz-uptime/
• 管理账号：admin，密码 q1w2e3r4q1w2e3r4（⚠️ Kuvasz 要求管理密码最少 12 位且不得与用户名相同，8 位的 q1w2e3r4 无法通过启动校验，故示例口令翻倍至 16 位，规则见官方文档 Configuration reference）
• REST API Key：kuvasz-demo-api-key-2026（官方要求最少 16 位，实测不足 16 位应用拒绝启动，见第十一章 Q2）

二、镜像选型说明

Kuvasz 只以 Docker 镜像形态分发（官方不提供裸机二进制与系统软件包），部署前先弄清「用哪个镜像、为什么」。本章结论：应用固定用官方 kuvaszmonitoring/kuvasz，数据库固定用与官方示例一致的 pgautoupgrade/pgautoupgrade。

2.1 应用镜像：kuvaszmonitoring/kuvasz

应用镜像托管在 Docker Hub 官方仓库 kuvaszmonitoring/kuvasz，官方同时在 GitHub Packages 提供 Helm Chart 形态（Kubernetes 部署用，本篇不展开）。

选型建议：本系列文档与实测均锁定 4.6.0。首次拉取的实测回显如下（该 tag 当前 digest 为 sha256:03371e15b5d3…，可用于核对镜像一致性）：

4.6.0: Pulling from kuvaszmonitoring/kuvasz
Digest: sha256:03371e15b5d3076370c5febca5994a34cc16c8e2c6aac041226fe0f471546fe8
Status: Downloaded newer image for kuvaszmonitoring/kuvasz:4.6.0
docker.io/kuvaszmonitoring/kuvasz:4.6.0

2.2 数据库镜像：为什么是 pgautoupgrade 而不是普通 postgres

Kuvasz 把全部监控器、检查结果、事件与状态页数据存在 PostgreSQL 里，官方部署文档给出的 compose 示例选用 pgautoupgrade/pgautoupgrade:18-alpine 而非普通 postgres:18-alpine，实测本篇沿用同款。

💡 技术拓展：自托管应用的数据库镜像常见三种选法——

选法	特点	适用场景
官方 postgres:<版本>	纯净、行为最标准	数据库大版本长期不变
pgautoupgrade/pgautoupgrade	启动时自动检测并升级数据目录到镜像内的大版本	想跟着应用一起无痛升 PG 大版本
bitnami/postgresql	带环境变量习惯封装与 charts 生态	已用 Bitnami 系列统一管理

Kuvasz 官方示例选 pgautoupgrade 的意图很直接：数据库大版本升级（如 14 → 15 → 16）历来是自托管应用最痛的运维点之一，换镜像即完成迁移。本文/本方案实际采用 pgautoupgrade/pgautoupgrade:18-alpine，与官方示例保持一致。

2.3 镜像体积实测

docker image ls kuvaszmonitoring/kuvasz --format '{{.Repository}}:{{.Tag}}  {{.Size}}  {{.ID}}'
docker image ls pgautoupgrade/pgautoupgrade --format '{{.Repository}}:{{.Tag}}  {{.Size}}  {{.ID}}'

实测输出：

kuvaszmonitoring/kuvasz:4.6.0  680MB  03371e15b5d3
pgautoupgrade/pgautoupgrade:18-alpine  764MB  e9fe125da1a0

应用镜像 680 MB（内含 JRE 运行时），数据库镜像 764 MB。官方资源基线：默认配置下 1,000 个监控器以内需要 768 MB 内存与 1 核（监控器更少时通常 512 MB 以内即可），来源：官方文档 Deployment 页「How much memory and CPU does Kuvasz need?」，查询日期 2026-11-01。

三、前置条件

开始部署前，按顺序确认三件事：端口空闲、Docker 环境就绪、镜像可达。

3.1 确认端口未被占用

本篇把 Web/API 映射到宿主机 8141（避开 8080 等常用端口）。确认目标端口空闲：

ss -ltn | grep 8141 || echo '8141 空闲，可用'

实测输出（部署完成后回看应出现监听行，部署前应无输出）：

LISTEN 0      4096         0.0.0.0:8141       0.0.0.0:*
LISTEN 0      4096            [::]:8141          [::]:*

若 8141 已被占用，把 compose 中的 "8141:8080" 改成任意空闲高位端口即可，应用内部始终监听 8080。

3.2 确认 Docker 与 Compose 就绪

docker --version && docker compose version

实测输出：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

两个命令都能出版本号即就绪。缺失时安装 Docker Engine（官方 get.docker.com 脚本或发行版仓库均可），Compose v2 起已内置于 Docker CLI 插件，无需单独安装。

3.3 拉取镜像

docker pull kuvaszmonitoring/kuvasz:4.6.0
docker pull pgautoupgrade/pgautoupgrade:18-alpine

实测输出（应用镜像）：

4.6.0: Pulling from kuvaszmonitoring/kuvasz
Digest: sha256:03371e15b5d3076370c5febca5994a34cc16c8e2c6aac041226fe0f471546fe8
Status: Downloaded newer image for kuvaszmonitoring/kuvasz:4.6.0
docker.io/kuvaszmonitoring/kuvasz:4.6.0

⚠️ 网络说明：两个镜像均来自 Docker Hub（docker.io）。本次实测环境下 Docker 守护进程已配置 HTTP 代理（192.168.1.62:7897），拉取直连成功未发生降级；国内服务器拉取缓慢或超时时，可为 Docker 守护进程配置代理或 registry mirror（/etc/docker/daemon.json 的 proxies / registry-mirrors 配置，改后 systemctl restart docker 生效），镜像本身在 Docker Hub 官方仓库始终可拉。

四、部署步骤

主线步骤共四步：建目录与配置文件 → 写 compose 文件 → 启动 → 验证。全程只需两个文件，都在部署目录 /opt/data/kuvasz-uptime/ 内。

4.1 建部署目录与配置文件

mkdir -p /opt/data/kuvasz-uptime && cd /opt/data/kuvasz-uptime

创建最小配置文件 kuvasz.yml（先用空配置启动完全合法，集成与监控器都可以之后再通过 Web 界面添加）：

touch kuvasz.yml

💡 说明：kuvasz.yml 是 Kuvasz 的 YAML 声明式配置入口，可承载集成（Slack/PagerDuty/邮件等）、全部六类监控器、状态页与维护窗口的定义，与应用级参数的 ENV 写法自由混用。本篇从零部署阶段保持空文件即可；逐项参数的取值、默认值与生效验证在配置详解篇展开，推送心跳、ICMP/TCP/DNS 等监控类型的 YAML 定义样例也可在《介绍与选型指南》的功能特性章找到背景说明。

4.2 编写 docker-compose.yml

创建 /opt/data/kuvasz-uptime/docker-compose.yml，内容如下（与官方示例同构，凭据与时区按本文实测值落定）：

# /opt/data/kuvasz-uptime/docker-compose.yml
name: kuvasz-uptime-460-stack

services:
  kuvasz-db:
    image: pgautoupgrade/pgautoupgrade:18-alpine
    container_name: kuvasz-4.6.0-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: kuvasz
      POSTGRES_PASSWORD: kuvaszdb2026
      TZ: 'Asia/Shanghai'
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "kuvasz"]
      interval: 10s
      start_period: 30s
    volumes:
      - kuvasz-db-data:/var/lib/postgresql
    networks:
      - kuvasz-net

  kuvasz:
    image: kuvaszmonitoring/kuvasz:4.6.0
    container_name: kuvasz-4.6.0-app
    restart: unless-stopped
    ports:
      - "8141:8080"
    environment:
      TZ: 'Asia/Shanghai'
      DATABASE_HOST: kuvasz-4.6.0-db
      DATABASE_USER: kuvasz
      DATABASE_PASSWORD: kuvaszdb2026
      ADMIN_USER: admin
      ADMIN_PASSWORD: q1w2e3r4q1w2e3r4
      ADMIN_API_KEY: kuvasz-demo-api-key-2026
    volumes:
      - /opt/data/kuvasz-uptime/kuvasz.yml:/config/kuvasz.yml
    healthcheck:
      test: ["CMD-SHELL", "wget --quiet --tries=1 --spider http://localhost:8080/api/v2/health || exit 1"]
      interval: 60s
      start_period: 30s
    depends_on:
      kuvasz-db:
        condition: service_healthy
    networks:
      - kuvasz-net

networks:
  kuvasz-net:
    driver: bridge

volumes:
  kuvasz-db-data:

逐段说明：

• name: kuvasz-uptime-460-stack：显式固定 compose 项目名。不写时项目名默认取目录名，目录一旦改名，下次 up 会被当成新项目、生成第二套同名服务，显式声明可避免这一类事故；
• kuvasz-db 服务：POSTGRES_USER/POSTGRES_PASSWORD 是数据库初始化凭据（首次建库后固化进数据卷，改动需先清卷，官方部署文档特别提醒过这一点）；healthcheck 用 pg_isready 就绪探测，配合 start_period: 30s 给首次初始化留时间；
• volumes: kuvasz-db-data:/var/lib/postgresql：命名卷做数据持久化，删服务不删数据（见第五章）；
• kuvasz 服务：ports 把应用内部 8080 映射到宿主机 8141；DATABASE_HOST 直接填数据库服务的 container_name（同 compose 网络内该名字可解析）；ADMIN_USER/ADMIN_PASSWORD/ADMIN_API_KEY 是 Web 登录与 REST API 的凭据，密码最少 12 位、API Key 最少 16 位，不满足应用会拒绝启动（见第十一章）；
• volumes: /opt/data/kuvasz-uptime/kuvasz.yml:/config/kuvasz.yml：YAML 配置文件的固定读取路径就是 /config/kuvasz.yml，必须按此路径挂载；
• 应用侧 healthcheck 探测自带健康端点 /api/v2/health，60 秒间隔；
• depends_on 带 condition: service_healthy：确保数据库完全就绪后应用才启动，否则应用会在数据库未就绪时连接失败重启。

4.3 启动

cd /opt/data/kuvasz-uptime && docker compose up -d

实测输出：

 Network kuvasz-uptime-460-stack_kuvasz-net Creating
 Network kuvasz-uptime-460-stack_kuvasz-net Creating
 Network kuvasz-uptime-460-stack_kuvasz-net Created
 Network kuvasz-uptime-460-stack_kuvasz-net Created
 Container kuvasz-4.6.0-db Creating
 Container kuvasz-4.6.0-db Created
 Container kuvasz-4.6.0-app Creating
 Container kuvasz-4.6.0-app Created
 Container kuvasz-4.6.0-db Starting
 Container kuvasz-4.6.0-db Started
 Container kuvasz-4.6.0-db Waiting
 Container kuvasz-4.6.0-db Healthy
 Container kuvasz-4.6.0-app Starting
 Container kuvasz-4.6.0-app Started

网络状态行打印两次是 compose v5 对「两个服务共用同一网络」的正常输出，非异常。注意 kuvasz-4.6.0-db Healthy 出现在应用启动之前——depends_on 条件生效的直接证据。

4.4 部署验证

四步验证：状态、健康端点、登录页、启动日志。

第一步，两个服务状态应为 Up 且数据库 healthy：

docker compose ps

实测输出（应用刚启动时健康检查处于 starting，约 1 分钟后转 healthy）：

NAME               IMAGE                                   COMMAND                  SERVICE     CREATED         STATUS                                     PORTS
kuvasz-4.6.0-app   kuvaszmonitoring/kuvasz:4.6.0           "java -XX:+UseCompac…"   kuvasz      6 seconds ago   Up Less than a second (health: starting)   0.0.0.0:8141->8080/tcp, [::]:8141->8080/tcp
kuvasz-4.6.0-db    pgautoupgrade/pgautoupgrade:18-alpine   "/usr/local/bin/dock…"   kuvasz-db   6 seconds ago   Up 5 seconds (healthy)                     5432/tcp

第二步，健康端点返回 UP（该端点无需认证，可直接作为拨测目标）：

curl -s http://127.0.0.1:8141/api/v2/health

实测输出：

{"name":null,"status":"UP","details":null}

第三步，浏览器访问 http://<服务器IP>:8141/，出现登录页后用 admin / q1w2e3r4q1w2e3r4 登录，即可进入控制台添加第一批监控器。命令行验证登录页可达：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8141/login

实测输出：

200

第四步，启动日志应看到「成功引导」与启动完成两行关键信息：

docker compose logs --tail 3 kuvasz

实测输出：

kuvasz-4.6.0-app  | 14:59:06.435 [main] INFO  c.k.kuvasz.services.AppBootstrapper - Kuvasz was successfully bootstrapped. Version: 4.6.0
kuvasz-4.6.0-app  | 14:59:07.169 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 1349ms. Server Running: http://4b03e9dc0fcf:8080

Server Running: 后面是容器内部主机名与内部端口 8080，属正常现象；对外访问一律走 http://<服务器IP>:8141。

五、数据持久化说明

监控器配置、检查结果、事件历史、状态页全部存在 PostgreSQL 数据卷 kuvasz-db-data 中；kuvasz.yml 则直接落在宿主机部署目录。两者共同构成全部持久化状态，容器本身无状态，随时可重建。

用「停止整套服务再启动」验证数据不丢：

cd /opt/data/kuvasz-uptime && docker compose down && docker compose up -d

实测输出（down 段）：

 Container kuvasz-4.6.0-app Stopping
 Container kuvasz-4.6.0-app Stopped
 Container kuvasz-4.6.0-app Removing
 Container kuvasz-4.6.0-app Removed
 Container kuvasz-4.6.0-db Stopping
 Container kuvasz-4.6.0-db Stopped
 Container kuvasz-4.6.0-db Removing
 Container kuvasz-4.6.0-db Removed
 Network kuvasz-uptime-460-stack_kuvasz-net Removing
 Network kuvasz-uptime-460-stack_kuvasz-net Removed

重启后检查数据完整性：登录 Web 或调 REST API（Key 用 kuvasz-demo-api-key-2026）查看此前创建的监控器，实测重启后监控器与其历史状态原样保留（GET /api/v2/push-monitors 返回的 nightly-backup 监控器 createdAt: 2026-11-01T12:46:10 为重启前时间，uptimeStatus: DOWN 的事故状态也原样延续）。

💡 技术拓展：容器场景的数据持久化常见三种做法——

方式	原理	适用场景
named volume（本篇）	Docker 统一管理的数据卷	数据库类服务，官方推荐
bind mount 宿主目录	直接映射宿主机目录	需要直接查看/备份数据文件
容器内临时存储	不挂载即消失	仅一次性测试

Kuvasz 官方示例对数据库用 named volume、对 kuvasz.yml 用 bind mount，各取所长：数据库文件不需要人工触碰，配置文件需要随手编辑。本文沿用此分工。删除数据卷才会真正清库：docker compose down -v。

六、环境变量表

compose 中出现的环境变量分两组：数据库初始化组（POSTGRES_*，归 PostgreSQL 镜像消费）与应用组（其余，归 Kuvasz 消费）。Kuvasz 支持环境变量与 YAML 两种写法并可自由混用，下表同时给出每个 ENV 对应的 YAML 键与默认值（来源：官方 Configuration reference，查询日期 2026-11-01）：

关键差异解读：POSTGRES_* 与 DATABASE_* 必须成对一致，否则应用连库失败；ADMIN_* 三项是本部署唯一的登录与 API 凭据来源，生产环境务必替换为强凭据。未出现在表中的其余应用参数（保留期、SMTP、指标导出等）不在 compose 里硬编码，走 YAML 或在需要时补 ENV，逐项详解见本系列配置详解篇。

七、配置参数说明

Kuvasz 的配置分三个层面，部署完成后应清楚每一层管什么：

1. 部署层（docker-compose.yml）：管「服务怎么跑」——端口映射、持久化、凭据注入、健康检查与启动顺序，本篇第四、六章已覆盖；
2. 应用层（kuvasz.yml 与 ENV 双轨）：管「应用行为」——认证开关与会话时长、数据保留期、HTTP 检查超时、语言、指标导出、SMTP 等。两个载体取值一致时效果完全等价，修改后需重启生效；
3. 资源层（kuvasz.yml 专属列表配置）：管「监控什么、通知谁」——集成（Slack/PagerDuty/Teams/邮件/Webhook）、六类监控器、状态页、维护窗口，只能写在 YAML（或经 Web/API 动态创建）。

一个重要机制：凡是出现在 kuvasz.yml 里的资源类型，外部修改会被冻结。实测本部署在 kuvasz.yml 中定义了一个 HTTP 监控器后，启动日志明确打印：

14:59:06.385 [main] INFO  c.k.kuvasz.services.AppBootstrapper - Disabled external modifications of HTTP_SSL monitors, because a YAML monitor config was found. Loading HTTP_SSL monitors from YAML config...
14:59:06.407 [main] INFO  c.k.k.s.monitor.MonitorImporter - Loaded 1 http monitors from external config, dryrun: false

此后该类型监控器在 Web 界面与 REST API 中均为只读，改 YAML 重启才是唯一修改通道——这是防「YAML 与界面双头修改打架」的设计，把 IaC 文件当作唯一事实源。何时该把监控器写进 YAML、各参数取值范围与生效验证，见本系列配置详解篇。

八、配置文件挂载

kuvasz.yml 通过 bind mount 挂到应用固定读取路径 /config/kuvasz.yml，文件修改在宿主机直接进行，随后重启应用生效：

vi /opt/data/kuvasz-uptime/kuvasz.yml
cd /opt/data/kuvasz-uptime && docker compose restart kuvasz

实测输出：

 Container kuvasz-4.6.0-app Restarting
 Container kuvasz-4.6.0-app Started

两个实测结论：

1. 修改必然要重启：与支持配置热重载的 Gatus 不同，Kuvasz 在启动时读取并导入 YAML 配置，重启前修改不生效。实测修改 kuvasz.yml 增加应用级参数（保留期、重定向上限）后重启，GET /api/v2/settings 返回的生效值随之变化（eventDataRetentionDays: 365 → 180、httpCheckMaxRedirects: 10 → 15）；
2. 重启期间监控不中断风险可控：重启耗时秒级（应用本体启动约 1.3~1.6 秒），但监控器调度在重启期间暂停，建议把大改版安排在检查间隔的空档。

YAML 写坏会导致应用拒绝启动（排障实录见第十一章 Q3）。

九、等价 docker run

不使用 compose 时的等价单命令部署，共三条命令：建网络 → 起数据库 → 起应用。以下命令实测可完整启动并通过验证（本节实测使用独立测试卷，不影响既有部署）：

# 1. 创建应用与数据库共用的网络
docker network create kuvasz-net

# 2. 启动 PostgreSQL（数据落命名卷 kuvasz-db-data）
docker run -d \
  --name kuvasz-db \
  --network kuvasz-net \
  --restart unless-stopped \
  -e POSTGRES_USER=kuvasz \
  -e POSTGRES_PASSWORD=kuvaszdb2026 \
  -e TZ=Asia/Shanghai \
  -v kuvasz-db-data:/var/lib/postgresql \
  pgautoupgrade/pgautoupgrade:18-alpine

# 3. 等数据库就绪后启动 Kuvasz（约 15 秒）
docker run -d \
  --name kuvasz-app \
  --network kuvasz-net \
  --restart unless-stopped \
  -p 8141:8080 \
  -e TZ=Asia/Shanghai \
  -e DATABASE_HOST=kuvasz-db \
  -e DATABASE_USER=kuvasz \
  -e DATABASE_PASSWORD=kuvaszdb2026 \
  -e ADMIN_USER=admin \
  -e ADMIN_PASSWORD=q1w2e3r4q1w2e3r4 \
  -e ADMIN_API_KEY=kuvasz-demo-api-key-2026 \
  -v /opt/data/kuvasz-uptime/kuvasz.yml:/config/kuvasz.yml \
  kuvaszmonitoring/kuvasz:4.6.0

验证（实测输出）：

curl -s http://127.0.0.1:8141/api/v2/health

{"name":null,"status":"UP","details":null}

首启日志关键行（实测）：

15:11:31.701 [main] INFO  c.k.kuvasz.services.AppBootstrapper - Kuvasz was successfully bootstrapped. Version: 4.6.0
15:11:32.456 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 1645ms. Server Running: http://3b3d9a4f8dde:8080

参数与 compose 的对应关系：--network ↔ networks，-e ↔ environment，-p 8141:8080 ↔ ports，-v ↔ volumes。区别在于 compose 版的 depends_on: service_healthy 与数据库 healthcheck 在 docker run 模式下退化成「等待约 15 秒再启动应用」——生产环境多服务协同时仍推荐 compose，启动顺序由编排保证而非人肉计时。

十、常用运维命令

升级操作实测路径示例（4.6.0 → 后续版本）：把 compose 中两处 image tag 换成目标版本，docker compose up -d 即可，compose 会重建应用服务；数据库大版本如需跨越，pgautoupgrade 镜像会在启动时自动迁移数据目录。

十一、常见问题（FAQ）

Q1：ADMIN_PASSWORD 设成短口令或与用户名相同会怎样？ 应用启动校验失败，直接拒绝启动。官方规则：密码最少 12 位、不得与用户名相同（来源：官方 Configuration reference「The password for the admin user, minimum 12 characters long, can't be the same as the username」，查询日期 2026-11-01）。本篇实测用的 q1w2e3r4（8 位）不满足要求，故示例翻倍为 q1w2e3r4q1w2e3r4。

Q2：ADMIN_API_KEY 设短了会怎样？ 实测把 API Key 改成 short 后重建服务，应用启动即崩，日志关键行：

kuvasz-4.6.0-app  | Caused by: jakarta.validation.ValidationException: Admin API key must be at least 16 characters
kuvasz-4.6.0-app  | 	at com.kuvaszuptime.kuvasz.services.AppBootstrapper.validateApiKeyLength(AppBootstrapper.kt:167)

把 Key 换回 16 位以上重建即恢复。同理 ADMIN_MCP_API_KEY 也要求最少 16 位。

Q3：kuvasz.yml 写坏了会怎样？ 实测在文件尾部追加一行非法 YAML（ broken-key: [）后重启，应用启动即崩，日志关键行：

15:00:01.483 [main] ERROR io.micronaut.runtime.Micronaut - Error starting Micronaut server: while parsing a flow node

修复方式：还原文件语法后 docker compose restart kuvasz。因为文件是 bind mount，语法错误的代价只是应用起不来，宿主机改回来再重启即可，不涉及数据损坏。

Q4：启动时日志出现 DB: schema "kuvasz" already exists, skipping 正常吗？ 正常。实测全新数据卷的首次启动也会打印：

15:11:31.209 [main] WARN  o.f.c.i.p.ErrorOverridesSupportStub - DB: schema "kuvasz" already exists, skipping (SQL State: 42P06 - Error Code: 0)

这是应用初始化流程的幂等建 schema 输出：Kuvasz 会在目标数据库（默认库名 postgres）内自建 kuvasz schema 并完成建表迁移，日志紧随其后的 Kuvasz was successfully bootstrapped. Version: 4.6.0 才是判定启动成功的依据。

Q5：数据库凭据改了为什么连不上？ POSTGRES_USER/POSTGRES_PASSWORD 只在数据卷首次初始化时生效，之后固化进卷；只改 compose 再 up -d 不会改掉已初始化的库。要么保持 DATABASE_* 与首次初始化值一致，要么清卷重建（docker compose down -v，⚠️ 数据全丢）。官方部署文档对该行为有明确警告。

Q6：忘记管理口令怎么办？ 凭据来自环境变量，每次启动都会重新读取。实测把 compose 中 ADMIN_PASSWORD 改为新值（如 Xy9Kp2Vq7Rt4wZ8e）后 docker compose up -d 重建服务：旧口令登录被拒（响应 303 重定向回登录页、会话 Cookie 罐中无 JWT），新口令登录成功（303 重定向并下发 216 字符的 JWT Cookie）。改完记得同步更新你的凭据记录。

Q7：8080 端口冲突或想换对外端口？ 对外端口只由 ports 左侧决定（本篇为 8141），应用内部固定 8080 不可改。换端口只改 compose 一行，如 "1841:8080"，重建即可。

Q8：拉取镜像超时？ 见第三章 3.3 的 ⚠️ 网络说明：配置 Docker 守护进程代理或 registry mirror 后重试，镜像始终以 Docker Hub kuvaszmonitoring/kuvasz 与 pgautoupgrade/pgautoupgrade 为唯一官方来源。

十二、参考链接

• 官网与文档站：https://kuvasz-uptime.dev
• 官方部署文档（本篇 compose 结构来源）：https://kuvasz-uptime.dev/setup/installation/
• 官方配置参考（环境变量与 YAML 键权威出处）：https://kuvasz-uptime.dev/setup/configuration/
• 官方 OpenAPI 规范：https://kuvasz-uptime.dev/api-docs/kuvasz-latest.yml
• 官方 Changelog（4.6.0 发布记录）：https://kuvasz-uptime.dev/changelog/
• 官方 Docker Hub 仓库：https://hub.docker.com/r/kuvaszmonitoring/kuvasz
• 站内系列：《KuvaszUptime 介绍与选型指南》