企业官网建设流程全解析

Dozzle 应用图标指南：镜像识别匹配规则、隐私与dev.dozzle.icon自定义覆盖

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

Dozzle 会自动为常见的容器镜像匹配对应的项目 logo，并显示在侧边栏、容器表格和命令面板中容器名的旁边，让你在管理 *arr 全家桶、Plex、Home Assistant 等一堆容器时一目了然。本文以 docs/zh/guide/app-icons.md 为主线，结合前端源码详细讲解图标的匹配原理、开关位置、覆盖方式与离线隐私保证，读完你可以完全掌控 Dozzle 应用图标的显示行为。

应用图标显示在哪里

Dozzle 会把镜像名解析出的 logo 展示在多个界面位置：

• 侧边栏导航（HostMenu.vue）：主机菜单中每个容器条目左侧；
• 容器表格（ContainerTable.vue）：容器列表的图标列；
• 命令面板 / 模糊搜索（FuzzySearchModal.vue）：搜索容器时显示在结果条目左侧；
• 容器弹窗（ContainerPopup.vue）：导航栏悬停容器时的小卡片。

这些位置统一通过 ContainerIcon.vue 渲染：它接收container.icon解析出的 slug，再调用iconUrl()取到实际的图片 URL。图标左上角还会叠加状态角标——健康容器显示绿色对勾、不健康显示红色告警、暂停显示暂停符，未匹配到任何图标的容器则退化为纯状态图形。当容器未运行时，图标会被降为 40% 透明度并去色（opacity-40 grayscale），运行状态一目了然。

图标随包打包：隐私与离线友好

一个关键设计是：所有图标都与 Dozzle 一起打包，运行时不从任何 CDN 获取。这一点在 assets/utils/appIcons.ts 的注释中有明确说明：如果运行时向第三方请求sonarr.svg，就等于告诉外部服务“这个用户正在运行 Sonarr”，会泄露用户的部署信息；同时也会让隔离网络（air-gapped）环境的安装直接失效。

实现上，图标通过 Vite 的import.meta.glob在构建期被扫描打包：

const bundled = import.meta.glob<string>("../icons/apps/*.{svg,webp}", { eager: true, query: "?url", import: "default", });

每个图标文件被 Vite 输出为独立的哈希资源（见 assets/icons/README.md 关于vite.config.ts中assetsInlineLimit的说明），浏览器只会下载实际渲染到的几张图标，其余不会产生流量。所以容器的任何信息都不会离开你的网络。

关闭该功能

如果你不喜欢图标，可以随时关闭：

• 路径：设置 → 选项 → 显示应用图标（界面文案见 pages/settings.vue）；
• 这是一个按配置文件保存的设置，只对当前浏览器生效，不会同步到服务器或影响其他用户。

源码层面，开关对应 stores/settings.ts 中的showAppIcons字段，默认值为true（见 stores/settings.ts），通过useProfileStorage持久化到浏览器 profile 中。ContainerIcon.vue中src的计算直接受它控制：

const src = computed(() => (showAppIcons.value ? iconUrl(slug, isDark.value) : undefined));

关闭后图标槽位直接渲染为状态图形，不会留下空白占位。

匹配规则：只看镜像名

Dozzle 匹配图标时只看镜像名，忽略仓库地址、标签（tag）和摘要（digest）。以最后一段路径为准，下面这些写法都会匹配到 Sonarr 的图标：

• sonarr
• linuxserver/sonarr:latest
• lscr.io/linuxserver/sonarr
• ghcr.io/hotio/sonarr@sha256:...

这一行为在 appIcons.spec.ts 中有完整的参数化测试覆盖，包括linuxserver/radarr → radarr、lscr.io/linuxserver/prowlarr:latest → prowlarr、ghcr.io/hotio/bazarr → bazarr等。

解析流程源码拆解

核心解析函数iconSlugForImage()位于 assets/utils/appIcons.ts，整个流程可以拆成四步：

1. 去掉摘要与标签：先按@切掉 digest，再判断最后一个/之后的:——只有冒号位于最后一段（即标签位置）才被当作 tag 剥离。这样registry.local:5000/traefik中的端口:5000不会被误判为标签（测试见 appIcons.spec.ts）。
2. 去掉 registry 主机段：如果第一段包含.、:或是localhost，说明它是仓库地址而不是命名空间，会被shift()丢弃。
3. 最近的段优先：对剩余路径取最后两段并反转作为候选（segments.slice(-2).reverse()），先试镜像名本身，再试命名空间。因此linuxserver/sonarr命中的是 Sonarr 而不是 LinuxServer。
4. 规范化后查表：每个候选段统一转小写、把下划线替换成连字符，然后依次尝试ALIASES[name]、name、ALIASES[stripSuffix(name)]、stripSuffix(name)四种写法，在打包的图标集合中命中即返回。

三类过滤与别名机制

为了让匹配更精准，源码维护了三张辅助表：

• 分发者命名空间（DISTRIBUTORS）：library、linuxserver、lscr、hotio、bitnami、binhex、ich777等（appIcons.ts）。这些是打包别人软件的分发者，用它们的 logo 去匹配里面的镜像显然是错的，所以候选命中这些段会被直接跳过——这也是为什么linuxserver/plex一定解析为plex而非 LinuxServer（测试见 appIcons.spec.ts）。
• 泛化组件名（GENERIC）：server、client、app、core、api、backend、worker、db等几十个通用词（appIcons.ts）。它们防止ghcr.io/goauthentik/server这类镜像错误命中名为server的图标，从而触发下面要讲的命名空间回退。
• 部署后缀（SUFFIX）：-server、-client、-app、-core、-ce、-ee、-oss、-alpine、-slim、-nightly等（appIcons.ts），它们只是装饰性后缀，剥离后再查表。例如grafana/grafana-oss → grafana、ghcr.io/mealie-recipes/mealie:v1.2.0 → mealie（测试见 appIcons.spec.ts）。
• 别名映射（ALIASES）：处理镜像名与图标 slug 不一致的情况，共 70 余条（appIcons.ts），例如postgres → postgresql、mongo → mongodb、pihole → pi-hole、homeassistant → home-assistant、plexmediaserver → plex、goauthentik → authentik、immich-server → immich、actual-server → actual-budget等。

命名空间回退

当镜像名过于通用（命中 GENERIC 集合）时，Dozzle 会退回到命名空间来判断。ghcr.io/goauthentik/server就是这样匹配到 Authentik 的：server太泛化被跳过，于是尝试它的上一段goauthentik，再经 ALIASES 映射为authentik。反向的兜底保证在 appIcons.spec.ts 中：ghcr.io/goauthentik/server:2024.6 → authentik，而someunknownvendor/server这种两个候选都不认识的镜像会返回undefined（不显示图标）。

覆盖图标：dev.dozzle.icon标签

有些镜像匹配不上，而 fork 出来的镜像可能匹配到错误的 logo。Dozzle 提供了dev.dozzle.icon标签来手动指定图标；设为none则可以隐藏该容器的图标。

docker run方式：

docker run --label dev.dozzle.icon=plex my-custom-media-server

docker-compose.yml方式：

services: media: image: my-custom-media-server labels: - dev.dozzle.icon=plex scratch: image: alpine labels: - dev.dozzle.icon=none

标签的取值是 homarr-labs/dashboard-icons 仓库中的图标 slug（如plex、sonarr、home-assistant）。只有 Dozzle 打包进来的图标可用，未知名称会退回到不显示图标。

从源码看，标签的优先级实现在 models/Container.ts 的icongetter 中：

get icon() { const override = this.labels["dev.dozzle.icon"]?.trim().toLowerCase(); if (override) return override === "none" || !hasIcon(override) ? undefined : override; return iconSlugForImage(this.image); }

标签值会先被trim()并转小写（所以PLEX、plex都能被接受），none或打包集合中不存在的 slug 直接返回undefined（不显示图标），否则以标签为准，完全覆盖自动解析结果。这意味着你可以在 Compose/Swarm/K8s 的标签体系里统一管理图标，无需改动 Dozzle 配置。

图标渲染与主题适配

图标文件位于 assets/icons/apps/，遵循 dashboard-icons 的命名约定（详见 assets/icons/README.md）：

• 一个文件对应一个图标，以 slug 命名，如sonarr.svg；
• 上游有 SVG 就保留 SVG，否则使用缩放到 64px 的 WebP；
• <slug>-light是给深色背景用的浅色变体，<slug>-dark是给浅色背景用的深色变体，两者都是可选的。

iconUrl()（appIcons.ts）会根据当前主题自动挑选变体：深色主题优先取-light变体，浅色主题优先取-dark，都不存在则回退到基础图标。测试（appIcons.spec.ts）验证了plex在两种主题下返回不同 URL、而traefik没有变体时两种主题返回同一张图。

缺少某个图标？

为了控制镜像体积，Dozzle只收录了精选的一部分图标，而不是 dashboard-icons 全部 3000 多个。目前打包的图标清单可以直接查看 assets/icons/apps/ 目录（包含 docker、nginx、grafana、jellyfin、home-assistant、traefik 等常用服务）。如果你发现某个常见图标缺失，带上镜像名向 Dozzle 提交 issue，维护者会评估补进打包集合。

另外，图标对镜像体积的影响已经被刻意控制：由于每个图标独立作为文件输出，appIcons.ts中维护的只是一张字符串映射表（仅几 KB），浏览器按需加载实际渲染的图标。如果你希望新增某个图标，仓库 assets/icons/README.md 给出了流程：把文件放入apps/目录，若镜像名与 slug 不一致，再在appIcons.ts的ALIASES中补一条映射即可。

小结

Dozzle 的应用图标功能可以用一句话概括：本地打包、按名匹配、标签覆盖。图标完全离线可用，保护隐私；匹配算法经过规范化、过滤、别名、后缀剥离与命名空间回退的多层处理，误匹配率被压得很低；一旦自动匹配不符合预期，dev.dozzle.icon标签提供了简单可靠的兜底方案。这套设计兼顾了易用性、隐私与体积控制，值得在自建容器管理方案中直接采用。

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