Dozzle 开发实战手册：前后端架构、开发命令与仓库工程规范详解

Dozzle 开发实战手册前后端架构、开发命令与仓库工程规范详解【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzleDozzle 是一个支持 Docker、Swarm 与 Kubernetes 的实时容器日志查看器采用 Go 后端加 Vue 3 前端的混合应用架构。本文基于仓库根目录下的 CLAUDE.md 开发指南编写完整覆盖该文档中的项目定位、开发命令、前后端架构、通信流程、构建系统、Lint 与国际化规范、设计系统以及扩展模式并结合 Makefile、package.json、vite.config.ts 与各internal/源码包逐一印证帮助你在动手修改 Dozzle 之前建立完整、可执行的全局认知。项目定位与技术栈从 CLAUDE.md 的 Project Overview 一节看Dozzle 被明确定义为轻量级、基于 Web 的 Docker 日志查看器具备实时监控能力是一个混合hybrid应用后端Go负责 HTTP 服务器、Docker API 客户端、WebSocket 日志流式传输前端Vue 3SPA 形态使用 Vite 与 TypeScript。应用支持多种部署模式独立服务器standalone server、Docker Swarm、Kubernetes。仓库版本信息可见 package.json 中version: 11.0.1Go 侧模块声明在 go.mod要求 Go 1.27.1CLAUDE.md 表述为 Go 1.25以 go.mod 实际声明为准。从 go.mod 的依赖清单可以印证后端的实际能力边界moby/moby/clientDocker 引擎 API、k8s.io/client-go与k8s.io/metricsK8s 集群访问、google.golang.org/grpc多主机 Agent 与 Cloud 双向流、go-chi/chiHTTP 路由、go-chi/jwtauthJWT 鉴权、gorilla/websocket终端连接、stretchr/testify测试断言。这与 CLAUDE.md 描述的后端 HTTP 服务 Docker API 客户端 流式推送完全对应。环境准备与核心开发命令初始化# 安装前端依赖 pnpm install # 生成证书和 protobuf 文件 make generatemake generate是本地开发的必要前提。查看 Makefile 可以发现它做了两件事Makefile生成shared_key.pem/shared_cert.pem先用openssl genpkey -algorithm Ed25519生成 Ed25519 私钥再签发自签证书有效期 1825 天约 5 年这对证书用于 gRPC Agent 的 TLS 双向认证执行go generate ./...依据 protos/rpc.proto 与 protos/cloud.proto 重新生成internal/agent/pb下的 protobuf 代码。CLAUDE.md 特别强调证书生成是必须的否则 Agent 模式无法工作make test目标会自动先跑fake_assets generate再执行go test -cover -race -count 1 -timeout 40s ./...Makefile其中fake_assets只是造一个占位的dist/index.html让 Go embed 在测试环境下也能通过。开发态运行# 完整开发环境后端 air 热重启 前端 Vite HMR make dev # 多个 git worktree 并行开发时自动挑选空闲端口组并打印选定的 URL make dev-auto对应 package.json 的 scriptsmake dev等价于pnpm dev即用concurrently --kill-others同时拉起watch:backend与watch:frontendpackage.jsonwatch:backendLIVE_FStrue DEVtrue air -- --level debug --addr localhost:${DOZZLE_PORT:-3100}即 Go 后端由 air 监听文件变化自动重启默认端口 3100watch:frontendvite --port ${VITE_PORT:-5173} ... --open http://localhost:${DOZZLE_PORT:-3100}/。注意 CLAUDE.md 中前端端口 3100的注释实际指的是浏览器被打开的后端地址Vite 自身默认监听 5173通过环境变量VITE_PORT、DOZZLE_PORT可覆盖。make dev-autoMakefile调用scripts/dev-ports.mjs根据当前 checkout 路径派生一组空闲端口使多个 worktree 能各自跑一个实例这也是 CLAUDE.md 中several worktrees can each run an instance at once说法的出处。Agent 模式的独立开发入口是pnpm run agent:dev展开为DEVtrue air -- agent --level debug --agent-addr localhost:${AGENT_PORT:-7007}package.json即本进程以 Agent 身份监听本地 7007 端口的 gRPC。构建# 仅构建前端资源Vite - dist/随后 brotli 压缩 pnpm build # 等价于 make dist # 完整应用构建先构建前端再 Go 交叉编译 make build # 构建 Docker 镜像 make docker对照 Makefilebuild目标执行CGO_ENABLED0 go build -ldflags -s -w -X github.com/amir20/dozzle/internal/support/cli.Versionlocal即静态编译并把版本号注入internal/support/clidocker目标则docker build --build-arg TAGlocal -t amir20/dozzle:local。前端pnpm build实际是vite build node scripts/compress-dist.jspackage.json在产物之上追加了压缩步骤。测试# Go 测试race 检测器 覆盖率 make test # 前端测试Vitest pnpm test # 等价于 TZUTC vitest TZUTC pnpm test --watch # watch 模式 # 类型检查vue-tsc pnpm typecheck # Lint仅 Tailwind class 检查 pnpm lint pnpm lint --fix # 本地预览生产构建 pnpm preview # 或 make preview # Playwright 集成测试docker compose 拉起完整环境 make intCLAUDE.md 给出的两条硬性约束在仓库中都能找到落点TZUTC是时间戳相关测试的前提pnpm test脚本本身就硬编码了TZUTC vitestpackage.json集成测试同理避免本地时区造成的断言漂移。集成测试走 composemake int即docker compose up --build --force-recreate --exit-code-from playwrightMakefile依赖仓库根目录的 docker-compose.yml 与 e2e/ 下的 Playwright 用例visual.spec.ts、logs.spec.ts、remote-host.spec.ts等。CI 场景下有专门的test-ci目标Makefile跳过go generate因为所有生成代码均已提交CI 不需要安装 protoc 就能复现同样的输出。后端架构GoCLAUDE.md 的 Architecture 一节给出了后端包地图逐一与仓库目录核对后如下包职责关键文件仓库实际存在internal/web/HTTP 服务器与路由层routes.gochi 路由、logs.go日志流 SSE、auth.go、actions.go容器 start/stop/restartinternal/docker/Docker API 客户端实现client.go、log_reader.go8 字节头多路复用流解析、stats_collector.go、calculation.gointernal/agent/gRPC Agent多主机支持client.go、server.go、pb/生成的 protobuf 代码internal/cloud/Dozzle Cloud 工具执行引擎tools.go工具注册与executeTool分发、tools_containers.go、tools_logs.go日志拉取level/query/regex 过滤上限 100 行、tools_actions.go受enableActions门控的启停操作、tools_helpers.gointernal/k8s/Kubernetes 客户端client.go、log_reader.go、stats_collector.gointernal/support/支撑层cli/命令行参数解析、docker/多主机与 Swarm、k8s/、web/internal/auth/认证simple.go基于 users.yml 的文件认证、proxy.go反代认证、roles.go角色授权internal/container/容器领域模型client.goClient接口、event_generator.go多行合并、JSON 检测internal/notification/告警与通知manager.go规则求值与分发、log_listener.go日志模式匹配、persist.go、dispatcher/各通知渠道其中internal/support/docker/下的四个核心文件与 CLAUDE.md 描述的服务层架构严格对应docker_service.goClientService接口与编排、multi_host_service.goMultiHostService、retriable_client_manager.goServer 模式的多主机管理本地 远程 Agent、swarm_client_manager.goSwarm 节点发现。入口在 main.go按 server/swarm/k8s/agent 四种模式切换启动路径protobuf 的go generate指令也定义在此。后端分层新增容器操作的标准路径CLAUDE.md 给出了清晰的五层抽象HTTP Handlers → HostService → ClientService → container.Client → 具体实现HTTP Handlers (internal/web) ↓ HostService Interface (MultiHostService) ↓ ClientService Interface (per host) ↓ container.Client Interface ↓ Implementation (DockerClient, K8sClient, AgentClient)当你要新增一个容器操作时文档给出的四步流程是在 internal/container/client.go 的container.Client接口中定义方法在 internal/docker/client.go 实现如适用internal/k8s/client.go同步实现在 internal/support/docker/docker_service.go 的ClientService接口中加包装方法在internal/web/增加 HTTP handler 与路由。这套分层让 Docker、K8s、远程 Agent 三种后端对外呈现同一个接口面是理解整个后端的钥匙。前端架构Vue 3目录组织前端约定CLAUDE.md 原文要点与仓库实际目录核对如下assets/pages/基于unplugin-vue-router的文件式路由。container/[id].vue单容器视图、merged/[ids].vue多容器合并视图、host/[id].vue主机级日志、service/[name].vueSwarm 服务日志、stack/[name].vueDocker stack 日志、group/[name].vue自定义分组日志、namespace/、owner/等 K8s 相关路由以及 assets/pages/[...all].vue 兜底路由。assets/components/自动导入的组件库按功能域分目录——ui/通用原语BarChart.vue、UsageMeter.vue、InlineNotice.vue 等shell/应用框架及单例布局nav/侧边栏内部一切search/命令面板与搜索界面containers/ContainerTable.vue、工具栏、终端等hosts/HostCard.vue 等logs/日志流渲染其中logs/entries/为每种LogEntry类型各放一个组件SimpleLogItem.vue、ComplexLogItem.vue、GroupedLogItem.vue、ContainerEventLogItem.vue、SkippedEntriesLogItem.vue、LoadMoreLogItem.vue告警条目 AlertLogItem.vue 也插在同一层views/每个路由一个日志视图文件ContainerLog.vue、ServiceLog.vue、StackLog.vue 等notifications/、cloud/再分rail/、chat/、history/等。assets/stores/Pinia store自动导入。config.ts 保存后端注入 HTML 的应用配置与 feature flagfrozen 不可变container.ts 管理容器状态并经 EventSource 订阅/api/events/stream其余有hosts.ts、settings.tslocalStorage 偏好经 profileStorage、pinned.ts并排查看的固定容器、swarm.ts、k8s.ts、announcements.ts。assets/composable/组合式函数目录镜像组件组织。实际目录ui/、app/、logs/、containers/、cloud/、notifications/、editor/其中logs/是流式管线核心eventStreams.tsSSE 连接与 250ms 缓冲刷新、historicalLogs.ts、logContext.ts、scrollContext.ts、visible.ts以及duckdb.ts基于 DuckDB-WASM 的日志 SQL 查询依赖 package.json 中的duckdb/duckdb-wasm。assets/modules/Vue 插件router.ts、pinia.ts、i18n.ts。AutoImport 递归配置的静默故障陷阱CLAUDE.md 特别警告AutoImport的dirs必须是assets/composable/**不能写成裸目录名。这一警告在 vite.config.ts 的注释中得到了印证Recursive: composables live in feature subfolders. A bare dir is scanned one level deep only, which silently drops everything nested.——裸目录只扫描一层深度嵌套目录里的 composable 会不报任何错误地停止自动导入。同一段注释还提到**会连带 glob 到*.spec.ts这只有在测试文件不导出任何东西时才无害。配置同时把assets/stores与assets/utils/index.ts纳入自动导入类型声明输出到 assets/auto-imports.d.ts 与 assets/components.d.ts。组件命名空间约束unplugin-vue-components未启用directoryAsNamespace见 vite.config.ts 的Components配置因此组件名即文件名目录层级对模板完全不可见。这带来两个工程后果移动组件几乎零成本改文件名即可全局生效但任意深度的两个组件绝不能共享 basename。前后端通信流程CLAUDE.md 的 Communication Flow 一节列出了五条通道与internal/web/routes.go的路由设计一致实时日志前端对/api/hosts/{host}/containers/{id}/logs/stream建立 SSE 连接容器事件/api/events/stream推送容器生命周期事件统计信息CPU/内存统计与事件复用同一条 SSE 流容器操作POST /api/hosts/{host}/containers/{id}/actions/{action}start/stop/restart终端/api/hosts/{host}/containers/{id}/attach走 WebSocketattach/exec。实时日志的完整数据流文档给出的八步管线Frontend Data Flow 小节用户进入/container/{id}路由页面组件调用useContainerStream(container)组合式函数组合式函数对/api/hosts/{host}/containers/{id}/logs/stream建立 EventSource后端经 SSE 推送LogEvent对象前端对事件做缓冲250ms 防抖最长 1000ms 强制冲刷批量更新响应式messages数组缓冲冲刷后触发渲染LogViewer.vue 按条目类型分发到SimpleLogItem/ComplexLogItem/GroupedLogItem等组件当消息量超过maxLogs400时最旧条目被替换或标记为SkippedLogsEntry。统计流的管线是应用初始化时 container.ts store 连接/api/events/stream→ 后端把容器事件与统计复用到一条 SSE 流 →container-stat事件更新Container._stat并追加到_statsHistory→ EMA 平滑alpha0.2得到movingAverageStat→ ContainerTable.vue 用降采样后的历史数据渲染迷你柱状图。后端日志解析管线与前端渲染对应的后端管线Log Parsing Pipeline 小节Docker API 返回多路复用流8 字节头 payloadinternal/docker/log_reader.go 解析头部提取 stdout/stderr 类型internal/container/event_generator.go 接收原始日志行执行检测逻辑JSON 结构 →ComplexLogEntry多行模式如堆栈跟踪→GroupedLogEntry单行 →SimpleLogEntry经正则提取日志级别LogEvent序列化为 JSON经 SSE 发出前端反序列化并按类型渲染。前端三种条目类型对应 assets/models/LogEntry.ts 中的模型定义工厂方法LogEntry.create(logEvent)依据logEvent.t字段实例化正确类型CLAUDE.md 同时要求统一使用LogMessage类型别名代替裸的string | string[] | JSONObject。协议缓冲区流Agent 模式多主机场景下主服务器为每个远程主机创建agent.NewClient(endpoint, certs)AgentClient实现container.Client接口方法调用翻译为 protos/rpc.proto 定义的 gRPC 请求远程 Agent 收到调用后委托给本地DockerClient日志/统计/事件的流式 RPC 使用双向通道响应经FromProto()方法转回领域模型。Cloud 工具执行流internal/cloud/侧的调用链文档 Cloud Tool Execution Flow 小节cloud.Client.Run()阻塞直到配置好 cloud dispatcher →connect()建立到 cloud 端点的双向 gRPC 流ToolStreamRPC→ Cloud 下发ToolRequestListTools 或 CallTool客户端经executeTool()分发 → 工具并发执行加权信号量限 5 并发→ 断线后指数退避重连1s→30s 带抖动PermissionDenied错误API key 无效 / 无 pro 套餐则永久停止重试工具定义经sync.Once缓存对非 Cloud 用户零开销。消息定义在 protos/cloud.proto。构建系统CLAUDE.md 的 Build System 小节给出四条规则均可在仓库中验证前端Vite 构建到dist/并生成 manifestvite.config.ts 中build.manifest: true入口assets/main.ts同时把应用图标设为按需加载而非内联 base64后端用 Go embed 指令嵌入dist/热重载开发时DEVtrue禁用嵌入资源服务LIVE_FStrue改为从文件系统读资源对照 package.json 的watch:backend与preview脚本两者都同时设置了这两个变量Makefile编排构建与依赖生成Makefile。Lint 规范只做 Tailwind 的 ESLint这是 CLAUDE.md 中工程约束最重的一节核心立场是ESLint 在这里只检查 Tailwind class不是通用 JS/TS linter也不应该变成通用 linter。理由链条是tsconfig.json 已开启strict、strictNullChecks、noUnusedLocals类型与死代码问题由pnpm typecheckvue-tsc --noEmit覆盖Prettier 加prettier-plugin-tailwindcss负责格式化与 class 排序所以任何风格类规则都不属于 eslint.config.js。具体操作规范eslint.config.js 里逐条列出了 Tailwind 插件自带的每条规则及其开启/关闭理由新增规则要加入这个清单而不是引入 presetpre-commit 钩子simple-git-hooks见 package.json 与 lint-staged.config.mjs会对暂存的js/mjs/ts/mts/vue先跑eslint --fix再跑 prettier让 prettier 拥有格式化的最终决定权写完一批标记后建议手动pnpm lint --fix。文档还点明了两个绿灯不等于干净的盲区SFCstyle块里的apply永远不会交给 Tailwind 插件其中的错误 class 不会被报告任意值规则只映射整数间距步长gap-[2px]、w-[3px]这类写法不会被报告尽管gap-0.5、w-0.75这类标准值存在。国际化与文档翻译界面文案locales/locales/en.yml 是唯一事实源但绝不是唯一需要改的文件。任何在en.yml中新增、重命名或删除 key 的改动必须在同一个 commit 中对locales/下的每一个语言文件做同样改动且要写入真实翻译不是复制英文key 失去最后一个消费者时也要在所有语言中删除。本仓库没有 Crowdin/Weblate 同步只存在于en.yml的 key 会静默回退英文且无任何告警。locales/现有 da、de、en、es、fr、id、it、ko、nl、pl、pt、ru、sl、tr、zh、zh-tw 共 16 个语言文件。文档翻译docs/docs/ 下的英文页面是事实源翻译镜像到zh、de、fr、es四个目录docs/locale/same path。改动英文页意味着同 commit 更新全部四个翻译。与locales/的关键区别这里没有回退机制。过期的翻译页会自信地渲染错误的操作说明而不是安静地显示英文所以漂移比缺 key 更糟。每个翻译文件 frontmatter 里的sourceHash记录了它依据的英文源docs/scripts/check-translations.mjs 在哈希偏离时失败并在 CI 的Docs Translations任务中运行。完成真实翻译后用node docs/scripts/check-translations.mjs --update重打时间戳——--update只重打哈希不翻译在未翻译的页面上跑它只会让 CI 变绿而页面仍是错的必须先翻译再打戳。翻译页内部的纪律围栏代码块除自然语言注释外与英文保持字节级一致内部链接加 locale 前缀/guide/agent→/de/guide/agent侧边栏不按 locale 复制结构在docs/.vitepress/locales/structure.ts各语言文件只提供 label因此新增页面需要一个 slug 每语言一个 label。设计系统要点CLAUDE.md 的 Design System 一节把 UI 收敛为一套干净、扁平、安静的视觉语言新界面必须遵守触碰旧界面时也应顺手带过来。核心规则摘要表面分组面板用中性色rounded-lg border border-base-content/15 bg-base-200/40行分隔divide-y divide-base-content/10行内距p-4链接行p-2无阴影无渐变浮层下拉、popover、toast用rounded-box border ... bg-base-200加shadow-sm/shadow-lg。颜色与严重级别严重级别落在图标上而不是面板上——彩色圆底bg-error/10 text-error等加状态点承载状态面板保持中性以保住文字对比度禁止 daisyUI 的alert alert-error等饱和块。页内通知用 InlineNotice.vue浮动通知用ToastModal。状态文本用main.css中的status-pill描边、大写、mono chip。primary 按钮纪律primary只保留给一个表面希望用户执行的那个动作同一面板出现两个实心 primary 按钮即为 bug次要破坏性操作用btn text-error而不是btn-error。排版与密度正文text-sm次要文案text-base-content/60脚注text-xs配text-base-content/40数字、key、ID、百分比一律font-mono只读值是左 label、右 mono 值的文本而不是禁用输入框。仪表与图表用量条统一用 UsageMeter.vuebg-base-content/10 h-1.5轨道 bg-primary填充超 70% 变bg-warning、超 90% 变bg-error不用 daisyUIprogress图表保持轻量自研BarChart.vue不引入图表库。交互暗示Tailwind v4 preflight 给 button 设了cursor: defaultmain.css中有一条 base 层规则统一恢复 pointer覆盖button、select、[rolebutton]、.btn、复选/单选 label跳过禁用态可点击元素必须有 hover 态与可达点击区小于约 24px 的绘制框用::afterinset 画命中区。动效hover 用transition-colors仪表条宽duration-500图标弹簧动画200ms cubic-bezier(0.34, 1.56, 0.64, 1)所有动画提供prefers-reduced-motion逃逸。一致性面板在各状态下保持形状loading/error/healthy 共享头部、分隔线、页脚同一概念处处长一样如 Cloud 账户面板在CloudPopover.vue、CloudSettingsCard.vue、notifications/CloudDestinationForm.vue三种宽度下复用同一套部件需要第四处时抽组件而不是复制 class。新文件放哪里四条顺序判定CLAUDE.md 的 Where files go 一节给出新组件的四条判定按序应用、命中即停ui/除/composable/ui/外不 import 任何/路径且组件名不含 Dozzle 领域名词container、host、log、alert、cloud、nav、swarm、k8s、stack、service、chat、rail。判据是贴到另一个 Vue 应用里仍能构建既不是共享也不是小的意思cloud/该表面在无 Cloud 的安装中完全不存在。两个既定例外凡 assets/models/LogEntry.ts 注册的条目都是日志条目留在logs/entries/包括AlertLogItem.vue因为告警是拼接进本地流的插入本地表单的变体跟表单走所以CloudDestinationForm.vue与WebhookDestinationForm.vue并列views/assets/pages/中某路由文件整体挂载的视图一个路由一个文件ContainerLog.vue虽也被layouts/default.vue用于固定列仍属该路由的视图其余按组件名中的名词归入功能目录。补充纪律nav/是侧边栏内部一切shell/是定位它的框架功能目录超过约 15 个文件且有明显子名词时才允许嵌套一层最多一层spec 跟随主体assets/composable/使用同名目录与前两条同样的判定components/ui/只允许依赖composable/ui/与第三方代码这是评审中唯一值得强制的依赖边。关键实现细节速查CLAUDE.md 的 Important Development Notes 汇总了一批容易踩坑的实现约定值得整体保留自动导入composable、组件、Pinia store 均在 vite.config.ts 配置图标走unplugin-iconsmdi、carbon、material-symbols 等多套样式为 Tailwind CSS DaisyUI。日志条目三类型SimpleLogEntry单行string、ComplexLogEntry结构化 JSON、GroupedLogEntry多行分组string[]工厂模式LogEntry.create(logEvent)。EventSource 缓冲250ms 防抖、1000ms 强制冲刷批量更新 UI。图表自研轻量实现无 D3.jsBarChart.vue 内建响应式降采样按可用屏宽把数据分桶取均值Container.statsHistory是上限 300 的滚动窗口chartData永远是等长 300 的滚动窗口downsampledBars用ref而非computed以便原地修改最后一根柱、避免全量重渲染切换容器导致chartData整体替换时父组件必须调用组件暴露的recalculate()MultiContainerStat持有各 BarChart 的 ref 并在containerswatch 中调用。测试注意Container携带 Vueref所以setProps无法重触发该 watch需经父级 ref 重渲染换容器。后端make generate生成证书与 protobufDocker 客户端做 API 版本协商服务层三件套ClientService/MultiHostService/ClientManagerServer 模式RetriableClientManagerSwarm 模式SwarmClientManager。认证三种模式 none / simple./data/users.yml或./data/users.yamlJWT 可配 TTL/ forward-proxy如 Authelia。测试Go 用标准testing testify前端 Vitest vue/test-utils集成测试 Playwright 在e2e/必须TZUTC。统计指标EMA alpha0.2滚动窗口 300 项useSimpleRefHistoryCPU 按核心数归一cpuLimit优先否则宿主nCPU内存同时提供百分比与绝对值。容器标签dev.dozzle.name自定义显示名、dev.dozzle.group分组、dev.dozzle.url关联容器自己的 Web UI仅 http/https见 assets/models/Container.ts 的Container.url应用内多处基于标签过滤。部署模式CLAUDE.md 描述了四种运行形态与 main.go 的模式切换对应Server 模式默认单机或多主机 Docker 监控RetriableClientManager管理本地 远程 Agent 客户端Swarm 模式经 Docker API 自动发现 Swarm 节点每个节点起 gRPC Agent 服务器端口 7007SwarmClientManager负责节点发现K8s 模式Pod 日志监控Kubernetes 客户端实现container.Client接口Agent 模式轻量 gRPC Agent 用于远程日志采集dozzle agent或pnpm run agent:dev启动监听 7007 并做 TLS 证书认证即make generate生成的shared_cert.pem/shared_key.pem的用途。扩展模式手册CLAUDE.md 把五类常见扩展写成了可照抄的 checklist这里是其完整继承新增 HTTP 路由在 internal/web/routes.go 用 chi 定义路由r.Get(/api/custom-endpoint, h.customHandler)在合适的文件如actions.go、logs.go实现 handler 方法用hostService的FindContainer()/FindHost()定位容器/主机返回 JSON或建立 SSE/WebSocket 流。新增日志视图类型在assets/pages/建路由文件如custom/[id].vue在 assets/composable/logs/eventStreams.ts 建组合式函数如useCustomStream()职责包括按过滤条件拼 API URL、建立 EventSource、处理缓冲与消息批处理、返回响应式messages数组与控制方法用 LogViewer.vue 渲染消息如需新后端端点按上一条路由流程添加。新增容器统计指标在 internal/container/types.go 的Stat类型加字段更新 internal/docker/stats_collector.go 从 Docker API 响应提取指标如需要在 internal/docker/calculation.go 加计算逻辑确保 protos/rpc.proto 包含该字段Agent 通道要用前端经既有 SSE 流自动收到更新UI 需要访问时同步更新 assets/models/Container.ts。通知/告警系统后端manager.go 是规则求值引擎并管理告警状态log_listener.go 订阅容器日志流、把入站日志对照规则求值types.go 定义规则日志模式匹配、阈值dispatcher/放各渠道实现规则经 persist.go 持久化到./data/notifications.yml。前端规则编辑界面在 assets/pages/notifications.vue 与assets/components/notifications/AlertForm.vue、DestinationForm.vue等。新增通知渠道三步在internal/notification/dispatcher/实现 dispatcher 接口 → 在manager.go的 dispatcher 工厂注册 → 在assets/components/notifications/DestinationForm.vue加对应表单。新增 Cloud 工具在 internal/cloud/tools.go 的AvailableTools()中定义工具名称、描述、参数 schema在 protos/cloud.proto 加响应消息类型并加入CallToolResponse.resultoneofmake generate重新生成 protobuf 代码在internal/cloud/tools.go的executeTool()switch 中加 case在合适的tools_*.go文件实现执行函数经ToolHostService接口访问容器/主机数据在tools_test.go补测试。未发布 PR 的测试方式与社区沟通约定CLAUDE.md 还包含两条面向维护流程的约定测试未发布的 PR当 issue/discussion 的修复尚在开放 PR 中时请报告者直接测试 CI 为每个 PR 构建的镜像amir20/dozzle:pr-XXXXXX 为 PR 编号无需等下一个 release。仓库中的 Dockerfile 即该镜像的构建基础。GitHub 行文语气以人类维护者口吻发言而非 AI 助手口吻明确列出了要避免的AI 痕迹不用破折号、不用不是 X 而是 Y式修辞、不写开场白与收尾总结、不滥用加粗内联标签、去掉含糊措辞、小写与缩写均可、给出决定与一个理由即止。这部分属于社区协作规范转述在此供贡献者参考。Dozzle 与 Dozzle Cloud 的边界CLAUDE.md 用一句判据划定了功能归属Dozzle 拥有用户面前这个容器的一切Cloud 拥有历史、跨实例与账户的一切。展开为四条操作规则命名上Notifications用户自己写的规则及其结果与Findings用户没写、Cloud 主动发现的东西两个表面不得混淆Findings 不是告警永不与告警并列展示Cloud 提供的是记忆而非功能本地告警早已能拼接进日志流AlertLogItem.vue只是刷新即失Cloud 让同样的东西在 reload、重启、一周之后依然存在。没有 Cloud 的安装应展示一条说明它会存什么的空历史区而不是锁形卡片完全无本地对应物的表面如 Findings 列表仅在配置了 Cloud 时才挂载外链纪律Cloud 确实做得更好的事计费与密钥、报告归档、跨实例汇总、深度调查对话应链接出去protos/cloud.proto 的AlertHit.url已携带深链但对屏幕上这条流就能回答的问题例如给我看这些行——把历史滚动驱动到 finding 或告警描述的时间窗绝不外链这正是这些表面存在于 Dozzle 里的全部理由门控套餐决策在服务端算好fixLocked后交给 Dozzle渲染方只按给到的门控走除isPro的装饰性分支外不再推断全站唯一的 upsell 表面是CloudPopover其余位置保持安静。调试与日常开发提示热重载make dev下后端改动触发 air 自动重启前端改动触发 Vite HMRDEVtrue关闭嵌入资源LIVE_FStrue改从文件系统读资源调试开关后端用--level debug标志或DOZZLE_LEVELdebug环境变量Makefile 的agent-reload目标即以DOZZLE_LEVELdebug起 Agent前端用 Vue DevToolsSSE 流可在浏览器 DevTools 的 Network 面板查看 EventSource 连接测试纪律Go 测试始终带 race 检测器make test内置-race前端时间戳测试依赖TZUTC集成测试make int会经 docker compose 拉起完整环境。小结CLAUDE.md 本质上是一份如何在这个仓库里高效、不出错地干活的操作手册开发命令一节给出从pnpm install到make int的完整工作流Architecture 一节给出 Go 五层抽象与 Vue 目录组织Important Development Notes 固化了日志条目三类型、250ms 缓冲、300 项滚动窗口、EMA alpha0.2 等实现常量Design System 与 Where files go 两节则把 UI 品味与文件归属变成了可执行的判定规则。配合本文补充的 Makefile、package.json、vite.config.ts 与各internal/源码文件路径这份文档足以支撑你在不迷失的前提下完成路由新增、指标扩展、通知渠道接入与 Cloud 工具开发等典型改动。【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考