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 labelcolor等价于执行docker ps --filter labelcolor常见的过滤维度是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 labelcolordocker-compose 方式通过环境变量DOZZLE_FILTER配置效果与命令行参数完全等价services: dozzle: image: amir20/dozzle:latest volumes: - /var/run/docker.sock:/var/run/docker.sock ports: - 8080:8080 environment: DOZZLE_FILTER: labelcolor上面的例子会让 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 keyvalue) } key : filter[:pos] val : filter[pos1:] args.Filter[key] append(args.Filter[key], val) }这段代码揭示了两条重要规则每个过滤条件必须是keyvalue形式缺少会直接导致启动失败each filter should be of the form keyvalue同一 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: labelcom.example.appadmin用户没有设置filter可以看到所有容器guest用户设置了filter: labelcom.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-claimDOZZLE_AUTH_OIDC_FILTERS_CLAIM用于指定从 token claim 中读取容器过滤器的路径。Agent 级过滤器远程主机可见范围收敛在 Agent 模式下同样通过DOZZLE_FILTER为 Agent 单独设置过滤器详见 docs/guide/agent.mdservices: dozzle-agent: image: amir20/dozzle:latest command: agent environment: - DOZZLE_FILTERlabelcolor 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 labelcolor同时在 Agent 层设置--filter labeltype那么 Dozzle 只会展示同时拥有color与type两个标签的容器。也就是说跨层级的过滤器之间是AND 语义每一层都在上一层的可见集合基础上进一步收窄而不是取并集。而同一层级内同一 key 的多个值如labelcolor,labeltype通过一个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形如key1value1,key2value2下推给 Kubernetes API 的Pods().ListK8s 元数据metadata labels以k8s.前缀开头或命中namespace、owner.kind、owner.name、owner.key这类特殊 key 的过滤器由于无法用 K8s label selector 表达转而在客户端通过matchesContainerLabelsinternal/k8s/client.go对返回结果做精确匹配。可以推断在 K8s 环境下使用namespacexxx这类元数据过滤器时过滤发生在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考