126 lines
6.8 KiB
Markdown
126 lines
6.8 KiB
Markdown
# 群监控（GramJS 版）
|
||
|
||
使用 [GramJS](https://github.com/gram-js/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. 安装依赖：
|
||
```bash
|
||
npm install
|
||
```
|
||
2. 配置环境变量：
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
填写下方参数；`SESSION_DIR` 会自动创建并持久化 `*.session` 文件。
|
||
3. 配置 `keywords.yaml`（示例见下节）。
|
||
4. 启动：
|
||
```bash
|
||
npm run dev # tsx 直接运行 TypeScript
|
||
# 或
|
||
npm run build && npm run start
|
||
```
|
||
首次登陆会提示输入手机号验证码及二步验证密码（若有）。
|
||
|
||
## 环境变量说明
|
||
- `API_ID` / `API_HASH`：来自 [my.telegram.org](https://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 一致：
|
||
|
||
```yaml
|
||
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`，避免占用已有进程端口或破坏现有代理设置。
|