⚠️ 【重要】VRChat 官方 API 近期调整，好友资料不再返回头像缩略图字段，导致旧版本的好友头像无法加载（自己的头像正常）。其他受影响范围正在评估中。请及时更新到最新镜像修复：docker compose pull && docker compose up -d。

vrcnotifier

VRChat 好友监控与通知器:WebSocket 实时好友上线 / 下线 / 切换世界 / 状态变化+ 站内通知(仅推送邀请、戳一戳、群组公告,可在设置页分别开关,公告自动解析群组名),经 QQ bot推送到手机(2FA 验证码、查在线好友列表);自动恢复(cookie 失效自动重登、会话挂起自动 2FA、WS 自动重连);Web 面板、REST 对账、日志监控。敏感数据(VRChat 用户名/密码/cookie、QQ AppSecret)AES-256-GCM 加密落库。

快速开始(Docker)

将以下内容保存为 docker-compose.yml:

完整文件见仓库根目录 docker-compose.yml(含逐项注释)。

name: vrcnotifier

services:
  # 一次性主密钥生成器，密钥写入命名卷 vrcn-key
  vrcn-keygen:
    image: sihenglu/vrcnotifier-backend:latest
    entrypoint: []
    command:
      - sh
      - -c
      - |
        K=/data/vrcnotifier_master_key
        if [ ! -s "$$K" ]; then
          node -e 'process.stdout.write(require("crypto").randomBytes(32).toString("hex"))' > "$$K"
          chmod 600 "$$K"
          echo "vrcn-keygen: 已生成新的主密钥(32 字节)"
        else
          echo "vrcn-keygen: 检测到已有主密钥, 保持不变"
        fi
    volumes:
      - vrcn-key:/data
    network_mode: "none"
    restart: "no"

  # 面板 + API(同一进程、同一端口)
  vrcnotifier-backend:
    image: sihenglu/vrcnotifier-backend:latest
    restart: unless-stopped
    depends_on:
      vrcn-keygen:
        condition: service_completed_successfully
    environment:
      PORT: "3000"
      SERVE_STATIC: "1"        # 托管 public/ 静态页, 与 /api 同源
      TZ: Asia/Shanghai
    volumes:
      - vrcn-key:/run/secrets  # 主密钥
      - vrcn-data:/app/data    # 数据文件
    ports:
      - "${API_PORT:-3000}:3000"  # 面板 + API 端口
    healthcheck:
      test: ["CMD-SHELL", "node -e \"fetch('http://127.0.0.1:3000/api/config').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
      interval: 20s
      timeout: 5s
      retries: 5
      start_period: 15s

volumes:
  vrcn-key:
  vrcn-data:

docker compose up -d
docker compose logs vrcnotifier-backend | grep 访问令牌   # 访问令牌: 首启自动生成, 只打印一次

打开 http://<主机>:3000:填访问令牌 → 登录 VRChat(2FA 需邮箱验证码)→ 设置填 QQ AppID/AppSecret、QQ 里给机器人发任意一条消息完成绑定 → 好友列表开监控开关,完成。

门禁页的「后端地址」会自动预填为当前页面地址(同源),正常只需填令牌即可。

更新到新版本

docker compose pull        # 拉取最新镜像
docker compose up -d       # 用新镜像重建容器
docker compose ps          # 确认 healthy
docker compose logs -f     # 需要时看启动日志

更新只替换镜像,vrcn-key(密钥)与 vrcn-data(数据)两个命名卷原样保留,数据不会丢。 只有当 docker-compose.yml 本身有变更时才需要替换该文件;单纯升级镜像不用改 yaml。

停止

docker compose down        # 停止(保留卷)

本地运行

Node.js ≥ 22.13.0(推荐 24.x,依赖 node:sqlite):

npm install
npm start                    # 面板 + API 同源 :3000(默认行为, 打开 http://127.0.0.1:3000/)

加密与密钥

密钥优先级:Docker Secret(首启自动生成,存 vrcn-key 卷)→ 环境变量 MASTER_KEY(64 位 hex)→ 不加密启动(有提示)。密钥丢失/不匹配时已加密数据被清空(访问令牌保留);明文旧数据直通。

数据与安全

本项目将存储 VRChat 的用户名/密码和 cookies 信息;存储的密码可在 IP 变化等场景下重新登录,实现免 2FA、无需人工干预的自动重登

本项目与 VRChat 官方无关

环境变量

PORT ACCESS_TOKEN MASTER_KEY VRC_API_URL VRC_WS_URL QQ_API_BASE QQ_WS_URL VRC_STATUS_URL USER_AGENT SNAPSHOT_INTERVAL_MS DEDUPE_WINDOW_MS WATCHDOG_MS WATCHDOG_CHECK_MS WS_PING_INTERVAL_MS WS_PONG_TIMEOUT_MS RECONNECT_MAX_MS SERVE_STATIC(默认开: 同源托管面板; 置 0 只跑 API) LOG_SEGMENT_MB LOG_MAX_FILES

日志文件

后端日志写入 data/logs/:分段存储,一段一个文件(2MB),以创建时间命名(vrcnotifier-20260909-120000-123.log)。

灵感来自 shanyaojinjn/VRC-Notifier:改用 WebSocket 实时事件 + QQ 机器人集成,极致的vrcapi调用(平均3次/h)。

鉴定为玩vrc玩的

也就只能写写readme了