企业官网建设流程全解析

Dozzle 容器显示名称完整指南：dev.dozzle.name 标签与 Coolify 集成原理

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

本指南聚焦 Dozzle（Realtime log viewer for containers）如何决定每个容器在界面中显示的名称（name）与分组（group）。默认情况下名称直接来自 Docker，但在无法修改容器名本身时，可以通过dev.dozzle.name标签自定义显示名；若你使用 Coolify 部署应用，Dozzle 还会自动识别其标签作为备用值。读完本文，你将掌握名称解析的完整优先级、Docker CLI 与 Compose 两种打标签方式，以及 Swarm 模式、容器重命名等边界场景下的底层行为。

默认行为：名称直接来自 Docker

Dozzle 在启动时通过 Docker API 列出并 inspect 容器，把容器名称原样用作界面上的显示名。这一默认行为通常已足够，因为 Docker 生态本身提供了两层自定义手段：

• docker run --name <name>命令行参数；
• Docker Compose 服务定义中的container_name字段。

这两种方式修改的是容器本身的名称，Dozzle 不做任何额外处理。对应的底层实现在 internal/docker/client.go：当容器既没有dev.dozzle.name标签、也没有 Coolify 标签时，newContainer函数会从 Docker 返回的名称列表中取第一个，并去掉开头的/前缀后作为显示名；没有任何名称时回退为"no name"。

自定义名称：dev.dozzle.name 标签

当无法修改容器名称本身时（例如容器由外部编排系统创建、名称由服务名自动生成），可以通过给容器添加dev.dozzle.name标签来覆盖显示名称。这个标签只影响 Dozzle 界面中的展示，不会改动 Docker 里的真实容器名。

Docker CLI 方式

docker run --label dev.dozzle.name=hello hello-world

Docker Compose 方式

services: dozzle: image: hello-world labels: - dev.dozzle.name=hello

上述两个示例等效：容器在 Dozzle 界面中显示为hello，而不是镜像名或随机生成的容器 ID 前缀。

名称解析优先级（源码级验证）

从 internal/docker/client.go 的newContainer（列表场景）与 internal/docker/client.go 的newContainerFromJSON（inspect 场景）可以看到，名称解析遵循严格的三级优先级：

1. dev.dozzle.name标签—— 只要非空，立即采用；
2. Coolify 名称（coolifyName()函数，见下文）—— 标签未设置时作为回退；
3. Docker 原生名称—— 去掉/前缀后作为最终回退，否则显示"no name"。

Coolify 集成：自动识别项目标签

如果你使用 Coolify 管理应用，Dozzle 会自动识别 Coolify 写入容器的标签作为备用值，Coolify 部署无需任何额外配置即可获得友好的显示名与分组：

分组信息在界面中用于把容器归类显示。除这两条回退规则外，还有一个从源码中可以确认的细节：Coolify 会给应用及该应用的每个 PR 预览部署打上相同的coolify.serviceName标签，若不加区分，同一应用的所有 PR 预览在界面中会难以辨认。因此 internal/docker/client.go 中的coolifyName()函数会在coolify.pullRequestId非空且不为"0"时，把名称显示为PR <id> · <serviceName>的形式。

Coolify 与自定义标签的优先级关系

综合前文，完整的优先级可以总结为：

• 名称：dev.dozzle.name>coolify.serviceName（含 PR 预览前缀）> Docker 原生名称 >"no name"；
• 分组：dev.dozzle.group>coolify.projectName> 空（不分组）。

同样的优先级也体现在 internal/docker/service_labels.go 的mergeServiceLabels中，确保无论是列表加载还是后续事件更新，名称与分组都始终按这一顺序解析。

进阶场景一：Swarm 模式下的标签合并

在 Docker Swarm 集群中，Compose 文件的deploy.labels是写在service上的，而不会出现在 task 容器上——直接 inspect task 永远看不到这些标签。这意味着如果把dev.dozzle.name、dev.dozzle.url等标签写在deploy.labels里，默认情况下会被静默忽略（traefik 等工具的 swarm provider 正是靠读取 service 标签工作的，所以用户很容易这样写）。

为解决这个问题，Dozzle 实现了 service 标签合并机制（internal/docker/service_labels.go）：

• 只有manager 节点会列出 services 并读取其标签（列出 service 是 manager-only 操作，worker 节点会跳过）；
• 通过com.docker.swarm.service.id标签把 task 容器与对应 service 关联起来；
• 将 service 标签合并进容器标签，容器自身的标签优先级更高（合并时后写入覆盖先写入）；
• 合并后重新执行名称与分组的推导，使用与常规场景完全相同的优先级。

相关行为均有测试覆盖：例如 internal/docker/service_labels_test.go 验证了 service 上的dev.dozzle.name/dev.dozzle.group标签能正确更新容器的 Name 与 Group；internal/docker/service_labels_test.go 验证了容器自身标签在冲突时胜出。

此外，service 标签列表带有 30 秒的 TTL 缓存（serviceLabelTTL，见 internal/docker/service_labels.go）：因为docker service update之外标签几乎不变，缓存可以把"每个容器一次 API 调用"降为"每次刷新一次"。若刷新失败则继续保留旧缓存，避免 UI 上标签因一次瞬时错误而消失。

进阶场景二：容器重命名时保留自定义名称

Docker 支持docker rename修改容器名。此时需要区分：如果容器的显示名来自dev.dozzle.name或coolify.serviceName标签，那么重命名 Docker 容器不应覆盖这个自定义显示名；反之，如果显示名本就来自 Docker，则应跟随重命名更新。

这一逻辑在 internal/container/container_store.go 的rename事件处理中实现：当容器带有上述任一标签时，直接忽略 rename 事件；否则把显示名更新为ActorAttributes["name"]中携带的新名称。这是"自定义名称只覆盖展示、不改变容器本身"原则在事件流层面的延续。

前端视角：分组（group）与相关标签

名称与分组在 Dozzle 前端模型中同样被消费。前端Container模型的namespacegetter（assets/models/Container.ts）按以下顺序解析容器的命名空间用于归类展示：

1. dev.dozzle.group
2. coolify.projectName
3. com.docker.stack.namespace
4. com.docker.compose.project

可见dev.dozzle.group标签的优先级同样高于 Coolify 标签，这与后端newContainer中的分组解析顺序完全一致。另外，同类命名空间的标签还包括dev.dozzle.icon（覆盖按镜像推断的应用图标，设置none可退出图标猜测，见 assets/models/Container.ts）与dev.dozzle.url（为该容器声明一个可点击的 Web UI 链接，仅接受 http/https 绝对地址，见 assets/models/Container.ts）。这些标签共同构成了 Dozzle 通过 Docker 标签定制容器展示信息的完整生态。

快速验证

在 Docker 主机上执行以下命令后刷新 Dozzle 界面，即可验证自定义名称是否生效：

docker run -d --name real-name --label dev.dozzle.name=my-custom-name nginx:alpine

• 容器列表应显示my-custom-name，而非real-name；
• 移除标签（或在无标签的容器上）则显示 Docker 原生名称；
• 使用 Coolify 部署的应用无需任何标签即可显示coolify.serviceName，同一应用的 PR 预览显示为PR <id> · <name>，并按coolify.projectName分组。

更多相关说明可参考仓库中的英文原版文档 container-names.md，以及 Swarm 标签合并实现 internal/docker/service_labels.go 与对应测试 internal/docker/service_labels_test.go。

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