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

Dozzle 容器显示名称完整指南dev.dozzle.name 标签与 Coolify 集成原理【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzle本指南聚焦 DozzleRealtime log viewer for containers如何决定每个容器在界面中显示的名称name与分组group。默认情况下名称直接来自 Docker但在无法修改容器名本身时可以通过dev.dozzle.name标签自定义显示名若你使用 Coolify 部署应用Dozzle 还会自动识别其标签作为备用值。读完本文你将掌握名称解析的完整优先级、Docker CLI 与 Compose 两种打标签方式以及 Swarm 模式、容器重命名等边界场景下的底层行为。默认行为名称直接来自 DockerDozzle 在启动时通过 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.namehello hello-worldDocker Compose 方式services: dozzle: image: hello-world labels: - dev.dozzle.namehello上述两个示例等效容器在 Dozzle 界面中显示为hello而不是镜像名或随机生成的容器 ID 前缀。名称解析优先级源码级验证从 internal/docker/client.go 的newContainer列表场景与 internal/docker/client.go 的newContainerFromJSONinspect 场景可以看到名称解析遵循严格的三级优先级dev.dozzle.name标签—— 只要非空立即采用Coolify 名称coolifyName()函数见下文—— 标签未设置时作为回退Docker 原生名称—— 去掉/前缀后作为最终回退否则显示no name。Coolify 集成自动识别项目标签如果你使用 Coolify 管理应用Dozzle 会自动识别 Coolify 写入容器的标签作为备用值Coolify 部署无需任何额外配置即可获得友好的显示名与分组Coolify 标签用途生效条件coolify.serviceName用作容器显示名称未设置dev.dozzle.name时coolify.projectName用作分组group未设置dev.dozzle.group时分组信息在界面中用于把容器归类显示。除这两条回退规则外还有一个从源码中可以确认的细节Coolify 会给应用及该应用的每个 PR 预览部署打上相同的coolify.serviceName标签若不加区分同一应用的所有 PR 预览在界面中会难以辨认。因此 internal/docker/client.go 中的coolifyName()函数会在coolify.pullRequestId非空且不为0时把名称显示为PR id · serviceName的形式。Coolify 与自定义标签的优先级关系综合前文完整的优先级可以总结为名称dev.dozzle.namecoolify.serviceName含 PR 预览前缀 Docker 原生名称 no name分组dev.dozzle.groupcoolify.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 与 Groupinternal/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模型的namespacegetterassets/models/Container.ts按以下顺序解析容器的命名空间用于归类展示dev.dozzle.groupcoolify.projectNamecom.docker.stack.namespacecom.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.namemy-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考