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.mdSwarm 模式与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:latest3.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_ENABLED0-ldflags -s -w去符号表。最终默认阶段是FROM scratch只拷贝二进制、CA 证书与/data目录ENTRYPOINT [/dozzle]直接执行。仓库中前端产物通过//go:embed all:dist见 main.go 顶部内嵌进二进制因此镜像里没有 shell——这一点在 README 的镜像标签一节中有正式说明。四、镜像标签策略镜像同时发布到 Docker Hub 与 ghcr.io标签完全一致标签说明latest最新 release多数用户推荐。v10.6.15精确版本生产环境建议固定该标签以保证可复现。v10.6该 minor 版本内最新 patch只跟进 bug 修复。v10该 major 版本内最新 release会跟进新特性。alpine与latest相同但基于 Alpine 而非scratch。v10.6.15-alpine、v10.6-alpine、v10-alpine上述版本标签的 Alpine 变体。master每次推送master分支时构建未发布、不稳定。pr-1234、pr-1234-alpine由 pull request #1234 构建用于正式发布前验证修复。关于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_MODEswarm \ --mode global \ --mount typebind,source/var/run/docker.sock,target/var/run/docker.sock \ -p 8080:8080 \ amir20/dozzle:latest从源码看swarm 模式的启动路径在 main.go 的args.Mode swarm分支中创建本地 Docker 客户端不覆盖 host id——源码注释解释swarm 中节点身份就是 swarm node id天然稳定其他节点本就靠它引用本节点通过 swarm service 发现同集群的其它副本NewSwarmClientManager每个副本再作为 agent 监听:7007供对等节点连接形成去中心化的多主机视图通知管理器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 agentagent子命令的实现位于 internal/support/cli/agent_command.go默认绑定地址:7007AgentCmd.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_AGENT167.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取值及源码级行为provider行为none默认无认证。simple从./data/users.yml或users.yaml加载用户白名单文件缺失直接启动失败可叠加 GitHub / OIDC 作为证明你是白名单成员的登录方式。forward-proxy信任反代注入的请求头默认读取Remote-User、Remote-Email、Remote-Name、Remote-Filter、Remote-Roles可用--auth-header-*系列 flag 改写。oidc用户与角色全部来自 OIDC token 的 claims不读取 users.yml源码中遇到 data 目录下存在 users.yml 会打印警告并忽略--auth-oidc-issuer/client-id/client-secret三者缺一即 fatal且不允许与 GitHub 凭据混用。另有几个工程细节值得注意github与google是simple的别名在 main 入口处被统一归一化避免新手在默认路径上遇到 fatal会话密钥与users.yml同目录派生auth.SessionSecret多副本共享同一数据卷时各副本用同一把密钥签发会话用户文件可用官方 generate 子命令生成docker run -it --rm amir20/dozzle generate admin --password ... --email ... --name ... --user-filter namefoo --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_ANALYTICStrue上报端在 internal/analytics/http_beacon.goflag 校验由 internal/support/cli/valid_env.go 统一处理。十一、环境变量与配置体系Dozzle 遵循 12-factor 模型所有配置既可以用 CLI flag 也可以用环境变量。完整对照表摘自 docs/guide/supported-env-vars.mdFlag环境变量默认值--addrDOZZLE_ADDR:8080--baseDOZZLE_BASE/--hostnameDOZZLE_HOSTNAME--host-idDOZZLE_HOST_ID--levelDOZZLE_LEVELinfo--auth-providerDOZZLE_AUTH_PROVIDERnone--auth-header-userDOZZLE_AUTH_HEADER_USERRemote-User--auth-header-emailDOZZLE_AUTH_HEADER_EMAILRemote-Email--auth-header-nameDOZZLE_AUTH_HEADER_NAMERemote-Name--auth-header-filterDOZZLE_AUTH_HEADER_FILTERRemote-Filter--auth-header-rolesDOZZLE_AUTH_HEADER_ROLESRemote-Roles--auth-logout-urlDOZZLE_AUTH_LOGOUT_URL--auth-ttlDOZZLE_AUTH_TTLsession--auth-github-client-idDOZZLE_AUTH_GITHUB_CLIENT_ID--auth-github-client-secretDOZZLE_AUTH_GITHUB_CLIENT_SECRET--auth-oidc-issuerDOZZLE_AUTH_OIDC_ISSUER--auth-oidc-client-idDOZZLE_AUTH_OIDC_CLIENT_ID--auth-oidc-client-secretDOZZLE_AUTH_OIDC_CLIENT_SECRET--auth-oidc-nameDOZZLE_AUTH_OIDC_NAMESSO--auth-oidc-roles-claimDOZZLE_AUTH_OIDC_ROLES_CLAIM--auth-oidc-filters-claimDOZZLE_AUTH_OIDC_FILTERS_CLAIM--enable-actionsDOZZLE_ENABLE_ACTIONSfalse--enable-shellDOZZLE_ENABLE_SHELLfalse--enable-mcpDOZZLE_ENABLE_MCPfalse--disable-avatarsDOZZLE_DISABLE_AVATARSfalse--filterDOZZLE_FILTER--no-analyticsDOZZLE_NO_ANALYTICSfalse--modeDOZZLE_MODEserver--release-check-modeDOZZLE_RELEASE_CHECK_MODEautomatic--image-check-modeDOZZLE_IMAGE_CHECK_MODEinherited--remote-hostDOZZLE_REMOTE_HOST可多次指定--remote-agentDOZZLE_REMOTE_AGENT可多次指定--timeoutDOZZLE_TIMEOUT10s--namespaceDOZZLE_NAMESPACE--certDOZZLE_CERTdozzle_cert.pem--keyDOZZLE_KEYdozzle_key.pem三个容易踩坑的补充说明均来自该文档DOZZLE_AUTH_GITHUB_CLIENT_SECRET与DOZZLE_AUTH_OIDC_CLIENT_SECRET均支持_FILE后缀变体指向一个存放密钥值的文件便于配合 Docker secrets 使用源码实现在 internal/support/cli/secrets.go--remote-host/--remote-agent可重复指定或逗号分隔--mode除默认的server外还支持swarm与k8smain.go 中对三种模式分别构建hostServicek8s 模式的部署示例见 examples/k8s.dozzle.yml指南见 docs/guide/k8s.md。十二、本地构建与二次开发项目分为两部分Go 后端对接 Docker API与Vue 前端运行在浏览器中。按 README.md 的 Building 章节开发流程如下。1. 安装前置依赖需要 Go 1.25、Node.js含 pnpm、protoc。macOSbrew install go node pnpm protobufLinuxDebian/Ubuntusudo apt install golang nodejs protobuf-compiler npm install -g pnpmWindows 建议通过 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.pemopenssl genpkey -algorithm Ed25519与shared_cert.pem自签名 1825 天的 Ed25519 证书随后执行go generate ./...生成 protobuf 代码protoc 指令内嵌在 main.go 顶部的//go:generate注释中proto 源文件在 protos/make devgenerate fake_assets后运行pnpm devfake_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.sockmake generate失败——确认protoc在 PATH 中protoc --version本地打镜像可直接用make docker构建amir20/dozzle:localmake 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考