KuvaszUptime 4.6.0 配置参数详解

目标：逐参数讲清 KuvaszUptime（项目名 Kuvasz）4.6.0 的配置体系——YAML 与环境变量双轨写法、每项参数的默认值与取值约束、修改后如何重启生效，并给出可直接落地的生产配置模板与踩坑实录。全部参数取值均对照官方 Configuration reference 并在 Ubuntu 26.04.1 LTS（x86_64，Kuvasz 4.6.0）实测实例上验证回显，服务端口 8141。部署与环境变量基础见《KuvaszUptime 4.6.0 Docker Compose 部署指南》，软件定位与同类对比见《KuvaszUptime 介绍与选型指南》。

一、环境信息

本篇所有命令与回显均在以下环境实测：

• 操作系统：Ubuntu 26.04.1 LTS（x86_64）
• Kuvasz 版本：4.6.0（应用内「设置」接口 GET /api/v2/settings 实测返回 versionInfo.installedVersion: 4.6.0、isUpToDate: true）
• 数据库：PostgreSQL 18（官方最低实测版本 PostgreSQL 14）
• 服务地址：宿主机 8141 端口（应用内部 8080）
• 配置文件：/opt/data/kuvasz-uptime/kuvasz.yml（应用固定读取路径 /config/kuvasz.yml）
• 管理账号：admin，密码 q1w2e3r4q1w2e3r4（Kuvasz 要求管理密码最少 12 位，8 位的 q1w2e3r4 无法通过启动校验，故示例口令翻倍至 16 位）
• REST API Key：kuvasz-demo-api-key-2026（最少 16 位，实测不足 16 位应用拒绝启动，见第七章 Q2）

二、前置条件

确认两件事：服务在运行、配置文件可编辑。

第一步，健康端点返回 UP（该端点无需凭据）：

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

实测输出：

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

第二步，确认配置文件在宿主机上可编辑。Kuvasz 的 YAML 配置文件必须挂载到应用固定路径 /config/kuvasz.yml（官方文档明确说明该路径），部署篇已把宿主机 /opt/data/kuvasz-uptime/kuvasz.yml 映射到该路径，本篇所有 YAML 修改都直接编辑宿主机这份文件：

ls -l /opt/data/kuvasz-uptime/kuvasz.yml

实测输出：

-rw-r--r-- 1 root root 481 Nov  1 15:06 /opt/data/kuvasz-uptime/kuvasz.yml

三、参数查看与修改方式

3.1 双轨制：YAML 与环境变量自由组合

Kuvasz 的配置有两个入口，可自由混用：

💡 技术拓展：自托管应用的配置载体常见三种设计——

设计	代表	特点
纯环境变量	大多数官方发行版应用	简单直接，但列表/嵌套结构表达困难
纯配置文件	Gatus、Prometheus	表达力强，凭据需额外注入
双轨混用（Kuvasz）	Kuvasz、Grafana 系	标量走 ENV、结构化走文件，各取所长

Kuvasz 官方明确：integrations、监控器、状态页、维护窗口这类「结构化、列表型」设置只能用 YAML 表达，其余标量参数两种写法等价、自由组合。本文/本方案实际采用「凭据与数据库地址走环境变量（部署篇已注入）、集成与监控器走 YAML」的分工。

两条规则必须记住：

1. 修改必然要重启：Kuvasz 在启动时读取并导入全部配置，无论 YAML 还是环境变量，改完都要重启服务才生效（重启命令按部署形态执行，见《KuvaszUptime 4.6.0 Docker Compose 部署指南》第八章，实测重启秒级完成）；
2. YAML 写坏会拒绝启动：语法错误的应用起不来（排障实录见第七章 Q3），好在文件在宿主机上，改回来再重启即可。

3.2 查看当前生效参数：GET /api/v2/settings

不用猜配置是否生效——REST API 的设置接口直接返回当前生效值（带 API Key 调用，认证方式详见《KuvaszUptime 4.6.0 REST API 实战指南》，本篇先直接使用）：

curl -s -H "X-API-KEY: kuvasz-demo-api-key-2026" http://127.0.0.1:8141/api/v2/settings

实测输出（完整 JSON）：

{"authentication":{"enabled":true,"accessTokenMaxAge":86400,"oidc":null},"app":{"version":"4.6.0","eventDataRetentionDays":365,"latencyDataRetentionDays":7,"language":"en","eventLoggingEnabled":true,"editabilityState":{"areHttpMonitorsReadOnly":true,"areStatusPagesReadOnly":false,"arePushMonitorsReadOnly":false,"areIcmpMonitorsReadOnly":false,"areTcpMonitorsReadOnly":false,"areDnsMonitorsReadOnly":false,"areDockerMonitorsReadOnly":false,"areMaintenanceWindowsReadOnly":false},"updateChecksEnabled":true,"httpCheckTimeoutSeconds":30,"httpCheckMaxRedirects":10,"virtualThreadSchedulingEnabled":true},"metricsExport":{"exportEnabled":false,"meters":{"sslExpiry":false,"httpLatestLatency":false,"httpUptimeStatus":false,"sslStatus":false,"pushUptimeStatus":false,"icmpUptimeStatus":false,"icmpLatestLatency":false,"icmpLatestPacketLoss":false,"tcpUptimeStatus":false,"tcpLatestLatency":false,"dnsUptimeStatus":false,"dnsLatestLatency":false,"dockerUptimeStatus":false,"dockerLatestLatency":false,"dockerLatestCpuUsage":false,"dockerLatestMemoryUsage":false,"dockerLatestRestartCount":false},"exporters":{"prometheus":{"enabled":false,"descriptions":true},"openTelemetry":{"enabled":false,"url":"","step":"PT1M"}}},"mcpServer":{"enabled":false},"connectivityCheck":null,"smtp":null,"versionInfo":{"installedVersion":"4.6.0","latestVersion":"4.6.0","latestVersionDetails":"https://kuvasz-uptime.dev/changelog#4.6.0","isUpToDate":true}}

逐段解读：

• authentication：认证开关与会话时长（accessTokenMaxAge: 86400 即 24 小时）；
• app.editabilityState：各资源类型的只读状态。实测 areHttpMonitorsReadOnly: true——因为当前 kuvasz.yml 里定义了 HTTP 监控器，该类型被冻结为只读（机制见 5.6 节）；
• metricsExport：指标导出总开关、逐项 meter 与两个 exporter（Prometheus/OpenTelemetry）；
• versionInfo：版本自检结果，升级判断依据。

3.3 修改后如何生效：重启实测

以「事件数据保留 365 天改 180 天、重定向上限 10 改 15」为例走一遍完整闭环。

第一步，改前确认当前值（上文 settings 回显中 eventDataRetentionDays: 365、httpCheckMaxRedirects: 10）。

第二步，编辑 kuvasz.yml 追加 app-config 段：

# /opt/data/kuvasz-uptime/kuvasz.yml（追加以下内容）
app-config:
  event-data-retention-days: 180
  http-check-max-redirects: 15

第三步，重启 Kuvasz 服务使配置生效（重启方式按部署形态执行，命令与实测回显见部署篇第八章），等待健康检查通过（实测约 1 分钟内转 healthy）。

第四步，复查 settings，两个值已变化：

curl -s -H "X-API-KEY: kuvasz-demo-api-key-2026" http://127.0.0.1:8141/api/v2/settings | python3 -c "import json,sys; d=json.load(sys.stdin)['app']; print({k: d[k] for k in ['eventDataRetentionDays','latencyDataRetentionDays','httpCheckMaxRedirects','httpCheckTimeoutSeconds']})"

实测输出（修改后）：

{'eventDataRetentionDays': 180, 'latencyDataRetentionDays': 7, 'httpCheckMaxRedirects': 15, 'httpCheckTimeoutSeconds': 30}

把 app-config 段从文件中删掉再重启，实测回到默认值：

{'eventDataRetentionDays': 365, 'httpCheckMaxRedirects': 10}

结论：改配置 → 重启 → settings 回显变化，这是验证任何参数生效与否的标准动作，本章后续所有参数均可用此法核对。

四、参数总览

按功能分组一屏总览（默认值与约束来源：官方 Configuration reference，查询日期 2026-11-01；「版本」列为该参数引入的 Kuvasz 版本）：

⚠️ 注意：结构化列表配置（integrations、六类监控器、状态页、维护窗口）没有 ENV 等价物，只能写在 kuvasz.yml，这是双轨制唯一的重要例外。

五、核心参数分类详解

5.1 认证与凭据（micronaut.security / admin-auth）

认证三件套决定「谁能进 Web 界面、谁能调 API」：

micronaut:
  security:
    enabled: true                                    # 总开关，false = 彻底免认证
    token:
      generator.access-token.expiration: 86400       # 会话 24 小时
      jwt.signatures.secret.generator.secret: your-very-long-random-secret
admin-auth:
  username: admin
  password: q1w2e3r4q1w2e3r4
  api-key: kuvasz-demo-api-key-2026

逐项说明：

• micronaut.security.enabled：设为 false 时 Web 界面与 API 全部免凭据访问。内网隔离环境可用，公网暴露务必保持 true 并配合防火墙或带认证的反向代理；
• JWT 签名密钥：默认每次启动随机生成，副作用是服务重启后所有已登录会话失效、需要重新登录。实测本部署重启后再次访问控制台即被要求重新登录。生产环境如希望会话跨重启存活，设一个固定密钥（至少 32 字符）；泄露或轮换该密钥会使全部会话立即失效；
• admin-auth.username / password：表单登录凭据。密码两条硬规则——最少 12 位、不得与用户名相同，启动时校验不通过直接拒绝启动（实测见第七章 Q1）；
• admin-auth.api-key：REST API 的专用 Key，最少 16 位。不设（或留空）时 API Key 认证整体关闭，API 只能靠 Web 会话调用。实测设短后启动即崩（见第七章 Q2）；
• admin-auth.mcp-api-key：内置 MCP 服务器（/mcp 端点，AI 助手用）的独立 Key，与 REST API Key 故意分开——可以独立发放、独立吊销，互不影响。

💡 技术拓展：登录方式二选一——内置表单登录（ADMIN_USER/PASSWORD）与 OIDC 单点登录（ENABLE_OIDC=true + issuer/client-id/client-secret）。启用 OIDC 后登录页只剩「Login (OIDC)」按钮、表单登录关闭，ADMIN_USER/PASSWORD 不再需要（也不校验）；而 API Key 认证与登录方式无关、始终独立可用。Kuvasz 支持 Auth0、AWS Cognito、Keycloak、Microsoft Entra ID、Okta、Oracle Cloud 六类 provider（OIDC_AUTH_SERVER 大小写不敏感）。OIDC 还提供邮箱白名单（OIDC_ALLOWED_EMAILS，逗号分隔）与「必须已验证邮箱」开关（OIDC_REQUIRE_VERIFIED_EMAIL，默认 true），共享型企业 IdP 场景务必配置白名单，否则任何能通过 IdP 认证的人都拿到 Kuvasz 管理权。本部署未启用 OIDC（settings 回显 oidc: null），走表单登录。

5.2 数据库连接（DATABASE_* 五件套）

Kuvasz 把全部监控器、检查结果、事件、状态页数据存 PostgreSQL，官方推荐用五个环境变量而不是手拼 JDBC 串：

DATABASE_HOST=kuvasz-4.6.0-db      # 数据库地址
DATABASE_PORT=5432                 # 端口，默认 5432
DATABASE_NAME=postgres             # 库名，默认 postgres；应用在其中自建 kuvasz schema
DATABASE_USER=kuvasz               # 连库用户，需有建 schema/建表权限
DATABASE_PASSWORD=kuvaszdb2026     # 连库密码

要点：

• 最低版本 PostgreSQL 14，alpine 发行版支持（官方文档明确）；
• 首次启动会在目标库自建 kuvasz schema 并完成建表迁移，启动日志出现 DB: schema "kuvasz" already exists, skipping 属幂等建 schema 的正常输出（部署篇 Q4 有实测）；
• 4.5.0 起支持 Unix 套接字连接：DATABASE_HOST 填套接字目录（如 /var/run/postgresql），同机部署可不把数据库暴露到网络；
• 坚持全 YAML 的话可改写 datasources.default.url（JDBC 串）+ username + password，两种写法等价。

凭据一致性是最常见的坑：DATABASE_PASSWORD 必须与数据库侧实际口令一致；数据库自身的初始化口令只在数据目录首次初始化时生效（部署篇 Q5 有实测分析）。

5.3 应用行为（app-config）

app-config 段管应用整体行为，本节按「数据保留 → 检查行为 → 界面杂项」展开：

app-config:
  event-data-retention-days: 365     # 已结束事件保留天数，最小 1
  latency-data-retention-days: 7     # 延迟明细保留天数，最小 1
  log-event-handler: true            # 事件写标准输出
  language: en                       # 界面语言 en/fr/pl
  check-updates: true                # 后台检查新版本
  incident-notes-enabled: true       # 事故备注开关
  http-check-timeout-seconds: 30     # HTTP 检查读超时（默认=最大 30）
  http-check-max-redirects: 10       # 重定向链上限

• 两条保留期是磁盘占用的总闸门：event-data-retention-days 管已结束的 UP/DOWN 与 SSL 事件（事故备注随事故一起清理），latency-data-retention-days 管逐次检查的延迟明细。监控器数量多时延长延迟保留期的磁盘与数据库开销显著；保留期设短于 30 天还有个连带效应——状态页的历史条带只显示保留期内的天数（如设 7 天，状态页只展示最近 7 天而非 30 天）；
• http-check-timeout-seconds：官方文档给的调参思路很实用——如果监控器用了很短的检查间隔（如 10 秒），而超时仍是 30 秒，那么一次慢响应会占掉 3 个检查周期，此时应把全局超时调低。注意默认值 30 就是最大值，只能往下调；
• http-check-max-redirects：管理「跟随重定向」的链长上限。链条超限时监控器 DOWN，报错 The redirect chain was longer than the allowed maximum of N redirect(s)。设 0 的语义是「完全不跟随」——首个 3xx 就 DOWN 并触发告警，而不是静默关闭该特性。Kuvasz 只能识别「同一 URL 出现两次」的环，全由不同 URL 组成的长链靠这个上限兜底；
• incident-notes-enabled：设 false 后备注的新增/修改/删除接口一律返回 405，但已有备注仍到处展示（含状态页公开备注）。官方给的场景是公开演示实例——不希望访客留下任何记录；
• language：目前支持 en/fr/pl 三种，中文界面暂未提供；
• check-updates：后台检查新版本，发现新版时在界面提示并可通过 settings 接口查到（实测 versionInfo.latestVersionDetails 指向 changelog 对应锚点）。离线环境可关。

5.4 连通性检查（connectivity-check，4.5.0 新增）

这是 4.5.0 引入的防误报机制，默认关闭：

app-config:
  connectivity-check:
    enabled: true
    targets:
      - "1.1.1.1:53"
      - "8.8.8.8:53"
    interval-seconds: 60
    timeout-seconds: 5

工作逻辑：启用后 Kuvasz 周期性向 targets 逐个发起 TCP 拨号，一个能通即视为有外网；当宿主机失去出网能力时，暂停所有由 Kuvasz 自己发起的检查，避免「机房断网把全部监控器同时打成 DOWN」的告警风暴。恢复连通后自动续查。

官方警告必须正视：如果你的网络过滤出站流量、或 Kuvasz 只能访问内网，必须把 targets 改成内网里始终可达的地址（任何 TCP 端点都行，不限于 DNS 服务器，比如网关），否则 Kuvasz 会认为「永久断网」而停摆全部监控。targets 至少列两个不同供应商的端点。实测本部署 connectivityCheck: null（未启用，默认关闭），监控器列表里每个监控器还有独立的 ignoreConnectivityCheck 字段可对单个监控器豁免暂停。

5.5 通知集成（integrations，YAML 专属）

集成只写在 YAML，本部署的实测配置：

integrations:
  slack:
    - name: ops-channel-demo
      webhook-url: 'https://hooks.slack.com/services/T00000000/B00000000/DEMO00000000000000000000'
      enabled: false
      global: true

字段含义：name 唯一标识；webhook-url 是 Slack Incoming Webhook 地址；enabled: false 表示暂停发送（定义保留）；global: true 表示全局集成——自动挂到所有监控器，省去逐个绑定。

• API 视角的集成标识是 type:name 复合形式，实测 GET /api/v2/integrations 返回：

[{"id":"slack:ops-channel-demo","type":"SLACK","name":"ops-channel-demo","enabled":false,"global":true,"excludedEvents":[]}]

• 集成支持发送测试通知：POST /api/v2/integrations/{integrationId}/test，实测用演示 webhook 得到（HTTP 200，success: false 属预期——地址是演示占位值，Slack 端返回 no_team）：

{"success":false,"message":"Test notification failed with error: no_team"}

• 除 Slack 外还支持 PagerDuty、Teams、Webhook、Email（邮件依赖 5.7 的 SMTP 配置）；excludedEvents 可按事件类型过滤，让某集成只收 SSL 告警或只收 DOWN 告警。

5.6 监控器定义（六类 monitors 段与 YAML 冻结机制）

监控器可在 YAML 声明、Web 界面创建或 API 创建。本部署 kuvasz.yml 中的实测段：

http-monitors:
  - name: yaml-managed-site
    url: 'https://www.example.org'
    uptime-check-interval: 300
    ssl-check-enabled: true
    enabled: true

常用字段：uptime-check-interval 检查间隔秒（最小 5，OpenAPI 约束实测确认）、ssl-check-enabled 顺带做证书检测、ssl-expiry-threshold 证书到期告警阈值天数（默认 30）、failure-count-threshold 连续失败几次才判 DOWN（默认 1）、request-method 默认 GET、force-no-cache 默认 true。

YAML 冻结机制是本节最重要的规则：某类监控器只要出现在 kuvasz.yml 里，启动后该类型在 Web 界面与 REST API 中就整体转为只读。实测本部署启动日志明确打印：

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

在 API 层实测，对 YAML 管理的 HTTP 监控器做任何写操作（改、删、新建同类）都被拒绝：

HTTP 405
{"message":"The given type of monitors were configured via a YAML file. You cannot modify them via the API. Please change the configuration in the YAML file and restart the server.","errorCode":null}

同时 settings 的 editabilityState.areHttpMonitorsReadOnly 变为 true（见 3.2 节回显）。反方向实测：把 http-monitors 段从 YAML 移除并重启，areHttpMonitorsReadOnly 恢复 false，API 写操作立即恢复可用（原 YAML 导入的监控器转由数据库管理，数据不丢）；把段落加回去重启，重新冻结。

💡 设计意图：这是防「YAML 与界面双头修改打架」的机制——把 YAML 当作该类资源唯一事实源（IaC 思路），其他类型（PUSH/ICMP/TCP/DNS/DOCKER）未出现在 YAML 中时依旧走数据库动态管理。启动日志对每种类型都会打印一行「YAML 段存在 → 冻结 / 不存在 → 开放」的判定，是排查只读问题的第一现场。

六类监控器各自的 YAML 段名：http-monitors、push-monitors（心跳型）、icmp-monitors（ping 型）、tcp-monitors（端口型）、dns-monitors（解析型）、docker-monitors（Docker 主机监控，需先配 docker-hosts）。完整可用的六类定义样例可直接用 API 导出功能拿到——GET /api/v2/monitors/export/yaml 返回的就是规范的全字段 YAML（详见《KuvaszUptime 4.6.0 REST API 实战指南》导入导出一章），把它粘贴进 kuvasz.yml 即完成「数据库 → YAML」的配置迁移。

5.7 SMTP 邮件（smtp-config）

SMTP 只在需要邮件通知时配置，可选：

smtp-config:
  host: 'your.smtp.server'
  port: 465
  transport-strategy: SMTP_TLS
  username: YourSMTPUsername        # 服务器不要求认证时可省略或显式设 null
  password: YourSMTPPassword

两条硬规则：只要配了 host，其余必填项必须配全，否则应用拒绝启动；transport-strategy 三选一。

💡 技术拓展：三种传输策略对应三种加密姿势——

策略	加密方式	典型端口	适用
SMTP_TLS（默认）	明文连接后升级 TLS（STARTTLS）	587	现代邮件服务主流
SMTPS	一开始就是 TLS（隐式加密）	465	老一些的服务商
SMTP	不加密	25	仅内网中继

本文/本方案未启用邮件通知（settings 回显 smtp: null），生产建议按服务商文档选择，587 + SMTP_TLS 是最不容易踩坑的组合。

5.8 指标导出（metrics-exports）

三层结构：exporter（往哪发）→ meters（发哪些指标）→ 总开关。YAML 写法：

metrics-exports:
  http-uptime-status: true
  http-latest-latency: true
  ssl-status: true
  ssl-expiry: true
  # ……其余 icmp/tcp/dns/push/docker 系列同构，共 17 项

exporter 部分在 micronaut.metrics.export 下：prometheus.enabled（抓取端点 /api/v2/prometheus）与 otlp.enabled（推送到 OpenTelemetry Collector，需配 url）。未启用 exporter 时实测访问 Prometheus 端点返回 404（{"message":"Not Found",...}），启用后才有指标输出。全部 meter 默认关闭，按需逐项打开即可，实测 settings 回显的 metricsExport 段与上表一一对应。

5.9 其他杂项

• TZ：应用与数据库的展示时区，建议设本地时区（本部署 Asia/Shanghai，实测事件时间戳均带 +08:00）；
• YAML_MAX_ALIASES（仅 ENV，默认 50）：YAML 文件里别名（&anchor + <<: *anchor 复用公共配置）的数量上限，只对每个文件单独计数。监控器数量多、大量复用锚点模板时才需要调大；该限制防的是恶意构造的嵌套别名在启动解析时耗尽内存，文件仅由可信方维护时可放心上调；
• micronaut.mcp.server.enabled / ENABLE_MCP_SERVER：内置 MCP 服务器开关（4.0.0+），开启后 /mcp 端点把监控器、事故等暴露为 AI 助手可调用的工具，凭据用独立的 ADMIN_MCP_API_KEY。实测默认关闭（settings 回显 mcpServer.enabled: false）。

六、生产配置模板

以下模板面向「中小团队自托管：20~200 个监控器、4GB 内存 / 40GB 磁盘、需要 Slack 告警与邮件通知」的典型场景，可直接作为 kuvasz.yml 起点（凭据类值替换为自己的强凭据）：

# /opt/data/kuvasz-uptime/kuvasz.yml —— Kuvasz 4.6.0 生产配置模板
# 场景：4GB 内存 / 40GB 磁盘 / 20~200 监控器 / Slack+邮件告警

integrations:
  slack:
    - name: oncall-slack
      webhook-url: '${SLACK_WEBHOOK_URL}'   # 建议从环境变量注入，避免密钥进文件
      enabled: true
      global: true

http-monitors:
  - name: portal-homepage
    url: 'https://portal.example.com'
    uptime-check-interval: 60
    ssl-check-enabled: true
    ssl-expiry-threshold: 30
    response-time-threshold-millis: 3000   # 慢于 3s 记一次慢响应事件
    failure-count-threshold: 2             # 连续 2 次失败才告警，防抖
    enabled: true

app-config:
  event-data-retention-days: 180           # 半年事件史，磁盘可控
  latency-data-retention-days: 14          # 两周延迟明细（默认 7，按需）
  http-check-timeout-seconds: 15           # 配合 60s 间隔收紧超时
  http-check-max-redirects: 10
  log-event-handler: true
  language: en
  connectivity-check:
    enabled: true                          # 有外网依赖时启用防误报
    targets:
      - "1.1.1.1:53"
      - "8.8.8.8:53"

smtp-config:
  host: 'smtp.example.com'
  port: 587
  transport-strategy: SMTP_TLS
  username: '${SMTP_USERNAME}'             # 凭据走环境变量注入
  password: '${SMTP_PASSWORD}'

配套的凭据类参数建议全部走环境变量（部署篇 compose 的 environment 段）：ADMIN_USER、ADMIN_PASSWORD（≥12 位强口令）、ADMIN_API_KEY（≥16 位强随机值）、DATABASE_* 五件套、TZ=Asia/Shanghai。

⚠️ 注意：模板里 ${SLACK_WEBHOOK_URL} 等占位不是 Kuvasz 语法，而是提醒你在部署层注入——Kuvasz 本身读取的是合成后的最终文件。若使用部署篇的编排方式，可在宿主机用环境变量替换工具生成该文件后再挂载。模板中 http-monitors 段一旦写入，HTTP 类型即被冻结为只读（5.6 节），后续增删改都要回到这份文件并重启。

七、常见问题（FAQ）

Q1：管理密码设短了会怎样？ 启动校验失败、拒绝启动。官方规则：密码最少 12 位、不得与用户名相同（来源：官方 Configuration reference，查询日期 2026-11-01）。本系列实测环境因此把示例口令设为 16 位的 q1w2e3r4q1w2e3r4。

Q2：ADMIN_API_KEY 设短了会怎样？ 实测把 API Key 改成 short 后重启，应用启动即崩，服务日志关键行（节选，原始日志较长）：

Message: Admin API key must be at least 16 characters
Path Taken:
new @i.m.c.a.Context c.k.k.s.AppBootstrapper(List<HttpMonitorConfig> yamlHttpMonitorConfigs, ...)

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

换回 16 位以上重启即恢复。ADMIN_MCP_API_KEY 同规。

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

完整堆栈会指向配置加载器（AbstractPropertySourceLoader.read 一线），一眼可定位到 YAML 解析层。修复：宿主机还原文件语法后重启即可——文件是挂载进来的，语法错误的代价只是应用起不来，不涉及数据损坏。

Q4：改了 YAML 为什么没生效？ 配置只在启动时读取，重启前修改不生效（3.3 节实测闭环）。另一个隐蔽场景：改的是 YAML 里的监控器，但该类型此前从未出现在 YAML 中——新段落只有随重启导入后才生效，生效标志同样是启动日志的 Loaded N http monitors from external config 一行。

Q5：监控器在 Web 界面上变成只读了？ 该类型出现在 kuvasz.yml 里触发了冻结机制（5.6 节）。先看 settings 的 editabilityState 确认哪个类型只读，再决定「改 YAML」还是「把段落从 YAML 移除后重启」。二选一，没有第三条修改通道。

Q6：忘了管理口令怎么办？ 凭据来自环境变量，每次启动重新读取。改掉凭据注入值并按部署形态重建服务即可（部署篇 Q6 有完整实测：旧口令失效、新口令登录成功）。若同时设置了固定 JWT 签名密钥，轮换它可让所有已发会话立即失效。

Q7：密码、API Key、webhook 这类敏感值想留在环境里不进 YAML？ Webhook/SMTP 密码写在 YAML 里的替代方案：官方提供「Keeping secrets out of your configuration file」配方，配合 5.9 节的部署层注入思路处理；ADMIN_API_KEY/ADMIN_PASSWORD 本身就有 ENV 写法，天然不进文件。

八、参考链接

• 官方配置参考（本篇参数默认值与约束的权威出处）：https://kuvasz-uptime.dev/setup/configuration/
• 官网与文档站：https://kuvasz-uptime.dev
• 官方 OpenAPI 规范：https://kuvasz-uptime.dev/api-docs/kuvasz-latest.yml
• 官方 Changelog（4.6.0 发布记录）：https://kuvasz-uptime.dev/changelog/
• 站内系列：《KuvaszUptime 介绍与选型指南》、《KuvaszUptime 4.6.0 Docker Compose 部署指南》、《KuvaszUptime 4.6.0 REST API 实战指南》