# 群监控（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`，避免占用已有进程端口或破坏现有代理设置。