企业官网建设流程全解析

ntfy 如何配置 JSON 日志与临时 debug 日志级别辅助问题定位

【免费下载链接】ntfySend push notifications to your phone or desktop using PUT/POST项目地址: https://gitcode.com/GitHub_Trending/nt/ntfy

当你自托管 ntfy 服务器并且某个组件行为不符合预期时，官方推荐的排查手段是：先确认服务器日志格式便于收集，再临时把日志级别提高到debug或trace观察服务器内部发生了什么。这篇文章基于 ntfy 的配置文档和故障排查文档，给出这条排查路径的完整配置项、命令行写法、热重载方式和验证方法。适用对象是自己运行ntfy serve的服务器；Android、Web 等客户端侧的日志不在这篇范围内。

了解默认日志行为

ntfy 的默认日志行为是：输出到控制台（stderr），日志级别为info，格式为人类可读的文本（text）。也就是说，默认配置下日志没有写入任何文件，也没有结构化格式。

相关配置项及其对应环境变量如下（均来自配置文档的选项表）：

配置有三种设置方式：配置文件（默认路径/etc/ntfy/server.yml）、命令行选项（如--log-format json）、环境变量。配置文件里也可以把连字符写成下划线（log_format与log-format等价）。

配置 JSON 格式日志

官方给出的、适合生产使用的日志配置示例是：

log-level: info log-format: json log-file: /var/log/ntfy.log

含义很直接：保持info级别不变，把输出格式改为json，并写入/var/log/ntfy.log。/var/log/ntfy.log是文档示例路径，你可以按自己的日志目录替换；如果不设置log-file，日志会一直输出到 stderr。

如果不想改配置文件，也可以用命令行选项临时指定，例如在启动参数上加--log-format json（对应环境变量NTFY_LOG_FORMAT）。

临时开启 debug / trace 日志定位问题

当某项功能不正常时，把日志级别临时调高是官方故障排查文档给出的通用做法。

在server.yml中设置：

log-level: debug

或者：

log-level: trace

其他等价方式：

• 使用环境变量时：NTFY_LOG_LEVEL=debug（或trace）；
• 直接在启动命令上追加参数：ntfy serve --debug或ntfy serve --trace。

debug与trace的输出粒度不同：debug会输出每条已发布消息的信息，但不包含消息内容；trace会连消息内容一起打印。

文档示例（debug 级别日志）：

$ ntfy serve --debug 2023/03/20 14:45:38 INFO Listening on :2586[http] :1025[smtp], ntfy 2.1.2, log level is DEBUG (tag=startup) 2023/03/20 14:45:38 DEBUG Waiting until 2023-03-21 00:00:00 +0000 UTC to reset visitor stats (tag=resetter) 2023/03/20 14:45:39 DEBUG Rate limiters reset for visitor (visitor_auth_limiter_limit=0.016666666666666666, visitor_auth_limiter_tokens=10, visitor_emails=0, visitor_emails_limit=12, visitor_emails_remaining=12, visitor_id=ip:127.0.0.1, visitor_ip=127.0.0.1, visitor_messages=0, visitor_messages_limit=500, visitor_messages_remaining=500, visitor_request_limiter_limit=0.2, visitor_request_limiter_tokens=60, visitor_seen=2023-03-20T14:45:39.7-04:00) 2023/03/20 14:45:39 DEBUG HTTP request started (http_method=POST, http_path=/mytopic, tag=http, visitor_auth_limiter_limit=..., visitor_ip=127.0.0.1, ...) 2023/03/20 14:45:39 DEBUG Received message (http_method=POST, http_path=/mytopic, message_body_size=2, message_delayed=false, ..., message_id=EZu6i2WZjH0v, message_sender=127.0.0.1, ..., tag=publish, topic=mytopic, topic_subscribers=0, ...) 2023/03/20 14:45:39 DEBUG Adding message to cache (...) 2023/03/20 14:45:39 DEBUG HTTP request finished (http_method=POST, http_path=/mytopic, tag=http, time_taken_ms=2, ...) 2023/03/20 14:45:39 DEBUG Wrote 1 message(s) in 8.285712ms (tag=message_cache) ...

文档示例（trace 级别日志），可以看到 trace 额外打印了完整 HTTP 请求头和消息体：

$ ntfy serve --trace 2023/03/20 14:40:42 INFO Listening on :2586[http] :1025[smtp], ntfy 2.1.2, log level is TRACE (tag=startup) ... 2023/03/20 14:40:59 TRACE HTTP request started (http_method=POST, http_path=/mytopic, http_request=POST /mytopic HTTP/1.1 User-Agent: curl/7.81.0 Accept: */* Content-Length: 2 Content-Type: application/x-www-form-urlencoded hi, tag=http, ...) 2023/03/20 14:40:59 TRACE Received message (http_method=POST, http_path=/mytopic, message_body={ "id": "Khaup1RVclU3", "time": 1679337659, "expires": 1679380859, "event": "message", "topic": "mytopic", "message": "hi" }, message_body_size=2, message_delayed=false, ...) 2023/03/20 14:40:59 TRACE No stream or WebSocket subscribers, not forwarding (...)

上面两段都是文档中的示例日志，实际输出的时间戳、消息 ID、数值会不同；观察重点在于级别生效后出现DEBUG/TRACE行，以及每类事件（HTTP 请求开始/结束、消息接收、写入缓存）是否齐全。

只提高特定字段相关的日志级别：log-level-overrides

把全局级别提到debug或trace会产生大量日志。如果只想盯住系统的某一部分（例如某个账号管理流程、某个访问者），可以用log-level-overrides做细粒度覆盖。它是一组字符串数组，格式为：

• field=value -> level：精确匹配某个值，例如tag=manager -> trace
• field -> level：匹配任意值，例如time_taken_ms -> debug

官方示例：只输出info级别，但当事件匹配到任一覆盖规则时提高级别：

log-level: info log-level-overrides: - "tag=manager -> trace" - "visitor_ip=1.2.3.4 -> debug" - "time_taken_ms -> debug"

文档中明确提到的可用于匹配的字段包括访问者 IP（visitor_ip）、用户名（user_name）、标签（tag），实际有几十个字段可用；要弄清都有哪些，可以把日志级别临时设为trace观察输出，或查阅 ntfy 源码。

验证配置是否生效

修改server.yml后，log-level和log-level-overrides支持热重载，不需要重启服务。发送SIGHUP信号即可：

systemctl reload ntfy # ntfy 由 systemd 托管时 kill -HUP $(pidof ntfy) # 或者直接向进程发信号

重载成功后，日志中会出现类似下面的内容（文档示例，日期时间与日志级别以实际为准）：

$ ntfy serve 2022/06/02 10:29:28 INFO Listening on :2586[http] :1025[smtp], log level is INFO 2022/06/02 10:29:34 INFO Partially hot reloading configuration ... 2022/06/02 10:29:34 INFO Log level is TRACE

判断标准：看到Partially hot reloading configuration和随后新的Log level is ...行，说明热重载成功、新级别已生效。注意热重载只覆盖log-level和log-level-overrides这两项；log-format、log-file不在可热重载范围内，修改它们需要重启服务。

如果 ntfy 是通过 systemd 运行的，还可以直接用journalctl -u ntfy -f跟踪日志。

限制与收尾

• 配置文档明确警告：debug（尤其是trace）输出非常冗余，只应短暂开启用于调试；使用log-level-overrides也存在性能开销，同样只建议临时使用。
• 排查结束后，记得把log-level恢复为info（改完配置后同样可以systemctl reload ntfy生效），并移除临时的log-level-overrides条目。
• trace会把消息内容写入日志，开启前需要考虑日志中出现的消息内容；文档没有给出其他自动脱敏机制。

完成一次"JSON 格式 + 临时 debug 级别"的定位后，如果你的问题出在反向代理后的 WebSocket 行为（例如客户端一直显示 Reconnecting），故障排查文档中还列出了behind-proxy配置和主题访问权限两类需要核对的项，可作为下一个排查方向。

【免费下载链接】ntfySend push notifications to your phone or desktop using PUT/POST项目地址: https://gitcode.com/GitHub_Trending/nt/ntfy