Dozzle：面向 Docker、Swarm 与 K8s 的实时容器日志查看器

Dozzle：面向 Docker、Swarm 与 K8s 的实时容器日志查看器

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

本文围绕 Dozzle 项目的 README 展开，介绍这个轻量级 Web 日志查看器的核心设计（不落地存储、纯实时查看）、完整的部署方式（单容器、Compose、Swarm 全局服务、多主机 Agent 模式）、镜像标签策略、Podman/Colima 等兼容引擎的接入细节，以及从源码可验证的运行机制与环境变量配置体系。读完后你可以直接在自己的 Docker 或 Podman 主机上跑起 Dozzle，并理解它"只看不存"背后的内存实现。

一、定位与设计哲学：只查看，不存储

Dozzle 的定位在 README.md 中表述得非常明确：它是一个基于 Web 的轻量应用，用于实时监控 Docker 日志，本身不存储任何日志文件——纯粹为"看实时日志"而设计。这一设计决策在源码中处处可见：

• 日志走流式 API 而非落盘。internal/docker/client.go 中ContainerLogs方法以Follow: true订阅引擎日志流，并用Tail: 100只拉取最近 100 行作为回放缓冲，Since参数向前回退 50ms 以覆盖并发间隙。历史日志依赖容器引擎自身的日志驱动，Dozzle 只在需要某个时间窗时通过ContainerLogsBetweenDates临时拉取。
• 实时指标用环形缓冲，内存占用恒定。容器模型为每个容器分配一个容量 300 的RingBuffer（对应约 300 秒的统计窗口，见 internal/docker/client.go 中newContainer与newContainerFromJSON的Stats: utils.NewRingBuffercontainer.ContainerStat注释），底层实现在 internal/utils/ring_buffer.go。这就是"Small memory footprint"这一特性的实现来源。

README 同时给出能力边界的官方说明：Dozzle 已在数百个容器的规模上测试过，但不支持离线搜索；完整的日志检索能力应交给 Loggly、Papertrail、Kibana 一类专业产品。因此把它理解为"实时观察工具"而非"日志平台"是准确的。

二、核心功能一览

README 列出的功能清单如下，每一项在仓库中都有对应实现：

• 容器名智能模糊搜索：前端FuzzySearchModal组件，见 assets/components/search/FuzzySearchModal.vue；
• 日志正则搜索与SQL 查询搜索：SQL 引擎的完整用法见 docs/guide/sql-engine.md；
• 小内存占用：环形缓冲 + 流式日志，如上一节所述；
• 分屏查看多个日志：前端分屏布局组件；
• 实时统计：内存与 CPU 占用，统计采集在 internal/docker/stats_collector.go；
• 多用户认证：支持文件认证与反向代理转发认证（Authelia 等），见 docs/guide/authentication.md；
• Swarm 模式与Agent 模式（监控多个 Docker 主机），分别见下文第五、六节及 docs/guide/swarm-mode.md、docs/guide/agent.md；
• 暗色模式：主题切换逻辑在 assets/composable/app/theme.ts。

三、快速开始

3.1 拉取镜像

Dozzle 官方镜像仅 7 MB 压缩体积：

$ docker pull amir20/dozzle:latest

3.2 运行容器

最简单的方式是直接把宿主机 Docker Unix socket 挂载进容器：

$ docker run --name dozzle -d \ --volume=/var/run/docker.sock:/var/run/docker.sock \ -v dozzle_data:/data \ -p 8080:8080 \ amir20/dozzle:latest

启动后访问http://localhost:8080/。/data卷用于存放users.yml、通知配置等持久化数据（internal/support/cli/agent_command.go 中可以看到配置写入./data/notifications.yml、./data/cloud.yml的逻辑，simple 认证则读取./data/users.yml）。

Docker Compose 示例：

services: dozzle: container_name: dozzle image: amir20/dozzle:latest volumes: - /var/run/docker.sock:/var/run/docker.sock - dozzle_data:/data ports: - 8080:8080 volumes: dozzle_data:

仓库根目录也提供了一份 docker-compose.yml 可直接参考。更高级的选项（认证、远程主机等）参见 docs/guide/getting-started.md 与 docs/guide/remote-hosts.md。

3.3 为什么只有 7 MB：镜像构建拆解

Dockerfile 是一个多阶段构建：node阶段用 pnpm 构建 Vue 前端产物，golang阶段交叉编译出静态二进制（CGO_ENABLED=0+-ldflags "-s -w"去符号表）。最终默认阶段是FROM scratch，只拷贝二进制、CA 证书与/data目录，ENTRYPOINT ["/dozzle"]直接执行。仓库中前端产物通过//go:embed all:dist（见 main.go 顶部）内嵌进二进制，因此镜像里没有 shell——这一点在 README 的镜像标签一节中有正式说明。

四、镜像标签策略

镜像同时发布到 Docker Hub 与 ghcr.io，标签完全一致：

关于alpine变体，README 给出了一条实用建议：默认scratch镜像内没有 shell，只有当你的平台需要在容器入口点之上绑定挂载一个#!/bin/sh包装脚本时才需要它，最典型的场景是 Unraid 的每容器 Tailscale 开关。Dockerfile 中可以看到FROM alpine:3.24 AS alpine阶段位于scratch阶段之前，注释明确"必须保持在 scratch 阶段之上，因为最后阶段才是默认构建目标"。

生产环境建议：避免latest和master。latest随每次 release 移动，master是未发布代码。

五、Swarm 模式：作为全局服务运行

Dozzle 原生支持 Docker Swarm，可以以 global service 形式部署——每个节点一个副本，共同构成一个集群视图：

$ docker service create --name dozzle \ --env DOZZLE_MODE=swarm \ --mode global \ --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \ -p 8080:8080 \ amir20/dozzle:latest

从源码看，swarm 模式的启动路径在 main.go 的args.Mode == "swarm"分支中：

1. 创建本地 Docker 客户端，不覆盖 host id——源码注释解释：swarm 中节点身份就是 swarm node id，天然稳定，其他节点本就靠它引用本节点；
2. 通过 swarm service 发现同集群的其它副本（NewSwarmClientManager），每个副本再作为 agent 监听:7007供对等节点连接，形成去中心化的多主机视图；
3. 通知管理器（alerts/webhooks）在每个副本上启动。

仓库 examples/docker.swarm.yml 与 examples/docker.swarm.auth.yml（带认证版本）提供了可直接使用的 Compose/Service 定义，更多细节见 docs/guide/swarm-mode.md。

六、Agent 模式：监控多台 Docker 主机

当日志分散在多台主机上时，在每台远程主机上运行一个 agent，中心端 Dozzle 统一展示：

$ docker run -v /var/run/docker.sock:/var/run/docker.sock \ -p 7007:7007 amir20/dozzle:latest agent

agent子命令的实现位于 internal/support/cli/agent_command.go：

• 默认绑定地址:7007（AgentCmd.Addr的default:":7007"，可用环境变量DOZZLE_AGENT_ADDR覆盖）；
• agent 复用与主服务相同的 Docker 客户端、容器存储与通知管理器，通知配置持久化到./data/notifications.yml以便重启后保留；
• 启动时会把监听地址写入/tmp/dozzle-agent.addr供健康检查使用。

中心端通过--remote-agent（或DOZZLE_REMOTE_AGENT）指向 agent 地址；docs/guide/supported-env-vars.md 说明该 flag可以重复多次，也可用逗号分隔：

# 形式一：重复 flag --remote-agent 167.99.1.1:7007 --remote-agent 167.99.1.2:7007 # 形式二：逗号分隔环境变量 DOZZLE_REMOTE_AGENT=167.99.1.1:7007,167.99.1.2:7007

完整示例见 examples/docker.agents.yml（无 TLS）与 examples/docker.agents-with-certs.yml（含证书），以及 examples/setup-remote-agent.sh 自动化脚本。更多说明见 docs/guide/agent.md。

七、技术细节：API 协商与引擎要求

README 声明了几条兼容性事实，均可在源码中得到印证：

• 自动 API 版本协商：internal/docker/client.go 的NewLocalClient/NewRemoteClient均使用client.New(client.FromEnv, ...)并在连接后执行Ping(ctx, PingOptions{NegotiateAPIVersion: true})，因此绝大多数 Docker 配置无需手动指定 API 版本；
• 最低版本要求：需要 Docker Engine 19.03 或更新（API 1.40+），错误信息会显式带上minimum API version（即底层 Docker SDK 的client.MinAPIVersion）；
• 兼容 Colima 与 Podman：运行时探测函数detectRuntime会调用ServerVersion，从组件名/平台名/OperatingSystem 字段中识别 "podman"，否则归为 "docker"。

八、在 Podman 上运行

Podman 默认没有常驻 daemon 进程，需要开启 remote socket 才能让 Dozzle 通过 Docker API 与之通信。

第一步，检查 remote socket 是否已启用：

podman info

若输出中 remote socket 段如下，即已启用：

remoteSocket: exists: true path: /run/user/1000/podman/podman.sock

若未启用，按 Podman 官方的 socket activation 教程开启即可。

第二步，运行 Dozzle，把 Podman socket 挂载到 Docker socket 位置：

podman run --volume=/run/user/1000/podman/podman.sock:/var/run/docker.sock \ -d -p 8080:8080 docker.io/amir20/dozzle:latest

至此即可，无需其它操作。README 特别强调了一个常见误解的修正：旧版文档曾让你创建/var/lib/docker/engine-id文件来规避host not found错误，那从未生效过。从源码看原因很清楚——internal/container/host_id.go 的注释写明：Podman 是无守护进程的，其 Docker 兼容/info端点不会读取任何文件，而是每次调用都返回一个全新随机 UUID。因此 Dozzle 现在改为自行推导稳定 host id：

• 对 Podman 主机，用uuid.NewSHA1(固定命名空间, hostname + "\x00" + storageRoot)派生 id。存储根目录让同一台机器上的不同 rootless 用户（共享主机名但各自独立存储目录）互不冲突；
• 若 Podman 既未报告主机名也未报告存储根，则拒绝派生（返回空），因为哈希两个空字符串会让整个集群的所有主机塌缩成同一个 id——"id 抖动"和"主机静默消失"相比，前者更轻；
• 若两主机派生 id 冲突（主机名与存储根都相同），可用DOZZLE_HOST_ID手动指定（StaticHostID解析器）。

详见 docs/guide/podman.md 及 docs/guide/faq.md 中 "host not found" 相关条目。

九、安全：认证与授权

Dozzle 支持文件认证与反向代理认证（配合 Authelia 等），完整指南见 docs/guide/authentication.md。从 main.go 的createServer可以看到四种--auth-provider取值及源码级行为：

另有几个工程细节值得注意：

• github与google是simple的别名，在 main 入口处被统一归一化，避免新手在默认路径上遇到 fatal；
• 会话密钥与users.yml同目录派生（auth.SessionSecret），多副本共享同一数据卷时各副本用同一把密钥签发会话；
• 用户文件可用官方 generate 子命令生成：docker run -it --rm amir20/dozzle generate admin --password ... --email ... --name ... --user-filter name=foo --user-roles shell > users.yml，参数表见 docs/guide/supported-env-vars.md。

十、匿名统计（Analytics）及其关闭方式

README 说明：Dozzle 通过 Google Analytics 收集匿名用户配置数据。项目无资金来源、没有正式用户调研的时间，数据用于按实际使用情况排定特性与修复优先级，且该数据完全公开、可实时查看。关闭方式：

docker run ... amir20/dozzle:latest --no-analytics # 或 DOZZLE_NO_ANALYTICS=true

上报端在 internal/analytics/http_beacon.go，flag 校验由 internal/support/cli/valid_env.go 统一处理。

十一、环境变量与配置体系

Dozzle 遵循 12-factor 模型：所有配置既可以用 CLI flag 也可以用环境变量。完整对照表（摘自 docs/guide/supported-env-vars.md）：

三个容易踩坑的补充说明（均来自该文档）：

1. DOZZLE_AUTH_GITHUB_CLIENT_SECRET与DOZZLE_AUTH_OIDC_CLIENT_SECRET均支持_FILE后缀变体，指向一个存放密钥值的文件，便于配合 Docker secrets 使用（源码实现在 internal/support/cli/secrets.go）；
2. --remote-host/--remote-agent可重复指定或逗号分隔；
3. --mode除默认的server外还支持swarm与k8s（main.go 中对三种模式分别构建hostService，k8s 模式的部署示例见 examples/k8s.dozzle.yml，指南见 docs/guide/k8s.md）。

十二、本地构建与二次开发

项目分为两部分：Go 后端（对接 Docker API）与Vue 前端（运行在浏览器中）。按 README.md 的 Building 章节，开发流程如下。

1. 安装前置依赖

需要 Go 1.25+、Node.js（含 pnpm）、protoc。

macOS：

brew install go node pnpm protobuf

Linux（Debian/Ubuntu）：

sudo apt install golang nodejs protobuf-compiler npm install -g pnpm

Windows 建议通过 WSL2 走 Linux 流程。

2. 克隆与初始化

git clone https://gitcode.com/GitHub_Trending/do/dozzle.git cd dozzle pnpm install # 安装前端依赖 go install tool # 安装 go.mod 中声明的构建工具（air、protoc-gen-go 等） make generate # 生成 TLS 证书与 protobuf 代码（只需一次）

对照 Makefile 可以看清每条命令的实际动作：

• make generate依赖两个目标：shared_key.pem（openssl genpkey -algorithm Ed25519）与shared_cert.pem（自签名 1825 天的 Ed25519 证书），随后执行go generate ./...生成 protobuf 代码（protoc 指令内嵌在 main.go 顶部的//go:generate注释中，proto 源文件在 protos/）；
• make dev=generate + fake_assets后运行pnpm dev，fake_assets用一个占位dist/index.html跳过前端构建，因为开发时由 Vite dev server 提供页面。

3. 启动开发服务

make dev

打开http://localhost:3100，应能看到连接了本地 Docker 的 Dozzle UI；前后端保存文件后均会自动热重载/重启。仓库还提供make dev-auto，从检出路径推导端口三元组，允许多个 worktree 同时各跑一个实例。

4. 第一次修改

• 前端：编辑 assets/pages/index.vue 并保存，浏览器即时更新；
• 后端：编辑任意.go文件，服务器自动重启。

5. 排障

• localhost:3100 无内容——确认 Docker 正在运行且 socket 位于/var/run/docker.sock；
• make generate失败——确认protoc在 PATH 中（protoc --version）；
• 本地打镜像可直接用make docker（构建amir20/dozzle:local），make run会以挂载本机 socket 的方式运行它。

十三、小结

Dozzle 用极小的代价（7 MB 镜像、恒定内存占用、单 socket 挂载）换取了 Docker / Swarm / K8s / Podman 多引擎下的实时日志观察能力：日志不落地、统计用环形缓冲、多主机靠 agent 聚合、身份靠稳定派生的 host id。以上每一节的行为都能在当前仓库源码中找到对应实现与测试（如 internal/container/host_id_test.go、internal/docker/client_test.go），适合作为一个"小而完整"的 Go + Vue 全栈项目来阅读。

项目采用 MIT 许可（见 LICENSE），社区支持渠道包括在 issue 区提问与提交文档改进 PR。

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