Skip to content
BranchesTags

Repository files navigation

NodeBeacon

现代化、API-first 的 VPS 库存监控与补货通知中心。

NodeBeacon 按周期探测产品页面，通过文本、反向文本、正则表达式或 HTTP 状态判断库存变化，并把事件推送到 Telegram Bot / 频道、Discord、Slack 或通用 Webhook。

当前开发版本：0.1.0。这是全新的 Node.js / SQLite 基线，不包含旧版 Cloudflare、D1 或 Vinext 兼容层。

核心能力

  • 独立页面路由：总览、监控、数据洞察、通知渠道、事件、开发者和设置均有可刷新、可分享的 URL。
  • 前后端边界：浏览器只通过 /api/v1/* 使用后端能力，不直接导入数据库或服务模块。
  • 库存探测：支持 includes、excludes、regex、status 四种规则以及独立周期、优先级和标签。
  • 批量运维：批量检测、启用、暂停和删除监控项。
  • 完整遥测：持久化每次检测的状态、耗时、错误、连续失败和状态变化。
  • 多渠道通知：Telegram 私聊 / 群组 / 频道、Discord Embed、Slack Block Kit 和通用 Webhook。
  • Bot 接入：外部系统可通过 /api/v1/ingest 注入事件并触发通知。
  • 内嵌调度器：Web、REST API、调度器和通知适配器运行在同一个容器中。
  • 本地持久化：SQLite WAL 数据库显式绑定到宿主机 ./data，升级或重建容器不会丢失。
  • 运维能力：健康检查、日志轮转、一致性在线备份、保护性恢复脚本和拉取式升级。
  • 安全基线：非 root 用户、只读根文件系统、无 Linux capabilities、no-new-privileges 和环境变量密钥。
  • 多架构镜像：GitHub Actions 构建 linux/amd64 与 linux/arm64 GHCR 镜像。
  • 现代界面：响应式布局、明暗主题、亚克力层次、动态信号背景、Radix 可访问交互和命令中心。

页面路由

路径 功能
/overview 实时态势、重点探针、系统健康度与事件流
/monitors 搜索、筛选、排序、表格 / 卡片视图与批量运维
/analytics 事件趋势、库存分布、服务商健康度与送达指标
/channels Telegram、Discord、Slack 与 Webhook 渠道管理
/events 可追溯事件时间线与确认闭环
/developers REST API、OpenAPI 与 Bot 接入示例
/settings 调度、韧性、通知策略和静默时间

根路径 / 会重定向到 /overview。页面切换使用 Next App Router，支持浏览器前进、后退和链接直达。

项目结构

NodeBeacon/
├─ src/
│  ├─ app/                 Next.js 页面路由与 HTTP Route Handlers
│  ├─ frontend/            API Client、UI 组件、功能页面和状态层
│  ├─ server/              检测、调度、通知、设置和数据库服务
│  └─ shared/              前后端共享契约、校验与配置
├─ drizzle/                0.1.0 SQLite 初始迁移
├─ deploy/                 Debian 准备、升级、备份和恢复工具
├─ scripts/docker/         容器健康检查、备份和运行时冒烟测试
├─ tests/                  架构与发布能力测试
├─ tooling/                Drizzle 等开发工具配置
├─ compose.yaml            拉取式单容器生产部署
└─ Dockerfile              Node.js 24 多阶段镜像

这是一套“源码前后端分层、部署单元合并”的模块化单体架构。它保留清晰的 HTTP 边界，同时避免在小型 VPS 上运维多个容器。更多说明见 架构文档。

本地开发

需要 Node.js 24 和 npm。推荐使用 .nvmrc：

git clone https://github.com/Elainaicey/NodeBeacon.git
cd NodeBeacon
nvm use
npm ci
cp .env.example .env.local
npm run dev

打开 http://localhost:3000。本地数据库默认写入 data/nodebeacon.db。如果需要演示数据，在 .env.local 中设置：

NODEBEACON_SEED_DEMO_DATA=true
NODEBEACON_SCHEDULER_ENABLED=false

常用命令：

npm run dev             # 开发服务器
npm run build           # 标准 Next.js 生产构建
npm run start           # 启动生产构建
npm run lint            # ESLint
npm run typecheck       # TypeScript 严格检查
npm test                # 构建与架构测试
npm run docker:build    # 构建 standalone 运行时
npm run docker:smoke    # 验证 API、SQLite 和在线备份
npm run db:generate     # 根据 Schema 生成迁移

Debian 单容器 Docker 部署

要求 Debian 12/13、Docker Engine 和 Docker Compose 插件。

推荐：最小化拉取部署

运行服务器不需要完整源码。/opt/nodebeacon 只需以下内容：

/opt/nodebeacon/
├─ compose.yaml
├─ .env
└─ data/
   ├─ nodebeacon.db
   ├─ nodebeacon.db-wal
   ├─ nodebeacon.db-shm
   └─ backups/

准备目录：

sudo install -d -m 0755 /opt/nodebeacon
cd /opt/nodebeacon

sudo curl -fsSLo compose.yaml \
  https://raw.githubusercontent.com/Elainaicey/NodeBeacon/main/compose.yaml
sudo curl -fsSLo .env \
  https://raw.githubusercontent.com/Elainaicey/NodeBeacon/main/.env.example

sudo install -d -m 0750 -o 10001 -g 10001 \
  /opt/nodebeacon/data /opt/nodebeacon/data/backups
sudo chmod 0600 .env
sudo nano .env

至少为 NODEBEACON_API_KEY 和 CRON_SECRET 写入两个不同的随机值。可用 openssl rand -hex 32 生成。

拉取并启动：

docker compose pull
docker compose up -d
docker compose ps
docker compose logs -f nodebeacon

打开 http://服务器IP:3000。使用 Caddy、Nginx 或 Traefik 提供 HTTPS 时，建议设置 NODEBEACON_BIND_ADDRESS=127.0.0.1。

docker compose ps 只会显示一个应用容器：nodebeacon。调度器已经嵌入该进程，不再创建第二个容器。

完整源码部署

需要在服务器修改源码或本机构建时使用：

git clone https://github.com/Elainaicey/NodeBeacon.git /opt/nodebeacon
cd /opt/nodebeacon
sudo ./deploy/prepare.sh
nano .env
docker compose pull
docker compose up -d

从源码构建镜像：

docker compose -f compose.yaml -f deploy/compose.build.yaml up -d --build

数据存放与持久化

生产 Compose 使用显式 bind mount：

宿主机 /opt/nodebeacon/data  →  容器 /data

SQLite 主库位于 data/nodebeacon.db，WAL 运行时文件位于同一目录，备份位于 data/backups/。执行以下操作不会删除数据：

  • docker compose restart
  • docker compose down
  • docker compose pull && docker compose up -d
  • 删除并重新创建应用容器

请不要在容器运行时直接复制主数据库文件；使用内置在线备份命令：

docker compose exec -T nodebeacon node scripts/docker/backup.mjs

输出会包含备份路径，例如 /data/backups/nodebeacon-2026-07-31T10-00-00-000Z.db，在宿主机上对应 /opt/nodebeacon/data/backups/...。

完整源码部署还可使用：

./deploy/backup.sh
sudo ./deploy/restore.sh /opt/nodebeacon/data/backups/备份文件.db --yes

恢复脚本会先停止容器，并把当前数据库保存为 pre-restore-*.db，再替换数据库并重启服务。

本基线按全新项目设计，不自动导入旧版 D1、旧命名卷或旧 SQLite 结构。部署 0.1.0 时请使用空的 data 目录。

升级与回滚

拉取最新镜像并重建单个应用容器：

./deploy/backup.sh
./deploy/update.sh

最小化部署可直接运行：

docker compose exec -T nodebeacon node scripts/docker/backup.mjs
docker compose pull nodebeacon
docker compose up -d --remove-orphans
docker compose ps

正式发布后建议把 .env 的镜像标签从 main 固定到明确版本，例如 ghcr.io/elainaicey/nodebeacon:0.1.0，便于可重复部署和回滚。

环境变量

变量 必需 说明
NODEBEACON_API_KEY 生产必需 保护外部写 API 的 Bearer Token
CRON_SECRET 生产必需 保护可选的 /api/cron/check 外部触发接口
NODEBEACON_IMAGE Docker 可选 GHCR 镜像，默认 ghcr.io/elainaicey/nodebeacon:main
NODEBEACON_DATA_PATH Docker 可选 宿主机数据目录，默认 ./data
NODEBEACON_BIND_ADDRESS Docker 可选 监听地址，默认 0.0.0.0
NODEBEACON_PORT Docker 可选 对外端口，默认 3000
NODEBEACON_SCHEDULER_ENABLED 可选 启用容器内嵌调度器，默认 true
NODEBEACON_SCHEDULER_INTERVAL_SECONDS 可选 到期任务唤醒周期，范围 15–3600 秒
NODEBEACON_SEED_DEMO_DATA 可选 空库是否写入演示数据，生产默认 false
TELEGRAM_BOT_TOKEN Telegram 必需 BotFather 返回的 Token
DISCORD_WEBHOOK_URL Discord 必需 Discord Incoming Webhook URL
SLACK_WEBHOOK_URL Slack 必需 Slack Incoming Webhook URL
WEBHOOK_SECRET Webhook 可选 通用 Webhook Bearer Token
TZ 可选 容器时区，默认 Asia/Shanghai

数据库只保存渠道所引用的环境变量名称，不保存 Bot Token 或 Webhook Secret。真实密钥只通过 .env 或容器编排系统注入。

Telegram Bot / 频道

  1. 使用 @BotFather 创建 Bot 并获取 Token。
  2. 在 .env 中设置 TELEGRAM_BOT_TOKEN，重建容器。
  3. 私聊推送时，先向 Bot 发送消息，再填写对应 Chat ID。
  4. 频道推送时，把 Bot 添加为频道管理员，填写 @channel_name 或数字 Chat ID。
  5. 在“通知渠道”页面创建 Telegram 渠道，凭据引用填写 TELEGRAM_BOT_TOKEN。
  6. 启用渠道并发送测试消息。

同一个 Token 可连接多个 Chat ID；多个 Bot 可分别使用不同的环境变量名称。

REST API

OpenAPI 概览：GET /api/v1/openapi

方法 路径 用途
GET /api/v1/health 数据库、调度器与版本健康状态
GET /api/v1/dashboard 聚合管理台数据
GET / POST /api/v1/monitors 查询 / 创建监控
PATCH / DELETE /api/v1/monitors/:id 修改 / 删除监控
POST /api/v1/monitors/:id/check 立即检测单个探针
GET /api/v1/monitors/:id/history 检测历史与质量统计
POST /api/v1/monitors/bulk 批量运维监控
GET / POST /api/v1/channels 查询 / 创建渠道
POST /api/v1/channels/:id/test 发送测试消息
POST /api/v1/events/acknowledge 确认事件
POST /api/v1/ingest Bot / 外部系统注入事件
GET / PUT /api/v1/settings 查询 / 更新系统设置
POST /api/cron/check 可选的外部调度触发器

外部事件示例：

curl -X POST https://your-domain.example/api/v1/ingest \
  -H "Authorization: Bearer $NODEBEACON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"补货提醒","message":"Tokyo 2GB 已有库存","severity":"success"}'

安全边界

  • NodeBeacon 只读取目标页面，不会自动下单、登录或提交表单。
  • Token 和 Secret 不写入 SQLite，也不输出到应用日志。
  • 外部写请求需要 Authorization: Bearer <NODEBEACON_API_KEY>。
  • 外部调度请求需要 x-cron-secret: <CRON_SECRET>。
  • 建议在反向代理启用 HTTPS、访问控制和速率限制。
  • .env 权限应为 0600，data 目录应只允许容器 UID 10001 访问。

贡献与许可证

提交改动前运行：

npm run lint
npm run typecheck
npm test
npm run docker:build && npm run docker:smoke
npm audit --omit=dev

项目采用 MIT License。

About

Modern VPS inventory monitoring and restock notification center with Telegram, Webhook, Docker Compose, and Cloudflare support.

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages