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
@@ -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 <你的仓库>
|
||||
cd shiroko-monitor
|
||||
|
||||
# 私有配置（不入库）：真实地址、API Key 等放这里
|
||||
cp local.monitors.json.example local.monitors.json # 或按下面提示自建
|
||||
# 私有配置（可选）：真实地址、API Key 等敏感信息放这里，不入库
|
||||
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>
|
||||
|
||||
启动后确认：
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user