teelebot

Python实现的Telegram Bot机器人框架，具有插件系统，插件支持热更新和热装载。

    __            __     __          __
   / /____  ___  / /__  / /_  ____  / /_
  / __/ _ \/ _ \/ / _ \/ __ \/ __ \/ __/
 / /_/  __/  __/ /  __/ /_/ / /_/ / /_
 \__/\___/\___/_/\___/_.___/\____/\__/

说明

teelebot 是Python编写的Telegram Bot框架。teelebot 具有插件系统，Bot功能以插件的形式组织，你只需要实现具有特定功能的插件，其余细节交给 teelebot 框架处理，极大地提高了Bot的开发部署效率。你可以自由地组合插件，来搭建具有特定功能的Bot。

插件请前往：官方插件仓库

推荐插件：

• Menu - 自动生成的插件菜单

• Uptime - 获取Bot运行状态

• PluginCTL - 插件分群开关控制

• PluginManagementTools - 插件包管理工具

• Guard - 广告过滤， 使用 DFA 对消息进行过滤；入群验证码人机检测

更新日志

• 更新日志

方法列表

• 方法列表

插件开发指南

• 插件开发指南

Demo

• Telegram Group：teelebot official（t.me/teelebot_official）
• Bot : teelebotBot（t.me/teelebotBot）
• Telegram Group： teelebot体验群（t.me/teelebot_chat）
• Bot : teelebot（t.me/teelebot）

环境要求

Python版本

teelebot 只支持 Python3.x，不支持Python2.x。

本项目在 Python 3.6 及以上版本测试通过。

安装

1.Pip

pip install teelebot

此方式推荐使用Python虚拟环境安装

2.Docker

# 无代理
docker run -it \
	--name teelebot \
	--restart always \
	-v /path/to/teelebot/config:/config \
	-v /path/to/teelebot/plugins:/plugins \
	ghcr.io/plutobell/teelebot:latest
	
# 有代理
docker run -it \
	--name teelebot \
	--restart always \
	--network host \
	-e http_proxy="http://ip:port" \
	-e https_proxy="http://ip:port" \
	-v /path/to/teelebot/config:/config \
	-v /path/to/teelebot/plugins:/plugins \
	ghcr.io/plutobell/teelebot:latest

Tip: 容器创建后请完善配置文件参数，然后重启容器

升级

1.Pip

pip install teelebot --upgrade

2.Docker

# 与Docker容器升级方法相同

另外，可通过 exec 指令在容器中执行命令 pip install teelebot --upgrade 进行升级

使用

一行命令启动 (Polling Mode)

请自行替换 < ... > 的内容

teelebot -c/--config <config file path> -p/--plugin <plugin path> -k/--key <bot key> -r/--root <your user id>

此命令会自动生成在Polling模式下适用的配置文件，并且，-c/--config 参数可以省略(省略将使用默认配置文件路径)。

一、运行模式

teelebot 支持以 Webhook 模式和 Polling 模式运行。生产环境推荐使用 Webhook 模式，而 Polling 则仅用于开发环境。

1、Webhook 模式

要以 Webhook 模式运行，请将配置文件字段 webhook 设置为 True ，此模式涉及的配置文件字段如下：

[config]
webhook=True
self_signed=False
cert_key=your private cert path
cert_pub=your public cert path
load_cert=False
server_address=your server ip address or domain
server_port=your server port
local_address=webhook local address
local_port=webhook local port
secret_token=webhook secret token

self_signed 用于设置是否使用自签名证书，而 cert_key 和 cert_pub 是你的证书路径(绝对路径)，load_cert 则用于设置 Webhook 是否加载本地证书； server_address 为你的服务器公网IP, server_port 为服务器的端口(目前 telegram 官方仅支持 443, 80, 88, 8443)，local_address 为Webhook 本地监听地址， local_port 为 Webhook 本地运行的端口；secret_token 则用于设置 Webhook 的secret token。

自签名证书生成请参考：Generating a self-signed certificate pair (PEM)

2、Polling 模式

要以 Polling 模式运行，只需要保证配置文件 webhook 字段为 False 即可。此模式最基本的配置文件如下:

[config]
key=bot key
root_id=your user id
pool_size=40
webhook=False
debug=False
plugin_dir=your plugin dir

二、运行

任意路径打开终端，输入以下命令：

• 对于使用程序配置文件默认路径的：

  输入teelebot 回车,正常情况下你应该能看见屏幕提示机器人开始运行。

• 对于命令行手动指定配置文件路径的：

  输入teelebot -c/--config <configure file path> 回车,正常情况下你应该能看见屏幕提示机器人开始运行。

  更多指令请通过 -h/--help 查看：

  usage: -m [-h] [-c CONFIG] [-k KEY] [-r ROOT] [-p PLUGIN] [-mp MAKE_PLUGIN]
            [-L] [-C] [-hi] [-d] [-v]
  
  teelebot console command list
  
  options:
    -h, --help            show this help message and exit
    -c CONFIG, --config CONFIG
                          specify the configuration file
    -k KEY, --key KEY     specify the bot api token
    -r ROOT, --root ROOT  specify the telegram user user_id of bot admin
    -p PLUGIN, --plugin PLUGIN
                          specify the plugin path
    -mp MAKE_PLUGIN, --make_plugin MAKE_PLUGIN
                          create a plugin template
    -L, --logout          log out from the cloud Bot API server before running
                          the bot locally
    -C, --close           close the bot instance before transferring it between
                          local servers
    -hi, --hide_info      hide plugin info-level console logs
    -d, --debug           run teelebot in debug mode
    -v, --version         show the current version of teelebot
  

三、配置文件

完整的配置文件如下所示:

[config]
key=bot key
root_id=your user id
plugin_dir=your plugin dir
pool_size=40 # the thread pool size, default 40, range(1, 101)
buffer_size=16 # the buffer area size, default 16(MB)
webhook=False
self_signed=False # Optional while webhook is False
cert_key=your private cert path # Optional while webhook is False
cert_pub=your public cert path # Optional while webhook is False
load_cert=False # Optional while webhook is False
server_ip=your server ip address # Optional while webhook is False
server_port=your server port # Optional while webhook is False
local_address=webhook local address # Optional while webhook is False
local_port=webhook local port # Optional while webhook is False
secret_token=webhook secret token
debug=False
hide_info=False
drop_pending_updates=False
local_api_server=local api server address # [Optional]
updates_chat_member=False # [Optional]
proxy=socks5h://user:pass@host:port # [Optional]

在 1.13.0 及以上版本，支持自动生成配置文件。（默认为Polling模式）

1.在命令行未指定配置文件路径的情况下，会在默认配置文件路径下不存在配置文件时自动生成配置文件 config.cfg。

• 在Linux下，会自动在用户目录下创建文件夹 .teelebot ，并生成配置文件 config.cfg

• 在Windows下，则会在 C:\Users\<username> 目录下创建文件夹 .teelebot ，并生成配置文件 config.cfg

2.指定配置文件

Linux 和 Windows 都可在命令行通过参数手动指定配置文件路径，命令格式：

teelebot -c/--config <configure file path>

路径必须为绝对路径，并且配置文件名也应当包含在路径内，此情况下会在指定的配置文件不存在时自动生成配置文件 。

四、导入使用

# 导入Bot类
from teelebot import Bot

# 实例化Bot类
# 不传参数时会使用teelebot默认配置文件路径下的配置文件实例化Bot类
# 在v2.2.0及以上版本，可传递参数覆盖配置文件的设定，可覆盖的参数:
#     Bot(key: str = None, debug: bool = False, proxies: dict = None)
bot = Bot()

# 使用Bot类
bot.sendMessage(chat_id="chat_id", text="Hello World!")

Tip: 导入使用时需要确保默认配置文件路径中存在配置文件,并且必须的字段已经填写

联系我

• Email：hi#ojoll.com ( # == @ )
• Blog: 北及
• Telegram Group：teelebot official（t.me/teelebot_official）
• Telegram Group：teelebot体验群（t.me/teelebot_chat）
• 其他：本repo 的 Issue