Telegram Bot with FastAPI

一个基于 FastAPI + Python Telegram Bot 的 Telegram 消息 Bot 应用

功能特性

• 📨 接收并处理 Telegram 消息
• 💬 自动回复用户消息
• 🔄 支持 Webhook 和 Polling 两种模式
• 📝 简单的命令处理（/start, /help 等）
• 🚀 使用 FastAPI 构建高效 API 服务
• ⚡ 使用 uv 作为现代 Python 包管理器

环境要求

• Python 3.11+
• uv (Python 包管理器)
• Telegram Bot Token (从 BotFather 获取)

快速开始

1. 安装依赖

uv sync

2. 配置环境变量

创建 .env 文件在项目根目录：

TELEGRAM_BOT_TOKEN=your_bot_token_here
WEBHOOK_URL=https://your-domain.com/webhook
DEBUG=False
LOG_LEVEL=INFO

3. 获取 Telegram Bot Token

1. 在 Telegram 中搜索 @BotFather
2. 发送 /newbot 命令
3. 按照提示设置机器人名称和用户名
4. 复制返回的 Token 到 .env 文件

4. 运行应用

方式 1: Polling 模式 (开发环境推荐)

uv run python -m app.main --mode polling

方式 2: Webhook 模式 (生产环境)

uv run python -m app.main --mode webhook --host 0.0.0.0 --port 8000

Webhook 模式需要 HTTPS 服务器和公网访问。

项目结构

telegram-demo/
├── app/
│   ├── __init__.py           # 包初始化
│   ├── main.py               # 应用入口
│   ├── bot.py                # Bot 核心逻辑
│   ├── handlers.py           # 消息处理器
│   ├── config.py             # 配置管理
│   └── api.py                # FastAPI 应用
├── pyproject.toml            # 项目配置
├── .env                      # 环境变量 (需创建)
└── README.md                 # 本文件

API 端点

系统端点

• GET /health - 健康检查
• GET /info - 获取 Bot 信息
• GET /status - 获取 Bot 运行状态

Webhook 端点 (仅 Webhook 模式)

• POST /webhook - 接收 Telegram 消息

Bot 命令

启动应用后，向 Bot 发送以下命令：

• /start - 获取欢迎信息
• /help - 获取帮助信息
• /ping - 测试 Bot 连接
• 任何其他文本 - Bot 将自动回复

开发指南

添加新命令

编辑 app/handlers.py，添加处理函数：

async def handle_echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """处理自定义命令"""
    await update.message.reply_text("你的回复内容")

然后在 app/bot.py 的 _setup_handlers 方法中注册：

self.app.add_handler(CommandHandler("echo", handle_echo))

添加消息过滤器

from telegram.ext import filters

# 处理所有不是命令的文本消息
self.app.add_handler(
    MessageHandler(filters.TEXT & ~filters.COMMAND, handler_function)
)

# 处理照片
self.app.add_handler(
    MessageHandler(filters.PHOTO, handle_photo)
)

使用 uv 的优势

• 🚀 极快的包解析速度
• 📦 统一的依赖管理
• 🔒 确定性的锁文件 (uv.lock)
• 🐍 Python 版本管理
• ⚡ 极小的内存占用

故障排查

Bot 无法接收消息

1. 确认 Bot Token 正确
2. 检查网络连接
3. 查看日志输出是否有错误信息

# 启用调试模式
DEBUG=True LOG_LEVEL=DEBUG uv run python -m app.main

Webhook 连接失败

1. 确保服务器支持 HTTPS
2. SSL 证书必须有效
3. 防火墙需要允许 443 端口
4. WEBHOOK_URL 必须是有效的公网地址

依赖安装失败

# 清理缓存重新安装
uv sync --refresh

部署建议

Polling 模式部署

• 适合小规模使用
• 无需公网 IP
• 可以在任何地方运行

Webhook 模式部署

推荐使用 Docker 或云平台（如 Railway, Fly.io, Heroku）:

FROM python:3.11-slim

WORKDIR /app

# 安装 uv
RUN pip install uv

# 复制项目文件
COPY . .

# 安装依赖
RUN uv sync --frozen

# 运行应用
CMD ["uv", "run", "python", "-m", "app.main", "--mode", "webhook"]

常用命令

# 创建虚拟环境并安装依赖
uv sync

# 运行应用 (Polling 模式)
uv run python -m app.main

# 运行应用 (Webhook 模式)
uv run python -m app.main --mode webhook

# 直接运行 FastAPI 服务器
uv run uvicorn app.api:app --reload

# 检查依赖
uv pip list

# 添加新依赖
uv add package-name

# 删除依赖
uv remove package-name

许可证

MIT

相关资源

• Python Telegram Bot 文档
• FastAPI 文档
• uv 文档
• Telegram Bot API 文档