Dozzle 项目部署
一、功能概览
| 类别 | 说明 |
|---|---|
| 实时日志流 | 浏览器中实时滚动查看容器日志 |
| 搜索与过滤 | 支持关键词与正则表达式搜索,按日志级别(ERROR、WARN、INFO、DEBUG)着色与过滤 |
| 多容器视图 | 分屏同时查看多个容器日志,Compose 项目自动按栈分组 |
| 资源统计 | 实时显示容器的 CPU 与内存占用 |
| 多用户认证 | 支持文件式简单认证,也支持与 Authelia 等转发代理认证配合 |
| 多主机监控 | 通过 Agent 模式汇总多台 Docker 主机的日志 |
| 多平台 | 支持 Docker、Docker Swarm、Podman,也可用于 Kubernetes |
| 轻量 | 镜像体积很小,运行内存占用低,且不占用日志存储空间 |
| 界面 | 内置深色模式,响应式设计,手机也能查看 |
二、工作原理与安全前提
Dozzle 通过读取宿主机的 Docker 套接字(/var/run/docker.sock)获取容器列表和日志流,所以部署时需要把这个套接字挂载给它。
务必理解这一点的安全含义:
- Docker 套接字本质上等同于宿主机的高权限入口,能访问它的程序,理论上可以操控所有容器。
- 因此 Dozzle 的访问入口必须受到保护,不要在没有认证的情况下把它暴露到公网。
- 套接字建议以只读方式挂载,并优先考虑第四章里的套接字代理方案。
默认情况下 Dozzle 只读取日志,不修改容器。较新的版本提供了可选的容器操作功能(启动、停止、重启等),这些功能需要显式通过环境变量打开,不开启就是纯只读,建议保持关闭。
三、环境要求
- 一台已安装 Docker Engine 的 Linux 主机(也可在 macOS、Windows 的 Docker 环境中使用)
- 能访问宿主机 Docker 套接字
- 内存:几十 MB 即可,几乎不构成负担
- 默认端口:8080(网页),Agent 模式使用 7007
四、Docker Compose 部署
4.1 创建目录
mkdir -p ~/dozzle/data && cd ~/dozzle
4.2 基础版(局域网内快速使用)
services:
dozzle:
image: amir20/dozzle:latest
container_name: dozzle
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
DOZZLE_NO_ANALYTICS: "true"
启动并访问:
docker compose up -d
docker compose logs -f dozzle
浏览器访问「服务器IP地址:8080」即可看到所有容器。
说明:
:ro表示以只读方式挂载套接字。DOZZLE_NO_ANALYTICS用于关闭匿名统计。项目默认会收集少量匿名使用数据,例如版本号、部署模式、启用的认证方式等,不涉及日志内容,不愿意上报就按此关闭。- 生产环境建议把镜像固定到具体版本号,按需升级。
- 基础版没有认证,只适合在受信任的内网使用。
4.3 启用认证(推荐)
第一步:生成用户文件。使用 Dozzle 自带的生成命令(请换成你自己的用户名、密码和邮箱):
docker run -it --rm amir20/dozzle generate admin \
--password 你的强密码 \
--email admin@example.org \
--name "管理员" > data/users.yml
第二步:修改 Compose,挂载数据目录并启用简单认证:
services:
dozzle:
image: amir20/dozzle:latest
container_name: dozzle
restart: unless-stopped
ports:
- "127.0.0.1:8080:8080"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- ./data:/data
environment:
DOZZLE_AUTH_PROVIDER: simple
DOZZLE_NO_ANALYTICS: "true"
要点:
- 使用简单认证时,必须先生成
users.yml再启动容器,否则会启动失败。 - 密码以哈希形式保存在文件中,
users.yml仍属敏感文件,不要提交到代码仓库。 - 端口只绑定 127.0.0.1,由反向代理对外提供 HTTPS,避免明文暴露。
- 如果前面已有统一认证网关(如 Authelia),可改用转发代理认证模式,由网关负责登录与授权,具体变量与请求头设置请查阅官方认证文档。
4.4 更安全的做法:使用套接字代理
为了不把完整的 Docker 套接字直接交给 Dozzle,可以放一个只开放读取权限的套接字代理,让 Dozzle 通过远程主机方式连接它:
services:
socket-proxy:
image: tecnativa/docker-socket-proxy
restart: unless-stopped
environment:
CONTAINERS: 1
INFO: 1
EVENTS: 1
POST: 0
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
dozzle:
image: amir20/dozzle:latest
restart: unless-stopped
depends_on:
- socket-proxy
environment:
DOZZLE_REMOTE_HOST: tcp://socket-proxy:2375
ports:
- "127.0.0.1:8080:8080"
说明:代理只放行容器读取、事件与基础信息,POST: 0 禁止任何写操作。具体开放哪些接口,请对照所用代理镜像的说明,并测试日志、统计功能是否正常。这是进阶方案,通常个人环境用基础版加认证加反向代理已足够。
五、反向代理与 HTTPS
5.1 Caddy 示例
logs.你的域名 {
encode zstd gzip
reverse_proxy 127.0.0.1:8080
}
5.2 Nginx 注意事项
Dozzle 使用服务器推送(SSE)的方式实时传输日志,Nginx 默认的缓冲会让日志迟迟不显示或一次性蹦出来。需要在代理该路径时:
- 关闭代理缓冲(
proxy_buffering off) - 适当延长读超时时间
- 使用 HTTP/1.1 并关闭连接头限制
5.3 放在子路径下
如果要通过子路径访问(例如把 Dozzle 挂在某个路径前缀下),使用 DOZZLE_BASE 变量设置路径前缀,并同步调整反向代理配置。
六、多主机监控(Agent 模式)
适用于有多台 Docker 服务器,希望在一个界面里统一查看日志的场景。
6.1 在被监控的主机上运行 Agent
services:
dozzle-agent:
image: amir20/dozzle:latest
container_name: dozzle-agent
restart: unless-stopped
command: agent
environment:
DOZZLE_HOSTNAME: 主机名称
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
ports:
- "7007:7007"
6.2 在主 Dozzle 上添加 Agent
environment:
DOZZLE_REMOTE_AGENT: 192.168.1.20:7007,192.168.1.21:7007
多个 Agent 用英文逗号分隔。
注意:
- 每个 Agent 要设置各自唯一的
DOZZLE_HOSTNAME,否则多主机菜单里无法区分。 - 7007 端口不要暴露在公网,应放在内网、专用网络或经 VPN 与加密隧道访问,并用防火墙限制只允许主 Dozzle 所在机器访问。
- 可在 Agent 端设置过滤条件,限制该 Agent 对外暴露的容器范围。
七、常用环境变量
| 变量 | 作用 | 建议 |
|---|---|---|
| DOZZLE_AUTH_PROVIDER | 认证方式(简单认证或转发代理) | 公网或多人使用时必开 |
| DOZZLE_NO_ANALYTICS | 关闭匿名统计 | 按需设置 |
| DOZZLE_ADDR | 监听地址与端口 | 默认 8080 |
| DOZZLE_BASE | 访问路径前缀 | 子路径部署时使用 |
| DOZZLE_HOSTNAME | 在界面中显示的主机名 | 多主机时每个必须唯一 |
| DOZZLE_REMOTE_AGENT | 远程 Agent 地址列表 | 多主机汇总时使用 |
| DOZZLE_REMOTE_HOST | 通过远程接口连接 Docker | 配合套接字代理使用 |
| DOZZLE_FILTER | 只显示符合条件的容器 | 精简列表或限制范围 |
| DOZZLE_LEVEL | Dozzle 自身日志级别 | 排障时调整 |
| DOZZLE_ENABLE_ACTIONS | 允许在界面中启停、重启容器 | 默认保持关闭,需要时再开 |
不同版本的变量可能有增减,请以官方文档为准。
八、使用技巧
- 按级别与关键词过滤:用级别颜色快速定位 ERROR 与 WARN,再用正则搜索缩小范围。
- 分屏对比:同时打开应用和数据库的日志,排查调用链问题。
- 按栈分组:Compose 项目自动聚合,多服务应用一目了然。
- 结合容器统计:日志异常时顺便看 CPU、内存是否飙升。
- 配合日志驱动与滚动:Dozzle 读的是 Docker 保存的日志,如果容器日志驱动不是默认的 JSON 文件,或日志已被滚动清理,就看不到更早的内容。建议在 Docker 守护进程里为日志配置大小与数量限制,防止磁盘被日志占满。
九、升级与维护
cd ~/dozzle
docker compose pull
docker compose up -d
docker image prune
建议:
- Dozzle 本身几乎无状态,升级风险很低,需要保留的只有
users.yml与你的 Compose 配置。 - 备份对象:
data目录与 Compose 文件即可,日志本身不在 Dozzle 里。 - 升级前简单浏览一下发布说明,留意环境变量的变化。
- 定期检查访问入口是否仍处于认证与 HTTPS 保护之下。
十、安全检查清单
- 是否已启用认证?没有认证就不要对外暴露。
- Docker 套接字是否只读挂载?是否考虑使用套接字代理?
- 容器操作类功能是否保持关闭?
- 8080 是否仅监听本机,并由 HTTPS 反向代理对外?
- Agent 的 7007 端口是否只对主 Dozzle 开放?
- 日志中是否可能含有密码、令牌等敏感信息?谁能看到日志就等于谁能看到这些内容,应遵循最小授权原则。
十一、常见问题排查
| 现象 | 可能原因 | 处理办法 |
|---|---|---|
| 页面空白或没有容器 | 未挂载套接字,或没有权限 | 检查挂载路径与套接字权限 |
| 启用简单认证后容器启动失败 | 没有生成 users.yml | 先生成用户文件并挂载到数据目录 |
| 登录后无法使用 | 用户文件格式或路径不正确 | 重新生成并确认挂载到 /data |
| 日志延迟很久才出现 | 反向代理开启了缓冲 | 关闭对该路径的代理缓冲,延长超时 |
| 子路径访问样式错乱 | 未设置路径前缀 | 配置 DOZZLE_BASE 并同步代理 |
| 多主机菜单里主机重名 | Agent 没有设置唯一主机名 | 给每个 Agent 设置不同的 DOZZLE_HOSTNAME |
| 连接不上远程 Agent | 7007 端口不通或地址错误 | 检查防火墙、网络与地址格式 |
| 看不到更早的日志 | 日志已滚动清理,或不在 Docker 保存范围内 | 调整日志驱动与保留策略,或使用专门的日志系统 |
| Podman 或其他运行时下异常 | 套接字路径不同 | 对照官方文档调整挂载与配置 |
十二、命令速查
# 启动 / 停止 / 重启
docker compose up -d
docker compose down
docker compose restart dozzle
# 查看自身日志
docker compose logs -f dozzle
# 生成认证用户文件
docker run -it --rm amir20/dozzle generate 用户名 --password 密码 --email 邮箱 --name "显示名" > data/users.yml
# 以 Agent 模式运行
docker run -v /var/run/docker.sock:/var/run/docker.sock:ro -p 7007:7007 amir20/dozzle:latest agent
# 升级
docker compose pull && docker compose up -d
- 点赞
- 收藏
- 关注作者
评论(0)