企业官网建设流程全解析

Dozzle MCP 集成指南：让 AI 编程助手通过 Model Context Protocol 读取容器日志与监控数据

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

Dozzle 原生支持 Model Context Protocol（MCP），允许 VS Code、Claude Desktop 等 AI 编程助手直接读取你的 Docker 容器列表、日志与性能指标。本指南将带你从零启用/api/mcp端点、配置主流 MCP 客户端，并深入讲解其 5 个只读工具的底层实现与认证隔离机制，读完即可让 AI 助手"看懂"你的容器运行状态。

为什么需要 MCP 集成

Model Context Protocol 是业界标准的开放协议，用于把外部数据源和工具能力以统一方式暴露给 AI 应用。Dozzle 借此让 AI 编程助手能够与 Docker 容器交互——例如在排障时让助手自动定位某个容器的错误日志、查看 CPU/内存占用历史，而无需人工复制粘贴。

从架构上看，启用后 Dozzle 会在同一个容器进程内提供 MCP 端点，基于 Streamable HTTP 传输方式暴露在/api/mcp：

• 不需要额外进程、sidecar 或独立 MCP 服务器；
• 复用 Dozzle 自身的 Docker 客户端、日志解析（级别识别、JSON 解析、多行分组）与统计收集能力；
• 端点挂载在已验证的 API 分组内，天然继承 Dozzle 的认证与容器标签过滤体系。

该特性支持 Docker 与 Swarm 模式。在 路由注册源码 中可以看到，仅当EnableMCP配置开启时，MCP 处理器才会被挂载到/api路由下：

// MCP (Model Context Protocol) endpoint if h.config.EnableMCP { mcpServer := dozzle_mcp.NewServer(h.hostService, h.config.Labels, h.config.Version) r.Mount("/mcp", mcpServer.Handler()) }

MCP 端点对应的 HTTP 处理器由 internal/mcp/server.go 中的mcp.NewStreamableHTTPHandler生成，HostService接口只暴露查找容器、罗列容器与罗列主机三类只读能力，为"只读设计"提供了接口层面的约束。

启用 MCP 端点

MCP 特性默认关闭。启用方式二选一：启动参数--enable-mcp，或环境变量DOZZLE_ENABLE_MCP=true。

方式一：docker run（CLI）

docker run --volume=/var/run/docker.sock:/var/run/docker.sock -p 8080:8080 amir20/dozzle --enable-mcp

方式二：docker-compose.yml

services: dozzle: image: amir20/dozzle:latest volumes: - /var/run/docker.sock:/var/run/docker.sock ports: - 8080:8080 environment: DOZZLE_ENABLE_MCP: true

在 CLI 参数定义 中可以确认该开关的完整语义：

EnableMCP bool `arg:"--enable-mcp,env:DOZZLE_ENABLE_MCP" default:"false" help:"enables the MCP (Model Context Protocol) endpoint for LLM integration."`

即默认值为false，--enable-mcp与DOZZLE_ENABLE_MCP等价，二者同时出现在 支持的环境变量文档 中。启用后，健康检查与 SPA 路由之外的端点/api/mcp即可被 MCP 客户端发现并调用。

提示：如果你为 Dozzle 配置了自定义基础路径（如--base /dozzle），则 MCP 端点位于/dozzle/api/mcp；默认部署下为http://localhost:8080/api/mcp。

可用工具一览

MCP 端点共注册 5 个工具（注册逻辑见 server.go）。所有工具均为只读，不会创建、修改或删除任何容器——每个工具在注册时都显式标注了ReadOnlyHint: true：

各工具的参数与返回结构均由 Go 结构体上的 JSON Schema 注解驱动（见 server.go），AI 客户端可据此自动生成正确的调用参数。

list_containers：容器清单与状态过滤

• state（可选）：按容器状态过滤，可取running、exited、created、paused、dead；留空返回全部。
• 返回 JSON 数组，每条包含id、name、image、state、health、host、created、labels、group等元数据，是其他工具获取host与container_id的入口。

get_container_logs：结构化日志读取

必需参数host与container_id（支持完整 ID 或短 ID，均可通过list_containers获取）。可选参数：

• since_minutes：读取最近 N 分钟的日志，默认 5 分钟；
• stream：选择输出流，stdout、stderr或all，默认all。

返回为换行分隔的 JSON（NDJSON），每条日志条目含timestamp（RFC3339Nano，UTC）、level（识别出的日志级别）、stream、type与message字段。message对多行分组日志会展开为字符串数组，对 JSON 日志则保留结构化对象。

实现上，该工具通过containerSvc.LogsBetweenDates拉取指定时间窗的日志事件，parseStream会严格校验stream取值，非法值直接返回错误（见 server.go）。

search_container_logs：高效关键词检索

在必需参数host、container_id、query之外，还支持：

• since_minutes：搜索最近 N 分钟的日志，默认 5 分钟；
• stream：限定搜索 stdout / stderr / all，默认 all；
• case_sensitive：是否大小写敏感，默认 false（不敏感）。

该工具只返回命中的条目，并在结果头部给出汇总，例如Found 2 matches for "payment" (scanned 4 entries):，非常适合定位特定错误或事件，而无需拉取整段日志。无命中时也会返回"已扫描多少条日志"的明确反馈。

list_hosts：主机清单

无需参数，返回 JSON 数组，包含id、name、nCPU、memTotal、dockerVersion、type、available等主机信息，适用于多主机（本地 + 远程 Host/Agent）部署场景。

get_container_stats：性能指标历史

必需参数host与container_id。返回结构包含containerId、containerName、memoryLimitBytes、cpuLimit、dataPoints以及stats数组，其中每个统计点包含cpuPercent、memoryPercent与memoryUsageBytes。数据来自 Dozzle 统计收集器维护的环形缓冲区，覆盖最近约 5 分钟的历史（容器未运行统计时返回空数组）。

配置 MCP 客户端

VS Code（GitHub Copilot / Copilot Chat）

在项目的.vscode/mcp.json或用户 MCP 设置中加入以下配置：

{ "servers": { "dozzle": { "type": "http", "url": "http://localhost:8080/api/mcp" } } }

Claude Desktop

在 Claude Desktop 的 MCP 配置中加入：

{ "mcpServers": { "dozzle": { "type": "streamable-http", "url": "http://localhost:8080/api/mcp" } } }

注意：请将localhost:8080替换为你的 Dozzle 实例实际地址；若配置了自定义基础路径（如--base /dozzle），端点应为/dozzle/api/mcp。

认证与访问控制

MCP 端点隶属于 Dozzle 的已验证 API 分组。从 路由构造源码 可以看到，一旦配置了认证提供方，/api分组会先经过AuthMiddleware再进入RequireAuthentication，MCP 端点因此自动获得与 Web UI 同级的认证保护。启用认证后，MCP 客户端必须携带有效凭据。

Simple Auth（用户名 / 密码）

使用--auth-provider simple时，MCP 客户端需要在Authorization请求头中携带有效的 JWT Token。获取流程：

1. 用用户名和密码向/api/token发送POST请求换取 Token；
2. 配置 MCP 客户端将 Token 作为 Bearer 请求头发送。

例如在 VS Code 的 MCP 设置中：

{ "servers": { "dozzle": { "type": "http", "url": "http://localhost:8080/api/mcp", "headers": { "Authorization": "Bearer <your-jwt-token>" } } } }

Forward Proxy 认证

使用--auth-provider forward-proxy时，Dozzle 前置的反向代理负责完成认证并注入相应请求头。MCP 客户端应通过同一代理连接，认证过程透明完成，无需在客户端配置额外凭据。

无认证模式

未配置任何认证提供方（默认状态）时，MCP 端点可公开访问，无需额外配置。此时建议仅在可信内网环境部署。

标签级的权限隔离（源码纵深）

除了 HTTP 层的认证，MCP 工具还实现了容器标签级的访问隔离。resolveLabels方法（见 server.go）会优先使用请求上下文中的当前用户容器标签过滤，而不是服务器全局标签：

func (s *Server) resolveLabels(ctx context.Context) container.ContainerLabels { if user := auth.UserFromContext(ctx); user != nil && user.ContainerLabels.Exists() { return user.ContainerLabels } return s.labels }

这意味着在启用认证（尤其是 OIDC/Forward Proxy 提供按用户过滤）的场景下，MCP 工具只能读取该用户在 Web 界面中同样可见的容器，杜绝了跨租户越权读取。对应测试 TestReadToolsUseRequestingUsersFilter 专门验证了"受限用户必须使用自己的过滤条件、未认证时回退到全局过滤"这一行为。

实现细节与安全边界

• 只读硬约束：5 个工具全部声明ReadOnlyHint: true，且HostService接口只提供查询类方法，从接口设计上排除了写操作路径；
• 1MB 响应上限：日志类工具通过maxLogSize = 1024 * 1024限制返回体积，超限时截断并在结果末尾注明"results truncated at 1MB"，避免一次性把海量日志灌给 AI 上下文（见 server.go）；测试 TestSearchContainerLogsTruncates 覆盖了该行为；
• 时间窗口默认值：日志读取与搜索默认回溯最近 5 分钟，可通过since_minutes调整，这既满足绝大多数排障场景，也限制了单次调用的数据量；
• 完整测试覆盖：server_test.go 通过内存传输模拟完整 MCP 会话，验证了工具注册数量（5 个）、容器与主机列举、日志级别识别、大小写敏感搜索、非法 stream 报错、必填参数校验等行为。

小结

启用 Dozzle 的 MCP 集成只需一个开关：--enable-mcp或DOZZLE_ENABLE_MCP=true。之后无论是 VS Code 中的 Copilot 还是 Claude Desktop，都能通过/api/mcp端点安全、只读地查询容器列表、检索日志并获取性能指标。结合认证提供的 JWT 保护与标签级过滤，这套能力在保持"只读、可控、有界"的前提下，把容器可观测数据无缝接入 AI 工作流——让 AI 助手真正成为你的排障搭档。

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