fix: 零配置克隆可直接看到数据 + 新增本地运行文档
实测「全新克隆 → node prober/node/index.js」时发现两个问题： 1. **面板是空的**（新手陷阱） public/monitors.json 默认 dataFilter=uptimerobot，但 uptimeRobot.enabled=false （API Key 放在不入库的 local.monitors.json 里）。新克隆的用户没有私有配置， 于是日志显示「探测范围: uptimerobot —— 仅 UptimeRobot（0 个）」，面板永远空白。 改默认为 dataFilter=both：零配置时探测 8 个示例目标，配了 UR 再自行切换口径。 2. DEPLOY-PAGES.md 里写了 `cp local.monitors.json.example` —— 该文件根本不存在。 改成直接启动 + 用 <details> 折叠说明可选的私有配置写法。 另外： - package.json 版本号从 0.1.0 同步到 0.12.3（此前一直漏更） - 新增 docs/DEPLOY-LOCAL.md：最短路径（3 条命令）、三种运行模式、常用参数、 配置示例（http/tcp/banner）、配置分层说明、UptimeRobot 接入、 管理端 2FA 绑定四步、通知配置、开机自启（systemd + NSSM）、八条常见问题 - README 加「本地运行」入口，指向两份部署文档 实测验证：干净克隆 + 默认配置 → 8 个目标、5 在线 3 离线，心率图与事件区块均有数据。
This commit is contained in:
tamakyi
@@ -822,6 +822,23 @@ node prober/node/index.js
|
|||||||
- [ ] 面板：更多形态（如时间线视图、地图视图）、明暗主题手动切换、可用率区间可配置（7/30/90 天）
|
- [ ] 面板：更多形态（如时间线视图、地图视图）、明暗主题手动切换、可用率区间可配置（7/30/90 天）
|
||||||
- [ ] 状态页 JSON API 的 CORS 开放与缓存策略细化
|
- [ ] 状态页 JSON API 的 CORS 开放与缓存策略细化
|
||||||
|
|
||||||
|
## 本地运行
|
||||||
|
|
||||||
|
**零依赖，不需要 `npm install`**：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/tamakyi/shiroko-monitor.git
|
||||||
|
cd shiroko-monitor
|
||||||
|
node prober/node/index.js
|
||||||
|
```
|
||||||
|
|
||||||
|
打开 <http://localhost:8787/>（管理端在 `/admin`）。要求 Node.js ≥ 18。
|
||||||
|
|
||||||
|
改 `public/monitors.json` 里的 `monitors` 即可添加自己的目标，**文件会被自动热重载，不用重启**。
|
||||||
|
|
||||||
|
- 完整说明（三种运行模式 / 配置分层 / 开机自启 / 常见问题）→ **[docs/DEPLOY-LOCAL.md](docs/DEPLOY-LOCAL.md)**
|
||||||
|
- 面板部署到 GitHub Pages → **[docs/DEPLOY-PAGES.md](docs/DEPLOY-PAGES.md)**
|
||||||
|
|
||||||
## 开发
|
## 开发
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|||||||
@@ -0,0 +1,282 @@
|
|||||||
|
# 本地运行指南
|
||||||
|
|
||||||
|
全部跑在自己机器上：探针、面板、管理端都在 `http://localhost:8787`。
|
||||||
|
|
||||||
|
**零依赖** —— 不需要 `npm install`，只用 Node 自带模块。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 最短路径（三条命令）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/tamakyi/shiroko-monitor.git
|
||||||
|
cd shiroko-monitor
|
||||||
|
node prober/node/index.js
|
||||||
|
```
|
||||||
|
|
||||||
|
打开 <http://localhost:8787/> 就能看到面板（内置了 8 个示例目标，第一次启动后约一分钟内有数据）。
|
||||||
|
|
||||||
|
要求：**Node.js ≥ 18**（`node -v` 查看）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 启动后有什么
|
||||||
|
|
||||||
|
| 地址 | 用途 |
|
||||||
|
| --- | --- |
|
||||||
|
| <http://localhost:8787/> | 公开面板（只读） |
|
||||||
|
| <http://localhost:8787/admin> | 管理端（需先绑定 2FA） |
|
||||||
|
| <http://localhost:8787/api/status> | 状态快照（JSON） |
|
||||||
|
|
||||||
|
启动日志会告诉你当前的探测范围与数据源，例如：
|
||||||
|
|
||||||
|
```
|
||||||
|
shiroko-monitor v0.12.3
|
||||||
|
面板: http://localhost:8787/
|
||||||
|
管理后台: http://localhost:8787/admin （仅本机可访问；需远程访问请设 settings.admin.allowRemote=true）
|
||||||
|
展示口径: both 探测范围: all —— 全部（自建 8 个）
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三种运行模式
|
||||||
|
|
||||||
|
### 1. 常驻（默认）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node prober/node/index.js
|
||||||
|
```
|
||||||
|
|
||||||
|
按各目标自己的 `interval` 持续探测，Ctrl+C 停止。**适合长期使用。**
|
||||||
|
|
||||||
|
### 2. 跑一轮就退（CI 用）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node prober/node/index.js --once
|
||||||
|
```
|
||||||
|
|
||||||
|
探测一轮、写出 `public/status.json` 后退出。
|
||||||
|
|
||||||
|
### 3. 演示数据（不想真探测）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node prober/node/index.js --once --demo
|
||||||
|
```
|
||||||
|
|
||||||
|
生成一份假的状态快照，用于静态部署的首版占位。
|
||||||
|
|
||||||
|
### 常用参数
|
||||||
|
|
||||||
|
| 参数 | 作用 |
|
||||||
|
| --- | --- |
|
||||||
|
| `--config=<path>` | 指定公开配置（默认 `public/monitors.json`） |
|
||||||
|
| `--local-config=<path>` | 指定私有配置（默认 `local.monitors.json`） |
|
||||||
|
| `--out=<path>` | 指定快照输出（默认 `public/status.json`） |
|
||||||
|
| `--data-dir=<path>` | 指定私有数据目录（默认 `./data`，存通知去抖状态与事件） |
|
||||||
|
| `--test-notify` | 给所有已启用渠道发一条测试消息 |
|
||||||
|
| `PORT=9000 node prober/node/index.js` | 换端口（`PORT` 是环境变量，不是参数） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 配置自己的监控目标
|
||||||
|
|
||||||
|
编辑 `public/monitors.json` 的 `monitors` 数组：
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
{
|
||||||
|
"id": "my-site", // 唯一标识，改了会丢失该目标的历史
|
||||||
|
"name": "我的站点",// 显示名
|
||||||
|
"group": "生产环境",// 分组（面板按它分页签）
|
||||||
|
"type": "http",// http | tcp | banner
|
||||||
|
"url": "https://example.com",
|
||||||
|
"expectStatus": [200], // 哪些状态码算正常
|
||||||
|
"interval": 60,// 探测间隔（秒）
|
||||||
|
"timeout": 10 // 超时（秒）
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
TCP 与 banner 类型：
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
{ "id": "db-5432", "name": "数据库", "type": "tcp", "host": "10.0.0.5", "port": 5432, "interval": 60 }
|
||||||
|
{ "id": "ssh", "name": "SSH", "type": "banner", "host": "10.0.0.6", "port": 22,
|
||||||
|
"expectBanner": "^SSH-2.0", "timeout": 10 }// 匹配标识串正则
|
||||||
|
```
|
||||||
|
|
||||||
|
改完**自动热重载**（监听文件变化，约 200ms 生效），不用重启。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 配置怎么分层
|
||||||
|
|
||||||
|
| 文件 | 是否入库 | 放什么 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `public/monitors.json` | ✅ | 目标定义、非敏感设置（会随 GitHub Pages 公开） |
|
||||||
|
| `local.monitors.json` | ❌（`.gitignore`） | 真实地址、`apiKey`、私有覆盖 |
|
||||||
|
|
||||||
|
`local.monitors.json` **可选**，不存在也能跑。要用时自建：
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
{
|
||||||
|
"_comment": "按 id 覆盖 public/monitors.json 的同名条目，或覆盖 settings",
|
||||||
|
"settings": {
|
||||||
|
"uptimeRobot": { "enabled": true, "apiKey": "ur1769665-...", "pollIntervalSec": 300 },
|
||||||
|
"probeScope": "all"
|
||||||
|
},
|
||||||
|
"monitors": [
|
||||||
|
{ "id": "example-com", "url": "https://real-host.internal" } // 只写要覆盖的字段
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> ⚠️ **API Key 绝不要写进 `public/monitors.json`** —— 它会随 Pages 部署公开。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 接UptimeRobot
|
||||||
|
|
||||||
|
项目支持把UptimeRobot 上已有的监控结果接进来（作为「异地探测视角」与自建探测并列展示）。**只读**，用 `ur` 开头的只读 Key 即可。
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
// local.monitors.json
|
||||||
|
{
|
||||||
|
"settings": {
|
||||||
|
"uptimeRobot": {
|
||||||
|
"enabled": true,
|
||||||
|
"apiKey": "ur1769665-xxxxxxxx",
|
||||||
|
"pollIntervalSec": 300
|
||||||
|
},
|
||||||
|
"probeScope": "uptimerobot" // 只同步 UR，不探测本地配置的目标
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
也可以直接用环境变量：`UPTIMEROBOT_API_KEY=ur... node prober/node/index.js`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 启用管理端（可选）
|
||||||
|
|
||||||
|
管理端能改配置、加维护窗口、发通知自检。**必须先绑定 2FA。**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Windows PowerShell
|
||||||
|
$env:SHIROKO_ADMIN_SETUP_KEY='换成一串足够长的随机口令'
|
||||||
|
node prober/node/index.js
|
||||||
|
|
||||||
|
# macOS / Linux
|
||||||
|
export SHIROKO_ADMIN_SETUP_KEY='换成一串足够长的随机口令'
|
||||||
|
node prober/node/index.js
|
||||||
|
```
|
||||||
|
|
||||||
|
打开 <http://localhost:8787/admin>，四步绑定：
|
||||||
|
|
||||||
|
1. 输入 `SHIROKO_ADMIN_SETUP_KEY` → 生成密钥
|
||||||
|
2. 用验证器 App 扫码（或手动输入密钥 / 复制 `otpauth://` 链接）
|
||||||
|
3. 输入 App 显示的 6 位码 → 完成绑定
|
||||||
|
4. **保存 10 枚恢复码**（只显示这一次）
|
||||||
|
|
||||||
|
之后每次进入管理界面都要输 6 位动态码或一枚恢复码。
|
||||||
|
|
||||||
|
> 不设 `SHIROKO_ADMIN_SETUP_KEY` 时绑定入口直接关闭，管理端处于「完全不可用」状态 —— 这是安全的默认值。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 通知（可选）
|
||||||
|
|
||||||
|
支持邮件（SMTP）与 [MeoW](https://www.chuckfang.com/MeoW/api_doc.html) 推送，写在 `local.monitors.json`：
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
{
|
||||||
|
"settings": {
|
||||||
|
"notify": {
|
||||||
|
"enabled": true,
|
||||||
|
"failureThreshold": 2,// 连续失败几次才告警
|
||||||
|
"recoveryNotify": true, // 恢复时也通知
|
||||||
|
"quietHours": "23:00-08:00",// 静默时段（不打扰）
|
||||||
|
"channels": {
|
||||||
|
"email": {
|
||||||
|
"enabled": true,
|
||||||
|
"host": "smtp.example.com",
|
||||||
|
"port": 465,
|
||||||
|
"secure": true, // 465 隐式 TLS；587 用 STARTTLS
|
||||||
|
"user": "[email protected]",
|
||||||
|
"pass": "授权码",
|
||||||
|
"from": "[email protected]",
|
||||||
|
"to": ["[email protected]"]
|
||||||
|
},
|
||||||
|
"meow": { "enabled": false, "nickname": "你的MeoW昵称" }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
配好后自检一下：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node prober/node/index.js --test-notify
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 开机自启（可选）
|
||||||
|
|
||||||
|
**macOS / Linux（systemd）**
|
||||||
|
|
||||||
|
```ini
|
||||||
|
# /etc/systemd/system/shiroko-monitor.service
|
||||||
|
[Unit]
|
||||||
|
Description=shiroko-monitor
|
||||||
|
After=network-online.target
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
WorkingDirectory=/opt/shiroko-monitor
|
||||||
|
ExecStart=/usr/bin/node prober/node/index.js
|
||||||
|
Restart=always
|
||||||
|
RestartSec=5
|
||||||
|
Environment=SHIROKO_ADMIN_SETUP_KEY=你的口令
|
||||||
|
Environment=SHIROKO_DATA_DIR=/var/lib/shiroko
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=multi-user.target
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo systemctl enable --now shiroko-monitor
|
||||||
|
sudo journalctl -u shiroko-monitor -f
|
||||||
|
```
|
||||||
|
|
||||||
|
**Windows（NSSM）**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
nssm install ShirokoMonitor "C:\Program Files\nodejs\node.exe" "C:\shiroko-monitor\prober\node\index.js"
|
||||||
|
nssm set ShirokoMonitor AppDirectory C:\shiroko-monitor
|
||||||
|
nssm set ShirokoMonitor AppEnvironmentExtra SHIROKO_ADMIN_SETUP_KEY=你的口令
|
||||||
|
nssm start ShirokoMonitor
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 常见问题
|
||||||
|
|
||||||
|
**面板一直显示「等待检测」**
|
||||||
|
第一次启动后需要等第一轮探测完成（按各目标的 `interval`，最长可能几分钟）。看日志确认探测范围。
|
||||||
|
|
||||||
|
**面板是空的**
|
||||||
|
检查日志里的「探测范围」。若显示「仅 UptimeRobot（0 个）」说明你把 `dataFilter` 设成了 `uptimerobot` 但没配 API Key —— 把它改成 `both`，或配置 `uptimeRobot.apiKey`。
|
||||||
|
|
||||||
|
**想改端口**
|
||||||
|
`PORT=9000 node prober/node/index.js`（环境变量，不是命令行参数）。
|
||||||
|
|
||||||
|
**端口被占用**
|
||||||
|
`PORT=9000 node prober/node/index.js` 换一个。
|
||||||
|
|
||||||
|
**改了配置没生效**
|
||||||
|
文件监听有 200ms 防抖，稍等即可；若是 `local.monitors.json`，确认 JSON 格式正确（尾逗号会导致解析失败，此时日志会打印 `[config] 重载失败`）。
|
||||||
|
|
||||||
|
**数据存在哪**
|
||||||
|
`public/status.json`（快照，会入库）与 `data/`（通知去抖状态、事件时间线、2FA 档案，不入库）。换机器时前者可以不带。
|
||||||
|
|
||||||
|
**内存占用**
|
||||||
|
常驻约 60–80 MB RSS。目标多、心率历史长时会略增。
|
||||||
+22
-2
@@ -34,11 +34,31 @@
|
|||||||
git clone <你的仓库>
|
git clone <你的仓库>
|
||||||
cd shiroko-monitor
|
cd shiroko-monitor
|
||||||
|
|
||||||
# 私有配置（不入库）：真实地址、API Key 等放这里
|
# 私有配置（可选）：真实地址、API Key 等敏感信息放这里，不入库
|
||||||
cp local.monitors.json.example local.monitors.json # 或按下面提示自建
|
|
||||||
node prober/node/index.js
|
node prober/node/index.js
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>想用私有配置文件？</summary>
|
||||||
|
|
||||||
|
`local.monitors.json` 是可选的，不存在也能跑（会直接用 `public/monitors.json`）。
|
||||||
|
需要拆分敏感信息时自建即可，结构如下：
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
// local.monitors.json（已在 .gitignore 中）
|
||||||
|
{
|
||||||
|
"_comment": "按 id 覆盖 public/monitors.json 的同名条目，或覆盖 settings",
|
||||||
|
"settings": {
|
||||||
|
"uptimeRobot": { "enabled": true, "apiKey": "ur...", "pollIntervalSec": 300 },
|
||||||
|
"probeScope": "all"
|
||||||
|
},
|
||||||
|
"monitors": [
|
||||||
|
{ "id": "example-com", "url": "https://real-internal-host.example" }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
启动后确认：
|
启动后确认：
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|||||||
+2
-2
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"name": "shiroko-monitor",
|
"name": "shiroko-monitor",
|
||||||
"version": "0.1.0",
|
"version": "0.12.3",
|
||||||
"description": "轻量级服务监控面板：纯静态前端 + Node/边缘探针，支持 HTTP 与 TCP 探测",
|
"description": "轻量级服务监控面板：纯静态前端 + Node/边缘探针，支持 HTTP/TCP 探测、UptimeRobot 数据源与 2FA 管理端",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"start": "node prober/node/index.js",
|
"start": "node prober/node/index.js",
|
||||||
|
|||||||
@@ -6,7 +6,7 @@
|
|||||||
"theme": "shiroko",
|
"theme": "shiroko",
|
||||||
"artwork": "assets/shiroko-figure.webp",
|
"artwork": "assets/shiroko-figure.webp",
|
||||||
"decoOpacity": 0.78,
|
"decoOpacity": 0.78,
|
||||||
"dataFilter": "uptimerobot",
|
"dataFilter": "both",
|
||||||
"refreshInterval": 300,
|
"refreshInterval": 300,
|
||||||
"dataSource": "auto",
|
"dataSource": "auto",
|
||||||
"adminUrl": "",
|
"adminUrl": "",
|
||||||
|
|||||||
+1415
-570
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user