80 lines
3.4 KiB
Markdown
80 lines
3.4 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` 热加载逻辑。
|
||
|
||
## 注意事项
|
||
- user-bot 与汇报 Bot 都必须在 `REPORT_CHAT_LINK` 对应的群/频道里，且 Bot 拥有发言权限。
|
||
- Telegram 对频繁入群会触发 `FLOOD_WAIT_xx`，日志会提示需要等待的秒数。
|
||
- `sessions/*.session` 含账号授权信息，请妥善保管。
|
||
- 长期部署建议使用 `pm2 / systemd` 等守护方式并接入日志轮转。
|