shiroko-monitor/docs/DEPLOY-LOCAL.md

本地运行指南

全部跑在自己机器上：探针、面板、管理端都在 http://localhost:8787。

零依赖 —— 不需要 npm install，只用 Node 自带模块。

---

最短路径（三条命令）

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. 常驻（默认）

node prober/node/index.js

按各目标自己的 interval 持续探测，Ctrl+C 停止。适合长期使用。

2. 跑一轮就退（CI 用）

node prober/node/index.js --once

探测一轮、写出 public/status.json 后退出。

3. 演示数据（不想真探测）

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 数组：

{
  "id": "my-site",              // 唯一标识，改了会丢失该目标的历史
  "name": "我的站点",// 显示名
  "group": "生产环境",// 分组（面板按它分页签）
  "type": "http",// http | tcp | banner
  "url": "https://example.com",
  "expectStatus": [200],        // 哪些状态码算正常
  "interval": 60,// 探测间隔（秒）
  "timeout": 10                 // 超时（秒）
}

TCP 与 banner 类型：

{ "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 可选，不存在也能跑。要用时自建：

{
  "_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 即可。

// 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。

# 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 推送，写在 local.monitors.json：

{
  "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昵称" }
      }
    }
  }
}

配好后自检一下：

node prober/node/index.js --test-notify

---

开机自启（可选）

macOS / Linux（systemd）

# /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

sudo systemctl enable --now shiroko-monitor
sudo journalctl -u shiroko-monitor -f

Windows（NSSM）

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。目标多、心率历史长时会略增。