Dozzle 主机名（Hostname）配置指南：通过 --hostname 与 DOZZLE_HOSTNAME 定制多主机界面标识

Dozzle 主机名（Hostname）配置指南：通过 --hostname 与 DOZZLE_HOSTNAME 定制多主机界面标识

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

Dozzle 默认将本机 Docker 连接命名为localhost，这一标识会同时出现在浏览器页面标题、侧边栏 Dozzle Logo 下方以及多主机（Multi-Host）菜单中。本文以 Dozzle 官方文档 docs/de/guide/hostname.md 为主体，结合仓库内 CLI 参数解析、前端标题渲染与多主机/Agent 的实现细节，完整讲解如何通过--hostname标志或DOZZLE_HOSTNAME环境变量修改 Dozzle 的显示名称，并阐明它在 Multi-Host、远程 Agent 与 Swarm 模式下的行为边界与最佳实践。读完本文，你将能独立完成单实例重命名、Agent 命名以及 Swarm 多节点区分等典型配置。

为什么需要自定义 Dozzle 的 Hostname

Dozzle 是一个面向容器的实时日志查看器，支持 Docker、Docker Swarm 与 Kubernetes。默认情况下，Dozzle 指向本机 Docker 守护进程，并将这条连接称为localhost。当你在同一台服务器上管理多个 Dozzle 实例，或在多主机环境中同时接入多台机器时，仅靠 "localhost" 无法区分不同来源，因此 Dozzle 提供了--hostname这个显示名称配置项。

该值并非修改系统主机名，而仅仅是 Dozzle 用于界面展示的名称。配置后它会在以下三个位置生效：

• 浏览器标签页/页面标题（Page Title）：标题以Dozzle @ <hostname>的形式呈现；
• 侧边栏 Dozzle Logo 下方的副标题（Subheader）：以等宽小字显示在 Logo 之下；
• 多主机菜单（Multi-Host Menu）中的连接名称：原本显示为localhost的连接条目会改用新名称。

快速上手：用 --hostname 修改显示名称

文档给出了两种等价方式：CLI 标志与 Docker Compose 环境变量。二者的效果完全相同，可按部署习惯任选其一。

方式一：docker run 命令行标志

docker run --volume=/var/run/docker.sock:/var/run/docker.sock -p 8080:8080 amir20/dozzle --hostname mywebsite.xyz

• --volume=/var/run/docker.sock:/var/run/docker.sock：挂载 Docker Socket，让 Dozzle 访问本机容器；
• -p 8080:8080：暴露 Web 端口；
• --hostname mywebsite.xyz：将 Dozzle 的显示名称设置为mywebsite.xyz。

方式二：docker-compose.yml 环境变量

services: dozzle: image: amir20/dozzle:latest volumes: - /var/run/docker.sock:/var/run/docker.sock ports: - 8080:8080 environment: DOZZLE_HOSTNAME: mywebsite.xyz

两种写法最终都会在启动参数解析阶段被统一读取。从源码看，internal/support/cli/args.go 中的Args结构体通过 go-arg 库声明了Hostname string \arg:"env:DOZZLE_HOSTNAME" help:"sets the hostname for display. This is useful with multiple Dozzle instances."`，即--hostname标志与DOZZLE_HOSTNAME` 环境变量指向同一个字段，二者互斥时环境变量与标志遵循 go-arg 的解析优先级。该参数的官方帮助文本也直接点明了它的使用场景：多 Dozzle 实例并存时用于区分显示。

默认值与相关参数速查

在 docs/guide/supported-env-vars.md 的全局环境变量表中，与显示名称相关的条目如下：

注意：--hostname只影响显示名称；而--host-id影响的是主机身份的推导与去重逻辑，二者职责不同，不要混淆。

配置生效的完整链路

为了确认该配置确实作用于界面，可以沿前端渲染链路逐层验证。

服务端下发配置

在 internal/web/index.go 中，服务端把配置项写入config["hostname"] = h.config.Hostname，随后随页面初始化数据一并下发到浏览器，前端 store 在 assets/stores/config.ts 中声明hostname: string字段承接该值。

页面标题的拼接逻辑

assets/composable/app/title.ts 定义了浏览器标题的生成规则：

const { hostname } = config; let subtitle = $ref(""); const title = $computed(() => (subtitle ? `${subtitle} - ` : "") + "Dozzle" + (hostname ? ` @ ${hostname}` : "")); useTitle($$(title));

可见标题的组成是：可选副标题（如当前容器/主机上下文）+ 固定 "Dozzle" + 可选的@ <hostname>后缀。当hostname为空时不追加后缀；配置为mywebsite.xyz后，浏览器标签页即显示Dozzle @ mywebsite.xyz。

侧边栏 Logo 下的副标题

assets/components/shell/SidePanel.vue 在侧边栏的 Dozzle 品牌区下方渲染：

<small class="text-base-content/45 mt-1.5 block truncate font-mono text-xs" v-if="hostname" :title="hostname"> {{ hostname }} </small>

v-if="hostname"保证未配置时不显示该行；配置后则以等宽字体、小字号展示完整名称，truncate处理超长名称的截断，:title提供悬浮完整提示。

多主机菜单中的连接标签

侧边栏导航中的主机条目读取的是主机对象自身的名称：assets/components/nav/HostNavItem.vue 中NavItem的:label与:title都绑定为host.name。对于本机连接，host.name即来自DOZZLE_HOSTNAME配置；对于远程连接，则来自 Agent 上报的名称。此外，在日志视图中还有一处可选的 Hostname 展示开关：多容器/多主机日志工具栏中的"显示主机名"选项（见 assets/components/logs/MultiContainerActionToolbar.vue 与 assets/components/logs/entries/LogItem.vue），它控制每条日志前是否渲染来源主机的彩色标签，与本文的主机命名配置相互配合。

Multi-Host 与 Agent 模式下的命名行为

这是本文档的核心边界说明：--hostname只重命名正在运行该 Dozzle 进程的那台主机，不会影响其他主机条目的显示。

远程 Agent 的独立命名

在多主机架构中，Dozzle 支持以 Agent 模式暴露远程 Docker 主机：在远程机器上以agent子命令启动 Dozzle，本地主 Dozzle 实例即可通过 TLS 安全连接将其纳入多主机视图（详见 docs/guide/agent.md）。每个远程 Agent 都会广播自己的名称，而不是沿用主实例的--hostname。因此：

• 在每个 Agent上分别设置DOZZLE_HOSTNAME（或--hostname），即可控制该 Agent 在多主机菜单中的显示名称；
• 主 Dozzle 实例的--hostname仅代表其自身（本地连接），不能替远程 Agent 改名。

Swarm 模式下的逐节点命名

在 Docker Swarm 模式下，每个 Swarm 节点都会运行自己的 Agent 进程（见 docs/guide/swarm-mode.md）。为了让多主机菜单中的各节点清晰可辨，应当为每个节点赋予互不相同的 hostname，例如按节点角色或机器名命名，否则多个节点都会显示为相同的默认名称，难以定位日志来源。

推荐配置模式

综合上述规则，一个典型的多主机部署应遵循以下命名策略：

常见问题与注意事项

• 不修改操作系统主机名：--hostname/DOZZLE_HOSTNAME是纯 UI 层显示名称，与hostname(1)、容器内/etc/hostname无关，也不影响 Docker 守护进程的识别。
• 空字符串即默认：参数默认值为""，不设置时 Dozzle 按默认逻辑以 localhost 命名本机连接。
• 区分--hostname与--host-id：前者是给人看的显示名称，后者是用于主机身份去重的内部 ID（internal/support/cli/args.go 中声明为 "overrides the id Dozzle derives for this host. Only needed when the derived id collides with another host."），仅在推导出的 ID 与另一主机冲突时才需要覆盖。
• Agent 与 Socket 代理不可叠加：官方文档明确提示，使用远程 Agent 时不能再在 Agent 之上叠加 Docker Socket 代理，Agent 本身就是代理的替代方案，此限制与命名配置一并纳入多主机部署规划（docs/guide/agent.md）。

小结

自定义 hostname 是 Dozzle 多实例、多主机运维中最基础也最实用的配置之一。通过--hostname mywebsite.xyz（或等价地DOZZLE_HOSTNAME），你可以让页面标题、侧边栏副标题与多主机菜单中的连接名称保持一致且易于辨识；在多主机与 Swarm 场景下，切记该配置只作用于当前进程所在主机，远程 Agent 需要逐台独立命名，Swarm 各节点则应使用彼此不同的名称。这套命名规范将显著提升多节点日志定位与日常排障的效率。

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