Pular para o conteúdo
DumbMonit

开发

Este conteúdo não está disponível em sua língua ainda.

DumbMonit 是一个 Rust 二进制文件(crates/server,其嵌入 SvelteKit 构建)加上用于时间序列的 VictoriaMetrics,由服务器从 二进制文件启动的镜像,以及用于配置和状态的嵌入式 SQLite 数据库。一个容器。Rust 代码和注释使用法语;网络 UI 使用英语。

项目布局

Section titled “项目布局”
crates/proto     shared types: Sample, Target, Credential, trait Collector (+ ProbeError)
crates/server    the binary
  api/           axum routes (mod.rs is the route table); spa.rs serves web/build
  auth/          single instance password, HttpOnly session cookie, rate limit
  collectors/    snmp (profiles/*.yaml loaded at startup), proxmox, pbs, synology, agent, uptime
  scheduler.rs   runs every enabled target on its interval through the collector registry
  tsdb/          VictoriaMetrics writer (batched flush) + query proxy; embedded.rs supervises the child VictoriaMetrics
  db/            SQLite + numbered migrations in db/migrations/
  alerting/      rules, state machine (Phase/EffectivePhase), suppression by parent, silences, seasonal baseline
  notify/        22 notification channels, described to the UI by notify/catalog.rs
  crypto.rs      AES-256-GCM for credentials/tokens, key derived from /data/secret.key or DUMBMONIT_SECRET
crates/agent     Linux/macOS/FreeBSD/Windows agent; install/ holds install.sh/.ps1 served by the server
web/             SvelteKit (Svelte 5 runes, Tailwind 4, uPlot), adapter-static SPA fallback, ssr=false
profiles/        SNMP collection profiles, auto-applied by sysObjectID
docs/            本文档(MkDocs 源文件,使用 Starlight 发布)

没有 Rust 工具链编译

Section titled “没有 Rust 工具链编译”

编译发生在 Docker 中;主机上不需要安装任何 Rust。

Terminal window
# 完整堆栈(构建镜像:大约 10 分钟冷启动) — UI on https://localhost:8080
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build


# Rust,在 builder 阶段内(musl/alpine)
docker build -t dumbmonit-devenv --target builder .
docker run --rm -v "$PWD:/build" -w /build dumbmonit-devenv cargo test
docker run --rm -v "$PWD:/build" -w /build dumbmonit-devenv cargo test -p dumbmonit-server --test alerts_api   # one integration test file
docker run --rm -v "$PWD:/build" -w /build dumbmonit-devenv cargo test -p dumbmonit-server test_name          # one test by name
docker run --rm -v "$PWD:/build" -w /build dumbmonit-devenv cargo clippy --all-targets --all-features -- -D warnings
docker run --rm -v "$PWD:/build" -w /build dumbmonit-devenv cargo fmt --all --check

安装了 Rust 本地,cargo test和cargo clippy -- -D warnings 直接工作。Edition 2024,MSRV 1.95;rustfmt.toml设置max_width = 100 和use_small_heuristics = "Max"。

Docker 构建分层:web 构建 → 假源上的 Rust 依赖 → 真实源(在第二个cargo build前用touch,否则 cargo 重用假工件) → 代理与 cargo-zigbuild 交叉编译为 x86_64-unknown-linux-musl、aarch64-unknown-linux-musl和 x86_64-pc-windows-gnu → FROM scratch。web/build必须在之前存在 cargo build,否则服务器没有 UI。

网络 UI

Section titled “网络 UI”

主机上 Node 22 足够。

Terminal window
cd web && npm run dev        # Vite on :5173, proxies /api to localhost:8080 (the Docker server)
cd web && npm run check      # svelte-check (CI runs this)
cd web && npm run build      # static build into web/build, embedded by rust_embed at cargo build

约定:Svelte 5 仅有绳索($props、$state、$derived、$effect, 片段,onclick)。所有网络访问通过src/lib/api/; 组件永不fetch。类型在api/types.ts精确镜像 Rust 结构 并必须与crates/server/src/api/*.rs保持同步。设计 系统生活在src/app.css(代币)和src/lib/ui/(原始)。永不运行两个vite build 同时:它们擦拭.svelte-kit/output。

翻译

Section titled “翻译”

Web 界面与其他贡献一样，通过 pull request 翻译。源语言为英语（web/messages/en.json：扁平键、{param} 占位符）；其他每种语言对应一个文件 web/messages/<locale>.json，由 Paraglide JS 编译为支持 tree-shaking 的消息函数，位于 web/src/lib/paraglide/（自动生成，不纳入版本控制）。

  1. 编辑 web/messages/<locale>.json（fr、de、es、it、pt、pt-BR、ru、zh-Hans），或复制 en.json 以添加新语言。
  2. 保留 en.json 中的所有键和所有 {variables}；只翻译值。消息中不要使用 HTML 标记。
  3. 复数使用消息语法，而不是手工拼接的字符串：保留英文消息的 match/plural 结构，并翻译每个分支。
  4. 运行 cd web && npm run i18n:check：如果某种语言缺少键或改动了 {variables}，检查会失败。
  5. 提交 pull request。

新的界面文本先添加到 web/messages/en.json（功能 pull request 只需要这个文件；npm run i18n:merge 会合并临时片段）。语言文件一存在，该语言就会出现在语言选择器中（设置，外观）。键的命名约定见 CONTRIBUTING.md。

web/project.inlang/settings.json指向其一个插件(message-format)在 ./node_modules/@inlang/plugin-message-format/dist/index.js而不是 jsdelivr URL inlang 自己的工具默认:相对的,非http路径是 直接从磁盘读取,所以npm run build永不达到 CDN — 重要因为镜像构建没有保证的温暖 npm 缓存提供 那 URL,以及 homelab 工具需要互联网自重新构建的是 坏看起来。

测试和 CI

Section titled “测试和 CI”

.github/workflows/ci.yml运行,在每个推送和拉取请求:

  1. cargo fmt --all --check、cargo clippy --all-targets --all-features -- -D warnings、cargo test --all-features;
  2. cargo deny check licenses bans — 仅 OSI 批准的许可证允许 由deny.toml;copyleft 或源可用依赖失败构建;
  3. npm run check和npm run build;
  4. 镜像(linux/amd64),仅构建。

.github/workflows/release.yml推送相同镜像到 ghcr.io/selfhostr/dumbmonit::edge在每个推送到main,:X.Y.Z, :X.Y、:X和:latest在每个v*标签。

集成测试生活在crates/server/tests/;纯模块(度量 转换、选项解析、告警状态机、沉默)被测试 不网络的地方。

添加收集器

Section titled “添加收集器”
  1. 从crates/proto/src/collector.rs实现Collector: kind()、probe(&Target) -> Result<Vec<Sample>, ProbeError>和可选 discover()用于配置文件检测。返回ProbeError变体 真实: means_down()决定失败是否计为”监控项 关闭”(告警)或作为配置错误(显示在监控项,不 通知)。
  2. 从Target::tags在options.rs中读取你的选项,带默认。
  3. 在crates/server/src/main.rs中用registry.register(...)注册它。 调度器和 API 永不知道具体类型。
  4. 在crates/server/src/api/collectors.rs中描述它:标签、摘要、 示例、凭证类型、地址提示、设置通知和options 列表(键、标签、帮助、占位符、默认、输入、选择)。UI 构建 其形式从此;一个测试那里检查每个已注册的类型有通知 以及选项键匹配收集器读取。
  5. 命名度量<what>_<unit>不用dumbmonit_前缀(写入 添加)并添加任何新度量内置规则针对列表在 alerting/rules.rs测试。
  6. 在docs/devices/下添加一个页面。

样本是Sample::new(name, value, MetricKind::Gauge | Counter, timestamp_ms)带.with_label(k, v);身份标签(target、host、 tag_*)由注册表添加。不自己发出它们:命名一个按对象的标签 对象(proxy_host、esxi、ceph_host)。碰撞标签 保持为exported_<name>,以及为类型列出的选项在 api/collectors.rs不复制为tag_*。

添加通知通道

Section titled “添加通知通道”
  1. 实现Notifier(crates/server/src/notify/mod.rs): kind()和async fn send(&Message) -> Result<(), NotifyError>。网络通道共享 HTTP 客户端和notify/http.rs中的帮助者;查看services.rs、 chat.rs、push.rs、oncall.rs和smtp.rs用于兄弟。
  2. 添加类型到CHANNEL_KINDS和到notify/mod.rs中的build匹配, 将存储的ChannelConfig(设置 + 解密 秘密)变成Notifier。
  3. 在notify/catalog.rs中描述它:标签、摘要、doc_url锚点,以及 settings和secrets字段(键、标签、必要、输入、帮助、 占位符、选项、形状、默认)。UI 从此 描述呈现形式,所以不需要 UI 发布。
  4. 在docs/notifications.md中在支持的通道下记录它,带有 标题其 slug 匹配doc_url锚点:UI 链接直接到 那个锚点在在线文档中。

无头截图

Section titled “无头截图”

web/tools/README.md描述如何呈现每个页面 在 Docker 中运行的无头 Chromium(zenika/alpine-chrome:with-puppeteer, 无需本地浏览器):用curl登录以获取dumbmonit_session cookie,然后针对预览服务器运行web/tools/screenshot.js或 直接对:8080。它写web/shots/<page>-<theme>-<viewport>.png 用于两个主题和两个视口,这是如何 UI 被检查后 改变以及如何这个文档的截图被制作。

文档

Section titled “文档”

此站点由 MkDocs 和 Material for MkDocs 从docs/构建 (mkdocs.yml在根)。预览:

Terminal window
pip install -r docs/requirements.txt
mkdocs serve
mkdocs build --strict   # 必须无警告通过

文档使用 Starlight 发布在 https://dumbmonit.selfhostr.io/docs/。