NodeNanny

# NodeNanny

**你只管买服务器，剩下的 NodeNanny 全程盯着。**

> **三句话说明（写给完全不懂技术的人）**
> 1. 你花几十块钱买一台"服务器"（VPS），装好代理软件，自己一个人用，比用来路不明的免费 App 更私密安全；
> 2. 但服务器这东西会时不时抽风（进程崩了、协议被识别），普通人不知道怎么发现、更不知道怎么修；
> 3. NodeNanny 就是帮你盯着这台服务器的"管家"：它挂了会自动重启、会发邮件告诉你、还有个网页能随时看看它状态好不好——你不需要看懂任何一行代码。

NodeNanny 是一个给"想自建代理节点，但不懂运维"的普通人用的自动看护工具。它不负责帮你部署节点（一键脚本已经做得很好了），而是负责节点部署之后的事：存活监控、自动重启、异常邮件通知、一个能看懂的状态面板。它不挑具体协议——**Xray、sing-box、v2ray、Shadowsocks、Trojan** 或任何其他代理软件都行，因为它只检测某个端口通不通、然后执行你指定的重启命令，完全不关心这个端口上跑的实际是什么。

如果你现在的状态是"听说过'自己搭梯子'这回事，但连服务器都还没有、也没碰过命令行"，建议先看下面「新手准备」这两节，其他偏技术的部分可以先跳过，等真的卡住了再回来查。

|  |  |
|---|---|
| **是什么** | 给单个自建代理节点用的存活"保姆"——监控、自动重启、异常告警、状态面板 |
| **支持哪些软件** | 任何代理软件都行（Xray、sing-box、v2ray、Shadowsocks、Trojan……）——设计上就不挑协议 |
| **给谁用** | 一个人、一台服务器、不需要运维背景——**不是**多用户/多节点面板（见下面「这不是什么」） |
| **费用** | 0元——只需要你本来就要付的服务器费用，没有NodeNanny账号，不依赖任何付费服务 |
| **需要什么** | 一台月租约几十元的VPS（Ubuntu/Debian）、5分钟命令行操作，仅此而已 |
| **技术栈** | Node.js + PM2 + 纯JSON文件存储——不需要数据库，不需要Docker |
| **面板支持语言** | 中文、英文、日文、德文、俄文 |
| **开源协议** | MIT |

## 这不是什么

- 不是机场面板（Marzban、3X-UI、Remnawave 已经做得很好，正面竞争没有意义）
- 不是节点池聚合工具
- 不面向机场主和企业用户

如果你要管理很多节点、很多用户，请去用 [Remnawave](https://remna.st/) 或 [Marzban](https://github.com/Gozargah/Marzban)。NodeNanny 只服务"一台服务器、一个节点、一个不太懂技术的人"这个场景。

## 新手准备一：需要准备什么

这是一份诚实、完整的清单，建议在跑安装脚本之前先通读一遍，免得装到一半才发现少东西。

**必须要有，没有绕不开：**
- **一台 VPS（云服务器）**——具体去哪买见下一节，最便宜那一档（大约 1 核 CPU / 1G 内存）就够用。
- **自己电脑上的一个终端**，用来 SSH 连接服务器。macOS/Linux 自带；Windows 10/11 也自带（PowerShell / Windows 终端），不需要额外装软件。
- **VPS 的 IP 地址、用户名（几乎总是 `root`）、密码**——这三样是服务商给你的全部凭证，也是登录唯一需要的东西。

**可选，只有想用对应功能才需要——安装脚本会逐一问你，不确定的话都可以先跳过，以后随时回来补：**
- **一个支持 SMTP 的邮箱账号**，如果你想要节点异常时收邮件通知。这是目前对不懂技术的人来说体验确实还不够友好的一步，具体原因和我们做了什么来减轻这一点，见下面专门的「配置 SMTP」一节。
- **一个 Anthropic 或 OpenAI 的 API Key**，如果你想用可选的 AI 故障诊断功能。用的是**你自己**申请的 Key，费用记在你自己账号上，NodeNanny 不经手也不代收费用。可以在 [console.anthropic.com](https://console.anthropic.com/) 或 [platform.openai.com](https://platform.openai.com/) 申请。
- **一个 GitHub 个人访问令牌（personal access token）**，如果你想用可选的"流量池候选来源发现"这个自愈实验功能（见下面专门一节）。**不勾选任何权限（zero scopes）**的令牌就够用，只是用来提高你的 GitHub API 请求额度，不会访问任何私有内容。生成方式：`github.com → Settings → Developer settings → Personal access tokens → Tokens (classic)`。
- **一键装节点脚本（比如 233boy 的 Xray 安装脚本）给你的真实订阅地址**，如果你想让"流量池自动切换"这个功能生效。如果你在装 NodeNanny 时用了内置的"自动装 Xray"这一步，这个地址 NodeNanny 已经自动拿到了，不用自己再去找。

以上这些东西本身都不需要额外花钱（VPS 服务商收服务器的钱是显然的，但 NodeNanny 的每一个功能本身免费，也不需要注册任何 NodeNanny 账号）。

## 新手准备二：还没有服务器？

NodeNanny 本身不卖服务器，你需要自己先买一台"VPS"（虚拟专用服务器，本质就是一台你能远程操作、只属于你自己的电脑）。最低限度需要知道这几点：

- **去哪买**：搜"VPS"或"云服务器"，国内外都有很多服务商（例如雨云、搬瓦工 RackNerd 之类），随便一家口碑正常的都可以，不需要货比三十家。
- **买什么配置**：这个用途对性能要求很低，最便宜的那一档（通常 1 核 CPU、1G 内存左右）完全够用，不用为了"保险"多花钱升配置。
- **地区怎么选**：选一个网络出口离你物理位置近、或者服务商标注"线路优化"的地区，具体选哪个对新手不重要，选错了也可以换。
- **系统选什么**：下单时会让你选操作系统，选 **Ubuntu 22.04** 或 **24.04** 就行（NodeNanny 支持 Ubuntu 20.04/22.04/24.04、Debian 11/12，选不到就选 Debian 12 也一样）。
- **买完你会拿到什么**：一个 IP 地址、一个用户名（几乎总是 `root`）、一个密码（有的服务商是发到邮箱，有的是在后台"登录信息/重置密码"页面里）。这三样东西是你接下来唯一需要的凭证，**不要把它们发给任何自称"帮你部署"的陌生人或来源不明的工具**。

买好之后就有了一台"空白"的服务器，接下来需要连上去才能跑安装脚本，见下一节。

## 新手准备三：怎么连接服务器（SSH）

服务器没有屏幕和键盘，你需要在自己电脑上打开一个"终端"程序，通过 SSH 这种方式远程登录进去操作，跟点鼠标操作软件不是一回事，但只需要学会输一行命令。

**Windows 用户**：
1. 按下 `Win` 键，搜索并打开「终端」或「PowerShell」（Windows 10/11 都自带，不需要额外安装）。
2. 输入（把 `你的服务器IP` 换成你买 VPS 时拿到的那个 IP 地址）：
   ```bash
   ssh root@你的服务器IP
   ```
3. 第一次连接会提示一段"是否信任这台主机"的英文，输入 `yes` 回车。
4. 提示输入密码时直接粘贴（终端里粘贴密码通常不会显示任何字符，这是正常的，不是没生效，输完直接回车）。

**Mac 用户**：
1. 按 `Command + 空格`，搜索并打开「终端 / Terminal」（macOS 自带）。
2. 后面步骤和 Windows 完全一样，同样是 `ssh root@你的服务器IP`。

连接成功后，命令行提示符会变成类似 `root@your-server:~#` 的样子，这就说明你已经在服务器里面了，接下来就可以照下面「安装」一节的命令走了。

> 如果连接时提示 `Connection refused` 或 `timed out`：多半是服务器还没启动完成（刚买的机器有时候要等几分钟）或者 IP 地址抄错了，先检查一下，过几分钟再试。

## 它做什么

- **存活监控**：每隔几分钟检测一次节点端口是否连通
- **自动重启**：检测到异常，自动执行重启命令
- **邮件通知**：节点挂了发邮件，恢复了也发邮件，不用你一直盯着
- **状态面板**：网页打开就能看到节点状态、稳定运行了多久、最近发生了什么，支持中/英/日/德/俄五种语言
- **AI 故障诊断（可选）**：节点持续异常时，用你自己的 Anthropic/OpenAI API Key 给出一段可能原因和排查建议，仅供参考，不会替你自动执行任何操作
- **登录密码保护**：面板可以通过 Nginx 反代对外开放，进入前需要输入你设置的密码

面板进程本身只监听服务器本机（`127.0.0.1`），要么用 SSH 隧道临时看一眼，要么按下面「面板访问」一节配置 Nginx 反代 + 密码常驻使用。

## 安装

```bash
git clone <你的仓库地址> nodenanny
cd nodenanny
sudo bash install.sh
```

> **全新服务器、连 git 都还没装？** 可以用这一行代替上面三行，会自动检查/安装 git、clone 仓库、再交给 `install.sh` 继续：
> ```bash
> sudo bash <(curl -fsSL https://raw.githubusercontent.com/yibentq/nodenanny/main/bootstrap.sh)
> ```
> 注意一定要用 `bash <(curl ...)` 这种写法，不要写成 `curl ... | bash` ——用管道会导致后面 install.sh 的问答读不到你的键盘输入。

脚本会依次：安装 Node.js / PM2、引导你完成交互式配置问答（节点信息、SMTP 邮箱、AI 诊断、流量池、在线终端、内容同步均可在此一步配好，也可跳过留待以后在 `config.json` 里手动填）、用 PM2 启动三个守护进程、最后帮你配好面板访问方式（可选域名/IP/SSH 隧道）。**全程只需运行一次。**

支持系统：Ubuntu 20.04 / 22.04 / 24.04，Debian 11 / 12。

## 配置说明

复制 `config/config.example.json` 为 `config/config.json` 后修改：

| 字段 | 说明 |
|---|---|
| `node.checkHost` / `node.checkPort` | 你的节点监听的地址和端口 |
| `node.restartCommand` | 节点异常时执行的重启命令，systemd 部署例如 `systemctl restart xray`，Docker 部署例如 `docker restart xray`。不确定服务名/容器名的话先运行 `bash scripts/check-service.sh` 查一下（两种部署方式都会自动检测），别瞎填 |
| `monitor.checkIntervalMinutes` | 检测间隔，默认 5 分钟 |
| `monitor.notifyCooldownMinutes` | 通知冷却时间，避免反复抖动时邮箱被刷屏 |
| `panel.password` | 面板登录密码。留空则跳过登录，但只建议在「只用 SSH 隧道访问、从不对外网开放」时留空 |
| `node.subscriptionUrl` | 你的一键装节点脚本（233boy 等）生成的真实订阅地址，可选。填了才能用下面「流量池」的自动切换 |
| `pool.enabled` | 是否启用流量池应急功能，默认 `false` |
| `smtp.*` | 发送通知邮件用的 SMTP 账号信息，见下方「配置 SMTP」 |
| `ai.*` | AI 故障诊断相关配置（可选），见下方「AI 故障诊断」 |

**不想手动 `nano` 改 JSON，或者想在无人值守/脚本化的服务器上批量部署？** `install.sh` 也支持完全非交互模式，靠环境变量驱动（`NN_NONINTERACTIVE=true`，再加上每个问题对应的一个 `NN_*` 变量，比如 `NN_NODE_NAME`、`NN_CHECK_PORT`、`NN_RESTART_CMD`、`NN_PANEL_PASSWORD`、`NN_SMTP_*`、`NN_AI_*`）。这个模式下唯一强制要求的变量是 `NN_PANEL_PASSWORD`——脚本会直接拒绝在没有它的情况下运行,因为面板密码留空等于对公网完全不设防。完整变量列表见 `install.sh` 开头的注释。

## 面板访问

面板进程只监听 `127.0.0.1:8787`（不改配置的话，外部网络直接连不上，这是故意的，更安全）。

**现在 `install.sh` 走到最后一步会自动问你要哪种访问方式，不需要再手动配宝塔**：
- 有域名 → 自动装 Nginx + 申请 Let's Encrypt 证书 + 配好反代，直接给你一个 `https://你的域名` 的链接。
- 没有域名 → 自动装 Nginx + 生成自签证书 + 挑一个随机端口 + 在 Nginx 层再加一道密码保护（跟面板密码相同），给你一个 `https://服务器IP:随机端口` 的链接。浏览器打开会提示证书不受信任，这是自签证书的正常现象（不影响加密效果），点"继续访问/高级"跳过即可；之后还会再要求输一次密码，这是 Nginx 那道额外保护，不是面板本身出错。
- 想跳过、自己用 SSH 隧道 → 脚本会打印类似下面的命令供你复制：
  ```bash
  ssh -L 8787:127.0.0.1:8787 root@服务器IP
  ```
  然后浏览器打开 `http://localhost:8787`。每次想看都要开一次隧道，适合偶尔看看，不适合日常。

生成的访问地址会同时打印在终端，并保存一份到 `PANEL_ACCESS_URL.txt`，忘了随时可以打开这个文件看。

**如果自动配置失败了，或者你想自己手动管 Nginx**：参考 `deploy/nginx-nodenanny.conf.example`，里面有域名+HTTPS 和纯 IP 两种场景的完整配置示例，改一下域名/证书路径即可用；也可以用宝塔面板手动加反代（网站 → 添加站点 → 反向代理，目标填 `http://127.0.0.1:8787`）。

配置完成后可以退出登录（面板右下角有退出按钮），下次访问会要求重新输密码。

## 在线终端（可选）

面板里可以开一个网页版终端，直接在浏览器里对服务器敲命令，不用另开 SSH 窗口——适合临时看一眼日志、重启某个进程这类小操作，日常维护建议还是用你自己电脑的正规终端。

- `install.sh` 会问你要不要开，选开的话会让你单独设一个终端密码（跟面板登录密码是两道独立的密码）——为了防止手滑打错，这里会让你输两遍，两遍对不上会重新问，避免设完之后自己都不知道密码打错了，回头被锁在外面。
- **如果是自己手动配置的 Nginx 反代**（没有走 `install.sh` 自动配置那条路），一定要确认反代配置里带了 WebSocket 升级相关的三行（`proxy_http_version 1.1;` / `proxy_set_header Upgrade $http_upgrade;` / `proxy_set_header Connection "upgrade";`，参考 `deploy/nginx-nodenanny.conf.example`）——少了这几行，终端会表现为"密码能验证通过，但一解锁就立刻断开连接"，这不是终端功能本身坏了，是反代没有正确升级成 WebSocket 连接。

## 流量池（应急兜底，可选）

**这不是核心功能，是安全气囊。** 正常情况下完全不启用；你的节点一旦异常，NodeNanny 会临时借用开源抓取到的陌生节点顶一下，让你的客户端不至于完全断线；自建节点恢复后自动切回，流量池停用。

**必须知道的安全须知：流量池里的节点是陌生人的服务器，安全性未知，只适合临时应急用几分钟到几小时，不要长期依赖。**

**关于内容会变化**：只要你正在使用流量池节点（自建节点还没恢复），订阅里的具体节点列表会随后台刷新（默认每 `pool.refreshIntervalHours` 小时刷新一次，默认6小时）而变化——这是设计如此，不是bug。只有在真的切到流量池那段时间才会这样，你自己的节点订阅内容不会自己变。

**关于"刷新失败"**：某一轮后台刷新抓到0个可用节点是正常现象，不代表流量池坏了——免费公开来源的节点质量参差不齐，绝大多数候选节点在"存活/测速/真实性"三层检测里任何一层没过都会被淘汰（`pm2 logs nodenanny-pool` 里看到"刷新失败"字样很可能就是这个原因）。这种情况下 NodeNanny 会继续沿用上一次成功验证过的节点，不会清空，下一轮再重新尝试。只有连续很多轮刷新都是0个节点，才需要认真排查。

### 怎么开启

- `install.sh` 走到"流量池"那一步会问你要不要现在装（需要服务器能访问 GitHub 和 pip 源，网络受限的服务器可能装不上，装失败也不影响其它功能，跳过就是了）。
- 也可以之后手动装：
  ```bash
  git clone --depth 1 https://github.com/wzdnzd/aggregator.git /root/aggregator
  cd /root/aggregator && pip3 install -r requirements.txt
  ```
  装好后把 `config.json` 里的 `pool.enabled` 改成 `true`，重启 PM2（`pm2 restart nodenanny-pool`）。
- 不管走哪条路径，流量池的三层质量检测（存活→测速→真实性验证）都还需要 **sing-box** 这个二进制程序作为检测后端。只要流量池被启用，`install.sh` 会通过 SagerNet 官方 apt 源自动装好；如果这一步自动安装失败，参考[官方安装文档](https://sing-box.sagernet.org/installation/package-manager/)手动装好之后运行 `pm2 restart nodenanny-pool` 即可，不需要重跑整个安装脚本。

### 怎么用（配合订阅链接自动切换）

1. 在 `config.json` 的 `node.subscriptionUrl` 里填上你的一键装节点脚本给你的**真实订阅地址**。
2. 面板日志（`pm2 logs nodenanny-panel`）里会打印一个 NodeNanny 自己的订阅地址，形如：
   ```
   http(s)://你的面板访问地址/sub/一串随机字符
   ```
3. 把这个地址填进你的客户端（Shadowrocket / Clash / sing-box 等）的订阅栏，而不是原来那个真实地址。
4. 平时客户端刷新订阅，NodeNanny 会自动跳转到你的真实订阅，你感觉不到任何区别；一旦自建节点异常，NodeNanny 会直接把流量池节点塞进订阅内容里（备注会自动加上"应急"字样），恢复后又会自动跳转回真实订阅。

**关于客户端兼容性(重要,不是 bug,是客户端自己的限制)**：如果你没有域名（走的是上面"面板访问"里"没有域名"那条路径），这个智能订阅地址是纯 `http://`（不是 `https://`）——这是为了兼容 Shadowrocket 这类客户端（它们遇到自签名 HTTPS 证书会直接判定订阅失败，没有信任例外的入口）。但反过来，**v2rayN（Windows/Mac 桌面版）和 v2rayNG（安卓版）从 2025 年的版本起，会直接拒绝保存 `http://` 开头的订阅地址**，报错"请不要使用不安全的 HTTP 协议订阅地址"——这是这两个客户端自己加的安全策略，跟 NodeNanny 生成的订阅内容本身没有关系（内容格式是标准的、干净的）。
如果你用的是 v2rayN / v2rayNG，目前这个纯 IP 无域名的部署方式下用不了智能订阅这个功能，两个可选做法：
- 换用 NekoBox 或 Shadowrocket 这类对 `http://` 订阅地址没有限制的客户端；
- 或者给服务器配一个域名，装 NodeNanny 时选"有域名"这条路径（走真实的 Let's Encrypt 证书，`https://` 地址两边客户端都认）。

### 候选来源发现（实验性"自愈"功能）

除了上面固定的抓取来源，NodeNanny 还可以定期扫描 GitHub 上其它发布类似节点列表的公开仓库，逐步建立对可靠来源的信任——每个新发现的来源一开始只给一个很低的权重上限，等它证明自己靠谱了才逐步提高；如果一个来源产出的数据出现明显异常（比如很多"不同"节点其实共用完全相同的凭证——这是低质量或者不诚实来源的强烈信号），会被自动拉黑。

- `install.sh` 会单独问这一项（紧跟在上面那个问题后面）。选是的话会问你要不要填一个 GitHub 令牌（可选）。**重要——这个令牌不是对所有功能都可选**：候选来源发现实际上跑的是两个独立的搜索。按话题标签搜索不需要令牌也能用（受 GitHub 未认证请求的较低额度限制）。按文件名搜索**必须**要令牌——GitHub 的代码搜索接口会直接拒绝未认证的请求，所以没填令牌的话这一半功能会静默跳过（不会报错，你也看不出来它没在跑）。两个搜索都只需要**不勾选任何权限（zero scopes）**的令牌，只是提高请求额度、解锁文件名搜索，不会授予任何私有内容的访问权限。
- 这确实还是一个实验性功能。已经用真实 GitHub 数据和真实候选节点做过端到端验证，但仍然是个比较年轻的功能——建议跟对待流量池其它部分一样：适合短时间应急，不建议长期依赖。

### 手动种子来源（自己挑的靠谱订阅，2026-07-14新增）

如果你自己找到了一个质量比较好、更新比较勤的免费节点订阅（比如某个专人在 Telegram 上分享、持续维护的订阅链接），可以手动加进 `config.json` 的 `pool.manualSources` 数组里，让它也参与流量池的多来源调度：

```json
"manualSources": [
  { "id": "wangcai", "name": "旺财", "url": "https://shz.al/~WangCai" }
]
```

- `id` 随便起一个英文/数字组合，唯一就行，改配置后需要 `pm2 restart nodenanny-pool` 生效。
- **重要**：这类手动加的来源，跟 GitHub 自动发现的来源用的是**同一套试用期/信任状态机**，不是加进去就永久信任——虽然是你自己验证过的，但我们没法验证这条订阅背后的运营者是谁、会不会哪天变质，所以第一轮权重同样会被锁在很低的上限内，靠持续的实测通过率慢慢转正，如果哪天这个来源产出异常（比如批量节点共享同一凭证这种蜜罐特征），会跟其它来源一样被自动降级/拉黑，不会因为是你手动加的就搞特殊。
- 这类来源通常比 GitHub 上随机发现的小仓库更新鲜、质量更好（毕竟是有人专门在维护），但风险跟所有陌生节点一样：内容检测能确认"连得上、内容没被篡改"，确认不了"运营者是不是在记录你的流量元数据"——面板上依然会诚实标注这是陌生服务器。

### Telegram 频道来源

`manualSources` 的 `url` 字段除了直接填订阅链接，也可以直接填一个 Telegram 频道地址（`https://t.me/频道名`）——很多免费节点分享频道每天/每次发新的订阅链接（带会员token，天天换），不是固定不变的一条链接。NodeNanny 会自动去频道的公开预览页找最新一条带订阅链接的消息，解析出当天真实的链接再去抓取，你不用每天手动更新配置。

```json
"manualSources": [
  { "id": "某频道", "name": "某频道", "url": "https://t.me/频道名" }
]
```

- 信任状态跟踪的是"这条订阅链接背后的域名"，不是频道本身——同一个频道天天换新token链接，只要域名不变，历史战绩照样累积，不会每天从零开始试用期。
- 如果频道里除了订阅链接，还直接在消息正文里贴了裸的节点链接（`vless://`/`vmess://` 等），这些也会被顺带收集起来，汇总进一个独立的"telegram-raw-pool"来源参与流量池调度，同样要经过正常的试用期检测，不会不经检测就直接信任。

### 官方来源列表同步（可选）

除了自己一条条手动加，NodeNanny 项目本身在 `data/source-list.json` 里维护了一份公开、经过初步筛选的候选来源列表（目前主要是几个稳定更新的 Telegram 频道）。开启后，面板里"节点来源列表同步"这一栏可以一键检查更新、预览差异、确认后合并进你自己的 `manualSources`——合并进来的每一条同样要走正常的试用期，不会自动获得信任。`install.sh` 走到"内容同步"那一步时会问你要不要顺带开启这个（跟内容同步 kbSync/wikiSync 是同一个问题，一起问），已经在跑的服务器需要手动在 `config.json` 里加 `sourceListSync` 字段并重启 `nodenanny-panel` 才会生效。

### 手动切换到备用池（人工触发）

除了上面"自建节点异常时自动切流量池、恢复后自动切回"这套全自动逻辑，面板上还有一个手动开关，可以自己决定"现在就切到流量池"，不用等自建节点真的挂了——比如你明知道接下来要重装/重启自建节点，想提前切一下避免中间断线。

- 打开后，即使自建节点这段时间检测一直正常，也**不会**被自动切回去，要你自己再手动点一次关闭。这是为了避免"我手动切过去是有原因的，结果系统自己给我切回来了"这种情况。
- 如果流量池当前是空的（没有任何节点通过检测），点开关会直接提示失败，不会切一个空池子过去。

## AI 故障诊断（可选）

**这是辅助建议，不是自动决策。** 节点连续异常达到设定次数后，NodeNanny 会拿最近的事件时间线去问 AI"可能是什么原因、接下来该查什么"，结果会显示在面板卡片上、也会单独发一封邮件通知你（如果配置了 SMTP）。全程只出建议，NodeNanny 不会替你执行任何修复动作。

用的是**你自己的** Anthropic 或 OpenAI API Key，直连官方 API，NodeNanny 不经手你的 Key、不收费、不看你的调用内容。

### 怎么开启

- `install.sh` 走到这一步会直接问你要不要开启（可以跳过，以后随时能开）。
- 也可以之后手动编辑 `config.json` 里的 `ai` 字段：

| 字段 | 说明 |
|---|---|
| `ai.enabled` | 是否开启，默认 `false` |
| `ai.provider` | `anthropic`、`openai`，或 `openai-compatible` |
| `ai.apiKey` | 你自己的 API Key，留空表示未配置（**不要**填成一句说明文字，那样会被当成真实 Key 发给官方 API，得到一个看不懂的报错） |
| `ai.model` | 具体模型名，留空 `""` 用默认模型（anthropic 默认 `claude-sonnet-4-6`，openai 默认 `gpt-4o-mini`）。选 `openai-compatible` 时**必填**，没有默认值 |
| `ai.baseUrl` | 只在 `ai.provider` 为 `openai-compatible` 时使用。填一个不带 `http(s)://` 前缀的裸域名（例如 `open.bigmodel.cn`） |
| `ai.apiPath` | 只在 `ai.provider` 为 `openai-compatible` 时使用。留空默认 `/v1/chat/completions` |
| `ai.triggerAfterFailures` | 连续失败几次后自动触发一次诊断，默认 `3` |
| `ai.language` | 诊断内容和报错文本用哪种语言生成：`zh`/`en`/`ja`/`de`/`ru`。默认跟随安装时选择的语言，跟面板网页上切换的显示语言是两回事（面板语言是浏览器本地记住的，服务器并不知道），想改就直接改这个字段 |

**`openai-compatible` 是干什么用的？** 不少第三方或者免费接口（比如智谱 GLM、DeepSeek、通义、Kimi 等）自己不是 OpenAI，但接口协议兼容 OpenAI 的 chat-completions 格式。选这个 provider，填好 `baseUrl`/`apiPath` 就能用——已经用智谱免费版 GLM 做过真实端到端验证，确认可用。跟另外两个官方 provider 的一点区别：发给 `openai-compatible` 接口的内容会先做脱敏处理（见 `core/ai-provider.js` 里的脱敏逻辑），因为这类接口通常是第三方或免费服务；官方 Anthropic/OpenAI 两条路径不做这一步。如果你接的是一个"会思考"的推理模型，诊断老是返回空结果，先确认 `ai.model` 填的是你这个接口真实提供的模型名——推理模型如果请求的 token 预算（这个不是用户可配置的）对它来说太小，可能把预算全耗在内部思考上，导致最终答案是空的。

改完保存后重启监控进程：`pm2 restart nodenanny-monitor`。

### 怎么用

- 正常情况下不用管，节点持续异常达到阈值时自动触发一次。
- 也可以在面板的"AI 诊断"卡片上点"立即诊断"按钮手动触发一次（不用等真的连续异常，方便测试；手动触发不会发邮件）。

## 配置 SMTP

任意支持 SMTP 的邮箱都可以，下面是常见邮箱的参数，照抄对应那一行填进 `config.json` 的 `smtp` 字段：

| 邮箱 | host | port | secure | 密码填什么 |
|---|---|---|---|---|
| QQ 邮箱 | smtp.qq.com | 465 | true | 邮箱设置里申请的**授权码**，不是QQ密码 |
| 163 邮箱 | smtp.163.com | 465 | true | 邮箱设置里申请的**授权码**，不是登录密码 |
| Gmail | smtp.gmail.com | 465 | true | Google 账号的**应用专用密码**，不是登录密码 |
| 企业自建邮箱 | 问你的邮箱服务商 | 通常 465 或 587 | 465 用 true，587 用 false | 正常登录密码 |

**说句实话**：这是目前整个安装流程里，我们自己都觉得对不懂技术的人不够友好的一步。"应用专用密码"、"授权码"这些是现代邮箱厂商必要的安全机制，但去哪个设置页面生成、具体点哪里，如果没做过真的会犯迷糊——我们自己挨个走了一遍几个邮箱的流程，发现有些即便对我们来说都不算清晰。`install.sh` 给了一个菜单（QQ / 163 / Gmail / 其它 / 跳过），前三个会自动帮你填好 host/port/加密方式，你只需要去生成授权码/应用密码本身，但这最后一步我们还没能做到真正的"新手友好"。如果卡住了，安装时直接选"跳过"（第 5 个选项）——跳过邮箱不影响 NodeNanny 的任何其它功能，只是你会靠面板而不是邮件来了解节点状态，以后随时可以回来补配置。

配好后可以先手动跑一次监控测试是否能发信：

```bash
node core/monitor.js
```

看终端有没有报 SMTP 相关的错误，没问题的话 `Ctrl+C` 退出，交给 PM2 管理即可（`pm2 restart nodenanny-monitor`）。

## 常用命令

```bash
pm2 status                      # 查看运行状态
pm2 logs nodenanny-monitor      # 查看监控日志
pm2 restart nodenanny-monitor   # 手动重启监控进程
sudo bash uninstall.sh          # 卸载
```

## 技术栈

Node.js + PM2 + 纯文件存储（JSON）+ 纯 HTML/JS 面板 + SMTP 邮件通知。没有数据库依赖、没有 Docker、没有需要付费的第三方服务，成本 $0。

流量池节点的国家标注用的是 [`@ip-location-db/geo-whois-asn-country-mmdb`](https://github.com/sapics/ip-location-db) 这个数据集（公有领域/CC0协议，跟着 `npm install` 自动装好，不需要注册也不需要署名）。查询是尽力而为的——查不出来就留空，不会影响其它功能。

## 常见问题

**为什么不用 Telegram 通知？**
Telegram 在国内注册和日常使用有门槛，跟"零运维、普通人友好"的定位冲突。邮件虽然"土"，但零门槛、人人都有。

**流量池呢？**
不是核心功能，是"主节点挂了"时的应急备用，默认关闭，启用方式见上面「流量池（应急兜底，可选）」一节；使用时面板和订阅备注里都会明确提示"这是陌生人的服务器，安全性未知，仅临时应急使用"。

**v2rayN / v2rayNG 导入 NodeNanny 的智能订阅地址，提示"请不要使用不安全的 HTTP 协议订阅地址"，导入失败？**
这是 v2rayN（桌面版）/ v2rayNG（安卓版）客户端自己从 2025 年起加的安全策略，不是 NodeNanny 的 bug——只要智能订阅地址是 `http://` 开头（没有域名的部署方式默认就是这样），这两个客户端会直接拒绝保存，不管订阅内容本身对不对。详见上面「流量池」章节「怎么用」里的"关于客户端兼容性"说明，换 NekoBox / Shadowrocket 或者给服务器配个域名都能解决。

**能同时管理多个节点吗？**
目前只支持单节点。这是一个给个人用的极简工具，不是多节点管理平台。

**面板对外开放安全吗？**
面板本身默认只监听本机，必须你主动配置 Nginx 反代才能被外部访问，而且反代打开后一定要求设密码，登录 Cookie 是 HttpOnly + 签名校验，连续输错密码会被限速锁一分钟。安全性和你自己的服务器、SSH 密码强度、是否配了 HTTPS 有关，NodeNanny 只能保证自己这一层做对，不能替你兜底服务器整体安全。

## 故障自救 FAQ

遇到问题先别慌，按下面对应的情况查，大部分不需要重装。

**面板网页打不开 / 打开转圈圈 / 显示"无法访问此网站"**
1. 先确认服务器本身有没有关机或者到期：登录你买 VPS 那个服务商的后台，看实例状态是不是"运行中"。
2. SSH 连上服务器（见上面「新手准备三」），输入 `pm2 status` 看看两个进程是不是 `online` 状态；如果不是，运行 `pm2 restart all` 试一下。
3. 如果你用的是"有域名"那种访问方式，确认域名的 DNS 解析有没有被改动过（比如换过服务商但忘了改解析）。
4. 如果你用的是"没有域名"那种随机端口方式，检查一下 `PANEL_ACCESS_URL.txt` 里记的端口号和你在浏览器里输的是不是同一个（这个端口是随机生成的，容易记错）。
5. 都排查完还是不行，把 `pm2 logs nodenanny-panel --lines 50` 的输出发给开发者。

**面板密码忘了**
密码是安装时你自己设的，NodeNanny 不会（也不能）帮你找回，只能重置：
```bash
cd nodenanny
nano config/config.json   # 找到 panel.password 这一行，改成你的新密码，保存退出（Ctrl+O 回车，Ctrl+X 退出）
pm2 restart nodenanny-panel
```
如果你用了"没有域名"那种访问方式，Nginx 那一层还有一道 Basic Auth 密码，安装时默认和面板密码相同，改完面板密码后这道密码不会自动跟着变，需要手动更新：
```bash
sudo openssl passwd -apr1 你的新密码   # 会输出一段哈希
sudo nano /etc/nodenanny/ssl/htpasswd  # 把冒号后面的部分换成上面输出的哈希，保存退出
sudo systemctl reload nginx
```

**服务器重启了（比如服务商维护、你自己手滑重启了）之后面板/监控没了**
正常情况下不需要你做任何事：NodeNanny 用 PM2 管理进程，`install.sh` 已经配置了开机自启，服务器重启后过一两分钟自己会恢复。如果等了几分钟还是没恢复，SSH 连上去运行：
```bash
pm2 resurrect
```
如果这条命令提示"没有保存的进程列表"，说明当时安装时开机自启没配置成功，运行 `pm2 startup` 后按它的提示再执行一遍打印出来的命令，然后 `pm2 save` 保存一次即可，以后重启就会自动恢复了。

**忘了自己当初是怎么访问面板的**
打开 `PANEL_ACCESS_URL.txt` 这个文件（在项目目录下），安装时生成的访问地址就存在里面，不需要重新走一遍安装流程。

## 许可证

MIT

---

*This README is also available in English: [README.md](README.md).*