前言

这个项目最初是为了把 Telegram 里的网盘资源频道做成更顺手的检索面板。

当前仓库已经不是早期那套 Streamlit + 单体页面 形态了，而是：

  • Telethon 负责监听频道消息
  • FastAPI 负责后端接口
  • React + Vite + Ant Design 负责前端页面
  • PostgreSQL 负责数据存储

项目地址：https://github.com/DEKVIW/tgmonitor

演示地址：https://pan.pkll.de

项目现状

当前版本的能力大致包括：

  • 自动监听网盘资源类 Telegram 频道
  • 仅保存命中规则且包含有效网盘链接的消息
  • 支持阿里云盘、百度网盘、夸克、天翼、115、123、UC、迅雷等主流网盘
  • 提供消息搜索、筛选、分页、统计、后台管理和游客模式
  • 支持频道管理、链接去重、链接巡检等运维命令

技术栈

  • Python 3.10 / 3.11
  • Telethon
  • FastAPI
  • React + TypeScript + Vite + Ant Design
  • PostgreSQL
  • Nginx

Telegram API 获取

1. 申请 Telegram API

  • 打开 https://my.telegram.org
  • 使用 Telegram 账号登录
  • 进入 API Development Tools
  • 按提示创建应用
  • 记下 api_id 和 api_hash

这两个值后面要写入项目根目录 .env。

环境变量

根目录 .env 建议至少包含：

1
2
3
4
5
6
7
8
9
TELEGRAM_API_ID=你的 Telegram API ID
TELEGRAM_API_HASH=你的 Telegram API HASH
DATABASE_URL=postgresql://tg_user:password@127.0.0.1:5432/tg_monitor
DATABASE_URL_ASYNC=postgresql+asyncpg://tg_user:password@127.0.0.1:5432/tg_monitor
DEFAULT_CHANNELS=channel_a,channel_b
SECRET_SALT=请替换成随机长字符串
LOG_LEVEL=INFO
FRONTEND_URL=http://localhost:3000
PUBLIC_DASHBOARD_ENABLED=false

说明：

  • DATABASE_URL_ASYNC 不填也能跑，程序会自动从 DATABASE_URL 推导
  • FRONTEND_URL 主要用于 CORS
  • PUBLIC_DASHBOARD_ENABLED=true 时可开启游客面板

本地启动

1. 准备数据库

先创建 PostgreSQL 数据库和账号，例如：

1
2
3
CREATE DATABASE tg_monitor;
CREATE USER tg_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE tg_monitor TO tg_user;

如果是 PostgreSQL 15+，遇到 permission denied for schema public，还要补：

1
2
3
GRANT ALL ON SCHEMA public TO tg_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO tg_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO tg_user;

2. 安装后端依赖

1
2
3
4
python -m venv tgmonitor-venv
source tgmonitor-venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Windows PowerShell：

1
2
3
4
python -m venv tgmonitor-venv
.\tgmonitor-venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install -r requirements.txt

3. 初始化数据库和默认用户

1
python -m app.scripts.init_db

这一步会自动：

  • 建表
  • 初始化默认频道
  • 在 users.json 不存在时创建默认管理员

默认管理员：

  • 用户名：admin
  • 密码：admin123

首次登录后请尽快修改密码。

4. 首次 Telethon 登录

直接运行监控程序：

1
python -m app.core.monitor

首次运行时输入手机号和验证码，登录成功后会生成：

1
tg_monitor_session.session

这个文件就是后续监听 Telegram 所需的本地 session。

5. 启动后端 API

1
uvicorn app.api.main:app --host 0.0.0.0 --port 8000 --reload

可以访问：

  • http://127.0.0.1:8000/api/health
  • http://127.0.0.1:8000/api/docs

6. 启动前端

1
2
3
cd frontend
npm install
npm run dev

默认访问：http://localhost:3000

7. 启动监控进程

开发阶段建议单独开一个终端常驻运行：

1
python -m app.core.monitor

生产部署

这里按当前项目形态，直接给出一套可落地的非 Docker 部署方式。

约定

  • 项目路径：/root/data/python/tg-monitor
  • 虚拟环境：tgmonitor-venv
  • 后端端口：8000
  • 前端静态服务端口：8501
  • 数据库：PostgreSQL
  • 前端：React + Vite 构建产物，由 Nginx 托管
  • 后端：FastAPI
  • 监控进程：python -m app.core.monitor

1. 安装基础环境

1
2
sudo apt update
sudo apt install -y python3-venv python3-pip nginx nodejs npm postgresql

如果系统自带 Node 太旧，建议单独安装 Node 18+。

2. 创建虚拟环境并安装后端依赖

1
2
3
4
5
cd /root/data/python/tg-monitor
python3 -m venv tgmonitor-venv
source tgmonitor-venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

如果遇到 uvicorn 缺失，可以补：

1
pip install "uvicorn[standard]"

如果遇到 bcrypt / passlib 兼容问题，可重装：

1
pip install --no-cache-dir --force-reinstall "bcrypt==4.1.2" "passlib==1.7.4"

3. 生产环境变量

后端根目录 .env 至少要确认这些值：

1
2
3
4
5
6
7
8
9
TELEGRAM_API_ID=你的 Telegram API ID
TELEGRAM_API_HASH=你的 Telegram API HASH
DATABASE_URL=postgresql://tg_user:password@127.0.0.1:5432/tg_monitor
DATABASE_URL_ASYNC=postgresql+asyncpg://tg_user:password@127.0.0.1:5432/tg_monitor
DEFAULT_CHANNELS=channel_a,channel_b
SECRET_SALT=请替换成随机长字符串
LOG_LEVEL=INFO
FRONTEND_URL=https://你的域名
PUBLIC_DASHBOARD_ENABLED=false

前端 frontend/.env 建议写：

1
VITE_API_BASE_URL=/api

这样浏览器请求统一走同域名下的 /api。

4. 数据库

如果数据库用户已存在，只需要改密码：

1
sudo -u postgres psql -c "ALTER USER tg_user WITH PASSWORD '<你的密码>';"

如果是新库，也可以手动创建：

1
2
3
CREATE DATABASE tg_monitor;
CREATE USER tg_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE tg_monitor TO tg_user;

PostgreSQL 15+ 如果遇到 permission denied for schema public，补：

1
2
3
GRANT ALL ON SCHEMA public TO tg_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO tg_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO tg_user;

5. 初始化数据库和默认用户

1
2
3
cd /root/data/python/tg-monitor
source tgmonitor-venv/bin/activate
python -m app.scripts.init_db

6. 前端构建

1
2
3
cd /root/data/python/tg-monitor/frontend
npm install
npm run build

构建产物位于：

1
frontend/dist/

7. 发布前端静态文件

1
2
3
sudo mkdir -p /var/www/tg-frontend
sudo cp -r /root/data/python/tg-monitor/frontend/dist/* /var/www/tg-frontend/
sudo chown -R www-data:www-data /var/www/tg-frontend

8. 项目机 Nginx 配置

先清理默认站点：

1
sudo rm -f /etc/nginx/sites-enabled/default

站点配置文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
server {
    listen 8501;
    server_name _;

    root /var/www/tg-frontend;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8000/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

保存到：

1
/etc/nginx/sites-available/tg-frontend.conf

启用并重载：

1
2
3
sudo ln -sf /etc/nginx/sites-available/tg-frontend.conf /etc/nginx/sites-enabled/tg-frontend.conf
sudo nginx -t
sudo systemctl restart nginx

9. systemd 服务

tg-api.service

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[Unit]
Description=TG Monitor API (FastAPI)
After=network.target

[Service]
User=root
WorkingDirectory=/root/data/python/tg-monitor
Environment="PATH=/root/data/python/tgmonitor-venv/bin"
ExecStart=/root/data/python/tg-monitor/tgmonitor-venv/bin/uvicorn app.api.main:app --host 0.0.0.0 --port 8000 --workers 2
Restart=always
RestartSec=3
KillSignal=SIGINT
TimeoutStopSec=20

[Install]
WantedBy=multi-user.target

tg-monitor.service

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[Unit]
Description=TG Monitor Worker
After=network.target

[Service]
User=root
WorkingDirectory=/root/data/python/tg-monitor
Environment="PATH=/root/data/python/tgmonitor-venv/bin"
ExecStart=/root/data/python/tg-monitor/tgmonitor-venv/bin/python -m app.core.monitor
Restart=always
RestartSec=3
KillSignal=SIGINT
TimeoutStopSec=20

[Install]
WantedBy=multi-user.target

写入对应文件后执行：

1
2
3
sudo systemctl daemon-reload
sudo systemctl enable --now tg-api tg-monitor
sudo systemctl status tg-api tg-monitor

10. 如果你前面还有一层反代机

域名可以直接转发到项目机：

  • https://你的域名 -> http://项目机IP:8501

11. 部署后验证

1
2
3
curl http://127.0.0.1:8000/api/health
curl -I http://127.0.0.1:8501
curl -I https://你的域名

浏览器侧再检查：

  • 登录是否正常
  • 消息列表是否正常加载
  • 统计页是否能正常出图

常用命令

频道管理

1
2
3
4
python -m app.scripts.manage --list-channels
python -m app.scripts.manage --add-channel channel_a channel_b
python -m app.scripts.manage --del-channel channel_a
python -m app.scripts.manage --edit-channel old_name new_name

去重与巡检

1
2
3
4
5
python -m app.scripts.manage --dedup-links
python -m app.scripts.manage --dedup-links-fast
python -m app.scripts.manage --check-links 24 5
python -m app.scripts.manage --link-stats
python -m app.scripts.manage --show-invalid-links

用户管理

1
2
3
4
5
python -m app.scripts.init_users --create-default
python -m app.scripts.init_users --list-users
python -m app.scripts.init_users --add-user username password
python -m app.scripts.init_users --change-password username new_password
python -m app.scripts.init_users --remove-user username

查看帮助

1
2
python -m app.scripts.manage --help
python -m app.scripts.init_users --help

迁移说明

为了避免文档和代码继续打架，这次已经按当前仓库做了口径统一：

  • 旧 Streamlit 前端不再作为部署入口
  • 当前可用前端是 frontend/ 下的 React 项目
  • 生产部署以 DEPLOY.md 为准
  • 老文章里出现的 get_session.py、generate_secret.py、tg-monitor-web.service 都不是当前仓库的标准入口