• 功能特性
• 快速开始
  • 前置要求
  • Docker 部署
  • 本地开发
• 配置说明
  • 环境变量配置
  • 个人服务配置
• 使用指南
  • 基本命令
  • 资源搜索
  • QAS 下载管理
  • Emby 集成
• 开发指南
• 项目结构
• 常见问题
• 鸣谢
• 许可证

• 多平台资源搜索: 支持 CloudSaver、PanSou 等多个资源搜索平台
• TMDB 集成: 集成 The Movie Database API 获取电影/电视剧详细信息
• 资源链接状态检查: 自动检查夸克网盘链接有效性
• 智能分类: 支持电视节目、电影分类和多季模式识别

• Quark Auto Save 集成: 集成 QAS 项目 实现夸克网盘自动下载
• AI 增强功能: 使用 AI 生成下载参数和正则表达式，智能识别季数
• 任务管理: 创建、更新、删除、运行下载任务，支持多季电视剧自动分类
• 正则匹配: 智能文件筛选和重命名规则，支持自定义 pattern 和 replace

• 媒体库管理: 搜索和管理 Emby 媒体库资源
• 媒体库刷新: 远程刷新 Emby 媒体库
• 通知配置: 管理 Emby 新媒体加入通知
• 元数据获取: 获取详细的媒体信息和海报

• 智能参数生成: AI 自动生成下载任务的 pattern 和 replace 规则
• 季数分类: AI 自动识别和分类电视剧季数
• 多 AI 提供商: 支持 OpenAI、DeepSeek、Kimi 等多个 AI 服务
• 动态配置: 通过 /upsert_configuration 命令配置，每个用户独立设置 AI 服务

• 角色权限: 支持 Owner、Admin、User 三级权限管理
• 命令权限: 基于角色的命令访问控制
• 用户注册: 简单的用户注册和权限分配

• 定时任务: 支持定时提醒和任务调度
• 作业管理: 创建、查看、删除定时作业

• Docker 和 Docker Compose（推荐）
• 或 Python 3.8+ 环境（本地开发）
• Telegram Bot Token（从 @BotFather 获取）

1. 创建部署目录

   mkdir tgbot && cd tgbot

2. 创建 docker-compose.yml 文件

   version: '3.8'
   
   services:
     tgbot:
       image: beocean/tgbot:latest
       container_name: tgbot
       restart: unless-stopped
       environment:
         # 必需配置
         - TG_BOT_TOKEN=your_telegram_bot_token
         - CRYPTO_PASSWORD=your_strong_password_16chars
         - CRYPTO_SALT=your_random_salt_16chars
   
         # 可选配置
         - TMDB_API_KEY=your_tmdb_api_key
         - TMDB_POSTER_BASE_URL=https://image.tmdb.org/t/p/original
         - PANSOU_HOST=https://your-pansou-host.com
         - CLOUD_SAVER_HOST=https://your-cloud-saver-host.com
         - CLOUD_SAVER_USERNAME=your_username
         - CLOUD_SAVER_PASSWORD=your_password
       volumes:
         - ./data:/app/db/data

3. 启动服务

   docker compose up -d

4. 查看日志

   docker compose logs -f

5. 在 Telegram 中使用

   • 找到你的机器人
   • 发送 /register 注册
   • 发送 /help 查看可用命令

1. 克隆仓库

   git clone <repository-url>
   cd tgbot

2. 安装依赖

   pip install -r requirements.txt

3. 配置环境变量

   export TG_BOT_TOKEN=your_telegram_bot_token
   export CRYPTO_PASSWORD=your_strong_password_16chars
   export CRYPTO_SALT=your_random_salt_16chars

4. 初始化数据库

   alembic upgrade head

5. 运行机器人

   python main.py

⚠️ 配置方式：通过系统环境变量设置（export KEY=value、Docker environment 字段、systemd/Supervisor 配置等）

🔒 安全提示：CRYPTO_PASSWORD 和 CRYPTO_SALT 一旦设置，后续修改会导致已加密数据无法解密，请妥善保管。

通过 /upsert_configuration 命令，每个用户可以配置自己的个人服务连接。

/register          # 注册新用户（首次使用必须）
/help              # 显示可用命令列表
/refresh_menu      # 刷新菜单
/my_info           # 查看个人信息
/upsert_configuration  # 配置个人服务（QAS、Emby、AI）

/search_tv {剧名}              # 搜索电视剧资源
/search_movie {电影名}         # 搜索电影资源
/search_media_resource {资源名} # 搜索媒体资源

示例：

/search_tv 权力的游戏
/search_movie 肖申克的救赎

QAS (Quark Auto Save) 集成，实现夸克网盘自动下载。

/qas_add_task {分享链接} {任务名}  # 添加下载任务
/qas_list_task {任务名}           # 列出任务
/qas_delete_task {任务ID}         # 删除任务
/qas_run_script {任务ID}          # 运行任务
/qas_view_task_regex {任务ID}     # 查看任务正则匹配效果

工作流程：

1. 使用 /upsert_configuration 配置 QAS 服务
2. 使用 /qas_add_task 添加夸克网盘分享链接
3. AI 自动生成下载参数和正则表达式
4. 使用 /qas_run_script 执行下载任务

/emby_list_resource {资源名}    # 列出 Emby 媒体资源
/emby_list_notification         # 列出 Emby 通知配置

功能：

• 搜索和管理 Emby 媒体库
• 远程刷新媒体库
• 管理新媒体加入通知

/remind {时间} {提醒内容}  # 设置提醒
/list_my_job               # 列出个人作业
/delete_job {作业ID}       # 删除作业

/set_admin {用户ID}  # 设置管理员权限

1. 克隆仓库并安装依赖

   git clone <repository-url>
   cd tgbot
   pip install -r requirements.txt

2. 配置环境变量

   export TG_BOT_TOKEN=your_token
   export CRYPTO_PASSWORD=your_password
   export CRYPTO_SALT=your_salt

3. 初始化数据库

   alembic upgrade head

# 生成迁移脚本（自动检测模型变更）
alembic revision --autogenerate -m "迁移描述"

# 应用迁移
alembic upgrade head

# 回滚到上一个版本
alembic downgrade -1

# 查看迁移历史
alembic history

1. 在 db/models/ 目录下创建新的模型文件
2. 在 alembic/env.py 中导入新模型
3. 运行 alembic revision --autogenerate -m "添加XXX模型"
4. 检查生成的迁移脚本
5. 运行 alembic upgrade head 应用迁移

1. 在 api/ 目录下创建或编辑命令文件
2. 使用 @command 装饰器定义命令处理函数

   from api.base import command
   
   @command(name="my_command", description="命令描述")
   async def my_command_handler(update, context):
       # 命令逻辑
       pass

3. 在 config/config.py 的 ROLE_COMMANDS 中配置权限
4. 在 main.py 中导入新命令模块

• 遵循 PEP 8 Python 代码规范
• 使用有意义的变量和函数名
• 添加必要的注释和文档字符串
• 敏感信息使用加密存储

tgbot/
├── 📂 api/                    # API 和命令处理
│   ├── base.py               # 基础命令框架
│   ├── commands.py           # 命令管理
│   ├── user.py               # 用户管理
│   ├── resource.py           # 资源搜索
│   ├── qas.py                # QAS 集成
│   ├── emby.py               # Emby 集成
│   ├── ai_config.py          # AI 配置
│   └── user_config.py        # 用户配置
│
├── 📂 config/                 # 配置文件
│   ├── config.py             # 主配置（权限、命令等）
│   ├── prod.py               # 生产环境配置
│   └── test.py               # 测试环境配置
│
├── 📂 db/                     # 数据库相关
│   ├── 📂 models/            # 数据模型
│   │   ├── base.py           # 基础模型
│   │   ├── user.py           # 用户模型
│   │   ├── qas.py            # QAS 任务模型
│   │   ├── emby.py           # Emby 配置模型
│   │   ├── ai_config.py      # AI 配置模型
│   │   └── job.py            # 定时任务模型
│   ├── main.py               # 数据库初始化
│   └── 📂 data/              # SQLite 数据库文件
│
├── 📂 utils/                  # 工具函数
│   ├── ai.py                 # AI 服务集成
│   ├── qas.py                # QAS 工具
│   ├── emby.py               # Emby 工具
│   ├── quark.py              # 夸克网盘工具
│   ├── crypto.py             # 加密工具
│   ├── command_middleware.py # 命令中间件
│   └── common.py             # 通用工具
│
├── 📂 alembic/               # 数据库迁移
│   ├── versions/             # 迁移脚本
│   └── env.py                # Alembic 配置
│
├── main.py                   # 主入口文件
├── requirements.txt          # Python 依赖
├── Dockerfile                # Docker 构建文件
└── README.md                 # 项目文档

docker compose pull
docker compose up -d

git pull
pip install -r requirements.txt
alembic upgrade head

# Docker 部署
cp -r ./data ./data_backup_$(date +%Y%m%d)

# 本地部署
cp -r db/data db/data_backup_$(date +%Y%m%d)

• 🔑 妥善保管密钥：Bot Token、API Key、加密密钥等敏感信息
• 🚫 不要提交密钥：确保 .env 文件在 .gitignore 中
• 🔒 使用强密码：CRYPTO_PASSWORD 和 CRYPTO_SALT 至少16位
• 👥 限制访问权限：合理分配 Owner、Admin、User 角色
• 🔄 定期更新：及时更新依赖包修复安全漏洞
• 📦 数据备份：定期备份数据库文件

本项目在开发过程中受益于以下优秀的开源项目：

感谢这些项目的开发者为开源社区做出的贡献！

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

• 遵循现有的代码风格和规范
• 添加必要的测试和文档
• 确保所有测试通过
• 提供清晰的提交信息

本项目采用 Apache License 2.0 许可证 - 详见 LICENSE 文件

Copyright 2024 tgbot

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

遇到问题？以下是获取帮助的方式：

1. 📖 查看文档：仔细阅读本 README 和常见问题部分
2. 🔍 搜索 Issues：查看是否有人遇到过类似问题
3. 📝 提交 Issue：在 GitHub 上创建新的 Issue，提供详细信息：
   • 问题描述
   • 复现步骤
   • 环境信息（操作系统、Python 版本等）
   • 相关日志
4. 💬 参与讨论：在 GitHub Discussions 中交流

Docker 部署：

docker compose logs -f tgbot

本地开发： 检查应用输出或日志文件