lanyuanxiaoyao
599d973cbd
- 新增 body 分组校验：contains、regex、json（JSONPath）、css（CSS选择器）、xpath - 新增操作符系统：equals、contains、match、empty、exists、gte、lte、gt、lt - 新增 headers 响应头校验 - 引入 cheerio、xpath、@xmldom/xmldom 依赖 - BREAKING: expect.bodyContains 迁移至 expect.body.contains
203 lines
5.9 KiB
Markdown
203 lines
5.9 KiB
Markdown
# Gateway Checker
|
||
|
||
基于 Bun + TypeScript 的 HTTP 拨测监控工具。通过 YAML 配置文件定义拨测目标，后端按配置定时并发拨测，结果持久化到本地 SQLite，前端 Dashboard 展示各目标实时状态、可用率、延迟趋势等。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
src/
|
||
server/
|
||
app.ts Bun HTTP 路由（API + 静态资源 + SPA fallback）
|
||
config.ts CLI 参数解析
|
||
dev.ts 开发期启动入口
|
||
server.ts HTTP server 启动
|
||
checker/
|
||
types.ts 类型定义
|
||
config-loader.ts YAML 配置解析与校验
|
||
store.ts SQLite 数据存储
|
||
fetcher.ts HTTP 拨测执行
|
||
engine.ts 调度引擎（按 interval 分组、组内并发）
|
||
shared/
|
||
api.ts 前后端共享 TypeScript 类型
|
||
web/ Vite + React 前端 Dashboard
|
||
components/ UI 组件
|
||
hooks/ 数据轮询 hooks
|
||
scripts/ 开发、构建和 smoke test 脚本
|
||
tests/ Bun test 测试
|
||
openspec/ OpenSpec 变更与规格文档
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
bun install
|
||
cp probes.example.yaml probes.yaml
|
||
bun run dev probes.yaml
|
||
```
|
||
|
||
`bun run dev` 会同时启动 Bun 后端和 Vite 前端。开发期请打开 Vite 前端地址 `http://127.0.0.1:5173`。
|
||
|
||
也可以分别运行：
|
||
|
||
```bash
|
||
bun run dev:server probes.yaml
|
||
bun run dev:web
|
||
```
|
||
|
||
## 配置文件
|
||
|
||
程序通过 YAML 配置文件定义所有运行参数：
|
||
|
||
```yaml
|
||
server:
|
||
host: "127.0.0.1"
|
||
port: 3000
|
||
dataDir: "./data"
|
||
|
||
defaults:
|
||
interval: "30s"
|
||
timeout: "10s"
|
||
method: "GET"
|
||
|
||
targets:
|
||
- name: "示例服务"
|
||
url: "https://httpbin.org/get"
|
||
interval: "60s"
|
||
|
||
- name: "POST 检查"
|
||
url: "https://httpbin.org/post"
|
||
method: "POST"
|
||
headers:
|
||
Content-Type: "application/json"
|
||
body: '{"ping": true}'
|
||
expect:
|
||
status: [200]
|
||
maxLatencyMs: 5000
|
||
|
||
- name: "JSON API 监控"
|
||
url: "https://httpbin.org/json"
|
||
expect:
|
||
status: [200]
|
||
headers:
|
||
Content-Type: application/json
|
||
body:
|
||
contains: "slideshow"
|
||
json:
|
||
$.slideshow.title: "Sample Slide Show"
|
||
|
||
- name: "HTML 页面监控"
|
||
url: "https://httpbin.org/html"
|
||
expect:
|
||
status: [200]
|
||
body:
|
||
css:
|
||
"h1": "Herman Melville - Moby-Dick"
|
||
xpath:
|
||
"/html/body/h1/text()": "Herman Melville - Moby-Dick"
|
||
```
|
||
|
||
### 配置说明
|
||
|
||
- **server**: 服务配置（均可省略，使用默认值）
|
||
- `host`: 监听地址，默认 `127.0.0.1`
|
||
- `port`: 监听端口，默认 `3000`
|
||
- `dataDir`: 数据目录，默认 `./data`
|
||
- **defaults**: 全局默认值（均可省略）
|
||
- `interval`: 拨测间隔，默认 `30s`
|
||
- `timeout`: 请求超时，默认 `10s`
|
||
- `method`: HTTP 方法，默认 `GET`
|
||
- `headers`: 全局 headers
|
||
- **targets**: 拨测目标列表（必填）
|
||
- `name`: 目标名称（必填，唯一）
|
||
- `url`: 目标 URL（必填）
|
||
- `method`、`headers`、`body`: 请求参数
|
||
- `interval`、`timeout`: 覆盖全局默认值
|
||
- `expect`: 期望校验
|
||
- `status`: 可接受的状态码列表
|
||
- `headers`: 响应头校验（键值对，全部匹配）
|
||
- `maxLatencyMs`: 最大延迟阈值（毫秒）
|
||
- `body`: 响应体校验（可组合使用）
|
||
- `contains`: 响应体包含的文本
|
||
- `regex`: 响应体匹配的正则表达式
|
||
- `json`: JSONPath 提取值比较（路径 → 期望值）
|
||
- `css`: CSS 选择器提取 HTML 元素比较（选择器 → 期望值，可选 `attr` 提取属性）
|
||
- `xpath`: XPath 提取 XML/HTML 节点比较（路径 → 期望值）
|
||
- body 比较支持操作符：`equals`（默认）、`contains`、`match`（正则）、`empty`、`exists`、`gte`、`lte`、`gt`、`lt`
|
||
|
||
时长格式支持：`30s`、`5m`、`500ms`
|
||
|
||
## API 端点
|
||
|
||
| 端点 | 说明 |
|
||
| --------------------------------------- | ---------------------------------------------------- |
|
||
| `GET /health` | 健康检查 |
|
||
| `GET /api/summary` | 总览统计（total/up/down/avgLatencyMs/lastCheckTime） |
|
||
| `GET /api/targets` | 目标列表及最新状态和统计摘要 |
|
||
| `GET /api/targets/:id/history?limit=20` | 指定目标的最近 N 条拨测记录 |
|
||
| `GET /api/targets/:id/trend?hours=24` | 指定目标的按小时聚合趋势 |
|
||
|
||
## 代码质量
|
||
|
||
```bash
|
||
bun run lint
|
||
bun run format:check
|
||
bun run format
|
||
bun run check
|
||
```
|
||
|
||
- `check` 依次运行 `typecheck`、`lint`、`format:check` 和单元测试。
|
||
|
||
## 构建 executable
|
||
|
||
```bash
|
||
bun run build
|
||
```
|
||
|
||
构建流程：
|
||
|
||
1. 运行 `vite build`，输出前端资源到 `dist/web`
|
||
2. 生成临时 `.build/static-assets.ts`，嵌入 Vite 产物
|
||
3. 生成临时 `.build/server-entry.ts`，作为生产入口
|
||
4. 运行 `Bun.build({ compile })`，输出 `dist/gateway-checker`
|
||
|
||
运行 executable：
|
||
|
||
```bash
|
||
./dist/gateway-checker probes.yaml
|
||
```
|
||
|
||
## 运行参数
|
||
|
||
CLI 只接受一个参数：YAML 配置文件路径。
|
||
|
||
```bash
|
||
./dist/gateway-checker ./probes.yaml
|
||
```
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
bun run check
|
||
bun run verify
|
||
```
|
||
|
||
- `check` 适合日常开发，包含类型检查、lint、格式检查和单元测试。
|
||
- `verify` 先运行 `check`，再重新构建生产 executable 并运行 smoke test。
|
||
|
||
## 前后端边界
|
||
|
||
前端只通过 HTTP 调用后端，API 路径为 `/api/*`。共享类型放在 `src/shared`，前端不得 import `src/server` 的运行时实现。
|
||
|
||
## 目标状态判定
|
||
|
||
两层判定模型：
|
||
|
||
- **success**: 请求是否成功完成（收到 HTTP 响应）
|
||
- **matched**: 是否符合 expect 规则（无 expect 时默认为 true）
|
||
- **UP** = success AND matched
|
||
- **DOWN** = NOT success OR NOT matched
|
||
|
||
## 已知限制
|
||
|
||
当前不做告警通知、数据自动清理、拨测目标动态增删、认证鉴权和分布式部署。
|