docs: 重写 README 为结构化项目文档，精简示例配置

2026-05-16 20:58:04 +08:00
parent 146cef982e
commit 04c24e6796
2 changed files with 128 additions and 273 deletions
--- a/README.md
+++ b/README.md
@@ -1,29 +1,61 @@
 # DiAL

-基于 Bun + TypeScript 的多类型拨测监控工具。通过 YAML 配置文件定义 HTTP 和命令行拨测目标，后端按配置定时并发拨测，结果持久化到本地 SQLite，前端 Dashboard 展示各目标实时状态、可用率、耗时趋势等，并支持手动、10 秒、30 秒、1 分钟、5 分钟刷新频率切换，以及系统、明亮、黑暗三种主题模式。主题模式选择会保存在当前浏览器本地存储中，同一浏览器再次访问时自动恢复。
+<p align="center">
+  <strong>轻量级多类型拨测监控工具</strong>
+</p>
+
+<p align="center">
+  基于 Bun + TypeScript 构建 · YAML 配置驱动 · 内置 Dashboard
+</p>
+
+---
+
+DiAL 是一个自托管的拨测监控工具，支持 **HTTP**、**命令行** 和 **数据库** 三种拨测类型。通过 YAML 配置文件定义拨测目标，后端定时并发执行拨测并将结果持久化到本地 SQLite，前端 Dashboard 展示各目标的实时状态、可用率和耗时趋势。
+
+**功能亮点：**
+
+- 多种拨测类型：HTTP（GET/POST/PUT 等）、Cmd（命令行执行）、DB（PostgreSQL/MySQL/SQLite）
+- 丰富的校验规则：状态码、响应头、JSONPath、CSS 选择器、XPath、正则匹配、数值比较等
+- 响应式 Dashboard：实时状态、可用率统计、耗时趋势图、手动/自动刷新
+- 多主题支持：系统、明亮、黑暗三种主题模式
+- 零外部依赖：数据存储使用 SQLite，无需额外数据库服务

 ## 快速开始

+**前置条件：** [Bun](https://bun.sh/) >= 1.0
+
 ```bash
+# 克隆仓库
+git clone https://github.com/your-org/DiAL.git
+cd DiAL
+
+# 安装依赖
 bun install
+
+# 复制示例配置并按需修改
 cp probes.example.yaml probes.yaml
+
+# 启动开发服务器
 bun run dev probes.yaml
 ```

-`bun run dev` 启动双进程开发服务器（Vite :5173 + Bun API :3000），访问 `http://127.0.0.1:5173`。
+`bun run dev` 会同时启动 Vite 开发服务器（`http://127.0.0.1:5173`）和 API 服务器（`http://127.0.0.1:3000`），访问前端地址即可使用 Dashboard。

-## 开发验证
+## 生产部署

 ```bash
-bun run check   # schema:check + typecheck + lint + bun test
-bun run verify  # check + build
+# 构建
+bun run build
+
+# 运行
+./dist/dial-server ./probes.yaml
 ```

-`verify` 会基于当前源码重新构建生产 executable。原 smoke test 已移除，executable/E2E 验证后续单独补充。
+构建产物为独立可执行文件，只需一个 YAML 配置文件即可运行。

 ## 配置文件

-程序通过 YAML 配置文件定义所有运行参数：
+程序通过 YAML 配置文件定义所有运行参数，完整示例参见 [`probes.example.yaml`](probes.example.yaml)。

 ```yaml
 # yaml-language-server: $schema=./probe-config.schema.json
@@ -38,7 +70,7 @@ runtime:
  retention: "7d"

 defaults:
-  interval: "5s"
+  interval: "30s"
  timeout: "10s"
  http:
    method: GET
@@ -65,23 +97,10 @@ targets:
        Content-Type:
          contains: "application/json"
      body:
-        - contains: "slideshow"
        - json:
            path: "$.slideshow.title"
            equals: "Sample Slide Show"

-  - name: "HTML 页面示例"
-    type: http
-    http:
-      url: "https://httpbin.org/html"
-    expect:
-      status: [200]
-      body:
-        - contains: "Moby-Dick"
-        - xpath:
-            path: "/html/body/h1/text()"
-            equals: "Herman Melville - Moby-Dick"
-
  - name: "Bun 脚本检查"
    type: cmd
    cmd:
@@ -106,145 +125,121 @@ targets:

 ### 配置说明

- **server**: 服务配置（均可省略，使用默认值）
-  - `host`: 监听地址，默认 `127.0.0.1`
-  - `port`: 监听端口，默认 `3000`
-  - `dataDir`: 数据目录，默认 `./data`，相对路径基于配置文件所在目录解析
- **runtime**: 运行时配置
-  - `maxConcurrentChecks`: 最大并发拨测数，默认 `20`
-  - `retention`: 历史数据保留时长，默认 `7d`，支持 `ms`/`s`/`m`/`h`/`d` 单位
- **defaults**: 全局默认值（均可省略）
-  - `interval`: 拨测间隔，默认 `30s`
-  - `timeout`: 超时时间，默认 `10s`
-  - `http`: HTTP 类型默认值
-    - `method`: HTTP 方法，默认 `GET`，必须使用大写枚举值，支持 `GET`、`HEAD`、`POST`、`PUT`、`PATCH`、`DELETE`、`OPTIONS`
-    - `maxBodyBytes`: 响应体最大字节数，默认 `100MB`
-    - `headers`: 默认请求头（target 中的 headers 会合并覆盖 defaults 中的同名头）
-  - `cmd`: Cmd 类型默认值
-    - `maxOutputBytes`: 输出最大字节数，默认 `100MB`
-    - `cwd`: 默认工作目录（相对于配置文件所在目录解析，默认 `.`）
- **targets**: 拨测目标列表（必填）
-  - `name`: 目标名称（必填，唯一）
-  - `type`: 目标类型，`http`、`cmd` 或 `db`（必填）
-  - `group`: 分组名称（可选，默认 `"default"`）
-  - `http`: HTTP 拨测配置（type 为 http 时必填）
-    - `url`: 目标 URL
-    - `method`、`headers`、`body`: 请求参数（`headers` 会与 `defaults.http.headers` 合并，target 优先）
-    - `ignoreSSL`: 是否忽略 HTTPS 证书校验，默认 `false`，用于自签名或私有证书服务
-    - `maxRedirects`: 最大重定向跟随次数，默认 `0`（不跟随重定向）
-  - `cmd`: 命令行拨测配置（type 为 cmd 时必填）
-    - `exec`: 可执行文件名或路径
-    - `args`: 命令行参数列表
-    - `env`: 环境变量覆盖（可选，继承进程环境变量并合并覆盖）
-    - `cwd`: 工作目录（可选，相对于配置文件所在目录解析，默认 `.`）
-  - `db`: 数据库拨测配置（type 为 db 时必填）
-    - `url`: 数据库连接字符串，支持 `postgres://`、`mysql://`、`sqlite://` 协议
-    - `query`: SQL 查询语句（可选，不配置时仅测试连接）
-  - `interval`、`timeout`: 覆盖全局默认值
-  - `expect`: 期望校验
-    - `status`: 可接受的状态码列表（HTTP），支持精确状态码和范围模式（如 `"2xx"`）混合配置；未指定时默认 `[200]`
-    - `exitCode`: 可接受的退出码列表（Cmd）；未指定时不校验退出码
-    - `headers`: 响应头校验（HTTP，支持字符串精确匹配或操作符对象）
-    - `maxDurationMs`: 最大耗时阈值（毫秒）
-      - HTTP：覆盖完整执行（含重定向、响应体读取和 expect 校验）
-      - Cmd：覆盖命令执行耗时（含 stdout/stderr 读取）
-    - `body`: HTTP 响应体校验（数组，可组合使用）
-      - `contains`: 响应体包含的文本
-      - `regex`: 响应体匹配的正则表达式（启动期会拒绝嵌套量词等存在 ReDoS 风险的模式）
-      - `json`: JSONPath 提取值比较
-        - `path`: JSONPath 表达式（必填，如 `$.slideshow.title`）
-        - 比较操作符（可选，无操作符时仅检查路径对应值是否存在）
-      - `css`: CSS 选择器提取 HTML 元素比较
-        - `selector`: CSS 选择器（必填）
-        - `attr`: 提取元素属性值而非文本内容（可选，如 `href`、`class`）
-        - 比较操作符（可选，无操作符时仅检查元素是否存在）
-      - `xpath`: XPath 提取 XML/HTML 节点比较
-        - `path`: XPath 表达式（必填，如 `/html/body/h1/text()`）
-        - 比较操作符（可选，无操作符时仅检查节点是否存在）
-    - `stdout` / `stderr`: Cmd 输出校验（数组，每项为一个操作符对象）
-    - `rowCount`: DB 查询返回行数校验（支持操作符对象）
-    - `rows`: DB 查询结果逐行校验（数组，每项为列名→操作符映射）
-    - 比较操作符：`equals`（默认）、`contains`、`match`（正则，启动期会拒绝存在 ReDoS 风险的模式）、`empty`、`exists`、`gte`、`lte`、`gt`、`lt`
+#### server — 服务配置（均可省略，使用默认值）

-大小说明：`maxBodyBytes` 和 `maxOutputBytes` 支持单位 `KB`、`MB`、`GB`，也可直接使用数字（非负安全整数字节数）。
+| 字段      | 说明                                       | 默认值      |
+| --------- | ------------------------------------------ | ----------- |
+| `host`    | 监听地址                                   | `127.0.0.1` |
+| `port`    | 监听端口                                   | `3000`      |
+| `dataDir` | 数据目录，相对路径基于配置文件所在目录解析 | `./data`    |

-配置校验：系统启动时会先用 TypeBox 生成的 JSON Schema 契约校验字段类型、必填字段、枚举、数组/对象形状和未知字段，再执行语义 validator 校验 target name 唯一性、URL、正则、JSONPath、XPath、size/duration 解析等规则。非法配置会阻止启动并输出中文错误信息。
+#### runtime — 运行时配置

-未知字段：除 `http.headers`、`defaults.http.headers`、`expect.headers`、`cmd.env` 等动态键值表外，未知字段会导致启动失败。配置备注请使用 YAML 注释，不要添加 `note`、`comment` 等未声明字段。
+| 字段                  | 说明                                             | 默认值 |
+| --------------------- | ------------------------------------------------ | ------ |
+| `maxConcurrentChecks` | 最大并发拨测数                                   | `20`   |
+| `retention`           | 历史数据保留时长，支持 `ms`/`s`/`m`/`h`/`d` 单位 | `7d`   |

-JSON Schema：仓库根目录导出 `probe-config.schema.json`，可在 YAML 文件顶部添加 `# yaml-language-server: $schema=./probe-config.schema.json` 获取编辑器提示和静态校验。该 schema 由运行期契约 fragments 生成，提交前可用 `bun run schema:check` 检查同步。
+#### defaults — 全局默认值（均可省略）

-时长格式支持：`500ms`、`30s`、`5m`、`2h`、`7d`
+| 字段                 | 说明                                                                 | 默认值  |
+| -------------------- | -------------------------------------------------------------------- | ------- |
+| `interval`           | 拨测间隔                                                             | `30s`   |
+| `timeout`            | 超时时间                                                             | `10s`   |
+| `http.method`        | HTTP 方法，支持 `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS` | `GET`   |
+| `http.maxBodyBytes`  | 响应体最大字节数                                                     | `100MB` |
+| `http.headers`       | 默认请求头（target 中的 headers 会合并覆盖同名头）                   | —       |
+| `cmd.maxOutputBytes` | 输出最大字节数                                                       | `100MB` |
+| `cmd.cwd`            | 默认工作目录（相对于配置文件所在目录）                               | `.`     |

-## API 端点
+#### targets — 拨测目标列表（必填）

-| 端点                                                              | 说明                                                         |
-| ----------------------------------------------------------------- | ------------------------------------------------------------ |
-| `GET /health`                                                     | 健康检查                                                     |
-| `GET /api/meta`                                                   | 运行时元信息（checker 类型列表）                             |
-| `GET /api/dashboard?window=24h&recentLimit=30`                    | Dashboard 首屏聚合数据（summary + targets）                  |
-| `GET /api/targets/:id/metrics?from=ISO&to=ISO&bucket=1h`          | 指定目标的统计、可靠性指标和按小时趋势                       |
-| `GET /api/targets/:id/history?from=ISO&to=ISO&page=1&pageSize=20` | 指定目标的拨测记录（时间范围 + 分页，`pageSize` 最大 `200`） |
+每个 target 的通用字段：

-### 响应字段
+| 字段       | 说明                          | 必填                 |
+| ---------- | ----------------------------- | -------------------- |
+| `name`     | 目标名称（全局唯一）          | 是                   |
+| `type`     | 目标类型：`http`、`cmd`、`db` | 是                   |
+| `group`    | 分组名称                      | 否，默认 `"default"` |
+| `interval` | 覆盖全局拨测间隔              | 否                   |
+| `timeout`  | 覆盖全局超时时间              | 否                   |

-**DashboardResponse**: `summary`、`targets`
+**HTTP 类型** (`type: http`)

-**DashboardResponse.summary**: `total`、`up`、`down`、`lastCheckTime`、`incidents`、`window`
+| 字段                | 说明                                    |
+| ------------------- | --------------------------------------- |
+| `http.url`          | 目标 URL                                |
+| `http.method`       | HTTP 方法（覆盖 defaults）              |
+| `http.headers`      | 请求头（与 defaults.http.headers 合并） |
+| `http.body`         | 请求体                                  |
+| `http.ignoreSSL`    | 忽略 HTTPS 证书校验，默认 `false`       |
+| `http.maxRedirects` | 最大重定向跟随次数，默认 `0`（不跟随）  |

-**MetaResponse**: `checkerTypes`（已注册 checker 类型标识符列表）
+**Cmd 类型** (`type: cmd`)

-**TargetStatus**: `id`、`name`、`type`（checker 类型，如 http/cmd/db）、`target`（URL、命令摘要或数据库连接摘要）、`group`、`interval`、`latestCheck`、`stats`、`currentStreak`、`recentSamples`
+| 字段       | 说明                                   |
+| ---------- | -------------------------------------- |
+| `cmd.exec` | 可执行文件名或路径                     |
+| `cmd.args` | 命令行参数列表                         |
+| `cmd.env`  | 环境变量覆盖（继承进程环境变量并合并） |
+| `cmd.cwd`  | 工作目录（相对于配置文件所在目录）     |

-**RecentSample**: `timestamp`、`durationMs`、`up`
+**DB 类型** (`type: db`)

-**CheckResult**: `timestamp`、`matched`、`durationMs`、`statusDetail`、`failure`
+| 字段       | 说明                                                          |
+| ---------- | ------------------------------------------------------------- |
+| `db.url`   | 数据库连接字符串，支持 `postgres://`、`mysql://`、`sqlite://` |
+| `db.query` | SQL 查询语句（不配置时仅测试连接）                            |

-**CheckFailure**: `kind`（error/mismatch）、`phase`、`path`、`message`、`expected?`（仅 mismatch）、`actual?`（仅 mismatch）
+#### expect — 期望校验

-**TargetStats**: `totalChecks`、`upChecks`、`downChecks`、`availability`
+| 字段                | 适用类型 | 说明                                                             |
+| ------------------- | -------- | ---------------------------------------------------------------- |
+| `status`            | HTTP     | 可接受的状态码列表，支持精确码和范围（如 `"2xx"`）；默认 `[200]` |
+| `exitCode`          | Cmd      | 可接受的退出码列表；未指定时不校验                               |
+| `headers`           | HTTP     | 响应头校验                                                       |
+| `maxDurationMs`     | 全部     | 最大耗时阈值（毫秒）                                             |
+| `body`              | HTTP     | 响应体校验（数组，可组合使用，见下方）                           |
+| `stdout` / `stderr` | Cmd      | 输出校验（数组，每项一个操作符对象）                             |
+| `rowCount`          | DB       | 查询返回行数校验（操作符对象）                                   |
+| `rows`              | DB       | 查询结果逐行校验（数组，列名→操作符映射）                        |

-**CurrentStreak**: `up`、`count`、`capped?`
+**body 校验项**（数组中可混合使用）：

-**TargetMetricsResponse**: `targetId`、`window`、`stats`、`trend`
+- `contains` — 响应体包含指定文本
+- `regex` — 正则匹配（启动期会拒绝存在 ReDoS 风险的模式）
+- `json` — JSONPath 提取值比较（`path` 必填，如 `$.slideshow.title`）
+- `css` — CSS 选择器提取 HTML 元素（`selector` 必填，`attr` 可选提取属性）
+- `xpath` — XPath 提取 XML/HTML 节点（`path` 必填，如 `/html/body/h1/text()`）

-**TargetMetricsResponse.stats**: `totalChecks`、`upChecks`、`downChecks`、`availability`、`avgDurationMs`、`p95DurationMs`、`p99DurationMs`、`mttr`、`longestOutage`、`incidentCount`、`currentStreak`
+**比较操作符**：`equals`（默认）、`contains`、`match`（正则）、`empty`、`exists`、`gte`、`lte`、`gt`、`lt`

-**TrendPoint**: `bucketStart`、`avgDurationMs`、`minDurationMs`、`maxDurationMs`、`availability`、`totalChecks`、`upChecks`、`downChecks`
+**大小说明**：`maxBodyBytes` 和 `maxOutputBytes` 支持 `KB`、`MB`、`GB` 单位，也可直接使用数字。

-**HistoryResponse**: `items`（CheckResult[]）、`total`、`page`、`pageSize`
+**时长格式**：`500ms`、`30s`、`5m`、`2h`、`7d`

-### 错误响应
+**JSON Schema**：仓库根目录导出 `probe-config.schema.json`，在 YAML 文件顶部添加 `# yaml-language-server: $schema=./probe-config.schema.json` 即可在编辑器中获得提示和校验。

-API 错误返回 `ApiErrorResponse` 格式：
-
-```json
-{ "error": "描述信息", "status": 400 }
-```
-
-| 状态码 | 触发场景                                                                                   |
-| ------ | ------------------------------------------------------------------------------------------ |
-| 400    | 参数格式错误（无效 ID、from/to 缺失或格式错误、page/pageSize 非正整数、pageSize 超过 200） |
-| 404    | 目标不存在、API 路由未匹配、非 GET 方法请求 API 路由                                       |
-
-## 运行参数
-
-CLI 只接受一个参数：YAML 配置文件路径。
-
-```bash
-./dist/dial-server ./probes.yaml
-```
+> **注意：** 配置校验在启动时执行，非法配置会阻止启动并输出错误信息。除动态键值表（`headers`、`env`）外，未知字段会导致启动失败，请使用 YAML 注释。

 ## 目标状态判定

-单层判定模型，适用于 HTTP 和 Cmd 两种类型：
+采用单层判定模型：

- **matched**: 是否符合 expect 规则（HTTP 未指定 `expect.status` 时默认检查 `[200]`）
- **UP** = matched
- **DOWN** = NOT matched
+- **UP** = 拨测结果符合 expect 规则
+- **DOWN** = 拨测结果不符合 expect 规则

-执行失败（网络错误、超时、进程崩溃）和 expect 不匹配都统一为 `matched=false`，通过 `failure.kind` 区分（`"error"` vs `"mismatch"`）。
+执行失败（网络错误、超时、进程崩溃）和 expect 不匹配都统一为 DOWN，通过 `failure.kind` 区分原因（`"error"` vs `"mismatch"`）。

---
+## 开发

-> 开发相关文档（项目结构、构建、测试、代码规范等）请参阅 [DEVELOPMENT.md](DEVELOPMENT.md)。
+```bash
+bun run check   # schema:check + typecheck + lint + test
+bun run verify  # check + build
+```
+
+开发相关文档（项目结构、构建、测试、代码规范等）请参阅 [DEVELOPMENT.md](DEVELOPMENT.md)。
+
+## License
+
+MIT
--- a/probes.example.yaml
+++ b/probes.example.yaml
@@ -48,34 +48,8 @@ targets:
        - json:
            path: "$.slideshow.slides[0].title"
            contains: "Wake"
-        - json:
-            path: "$.slideshow.slides[0].type"
-            equals: "all"
        - regex: '"title"'

-  - name: "HTML 页面 — CSS 选择器"
-    type: http
-    http:
-      url: "https://httpbin.org/html"
-    expect:
-      body:
-        - css:
-            selector: "h1"
-            contains: "Moby-Dick"
-        - css:
-            selector: "body"
-            exists: true
-
-  - name: "HTML 页面 — XPath 提取节点文本"
-    type: http
-    http:
-      url: "https://httpbin.org/html"
-    expect:
-      body:
-        - xpath:
-            path: "/html/body/h1/text()"
-            contains: "Melville"
-
  - name: "POST 接口测试"
    type: http
    http:
@@ -94,61 +68,6 @@ targets:
            path: "$.json.version"
            gte: 1

-  - name: "请求头验证"
-    type: http
-    http:
-      url: "https://httpbin.org/headers"
-      headers:
-        X-Custom-Header: "dial-server"
-    expect:
-      status: [200]
-      body:
-        - json:
-            path: "$.headers.X-Custom-Header"
-            equals: "dial-server"
-
-  - name: "响应头自定义校验"
-    type: http
-    http:
-      url: "https://httpbin.org/response-headers"
-      headers:
-        accept: "application/json"
-    expect:
-      body:
-        - json:
-            path: "$.Content-Type"
-            equals: "application/json"
-
-  - name: "多状态码允许"
-    type: http
-    http:
-      url: "https://httpbin.org/status/200"
-    expect:
-      status: [200, 201, 204]
-
-  - name: "状态码范围匹配"
-    type: http
-    http:
-      url: "https://httpbin.org/status/204"
-    expect:
-      status: ["2xx"]
-
-  - name: "自签名证书跳过 SSL"
-    type: http
-    http:
-      url: "https://internal.local/health"
-      ignoreSSL: true
-    expect:
-      status: ["2xx"]
-
-  - name: "跟随重定向"
-    type: http
-    http:
-      url: "https://httpbin.org/redirect/1"
-      maxRedirects: 5
-    expect:
-      status: [200]
-
  # ========== Cmd targets ==========

  - name: "Bun 版本输出匹配"
@@ -162,55 +81,6 @@ targets:
      stdout:
        - match: "^\\d+\\.\\d+\\.\\d+"

-  - name: "自定义文本输出"
-    type: cmd
-    cmd:
-      exec: "bun"
-      args: ["-e", "console.log('check ok')"]
-    expect:
-      stdout:
-        - equals: "check ok\n"
-      maxDurationMs: 3000
-
-  - name: "脚本执行无 stderr"
-    type: cmd
-    cmd:
-      exec: "bun"
-      args: ["-e", "process.stdout.write('ok')"]
-    expect:
-      exitCode: [0]
-      stderr:
-        - empty: true
-
-  - name: "日期脚本输出包含年份"
-    type: cmd
-    cmd:
-      exec: "bun"
-      args: ["-e", "console.log(new Date().getFullYear())"]
-    expect:
-      stdout:
-        - match: "^20\\d{2}\n?$"
-
-  - name: "环境变量覆盖"
-    type: cmd
-    cmd:
-      exec: "bun"
-      args: ["-e", "console.log(process.env.LANG ?? '')"]
-      env:
-        LANG: "C"
-    expect:
-      stdout:
-        - contains: "C"
-
-  - name: "运行平台非空输出"
-    type: cmd
-    cmd:
-      exec: "bun"
-      args: ["-e", "console.log(process.platform)"]
-    expect:
-      stdout:
-        - match: ".+"
-
  - name: "多规则 stdout 顺序校验"
    type: cmd
    interval: "5m"
@@ -243,16 +113,6 @@ targets:
    expect:
      maxDurationMs: 1000

-  - name: "SQLite 内存数据库查询行数"
-    type: db
-    db:
-      url: "sqlite://:memory:"
-      query: "SELECT 1 as cnt"
-    expect:
-      maxDurationMs: 1000
-      rowCount:
-        gte: 1
-
  - name: "SQLite 内存数据库多列结果校验"
    type: db
    db: