企业官网建设流程全解析

Dozzle 日志调试指南：用 --level 与 DOZZLE_LEVEL 定位容器日志查看器的问题

【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzle

Dozzle 是一款面向容器的实时日志查看器，支持 Docker、Swarm 与 Kubernetes。本文将围绕官方调试指南（docs/guide/debugging.md）展开，讲解 Dozzle 日志级别体系的含义、如何通过--level命令行参数或DOZZLE_LEVEL环境变量提升日志详细程度、如何从stdout读取日志，以及遇到 Bug 时如何组织一份高质量的问题报告。读完本文，你将掌握 Dozzle 从"静默运行"到"全量追踪"的完整调试链路。

为什么 Dozzle 默认日志很少

Dozzle 默认以info级别记录日志，输出刻意保持精简——正常运行时只有启动信息、错误和警告，避免刷屏干扰排查。只有当功能异常（如认证失败、agent 无法连接、容器日志不显示）时，才需要主动提高日志详细程度。这种设计在 internal/support/cli/args.go 中有直接体现：

Level string `arg:"env:DOZZLE_LEVEL" default:"info" help:"set Dozzle log level. Use debug for more logging."`

参数默认值就是info，同时绑定了DOZZLE_LEVEL环境变量。这意味着--level debug与DOZZLE_LEVEL=debug是等价的两种写法，详见全局参数对照表 docs/guide/supported-env-vars.md：

三个日志级别的适用场景

官方指南给出的级别划分如下：

实际使用建议：日常运行保持info；排查具体问题时先用debug，它会输出请求级诊断、认证判定、agent 连接状态和配置转储等关键信息，足以覆盖绝大多数故障；只有当debug信息仍不足以定位（例如需要观察逐条日志事件、云信标负载或 gRPC 帧的细节）时才升级到trace，并注意它会产生海量输出，不应在生产环境长期开启。

从源码看，日志级别的解析与设置在 internal/support/cli/logger.go 中完成：ConfigureLogger调用zerolog.ParseLevel解析级别字符串，再通过zerolog.SetGlobalLevel全局生效；如果传入了无法识别的级别，程序会直接panic。同时，日志输出会自动附带version字段（即 Dozzle 版本号），这对后续定位问题很有帮助。Dozzle 的后端日志体系基于github.com/rs/zerolog实现。

如何开启 debug 日志

方式一：docker-compose 中设置环境变量

这是最常用的方式。官方指南给出的最小示例：

services: dozzle: image: amir20/dozzle:latest volumes: - /var/run/docker.sock:/var/run/docker.sock ports: - 8080:8080 environment: DOZZLE_LEVEL: debug

方式二：命令行直接运行

不使用容器编排时，直接在启动命令中追加参数：

dozzle --level debug

或通过环境变量：

DOZZLE_LEVEL=debug dozzle

方式三：agent 模式

Dozzle 的 agent 模式同样支持该配置。examples/docker.agents.yml 中演示了 agent 容器开启DOZZLE_LEVEL=debug的写法（command: agent子命令，全局部署以暴露7007端口）。远程主机出现连接或日志流异常时，同时在 server 端和 agent 端开启 debug 往往能更快定位是哪一侧的问题。

此外，docker-compose.yml 与 Makefile 中也都包含DOZZLE_LEVEL=debug的用法，可以交叉参考实际项目中的配置方式。

日志输出到哪里：stdout 与 docker logs

Dozzle 把所有日志写入stdout，因此查看日志的唯一入口就是容器标准输出：

docker logs dozzle

如果容器名不是dozzle，请替换为实际容器名。此规则同样适用于 agent 容器——它的日志同样走自身 stdout，通过docker logs <agent容器名>读取。需要持续跟踪时可以用-f参数：docker logs -f dozzle。

从源码理解日志机制

结合源码可以更清楚地理解调试信息的产生位置：

• 配置解析与级别设置：internal/support/cli/args.go 中ParseArgs解析完参数后会立即调用ConfigureLogger(args.Level)，即日志级别在启动早期就生效，后续所有模块的日志都会按该级别过滤。
• 级别全局生效：internal/support/cli/logger.go 中zerolog.SetGlobalLevel(level)设置全局级别；若启用DEV环境变量，还会切换到带字段排序的 ConsoleWriter，便于开发时阅读。
• 认证判定的调试日志：main.go 在切换认证别名、校验 provider 时输出log.Debug()；main.go 在启用 GitHub OAuth、OpenID Connect 时也输出对应 debug 日志。认证失败排查时这些日志是关键证据。
• 版本信息：启动时 main.go 会输出Dozzle version <版本号>的info日志，与dozzle --version一致，可用于确认运行的版本。

不同部署模式下的调试要点

Dozzle 支持多种部署模式，故障排查时需结合模式判断日志应出现在哪里：

• server 模式：默认模式，直连本地 Docker 引擎，docker logs dozzle即可。
• swarm 模式：--mode swarm下每个节点上的 Dozzle 既是 server 又是 agent（监听:7007），需要逐节点查看各自容器的 stdout 日志。
• k8s 模式：--mode k8s下使用kubectl logs <dozzle-pod>读取日志；命名空间相关参数为DOZZLE_NAMESPACE。
• agent 模式：agent 与被监控主机分离，server 端与 agent 端各自开启 debug，配合对比连接日志。

无论哪种模式，DOZZLE_LEVEL=debug与--level debug的配置方式都一致，只是"在哪里看日志"不同。若怀疑是前端问题（界面无响应、SSE 流异常），项目自身的开发者指南 CLAUDE.md 还提供了补充手段：前端用 Vue DevTools 浏览器扩展调试，SSE 流在浏览器 DevTools 的 Network 面板中查看 EventSource 连接。

报告 Bug 时的必备信息清单

如果开启了 debug 甚至 trace 仍确认是 Dozzle 自身缺陷，请到项目仓库的 Issues 页面提交 issue，并附上以下信息。官方指南明确要求包含：

• Dozzle 版本：界面页脚可见，或执行dozzle --version获取；
• 部署模式：server、swarm、k8s 或 agent 四选一；
• Docker 或 Kubernetes 版本：运行时环境的精确版本号；
• 相关的debug或trace级别日志输出：在 debug/trace 级别下抓取的原始日志片段；
• 复现步骤：最好附上一个最小化的docker-compose.yml，让维护者能快速还原现场。

初次报告中的信息越完整，问题分类处理得就越快。其中"版本 + 部署模式 + 日志级别"三者缺一不可——同一现象在不同模式（如 swarm 与 k8s）下的根因可能完全不同，而默认的info级别日志信息量不足，往往无法直接定位。

小结

Dozzle 的日志调试遵循一条清晰的路径：默认info保持安静 → 遇到问题升级debug查看请求级诊断、认证判定、agent 连接与配置转储 → 仍不充分再升级trace观察逐条事件与 gRPC 帧。所有日志统一写入stdout，通过docker logs即可读取；--level与DOZZLE_LEVEL两种配置方式等价，可通用于 server、swarm、k8s 与 agent 全部模式。掌握这套方法，再配合完整的问题报告清单，绝大多数容器日志查看相关的疑难杂症都能高效定位。

【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzle