企业官网建设流程全解析

Dozzle 容器过滤完全指南：用--filter与DOZZLE_FILTER精确控制可见容器

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

导读

在真实的多租户或高密度 Docker 环境中，让 Dozzle 显示"所有容器"往往既嘈杂又危险。本文围绕 docs/guide/filters.md 讲解 Dozzle 的条件过滤机制：它复用了 Docker 原生的--filter语法，可通过命令行--filter或环境变量DOZZLE_FILTER配置，并能在 UI、Agent、用户三个层级分别生效。读完本文，你将掌握过滤参数的完整写法、三层过滤的叠加规则与优先级，以及过滤条件在 Docker/K8s 两种后端下从参数解析到列表返回的底层执行链路。

过滤机制概述：复用 Docker 原生--filter语法

Dozzle 的容器过滤与 Docker CLI 的docker ps --filter高度一致。官方文档明确说明：过滤条件直接传给 Docker，用来限制 Dozzle 能看到的容器范围。例如：

• --filter "label=color"等价于执行docker ps --filter "label=color"；
• 常见的过滤维度是name与label，用于把 Dozzle 的可见范围收敛到指定的容器集合。

这意味着过滤是服务端执行的，而不是在 Dozzle 内部把全量容器列表做一遍二次筛选——被过滤掉的容器从一开始就不会出现在列表接口的返回结果中，这在容器数量庞大时能显著降低 Dozzle 自身的内存与网络开销。

快速开始：CLI 与 docker-compose 两种配置方式

命令行方式

在docker run中直接追加--filter参数即可（注意是传给 Dozzle 容器主进程，而非 Docker 本身）：

docker run --volume=/var/run/docker.sock:/var/run/docker.sock -p 8080:8080 amir20/dozzle --filter label=color

docker-compose 方式

通过环境变量DOZZLE_FILTER配置，效果与命令行参数完全等价：

services: dozzle: image: amir20/dozzle:latest volumes: - /var/run/docker.sock:/var/run/docker.sock ports: - 8080:8080 environment: DOZZLE_FILTER: label=color

上面的例子会让 Dozzle 只展示带有color标签的容器。在生产环境中，最典型的用法是用name或label过滤，把 Dozzle 的可见范围收敛到指定应用集合，同时天然规避"能看到全部容器"带来的越权或误操作风险。

过滤参数的解析规则（源码级验证）

过滤条件并不只是字符串原样透传。在 internal/support/cli/args.go 中，过滤参数被定义为：

FilterStrings []string `arg:"env:DOZZLE_FILTER,--filter,separate" help:"filters docker containers using Docker syntax."` Filter map[string][]string `arg:"-"`

其中separate标签表示DOZZLE_FILTER支持以分隔符传入多个过滤条件。随后的 ParseArgs 负责把字符串解析成结构化映射：

args.Filter = make(map[string][]string) for _, filter := range args.FilterStrings { pos := strings.Index(filter, "=") if pos == -1 { parser.Fail("each filter should be of the form key=value") } key := filter[:pos] val := filter[pos+1:] args.Filter[key] = append(args.Filter[key], val) }

这段代码揭示了两条重要规则：

1. 每个过滤条件必须是key=value形式，缺少=会直接导致启动失败（each filter should be of the form key=value）；
2. 同一 key 支持多个值：由于结果被收集为map[string][]string，你可以为label配置多个值，它们会被组合传递给 Docker。

在 internal/docker/client.go 的ListContainers中，这个映射被转换回 Docker SDK 的过滤参数：

filterArgs := make(client.Filters) for key, values := range labels { filterArgs.Add(key, values...) } containerListOptions := client.ContainerListOptions{ Filters: filterArgs, All: true, }

可以看到All: true意味着 Dozzle 请求的是包括已停止容器在内的全部匹配项，过滤动作完全交给 Docker 守护进程完成。

三层过滤体系：UI、Agent 与用户

文档明确将 Dozzle 的过滤分为三个层级，理解它们的关系是正确配置的前提：

1. UI 过滤器（全局过滤器）

通过--filter/DOZZLE_FILTER设置在 Dozzle UI 实例上，条件被发送到 Docker 以限制可见容器。它对所有没有自定义过滤器的 Agent 和用户生效，相当于实例级默认值。

2. Agent 过滤器

在 Agent 实例上设置，条件发送到该 Agent 所连接的 Docker，限制该 Agent 暴露的容器。Agent 过滤器与 UI 过滤器是叠加关系，两者共同收窄可见容器集合（详见下文"叠加与优先级"）。

3. 用户过滤器

在用户级别设置，决定特定用户能看到的容器。如果用户未定义过滤器，Dozzle 默认回落到 UI 过滤器。

三者组合的完整效果是：UI 过滤器先做第一层收敛，Agent 过滤器再做第二层收敛，用户过滤器最终决定单个登录用户能看到什么。

用户级过滤器：在users.yml中按账号收窄权限

用户过滤器在启用--auth-provider simple的简单认证模式下，通过 Dozzle 自管理的users.yml文件配置，详见 docs/guide/authentication/simple.md。示例：

users: admin: email: name: Admin password: $2a$11$9ho4vY2LdJ/WBopFcsAS0uORC0x2vuFHQgT/yBqZyzclhHsoaIkzK filter: guest: email: name: Guest password: $2a$11$9ho4vY2LdJ/WBopFcsAS0uORC0x2vuFHQgT/yBqZyzclhHsoaIkzK filter: "label=com.example.app"

• admin用户没有设置filter，可以看到所有容器；
• guest用户设置了filter: "label=com.example.app"，只能看到带该标签的容器。

这种能力非常适合"给只读访客、外包或分部门用户授予最小可见范围"的场景。需要说明的是，用户级过滤器覆盖（override）全局过滤器：只要某个用户配置了自己的过滤器，全局--filter对该用户即失效。

此外，在 forward-proxy 认证模式下，过滤器还可以通过 HTTP Header 下发——internal/support/cli/args.go 中的--auth-header-filter（环境变量DOZZLE_AUTH_HEADER_FILTER，默认头名为Remote-Filter）即为该用途；OIDC 模式下也有--auth-oidc-filters-claim（DOZZLE_AUTH_OIDC_FILTERS_CLAIM）用于指定从 token claim 中读取容器过滤器的路径。

Agent 级过滤器：远程主机可见范围收敛

在 Agent 模式下，同样通过DOZZLE_FILTER为 Agent 单独设置过滤器，详见 docs/guide/agent.md：

services: dozzle-agent: image: amir20/dozzle:latest command: agent environment: - DOZZLE_FILTER=label=color volumes: - /var/run/docker.sock:/var/run/docker.sock:ro

该配置会让 Agent 只暴露带color标签的容器。注意这里有一个文档特别强调的点：Agent 过滤器会与 UI 过滤器合并使用，两者共同收窄容器范围（见下一节）。Agent 模式是远程主机接入推荐方式（支持过滤器、内置加密与自动重连），与不支持过滤器的远程 socket 连接（--remote-host）形成对比，详细对比可参考 docs/guide/agent.md。

叠加与优先级：多层过滤器如何合并

文档用一个醒目的警告强调了多层过滤的组合语义：

多个过滤器会组合（combined）以限制容器。例如在 UI 层设置--filter label=color，同时在 Agent 层设置--filter label=type，那么 Dozzle 只会展示同时拥有color与type两个标签的容器。

也就是说，跨层级的过滤器之间是AND 语义：每一层都在上一层的可见集合基础上进一步收窄，而不是"取并集"。而同一层级内同一 key 的多个值（如label=color,label=type通过一个DOZZLE_FILTER传入）则按照 Docker 原生语义处理。

Docker 与 K8s：不同后端的过滤实现差异

文档标注该功能同时支持 Docker 与 K8s，但两种后端的执行方式并不相同，这可以从源码中看出。

Docker：过滤下推到守护进程

如前面 internal/docker/client.go 所示，过滤条件被完整转换为 Docker SDK 的ContainerListOptions.Filters，由 Docker 守护进程执行。此外 internal/container/container_store.go 在增量同步新容器时还会校验"使用过滤器时容器确实在列表内"，避免事件驱动的新容器误入可见集合。

K8s：拆分为 Pod 标签选择器 + 元数据匹配

K8s 后端在 internal/k8s/client.go 中做了更细的拆解。splitK8sFilters把过滤器分成两类：

• Pod 标签（pod labels）：符合 K8s 标签命名规范的 key，会被拼成LabelSelector（形如key1=value1,key2=value2）下推给 Kubernetes API 的Pods().List；
• K8s 元数据（metadata labels）：以@k8s.前缀开头，或命中namespace、owner.kind、owner.name、owner.key这类特殊 key 的过滤器，由于无法用 K8s label selector 表达，转而在客户端通过matchesContainerLabels（internal/k8s/client.go）对返回结果做精确匹配。

可以推断：在 K8s 环境下使用namespace=xxx这类元数据过滤器时，过滤发生在 Dozzle 进程内而非 API 服务器，容器量大时需要注意列表全量拉取带来的开销。

实践建议与注意事项

• 优先用标签做过滤：label是团队协作中最可控的维度，相比按name匹配更稳定、更易于在部署编排（如 docker-compose 的labels:段）中统一维护；
• 理解叠加语义：跨 UI/Agent/用户三层的过滤器是 AND 关系，设置时务必自底向上推演最终可见集合，避免"想放行反而全被过滤掉"的配置事故；
• 用户过滤器覆盖全局：为单个用户配置filter后，全局--filter对该用户不再生效，权限设计时需把这一点纳入考量；
• K8s 注意元数据过滤的位置：namespace等特殊 key 在客户端匹配，其余标签下推给 API Server，两者性能特征不同。

围绕本主题可继续阅读的仓库资料：过滤参数定义与解析、Docker 端过滤下发实现、K8s 端过滤拆分实现、用户级过滤配置、Agent 级过滤配置。

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