群监控（GramJS 版）

使用 GramJS 驱动的 Node.js User-Bot 自动加入目标群、识别群主并实时监听消息。一旦命中关键词，结果会通过单独的 Telegram Bot 安全汇报到指定群/频道。

功能亮点

• GramJS 长连接：以 Node.js 形式运行，便于使用 Chrome DevTools Protocol 调试 Node 后端。
• 自动入群：支持公开群链接与 https://t.me/+xxxx 邀请链接，必要时自动执行 ImportChatInvite。
• 群主洞察：拉取 ChannelParticipantsAdmins，找到创建者后写入汇报，方便对齐「自动添加群主」的状态。
• 关键词热加载：keywords.yaml 被修改后自动重新解析，支持子串匹配与 (?i)、(?im) 等内联正则修饰符。
• Bot 汇报隔离：监听使用 user-bot，会话由用户账号维持；真正的告警与附件提醒交由 Bot Token 发出，避免刷屏。

环境要求

• Node.js 18+（建议 LTS）
• Telegram API 凭据：api_id / api_hash
• 可登录的手机号（首次运行需验证码）
• Telegram Bot Token（Bot 必须已经在汇报群内）

快速开始

1. 安装依赖：

   npm install
   

2. 配置环境变量：

   cp .env.example .env
   

   填写下方参数；SESSION_DIR 会自动创建并持久化 *.session 文件。
3. 配置 keywords.yaml（示例见下节）。
4. 启动：

   npm run dev       # tsx 直接运行 TypeScript
   # 或
   npm run build && npm run start
   

   首次登陆会提示输入手机号验证码及二步验证密码（若有）。

环境变量说明

• API_ID / API_HASH：来自 my.telegram.org。
• SESSION_NAME / SESSION_DIR：本地 session 文件名及所在目录。
• USER_PHONE：可选，预填手机号。
• TWO_FA_PASSWORD：可选，账号开启二步验证时使用。
• GROUP_LINKS：逗号分隔的群链接列表，可混合公开链接与 https://t.me/+xxxx。
• REPORT_CHAT_LINK：汇报消息要发送到的群/频道；留空时默认取 GROUP_LINKS 第一项。
• TELEGRAM_BOT_TOKEN：Bot HTTP API Token。
• KEYWORDS_FILE：关键词配置路径，默认 keywords.yaml。
• LOG_LEVEL：trace|debug|info|warn|error，默认 info。

关键词配置

keywords.yaml 结构与旧版 Python 一致：

keywords:
  - name: promo
    patterns:
      - "推广"
      - "广告"
    regex: false
  - name: join_request
    patterns:
      - "(?i)拉群"
      - "(?im)^加好友"
    regex: true

• regex: false：子串匹配，自动转为小写比较。
• regex: true：使用 JavaScript 正则。保留了 Python 示例中的 (?i)、(?im) 等内联修饰符，会自动拆解为对应的 i/m/s flags。
• 文件保存后会触发热加载，无需重启进程。

常用脚本

• npm run dev：tsx 直接运行 src/main.ts。
• npm run build：编译到 dist/，配合 npm run start 运行。
• npm run lint：tsc --noEmit 类型检查。
• npm run test：Vitest 单测，当前覆盖 KeywordStore 热加载逻辑。
• npm run dev:inspect：以 node --inspect 启动开发流程，便于 Chrome DevTools 调试。
• npm run start:inspect：对编译后的 dist/main.js 开启 Inspector，适合线上问题排查。

注意事项

• user-bot 与汇报 Bot 都必须在 REPORT_CHAT_LINK 对应的群/频道里，且 Bot 拥有发言权限。
• Telegram 对频繁入群会触发 FLOOD_WAIT_xx，日志会提示需要等待的秒数。
• sessions/*.session 含账号授权信息，请妥善保管。
• 长期部署建议使用 pm2 / systemd 等守护方式并接入日志轮转。

CDP 调试检查（Chrome DevTools）

1. 本地或服务器执行 npm run dev:inspect（开发态）或 npm run start:inspect（生产态）。Node 会输出 Debugger listening on ws://127.0.0.1:<port>/...，该端口是临时分配的，不会占用既有业务端口。
2. 在 Chrome 地址栏输入 chrome://inspect，点击 “Configure”，将服务器 IP:port（若为远程需先通过 SSH 端口转发）加入可调试目标，然后点击 inspect。
3. 在 Sources 面板设置断点，依次验证以下关键流程：
   • loadConfig：检查 .env 解析、会话目录创建与多群链接拆分。
   • createTelegramClient：确认 session 落盘、验证码 / 2FA 输入路径。
   • KeywordStore：在 registerWatcher 处模拟 keywords.yaml 修改，验证热加载是否触发。
   • GroupMonitor：跟踪 ensureJoined、watchGroup 调用链，确保入群与群主识别逻辑正确。
   • Reporter：在 sendAlert 断点检查 Markdown 转义与 Bot Token 使用。
4. 调试完成后可执行 disconnect()，或在终端 Ctrl+C 退出。若需复现问题，可结合 console.profile、Performance 面板导出火焰图。

服务器部署与 CI/CD

一次性初始化

1. 登录服务器（示例：ssh atai@172.16.74.159），确保 Node.js ≥ 18 与 npm 可用。
2. 安装 pm2（如未安装）：sudo npm install -g pm2。
3. 创建运行目录：mkdir -p /home/atai/services/qun-monitor。
4. 拷贝 .env.example 为 .env 并填入真实参数；首次登录需要人工输入短信验证码。

Gitea Workflow 自动部署

仓库内新增 .gitea/workflows/deploy.yaml，当 main 分支有推送时会执行：

1. npm ci && npm run lint && npm run test && npm run build，保证代码通过类型检查与单测。
2. npm prune --omit=dev 并将 dist/ + node_modules + 环境模板 + README 打包为 qun-monitor-release.tar.gz。
3. 通过 appleboy/scp-action 将制品上传到服务器（默认 /home/atai/deployments/qun-monitor）。
4. 使用 appleboy/ssh-action 在服务器解压至 APP_DIR（默认 /home/atai/services/qun-monitor），若检测到 .env，则：
   • 自动安装 pm2（若缺失）。
   • pm2 restart qun-monitor --update-env 或 pm2 start npm --name qun-monitor -- start。
   • pm2 save 持久化进程列表。

CI/CD 所需机密

请在 Gitea 仓库 Settings → Secrets 中配置以下变量：

Secret 名称	说明
DEPLOY_HOST	服务器 IP，例如 172.16.74.159
DEPLOY_PORT	SSH 端口，默认 22 可省略
DEPLOY_USER	SSH 用户名，例如 atai
DEPLOY_PASSWORD	对应的登录密码
DEPLOY_APP_DIR	（可选）部署目录，默认 /home/atai/services/qun-monitor
DEPLOY_PACKAGE_DIR	（可选）制品临时目录，默认 /home/atai/deployments/qun-monitor

如果服务器到 Gitea 存在网络限制（如本次环境无法直接访问 10.23.73.251:443），Workflow 将负责打包后 “推送” 到服务器，无需在服务器侧执行 git pull，避免占用已有进程端口或破坏现有代理设置。