# 本地运行指南

全部跑在自己机器上：探针、面板、管理端都在 `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": "ops@example.com",
          "pass": "授权码",
          "from": "ops@example.com",
          "to": ["ops@example.com"]
        },
        "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。目标多、心率历史长时会略增。