Uptime Kuma 配置参数详解

‍‍​​‌​‍‍​​‌​> 目标：系统梳理 Uptime Kuma 1.23.17 的运行参数、环境变量、界面设置项、监控项通用参数与六大监控类型实测配置，并给出 54 种通知渠道的选型矩阵，所有默认值与回显均取自 Ubuntu 22.04 实机验证。

一、环境信息

本章所有参数说明与实测回显均在以下环境中验证，不同版本的字段名与默认值可能存在差异，请以您实际部署的版本为准。

服务进程启动日志（节选）可以确认版本与监听状态：

2026-10-17T08:40:34Z [SERVER] INFO: Welcome to Uptime Kuma
2026-10-17T08:40:34Z [SERVER] INFO: Version: 1.23.17
2026-10-17T08:40:35Z [SERVER] INFO: Listening on 3001

版本号也可以通过运行环境内的 package.json 直接核对：

$ node -e 'console.log(require("/app/package.json").version)'
1.23.17

二、配置体系总览

Uptime Kuma 1.23.17 没有统一的配置文件，配置分散在三个层面，理解它们的加载顺序与作用范围，是排查配置问题的前提：

三个层面的分工非常明确：

• 进程级参数只影响服务如何「跑起来」（监听哪里、是否启用 TLS），改完必须重启进程；
• 应用设置存在数据库中，通过界面修改即时生效，不依赖重启；
• 监控项参数属于业务数据，每条监控项各自独立，互不影响。

另外有一个特殊的辅助文件 setup.json：当服务部署在反向代理之后时，在数据目录放置 {"setup": false} 可以关闭首次访问时的初始化向导，避免公网访客抢先创建管理员账号。实际部署中更稳妥的做法是：先完成初始化，再向公网开放代理端口，因为初始化一旦完成，setup 接口即自动失效（重复调用返回 Added user. We don't need more users.）。

忘记管理员密码时无法通过配置文件重置，只能使用官方提供的重置脚本：

$ npm run reset-password

脚本交互式询问用户名与新密码，直接改写 user 表中的 bcrypt 摘要，改完重启服务即可用新密码登录。

三、监听与运行环境变量

监听行为由 server/config.js 汇总，变量存在多层兜底，默认值可以从下面的优先级链直接读出（以下为 1.23.17 源码原文）：

const hostname = args.host || process.env.UPTIME_KUMA_HOST || hostEnv;

const port = [ args.port, process.env.UPTIME_KUMA_PORT, process.env.PORT, 3001 ]
    .map(portValue => parseInt(portValue))
    .find(portValue => !isNaN(portValue));

const sslKey = args["ssl-key"] || process.env.UPTIME_KUMA_SSL_KEY || process.env.SSL_KEY || undefined;
const sslCert = args["ssl-cert"] || process.env.UPTIME_KUMA_SSL_CERT || process.env.SSL_CERT || undefined;
const sslKeyPassphrase = args["ssl-key-passphrase"] || process.env.UPTIME_KUMA_SSL_KEY_PASSPHRASE || process.env.SSL_KEY_PASSPHRASE || undefined;

const isSSL = sslKey && sslCert;

逐参数解释如下。

UPTIME_KUMA_PORT —— 监听端口

优先级最高的端口环境变量（依次兜底 PORT，最后落到默认值 3001）。例如改为 8080：

UPTIME_KUMA_PORT=8080 node server/server.js

同优先级还有命令行参数写法 --port=8080，两者二选一即可。多套实例同机并存时，用不同端口区分是最简单的隔离手段。

PORT —— 通用端口变量

许多托管平台（PaaS 等）会注入 PORT，Uptime Kuma 将其作为第二优先级读取，方便直接托管，无需额外配置。

UPTIME_KUMA_HOST —— 监听地址

未设置时进程按双栈方式监听：IPv6 可用时绑 ::，否则退回 0.0.0.0。实测日志中的 Listening on 3001 即未设置 host 的默认行为。只需要监听内网时可以设置：

UPTIME_KUMA_HOST=127.0.0.1 node server/server.js

UPTIME_KUMA_SSL_KEY / UPTIME_KUMA_SSL_CERT / UPTIME_KUMA_SSL_KEY_PASSPHRASE —— 直接 HTTPS

三者分别对应私钥路径、证书路径、私钥口令（对应命令行参数 --ssl-key、--ssl-cert、--ssl-key-passphrase）。key 与 cert 必须同时提供，isSSL 才会为真，服务切换为 HTTPS + WSS。个人部署更推荐由反向代理终结 TLS，服务本体保持 HTTP，证书轮换不触碰监控进程。

UPTIME_KUMA_IS_CONTAINER —— 运行环境标记

官方提供的运行环境在构建时写入 UPTIME_KUMA_IS_CONTAINER=1，实测运行时 env 可见。它影响两类行为：一是界面隐藏源码构建相关提示，二是 RealBrowser（真实浏览器）监控优先探测运行环境内置 Chromium 的路径。常规部署不需要手动设置。

UPTIME_KUMA_ALLOW_ALL_CHROME_EXEC —— 放开浏览器路径限制

RealBrowser 监控默认只允许执行官方运行环境内置的 Chromium，防止任意路径注入。自备浏览器的部署设为 1 后允许任意可执行路径，属于安全性让步，仅在确有需要时使用。

UPTIME_KUMA_LOG_RESPONSE_BODY_MONITOR_ID —— 记录响应体

设置为某个监控项 ID（字符串）后，该 HTTP 监控失败时会把响应体一并写入日志，便于调试接口异常。只应临时开启，日志量与敏感信息风险都较高。

UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN —— 关闭同源框架限制

默认页面携带 X-Frame-Options: sameorigin 响应头，禁止被第三方网页内嵌。如需嵌入到自家门户，将此变量设为任意非空值即可移除该头，代价是点击劫持风险，请配合自家域名白名单使用。

UPTIME_KUMA_WS_ORIGIN_CHECK —— WebSocket 来源校验

控制 Socket.IO 握手的 Origin 校验策略，默认 cors-like（按同源策略放行）。历史版本中可选 allow-all 与 bypass-all，1.23.17 中保留该开关用于特殊反代场景下的放行排查；正常部署不要放开。

命令行参数与上述环境变量完全等价（args-parser 解析），常用的三个如下表：

四、界面设置项与数据库内置键

界面「设置」页的每一项都最终落库到 setting 表。实测查看该表（截取与运维相关的键）：

$ sqlite3 /opt/data/uptime-kuma/kuma.db "SELECT key, value FROM setting;"
database_version | 10
jwtSecret | $2a$10$s.Wz.ZUe4DJxFxfhZas3AO9M3j4mnQMdgSwwVTpPZwfFAHjAJ0kZK
serverTimezone | Asia/Shanghai

重点解释两个设置：

数据保留期 keepDataPeriodDays。清理任务每小时整点执行（cron 表达式 0 * * * *），首次运行时若发现该键不存在，会写入默认值 180 并据此清理，核心逻辑位于 server/jobs/clear-old-data.js：

const DEFAULT_KEEP_PERIOD = 180;
// ...
await R.exec(
    "DELETE FROM heartbeat WHERE time < DATETIME('now', '-' || ? || ' days') ",
    [ parsedPeriod ]
);
await R.exec("PRAGMA optimize;");

设为小于 1 的值表示永久保留，日志会输出 Data deletion has been disabled as period is less than 1。磁盘紧张的环境建议按监控数量与频率反推：每条监控每 60 秒一条心跳，一天 1440 条，100 条监控约每天 14 万行，保留 180 天就是两千多万行的量级。

时区 serverTimezone。设置后进程立即通过 process.env.TZ 生效，心跳的 time 字段随之切换时区，历史数据按新时区显示。定时维护窗口、证书到期提醒等都以该时区为基准，多地域团队协作时建议统一为业务主时区。

五、监控项通用参数

所有监控项共享同一组调度参数，字段名与默认值来自 1.23.17 前端构建产物与服务端代码，实测一致：

其中重试语义值得单独说明：maxretries 是「连续失败多少次才判 DOWN」。一次网络抖动在 maxretries=2 时会先记为重试状态，连续第 3 次失败才翻转为故障并触发通知；恢复同理，只要有一条 UP 心跳即回正常。这组参数与「通知不触发」类故障直接相关，建议先核对这里再去查通知渠道。

六、监控项类型逐类详解

Uptime Kuma 1.23.17 内置 22 种监控类型（http、keyword、port、ping、dns、push、json-query、grpc-keyword、steam、gamedig、mqtt、kafka-producer、sqlserver、postgres、mysql、mongodb、redis、radius、tailscale-ping、real-browser、group，以及面向外部宿主机的服务状态类型）。本节对最常用的六类逐一给出实测配置与心跳回显，其余类型参数结构类似，按界面提示填写即可。

6.1 HTTP 监控（type: http）

适用场景：站点、API、网关的可用性与响应延迟监控，是最常用的类型。

实测配置（监控「Kuma Web 首页」）：

实测心跳记录（SQLite heartbeat 表）：

{"monitor_id":1,"status":1,"msg":"200 - OK","ping":4}

回显解读：status 1 为正常、0 为故障；msg 直接回显 HTTP 状态行；ping 为整次请求耗时毫秒数。故障时 msg 会携带具体错误，例如把 URL 指向一个无监听的端口：

{"monitor_id":7,"status":0,"msg":"connect ECONNREFUSED 127.0.0.1:39999","ping":null}

要点：默认跟随最多 10 次重定向（maxredirects）；需要校验返回内容时升级为 keyword 类型；需要 POST 与自定义请求头 / Body 时在「高级」区展开填写。

6.2 HTTP 关键字监控（type: keyword）

适用场景：页面返回 200 但内容异常的「假活」场景，如被劫持的页面、缓存出来的错误页、接口返回的 JSON 错误体。

实测配置（监控「示例站点关键词」）：

实测心跳：

{"monitor_id":2,"status":1,"msg":"200 - OK, keyword is found","ping":200}

匹配逻辑为对响应体做 data.includes(this.keyword)，区分大小写的包含匹配；勾选 Invert Keyword 后语义反转，命中关键字反而判故障，可用于「页面上出现 panic 字样就报警」这类需求。状态码校验仍然生效，msg 会同时回显状态行与关键字命中结果。

6.3 TCP 端口监控（type: port）

适用场景：不解析应用层协议、只关心端口是否可达的服务，如 Redis 6379、SSH 22、MySQL 3306。

实测配置（监控「本机 3001 端口」）：

实测心跳：

{"monitor_id":3,"status":1,"msg":"","ping":0}

回显解读：TCP 建连成功时 msg 为空，ping 为建连耗时（本机回环近乎 0 毫秒）；失败时 msg 为 connect ECONNREFUSED ... 或 connect ETIMEDOUT ...。相比 HTTP 监控，端口监控不消耗应用资源，适合高频探测，缺点是无法发现「端口通但应用挂死」的情况。

6.4 Ping 监控（type: ping）

适用场景：网络层连通性与丢包延迟观测，如跨机房专线、VPN 隧道、网关设备。

实测配置（监控「阿里 DNS Ping」）：

实测心跳：

{"monitor_id":4,"status":1,"msg":"","ping":20.6}

实现上依赖操作系统的 ping 命令（Linux 下为 iputils-ping），因此服务器需要具备执行 ping 的权限；官方运行环境已内置所需命令。ping 值为实测 RTT（毫秒，保留一位小数），全部丢包时判故障。Packet Size 默认 56 字节，与系统 ping 默认一致，排障时可临时加大观察路径 MTU 问题。

6.5 DNS 监控（type: dns）

适用场景：验证域名解析是否被篡改、自建 DNS 是否正常应答、CDN CNAME 是否按预期切换。

实测配置（监控「baidu.com DNS 解析」）：

实测心跳：

{"monitor_id":5,"status":1,"msg":"Records: 111.63.65.103 | 124.237.177.164 | 111.63.65.247 | 110.242.74.102","ping":22}

回显解读：msg 直接列出全部解析结果，| 分隔，一眼可见是否被污染；ping 为 DNS 查询耗时。支持 A / AAAA / CNAME / MX / NS / PTR / TXT / SRV 等记录类型，其中 CNAME / MX / TXT 等类型还可进一步设置期望值比对。把 Resolver 指向公共 DNS 与自建 DNS 各建一条同域名监控，对比两条 msg 即可实现解析一致性巡检。

6.6 Push 推送监控（type: push）

适用场景：无法被主动探测的对象——定时任务是否跑完、脚本是否正常退出、IoT 设备心跳，方向由被监控方「报平安」。

创建时服务端自动生成推送令牌，实测本条为 kumae12d95d9e1bce1f55eacf29a。被监控方只需定期请求：

$ curl -s "http://127.0.0.1:3001/api/push/kumae12d95d9e1bce1f55eacf29a?msg=OK&ping=88"
{"ok":true}

服务端接受 GET 与 POST（表单）两种方式，可用参数：status（留空或 up 正常，down 判故障）、msg（心跳备注）、ping（自定义耗时数值）。

实测心跳（带 msg 与 ping 的推送）：

{"time":"2026-10-17 16:44:37.2","status":1,"msg":"OK","ping":88}

超过两个心跳周期没有收到推送时自动判故障，实测回显：

{"monitor_id":6,"status":0,"msg":"No heartbeat in the time window","ping":null}

要点：令牌即凭据，泄露后任何人都能伪造心跳，建议与 HTTPS 一起使用；周期脚本中把 curl 失败静默（|| true）是常见反模式，会掩盖本地网络故障，应保留退出码并配合推送 status=down。

6.7 其余类型速览

七、通知渠道矩阵

1.23.17 内置 54 个通知提供方，实测枚举如下（源码目录 server/notification-providers/）：

alerta alertnow aliyun-sms apprise bark clicksendsms dingding discord feishu
flashduty freemobile goalert google-chat gorush gotify home-assistant kook
line linenotify lunasea matrix mattermost nostr ntfy octopush onebot opsgenie
pagerduty pagertree promosms pushbullet pushdeer pushover pushy rocket-chat
serverchan serwersms signal slack smsc smseagle smsmanager smtp splunk
squadcast stackfield teams techulus-push telegram twilio webhook wecom zoho-cliq

按使用习惯归类的选型矩阵：

所有渠道共享一组行为参数，与「通知不触发」类故障强相关：

下面给出两种代表性渠道的实测记录，其余渠道按矩阵中关键字段填写即可。

7.1 Webhook 渠道实测

webhook 渠道把心跳事件序列化为 JSON / form-data POST 到任意 URL，是对接自有告警系统的标准入口。实测配置：

在监控项详情页点击「测试」按钮（服务端 testNotification 事件），服务返回发送成功。接收端 webhook.site 收到的四条请求载荷（故障触发 / 恢复 / 测试各一）原文如下：

{"heartbeat":{"id":26,"status":1,"time":"2026-10-17 16:48:59.7","msg":"","ping":null,"monitorID":8},"monitor":{"id":8,"name":"故障演示 HTTP（带通知）","type":"http","url":"http://127.0.0.1:39998","hostname":null,"port":null,"maxretries":0,"active":true,"description":"","interval":60,"retryInterval":60,"resendInterval":0,"ignoreTls":false,"upsideDown":false,"maxredirects":10,"accepted_statuscodes":["200-299"],"dns_resolve_type":"A","dns_resolve_server":"1.1.1.1","pushToken":null,"method":"GET","expiryNotification":false,"log_request_body":null,"insecure":false,"packetSize":56,"invertKeyword":false,"timeout":48,"keyword":null,"authMethod":0,"grpcUrl":null,"grpcEnableTls":false,"grpcMethod":null,"grpcBody":null,"grpcMetadata":null,"grpcProtobuf":null,"weight":2000,"basic_auth_user":null,"basic_auth_pass":null,"oauth_client_id":null,"oauth_client_secret":null,"oauth_token_url":null,"oauth_scopes":null,"oauth_auth_method":null,"customTimeline":false},"msg":"Reconnected again to 故障演示 HTTP（带通知）"}

{"heartbeat":{"id":25,"status":0,"time":"2026-10-17 16:47:59.3","msg":"connect ECONNREFUSED 127.0.0.1:39998","ping":null,"monitorID":8},"monitor":{"id":8,"name":"故障演示 HTTP（带通知）","type":"http",...},"msg":"故障演示 HTTP（带通知） is DOWN"}

{"heartbeat":{"id":32,"status":0,"time":"2026-10-17 16:50:01.6","msg":"connect ECONNREFUSED 127.0.0.1:39997","ping":null,"monitorID":9},"monitor":{"id":9,"name":"SMTP 告警演示 HTTP","type":"http",...},"msg":"SMTP 告警演示 HTTP is DOWN"}

载荷结构固定为 heartbeat（本次心跳）、monitor（监控项完整定义）、msg（人读摘要）三段，其中 msg 的取值规律：故障为 <名称> is DOWN，恢复为 Reconnected again to <名称>，测试发送为固定测试文案。Content Type 选 form-data 时同样的字段以表单编码发送，方便对接只收表单的老系统。

7.2 SMTP 邮件渠道实测

SMTP 渠道基于 nodemailer（1.23.17 内置版本 ~6.9.13），实测对接一台内网调试邮件服务器：

触发一条真实故障告警后，邮件服务器侧收到的完整信件（原文照抄）：

---------- MESSAGE FOLLOWS ----------
headers:

X-Mailer: nodemailer (6.9.13)
Content-Type: multipart/alternative; boundary="----sinikael-?=_1-17606885811590.4470145462697319"
From: uptime-kuma@monitor.local
To: ops@monitor.local
Subject: [Uptime Kuma] SMTP 告警演示 HTTP is DOWN (2026-10-17 16:49:41 UTC)
Message-ID: <c0785929-9450-c956-6a51-7084ba73297f@monitor.local>
Content-Transfer-Encoding: 7bit
Date: Fri, 17 Oct 2026 08:49:41 +0000
MIME-Version: 1.0

body:
 [Uptime Kuma] SMTP 告警演示 HTTP is DOWN

Time (UTC): 2026-10-17 16:49:41

Error: connect ECONNREFUSED 127.0.0.1:39997

------------ ENDED MESSAGE ----------

要点：主题遵循 [Uptime Kuma] <监控名> is DOWN/UP (<UTC时间>) 模板，可在 customSubject 字段自定义；正文为纯文本 + HTML 双部分，客户端择一渲染；服务器要求 STARTTLS 而您没有有效证书时，勾选「忽略 TLS 错误」可退回明文发送（仅限内网）。

八、状态页与公开 API 参数

状态页（Status Page）是把监控结果对外发布的门面，配置项与 1.23.17 服务端校验一一对应：

状态页内容以「分组 → 监控项」两级结构组织，监控项可勾选 sendUrl 决定是否在页面暴露链接。全部公开数据通过三个只读端点输出，实测如下：

$ curl -s http://127.0.0.1:3001/api/status-page/demo
{"config":{"slug":"demo","title":"演示状态页","description":"Uptime Kuma 实测演示状态页","icon":"/icon.svg","theme":"auto","published":true,"showTags":false,"domainNameList":[],"googleAnalyticsId":null,"customCSS":""},"publicGroupList":[{"name":"服务","monitorList":[{"id":2,"name":"示例站点关键词","sendUrl":false,"type":"keyword"},...]}]}

$ curl -s http://127.0.0.1:3001/api/status-page/heartbeat/demo | head -c 300
{"heartbeatList":{"1":[{"status":1,"time":"2026-10-17 16:43:18.3","ping":4}]},"uptimeList":{"1":100.0,"2":100.0}}

$ curl -s http://127.0.0.1:3001/status/demo -o /dev/null -w "%{http_code}\n"
200

注意心跳端点刻意不返回 msg 与 ping 明细，只输出 status 与时间，避免泄露内部错误信息；uptimeList 输出每个监控项 24 小时可用率。页面本身（/status/demo）为 Vue 单页应用，结构化数据一律走上述两个 JSON 端点，做二次集成时直接消费 JSON 即可。整体状态徽章以 SVG 输出，可直接嵌入其他系统：

$ curl -s "http://127.0.0.1:3001/api/status-page/demo/badge/overall" | head -c 120
<svg xmlns="http://www.w3.org/2000/svg" width="133" height="20" role="img" aria-label="Overall: Degraded">

（Degraded 来自演示环境刻意保留的故障监控项，全部正常时显示 Up。）

九、参考链接

• Uptime Kuma 官方仓库：https://github.com/louislam/uptime-kuma
• 1.23.17 版本发布说明：https://github.com/louislam/uptime-kuma/releases/tag/1.23.17
• 官方 Wiki（部署与参数索引）：https://github.com/louislam/uptime-kuma/wiki
• 环境变量与命令行参数源码（server/config.js）：https://github.com/louislam/uptime-kuma/blob/1.23.17/server/config.js
• Node.js 18 官方文档：https://nodejs.org/docs/latest-v18.x/api/
• 相关文档：《Beszel Docker Compose 部署指南》《Prometheus 3.x 配置参数详解》《Grafana 配置参数详解》