131 lines
5.0 KiB
Markdown
131 lines
5.0 KiB
Markdown
# Streaming Overseer: A Telegram Monitoring Tool
|
||
|
||
This tool monitors specified Telegram channels for messages that contain certain keywords and forwards them to a private channel. It's built using Python and Telethon, a Telegram client library.
|
||
|
||
## Features
|
||
|
||
- Monitors multiple channels.
|
||
- Searches for messages with specified keywords.
|
||
- Forwards matching messages to a private channel.
|
||
|
||
## Prerequisites
|
||
|
||
Before you can use this tool, you need to set up a few things:
|
||
|
||
1. **Python 3.8+** (Tested on 3.10+)
|
||
2. **Telethon Library**
|
||
3. **A Telegram API key and API Hash**
|
||
4. **A Telegram Bot**
|
||
5. **A Private Telegram Channel**
|
||
|
||
### Installing Python
|
||
|
||
Download and install Python from [python.org](https://www.python.org/downloads/).
|
||
|
||
## Setup Instructions
|
||
|
||
### Obtaining Telegram API ID and Hash
|
||
|
||
1. **Login to your Telegram account** at [Telegram Core](https://my.telegram.org).
|
||
2. Go to `API development tools` and fill out the form.
|
||
3. You will get an `api_id` and `api_hash` which are needed for the tool.
|
||
|
||
### Creating a Telegram Bot
|
||
|
||
1. **Open Telegram** and search for [BotFather](https://t.me/botfather).
|
||
2. Send `/newbot` and follow the instructions to create your bot.
|
||
3. **Copy the token** provided by BotFather.
|
||
|
||
### Setting Up a Private Channel
|
||
|
||
1. **Create a new channel** in Telegram.
|
||
2. **Switch the channel's privacy to private** in the channel settings.
|
||
3. **Add your bot as an administrator** to the channel.
|
||
|
||
## Configuration Files
|
||
|
||
The script uses several files for configuration:
|
||
|
||
- `credentials.json`: Automatically created if not present. It stores API keys, bot token, and private channel ID.
|
||
- `keywords.txt`: Contains keywords to monitor. Supports special modifiers for dynamic matching:
|
||
- `*` at the end allows up to three additional characters.
|
||
- `**` allows up to six additional characters.
|
||
- `#` at the start includes numeric characters (up to three).
|
||
- `##` includes numeric characters (up to six).
|
||
|
||
**Note: Separate keywords using commas. Keywords can span multiple lines for readability; newlines are ignored.**
|
||
- `channels.txt`: List of channel usernames (the part after `t.me/`) to monitor
|
||
- Separate channel names with commas, and feel free to list them across multiple lines for better readability. Newlines between names are ignored.
|
||
|
||
**Note: Ensure you have joined any channel you wish to monitor.**
|
||
|
||
### Examples
|
||
|
||
- `keywords.txt`
|
||
```
|
||
hello*, world**, #123,
|
||
##123456, #or_any_combination**
|
||
```
|
||
- `channels.txt`
|
||
```
|
||
python, daily_news,
|
||
target3, target4
|
||
```
|
||
|
||
|
||
## Running the CLI Tool
|
||
|
||
```bash
|
||
python streaming_overseer.py
|
||
```
|
||
|
||
## Web Control Panel (FastAPI + Vue)
|
||
|
||
The project now ships with a FastAPI backend (`backend/`) and a Vue 3 dashboard (`frontend/`) so you can update credentials, manage keywords/channels, and watch matches in real time.
|
||
|
||
### Authentication
|
||
|
||
- All API routes (except `/api/auth/token`) are protected with JWT. The default credentials are `admin / admin123` and are stored in `users.json`.
|
||
- After the first login, use the UI “change password” endpoint (or call `POST /api/auth/change-password`) to update the password. The JWT expires after 60 minutes.
|
||
- Include the bearer token in the `Authorization` header for REST calls; the frontend handles this automatically after you log in from the new login page.
|
||
|
||
### Backend
|
||
|
||
```
|
||
cd backend
|
||
python -m venv .venv
|
||
.venv\Scripts\activate
|
||
pip install -r ../requirements.txt
|
||
uvicorn app.main:app --reload
|
||
```
|
||
|
||
The API is exposed on `http://localhost:8000/api`. Important endpoints:
|
||
|
||
- `POST /api/auth/token`, `GET /api/auth/me`, `POST /api/auth/change-password`
|
||
- `GET /api/credentials` (list), `POST /api/credentials` (create), `PUT /api/credentials/{id}` (update), `DELETE /api/credentials/{id}`, `POST /api/credentials/{id}/activate`, `GET /api/credentials/active`
|
||
- `GET/PUT /api/keywords`
|
||
- `GET/PUT /api/channels`
|
||
- `POST /api/scanner/start|stop`, `GET /api/scanner/status`
|
||
- `GET /api/matches`, `GET /api/matches/stream`
|
||
|
||
### Frontend
|
||
|
||
```
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
Set `VITE_API_BASE` in a `.env` file if your backend is not running on `http://localhost:8000/api`. Once the dev server starts, visit `http://localhost:5173/login`, log in with the admin user, and the dashboard will become available.
|
||
|
||
### Production Notes
|
||
|
||
- FastAPI already enables permissive CORS for local development; tighten it for production.
|
||
- Ensure `credentials.json`, `keywords.txt`, `channels.txt`, and `users.json` are stored securely; the API reads/writes the same files as the CLI script.
|
||
- The Telethon scanner still forwards matching messages to the configured Telegram channel while also streaming match metadata to the dashboard.
|
||
|
||
### Managing multiple credentials
|
||
|
||
- The “凭据配置”页面 now supports multiple Telegram API credentials. Each record stores API ID/API Hash/手机号/Bot Token/频道 ID，列表中可一键设为当前使用的账号。
|
||
- 新建或编辑凭据后，点击“设为当前”即可让扫描器切换到该账号运行；激活状态会同步到 `credentials.json` 中的 `active` 字段。
|