尧图网页设计 
Dozzle 容器过滤--filter / DOZZLE_FILTER实战指南UI、Agent 与用户三级过滤机制详解【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzleDozzle 是面向 Docker、Swarm 与 K8s 的实时容器日志查看器而容器过滤Filter是控制其可见范围的核心安全与运维手段。本文以官方《Filtering Containers》文档中文参考原始文档、英文原版为主线系统讲解--filter/DOZZLE_FILTER的语法、UI / Agent / 用户三个层级的过滤器定义方式、组合生效规则并结合仓库源码揭示过滤器从命令行参数到 Docker / K8s 底层查询的完整链路。读完本文你将能独立为 Dozzle 配置按标签、名称等条件的容器可见性隔离并理解多过滤器叠加时的与AND语义。什么是容器过滤与 Docker 原生过滤器同源Dozzle 支持类似 Dockerdocker ps --filter的条件过滤能力通过DOZZLE_FILTER环境变量或--filter命令行参数启用。过滤条件会被原样直接传递给 Docker从而在源头限制 Dozzle 能够看到的容器集合。最常见的过滤目标是name与label。例如要限制 Dozzle 只能访问带有color标签的容器命令写法与docker ps --filter labelcolor如出一辙docker run --volume/var/run/docker.sock:/var/run/docker.sock -p 8080:8080 amir20/dozzle --filter labelcolor使用 docker-compose 时则通过环境变量注入services: dozzle: image: amir20/dozzle:latest volumes: - /var/run/docker.sock:/var/run/docker.sock ports: - 8080:8080 environment: DOZZLE_FILTER: labelcolor参数定义与解析从 CLI 到过滤映射从源码看--filter参数的定义位于 internal/support/cli/args.goFilterStrings []string arg:env:DOZZLE_FILTER,--filter,separate help:filters docker containers using Docker syntax. Filter map[string][]string arg:-可见--filter与DOZZLE_FILTER是同一配置项的两种注入方式支持重复声明、以separate分隔多个值最终被解析为map[string][]string形式。解析逻辑args.go#L77-L87要求每个过滤条件必须形如keyvalue且允许同一 key 多次出现追加为多个值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) }而在认证等场景下过滤器字符串还会经由 internal/container/types.go#L282-L299 的ParseContainerFilter做逗号分隔解析——它要求每个片段都必须包含否则返回错误。这与 OIDC claim、Forward Proxy 请求头中携带过滤器字符串的解析方式一致。过滤器的三个层级UI、Agent 与用户Dozzle 支持在三个不同层级设置过滤器用于限制可见容器UI 过滤器Interface / UI Filters作用于 Dozzle UI 实例本身被发送给 Docker 以缩小可见容器范围。它会影响所有 Agent 以及未设置自身过滤器的用户。Agent 过滤器Agent Filters在 Agent 层级设置被发送给 Docker 来限制该 Agent 对外暴露的容器。Agent 过滤器与 UI 过滤器会组合叠加共同收窄容器范围。用户过滤器User Filters在用户层级设置决定单个用户能看到哪些容器。若某用户未定义过滤器Dozzle 默认回退使用 UI 过滤器。[!WARNING] 必须清楚一点多个过滤器是组合AND生效的而不是任选其一。例如在 UI 层级设置--filter labelcolor、在 Agent 层级设置--filter labeltype那么 Dozzle 只会显示同时带有color与type两个标签的容器。UI 过滤器全局可见范围的基准线UI 过滤器即上一节中--filter/DOZZLE_FILTER声明的过滤器它作用于 Dozzle 主实例。设置后过滤器被送入 Docker 客户端转化为 Docker API 的原生过滤参数。核心实现在 internal/docker/client.go#L338-L348func (d *DockerClient) ListContainers(ctx context.Context, labels container.ContainerLabels) ([]container.Container, error) { filterArgs : make(client.Filters) for key, values : range labels { filterArgs.Add(key, values...) } containerListOptions : client.ContainerListOptions{ Filters: filterArgs, All: true, } list, err : d.cli.ContainerList(ctx, containerListOptions) ... }可以看到ContainerLabels即map[string][]string被逐一塞入 Docker SDK 的client.Filters随后调用ContainerList完成服务端过滤。这意味着过滤不是在前端界面隐藏容器而是真正发生在 Docker 守护进程端列表、日志、统计等所有后续环节都只能接触到过滤后的容器。UI 过滤器是所有 Agent 和没有个人过滤器的用户所看到的默认范围设置层级参考 docs/guide/filters.md。完整的配置项对应关系可参见 docs/guide/supported-env-vars.md 中--filter⇄DOZZLE_FILTER的对照表。Agent 过滤器限制单个 Agent 暴露的容器在 Docker Swarm / 远程主机等场景下Dozzle Agent 可以单独配置DOZZLE_FILTER用来限定该 Agent 所在节点上向主实例暴露哪些容器参见 docs/guide/agent.md#setting-up-filtersservices: 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 进程在启动时同样通过docker_support.NewDockerClientService(client, args.Filter)携带过滤器见 internal/support/cli/agent_command.go#L161并通过 gRPC 接口向主实例下发internal/agent/server.go#L228-L249 中从请求GetFilter()读取过滤映射。用户过滤器基于认证体系的按用户隔离当启用认证后Dozzle 支持在users.yml中为每个用户单独设置过滤器从而实现多租户式的容器访问隔离详见 docs/guide/authentication/simple.md#setting-specific-filters-for-usersusers: admin: email: name: Admin password: $2a$11$9ho4vY2LdJ/WBopFcsAS0uORC0x2vuFHQgT/yBqZyzclhHsoaIkzK filter: guest: email: name: Guest password: $2a$11$9ho4vY2LdJ/WBopFcsAS0uORC0x2vuFHQgT/yBqZyzclhHsoaIkzK filter: labelcom.example.app在这个例子中admin用户未设置过滤器可以查看全部容器guest用户则只能看到带有com.example.app标签的容器。用户过滤器与全局过滤器的优先级关系为若用户设置了过滤器则覆盖override全局过滤器否则回退到全局过滤器。从源码看users.yml中每个用户都有一个Filter字段internal/auth/users.go#L29加载时通过container.ParseContainerFilter(user.Filter)解析为标签映射internal/auth/users.go#L171-L173——如果某个用户的过滤器无法解析整份用户配置会被判定非法并拒绝加载而不是静默放行这一点在 internal/auth/simple_test.go#L194-L202 的TestReadUsersRejectsInvalidFilter中有明确验证。其他认证方式中的用户级过滤器除users.yml外用户过滤器还可以通过其他认证途径注入Forward Proxy 认证Dozzle 从 HTTP 头默认Remote-Filter可用--auth-header-filter/DOZZLE_AUTH_HEADER_FILTER调整见 internal/support/cli/args.go#L29读取过滤器字符串并解析internal/auth/proxy.go#L53-L63。若头中的过滤器非法认证会失败而不是放行全部容器internal/auth/proxy_test.go#L12-L29。OIDC 认证过滤器从 IdP 下发的 token claim 中读取默认依次查找dozzle_filters、resource_access.client-id.filters、filters三个路径也可用--auth-oidc-filters-claim指定自定义的 dot-separated claim 路径internal/support/cli/args.go#L39、internal/auth/oidc.go#L137-L154。非法的过滤器 claim 会直接拒绝登录internal/auth/oidc_test.go#L244-L250。过滤器在 Docker 与 K8s 下的不同落地方式文档头部同时标注了 Docker 与 K8s 两个徽章说明过滤能力在两种编排环境下都可用但其底层实现路径并不相同Docker / Swarm如上文所述ContainerLabels被直接转换为 Docker SDK 的Filters参数交给守护进程做服务端过滤。KubernetesDozzle 的 K8s 客户端会先把过滤器拆分为Pod 标签选择器与元数据过滤器两部分internal/k8s/client.go#L404-L425以k8s.前缀开头或属于namespace、owner.kind、owner.name、owner.key的 key 以及不合法的 K8s 标签 key 归入元数据类其余作为 Pod 标签随后用 Pod 标签构造 label selector 查询再以matchesContainerLabelsinternal/k8s/client.go#L442-L454对元数据类条件做逐项精确匹配只有全部命中的容器才会进入结果集。无论哪种后端多条件同时满足才可见的组合语义是贯穿一致的。过滤器的组合规则与安全提示同一层级的多个过滤条件取交集Dozzle 内部将所有条件汇总为map[key][]value最终每个 key 都要命中、且命中值需等于任一给定 value容器才会被列出。跨层级的过滤器叠加UI 过滤器 × Agent 过滤器 × 用户过滤器若存在层层取交集。因此即使某个 Agent 或用户自身没有配置也会受上一层过滤器的约束。过滤器在服务端执行由于过滤发生在 Docker / K8s 查询阶段internal/docker/client.go、internal/k8s/client.go被过滤掉的容器在日志流、统计指标、容器列表等所有接口中都不可见属于有效的访问隔离手段。非法过滤器宁可拒绝也不放行无论是users.yml、OIDC claim 还是代理头中的过滤器解析失败都会导致加载/登录失败避免解析失败却看到全部容器的安全漏洞见 internal/auth/users.go#L171、internal/auth/proxy.go#L53-L63。小结Dozzle 的容器过滤能力以 Docker 原生过滤器语法为基础通过--filter/DOZZLE_FILTER提供 UI 层全局基线通过 Agent 环境变量提供节点级约束再通过users.yml、OIDC claim 或 Forward Proxy 头提供用户级隔离三者叠加取交集最终由 Docker / K8s 服务端执行。这一设计让 Dozzle 既能作为共享的日志平台按用户划分可见性也能在 Swarm、K8s 等复杂环境下精准收窄每个数据源的暴露面。需要更深入的实践可继续阅读 Agent 过滤器配置、用户过滤器配置 以及 支持的配置项总表。【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dozzle 容器过滤（--filter / DOZZLE_FILTER）实战指南：UI、Agent 与用户三级过滤机制详解
Dozzle 容器过滤--filter / DOZZLE_FILTER实战指南UI、Agent 与用户三级过滤机制详解【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzleDozzle 是面向 Docker、Swarm 与 K8s 的实时容器日志查看器而容器过滤Filter是控制其可见范围的核心安全与运维手段。本文以官方《Filtering Containers》文档中文参考原始文档、英文原版为主线系统讲解--filter/DOZZLE_FILTER的语法、UI / Agent / 用户三个层级的过滤器定义方式、组合生效规则并结合仓库源码揭示过滤器从命令行参数到 Docker / K8s 底层查询的完整链路。读完本文你将能独立为 Dozzle 配置按标签、名称等条件的容器可见性隔离并理解多过滤器叠加时的与AND语义。什么是容器过滤与 Docker 原生过滤器同源Dozzle 支持类似 Dockerdocker ps --filter的条件过滤能力通过DOZZLE_FILTER环境变量或--filter命令行参数启用。过滤条件会被原样直接传递给 Docker从而在源头限制 Dozzle 能够看到的容器集合。最常见的过滤目标是name与label。例如要限制 Dozzle 只能访问带有color标签的容器命令写法与docker ps --filter labelcolor如出一辙docker run --volume/var/run/docker.sock:/var/run/docker.sock -p 8080:8080 amir20/dozzle --filter labelcolor使用 docker-compose 时则通过环境变量注入services: dozzle: image: amir20/dozzle:latest volumes: - /var/run/docker.sock:/var/run/docker.sock ports: - 8080:8080 environment: DOZZLE_FILTER: labelcolor参数定义与解析从 CLI 到过滤映射从源码看--filter参数的定义位于 internal/support/cli/args.goFilterStrings []string arg:env:DOZZLE_FILTER,--filter,separate help:filters docker containers using Docker syntax. Filter map[string][]string arg:-可见--filter与DOZZLE_FILTER是同一配置项的两种注入方式支持重复声明、以separate分隔多个值最终被解析为map[string][]string形式。解析逻辑args.go#L77-L87要求每个过滤条件必须形如keyvalue且允许同一 key 多次出现追加为多个值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) }而在认证等场景下过滤器字符串还会经由 internal/container/types.go#L282-L299 的ParseContainerFilter做逗号分隔解析——它要求每个片段都必须包含否则返回错误。这与 OIDC claim、Forward Proxy 请求头中携带过滤器字符串的解析方式一致。过滤器的三个层级UI、Agent 与用户Dozzle 支持在三个不同层级设置过滤器用于限制可见容器UI 过滤器Interface / UI Filters作用于 Dozzle UI 实例本身被发送给 Docker 以缩小可见容器范围。它会影响所有 Agent 以及未设置自身过滤器的用户。Agent 过滤器Agent Filters在 Agent 层级设置被发送给 Docker 来限制该 Agent 对外暴露的容器。Agent 过滤器与 UI 过滤器会组合叠加共同收窄容器范围。用户过滤器User Filters在用户层级设置决定单个用户能看到哪些容器。若某用户未定义过滤器Dozzle 默认回退使用 UI 过滤器。[!WARNING] 必须清楚一点多个过滤器是组合AND生效的而不是任选其一。例如在 UI 层级设置--filter labelcolor、在 Agent 层级设置--filter labeltype那么 Dozzle 只会显示同时带有color与type两个标签的容器。UI 过滤器全局可见范围的基准线UI 过滤器即上一节中--filter/DOZZLE_FILTER声明的过滤器它作用于 Dozzle 主实例。设置后过滤器被送入 Docker 客户端转化为 Docker API 的原生过滤参数。核心实现在 internal/docker/client.go#L338-L348func (d *DockerClient) ListContainers(ctx context.Context, labels container.ContainerLabels) ([]container.Container, error) { filterArgs : make(client.Filters) for key, values : range labels { filterArgs.Add(key, values...) } containerListOptions : client.ContainerListOptions{ Filters: filterArgs, All: true, } list, err : d.cli.ContainerList(ctx, containerListOptions) ... }可以看到ContainerLabels即map[string][]string被逐一塞入 Docker SDK 的client.Filters随后调用ContainerList完成服务端过滤。这意味着过滤不是在前端界面隐藏容器而是真正发生在 Docker 守护进程端列表、日志、统计等所有后续环节都只能接触到过滤后的容器。UI 过滤器是所有 Agent 和没有个人过滤器的用户所看到的默认范围设置层级参考 docs/guide/filters.md。完整的配置项对应关系可参见 docs/guide/supported-env-vars.md 中--filter⇄DOZZLE_FILTER的对照表。Agent 过滤器限制单个 Agent 暴露的容器在 Docker Swarm / 远程主机等场景下Dozzle Agent 可以单独配置DOZZLE_FILTER用来限定该 Agent 所在节点上向主实例暴露哪些容器参见 docs/guide/agent.md#setting-up-filtersservices: 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 进程在启动时同样通过docker_support.NewDockerClientService(client, args.Filter)携带过滤器见 internal/support/cli/agent_command.go#L161并通过 gRPC 接口向主实例下发internal/agent/server.go#L228-L249 中从请求GetFilter()读取过滤映射。用户过滤器基于认证体系的按用户隔离当启用认证后Dozzle 支持在users.yml中为每个用户单独设置过滤器从而实现多租户式的容器访问隔离详见 docs/guide/authentication/simple.md#setting-specific-filters-for-usersusers: admin: email: name: Admin password: $2a$11$9ho4vY2LdJ/WBopFcsAS0uORC0x2vuFHQgT/yBqZyzclhHsoaIkzK filter: guest: email: name: Guest password: $2a$11$9ho4vY2LdJ/WBopFcsAS0uORC0x2vuFHQgT/yBqZyzclhHsoaIkzK filter: labelcom.example.app在这个例子中admin用户未设置过滤器可以查看全部容器guest用户则只能看到带有com.example.app标签的容器。用户过滤器与全局过滤器的优先级关系为若用户设置了过滤器则覆盖override全局过滤器否则回退到全局过滤器。从源码看users.yml中每个用户都有一个Filter字段internal/auth/users.go#L29加载时通过container.ParseContainerFilter(user.Filter)解析为标签映射internal/auth/users.go#L171-L173——如果某个用户的过滤器无法解析整份用户配置会被判定非法并拒绝加载而不是静默放行这一点在 internal/auth/simple_test.go#L194-L202 的TestReadUsersRejectsInvalidFilter中有明确验证。其他认证方式中的用户级过滤器除users.yml外用户过滤器还可以通过其他认证途径注入Forward Proxy 认证Dozzle 从 HTTP 头默认Remote-Filter可用--auth-header-filter/DOZZLE_AUTH_HEADER_FILTER调整见 internal/support/cli/args.go#L29读取过滤器字符串并解析internal/auth/proxy.go#L53-L63。若头中的过滤器非法认证会失败而不是放行全部容器internal/auth/proxy_test.go#L12-L29。OIDC 认证过滤器从 IdP 下发的 token claim 中读取默认依次查找dozzle_filters、resource_access.client-id.filters、filters三个路径也可用--auth-oidc-filters-claim指定自定义的 dot-separated claim 路径internal/support/cli/args.go#L39、internal/auth/oidc.go#L137-L154。非法的过滤器 claim 会直接拒绝登录internal/auth/oidc_test.go#L244-L250。过滤器在 Docker 与 K8s 下的不同落地方式文档头部同时标注了 Docker 与 K8s 两个徽章说明过滤能力在两种编排环境下都可用但其底层实现路径并不相同Docker / Swarm如上文所述ContainerLabels被直接转换为 Docker SDK 的Filters参数交给守护进程做服务端过滤。KubernetesDozzle 的 K8s 客户端会先把过滤器拆分为Pod 标签选择器与元数据过滤器两部分internal/k8s/client.go#L404-L425以k8s.前缀开头或属于namespace、owner.kind、owner.name、owner.key的 key 以及不合法的 K8s 标签 key 归入元数据类其余作为 Pod 标签随后用 Pod 标签构造 label selector 查询再以matchesContainerLabelsinternal/k8s/client.go#L442-L454对元数据类条件做逐项精确匹配只有全部命中的容器才会进入结果集。无论哪种后端多条件同时满足才可见的组合语义是贯穿一致的。过滤器的组合规则与安全提示同一层级的多个过滤条件取交集Dozzle 内部将所有条件汇总为map[key][]value最终每个 key 都要命中、且命中值需等于任一给定 value容器才会被列出。跨层级的过滤器叠加UI 过滤器 × Agent 过滤器 × 用户过滤器若存在层层取交集。因此即使某个 Agent 或用户自身没有配置也会受上一层过滤器的约束。过滤器在服务端执行由于过滤发生在 Docker / K8s 查询阶段internal/docker/client.go、internal/k8s/client.go被过滤掉的容器在日志流、统计指标、容器列表等所有接口中都不可见属于有效的访问隔离手段。非法过滤器宁可拒绝也不放行无论是users.yml、OIDC claim 还是代理头中的过滤器解析失败都会导致加载/登录失败避免解析失败却看到全部容器的安全漏洞见 internal/auth/users.go#L171、internal/auth/proxy.go#L53-L63。小结Dozzle 的容器过滤能力以 Docker 原生过滤器语法为基础通过--filter/DOZZLE_FILTER提供 UI 层全局基线通过 Agent 环境变量提供节点级约束再通过users.yml、OIDC claim 或 Forward Proxy 头提供用户级隔离三者叠加取交集最终由 Docker / K8s 服务端执行。这一设计让 Dozzle 既能作为共享的日志平台按用户划分可见性也能在 Swarm、K8s 等复杂环境下精准收窄每个数据源的暴露面。需要更深入的实践可继续阅读 Agent 过滤器配置、用户过滤器配置 以及 支持的配置项总表。【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考