阅读其他语言版本: English

DomoBot

一个强大、多功能的Telegram机器人，支持价格查询、天气预报、电影电视信息、游戏价格比较等，使用Docker容器化以便于部署。

🚀 立即试用: @mengpricebot

🎉 全部免费 - 可添加到任意群组！

所有用户和群组可用的公开功能:

📺 流媒体价格: Netflix、Disney+、Spotify、HBO Max、Xbox Game Pass全球各地区订阅价格查询
👤 用户信息: Telegram注册日期、账号年龄和ID查询
⏰ 时间和时区: 当前时间查询、时区转换和时区列表
📰 新闻聚合: 来自40+源的实时新闻，包括科技、社交、财经和综合新闻
🌐 WHOIS和DNS查询: 域名、IP、ASN、TLD信息查询，包含DNS记录和Telegraph集成
🍳 烹饪助手: 菜谱搜索、分类浏览、智能膳食规划和每日菜单推荐
🎭 表情包娱乐: 随机表情包获取，AI生成描述增强理解，支持自定义数量（1-20），智能重试确保优质内容，自动删除和智能缓存
📊 股票金融: 实时股票价格查询、15类排行榜（涨跌幅、科技股、基金）、分析师评级、财务报表、多市场支持（美/港/沪/马），智能搜索支持股票代码和公司名称
🛢️ 燃油价格: 全球163国燃油价格查询（汽油+柴油）、中国31省油价排行（92/95/98/柴油）、支持多国查询、自动CNY转换、数据来源GlobalPetrolPrices.com并显示实际价格日期
📱 社交媒体解析: 支持20+平台（抖音、快手、B站、YouTube、TikTok、小红书、Twitter/X、Instagram、Facebook、微博等）的视频、图片、图文解析，支持命令模式和群组自动监听模式
🆔 快速命令: /nf, /ds, /sp, /max, /xbox, /when, /id, /time, /timezone, /news, /newslist, /whois, /dns, /recipe, /meme, /finance, /fuel, /platforms
👥 群组友好: 在任意 Telegram 群组中都可使用，无需白名单申请
🔧 自助服务: 如果新命令不在输入建议中显示，请使用 /refresh 刷新

高级功能（加密货币、天气、Steam价格、电影电视、地图服务等）需要白名单权限。

📝 项目概览

这是一款基于Python的、多功能的Telegram机器人，具备以下特性：

✨ 功能特性

📺 公开流媒体价格: 所有用户可用 - 查询Netflix、Disney+、Spotify、HBO Max等流媒体服务在全球各地区的订阅价格。
🎮 公开Xbox Game Pass价格: 所有用户可用 - 全面的Xbox Game Pass订阅价格查询，覆盖全球各地区。功能包括PC Game Pass和Ultimate套餐月度价格、多地区价格对比支持40+国家/地区、最便宜地区Top 10排行榜（PC和Ultimate套餐）、多国查询支持格式如/xbox US TR IN、本地货币显示并自动CNY转换、inline模式支持在任意聊天中快速查价、智能缓存系统和全面错误处理。支持国家代码（US、TR、IN）、中文名称（美国、土耳其、印度）和英文名称，输入格式灵活。命令：/xbox（PC套餐Top 10）、/xbox ultimate（Ultimate套餐Top 10）、/xbox <国家>（指定地区）。
👤 公开用户信息查询: 所有用户可用 - 查询Telegram用户注册日期、账号年龄，以及获取用户/群组ID。
⏰ 公开时间和时区查询: 所有用户可用 - 查询任意时区的当前时间，时区间时间转换，以及查看支持的时区列表和IANA数据库集成。
📰 公开新闻聚合: 所有用户可用 - 接入40+新闻源的实时资讯，包括GitHub趋势、知乎热榜、微博热搜、科技新闻（IT之家、Hacker News）、财经新闻（金十数据、华尔街见闻）等，支持智能缓存和分类界面。
🌐 公开WHOIS和DNS查询: 所有用户可用 - 全面的域名、IP地址、ASN和TLD信息查询，集成实时IANA数据库和IP地理位置服务。支持智能查询类型检测，支持域名（.com、.io）、IP地址（IPv4/IPv6）、ASN号码（AS15169）和TLD信息（.com、.me）查询，提供详细的注册机构、WHOIS服务器、创建日期和管理组织数据。新功能: IP查询现在包含服务器实际地理位置信息，包括国家、地区、城市、坐标、ISP信息和时区数据，通过IP-API.com集成实现，清晰区分WHOIS注册数据和实际地理位置。增强功能: 域名WHOIS查询现在自动包含完整的DNS记录（A、AAAA、MX、NS、CNAME、TXT、SOA、PTR），支持智能显示格式化。提供独立的/dns命令进行纯DNS记录查询。长查询结果自动使用Telegraph集成显示完整信息，并提供摘要预览。
🍳 公开烹饪助手: 所有用户可用 - 基于HowToCook数据库的全面菜谱搜索和膳食规划系统，包含1000+中文菜谱。功能包括智能菜谱搜索（关键词匹配）、分类浏览（荤菜、素菜、主食、汤羹、水产、早餐、甜品等）、智能膳食规划（支持过敏原和忌口设置）、每日菜单推荐（人数选择）、随机菜谱发现和Telegraph集成（长菜谱显示完整食材和制作步骤）。所有菜谱包含难度评级、烹饪时间、份量和详细营养指导。
🎭 公开表情包: 所有用户可用 - 从memes.bupt.site API获取随机表情包，配备AI生成描述增强理解体验。具备智能重试机制确保单个表情包请求时获得优质有描述内容，支持自定义数量（1-20），智能缓存系统，自动删除调度（15分钟）和链接后备显示。功能包括参数验证、实时状态更新和全面的错误处理，确保可靠的表情包投递。描述优先级：人工审核 > AI描述 > 无描述。
📊 公开股票金融: 所有用户可用 - 由Yahoo Finance API提供的全面金融市场数据，支持实时股票价格查询和技术指标。功能包括15类排行榜（日涨跌幅、最活跃、成长科技股、低估值股票、共同基金等6类）、智能股票搜索支持股票代码和公司名称跨多个市场（美国、香港、中国、马来西亚）、分析师评级（买入/卖出/持有评级）、财务报表（损益表、资产负债表、现金流量表）、分类按钮界面、智能缓存（不同数据类型采用不同TTL）和全面的错误处理及自动删除。支持灵活搜索查询如"AAPL"、"Apple"、"Tesla"、"6033.KL"、"Maybank"等多语言匹配。
🛢️ 公开燃油价格: 所有用户可用 - 全球163国和中国31省燃油价格查询。功能包括汽油和柴油价格自动CNY转换、全球排行榜显示最便宜和最贵Top 10国家（含国旗和中文名称）、中国省份排行榜支持92/95/98汽油和柴油详细价格对比、多国查询支持格式如/fuel my sg th、本地货币显示同时显示USD和CNY价格、实际价格日期来自源网站、Inline模式支持包含完整详情（排行榜和对比）、数据来源GlobalPetrolPrices.com（每周/每月更新）、智能缓存24小时TTL匹配爬虫计划。
📱 公开社交媒体解析 (仅查看支持平台): 所有用户可用 - 使用 /platforms 查看支持的20+平台列表。
🔴 Reddit帖子解析: 需要白名单 - 完整的Reddit帖子解析和列表查询功能。具备OAuth 2.0认证（客户端凭证流）、单帖解析（支持图片、视频、图集上传）、热门帖子列表（/reddit hot [subreddit]）、Top帖子列表（/reddit top [subreddit] [时间]，支持hour/day/week/month/year/all）、AI中文翻译（OpenAI API驱动的内容总结和列表翻译）、大文件视频上传（Pyrogram优先，支持最大2GB）、Inline模式（直接输入Reddit链接或使用reddit hot/top命令）、交互式按钮（原帖链接、AI总结/翻译）、Redis缓存（24小时TTL）、每周自动清理和MarkdownV2格式化。命令：/reddit <链接>、/reddit hot [subreddit]、/reddit top [subreddit] [时间]。(需要白名单)
🎵 网易云音乐: 需要白名单 - 完整的网易云音乐功能。功能包括歌曲搜索（/netease <关键词>）带交互式编号结果、直接下载（支持歌曲ID和music.163.com链接）、歌词获取（/lyric，LRC格式）、自动链接识别（music.163.com/163cn.tv/163cn.link链接自动下载）、Inline模式（后台下载+edit_inline_media无缝发送音频）、Redis缓存（7天TTL，缓存命中直接发送音频）、FLAC/MP3音质显示（含码率和文件大小）、ID3/Vorbis元数据嵌入（使用mutagen-rs，Rust驱动）、大文件上传（>50MB通过Kurigram MTProto）、EAPI加密和并发下载限制（信号量=4）。命令：/netease、/lyric。(需要白名单)
🎵 YouTube Music: 需要白名单 - 完整的YouTube Music功能。功能包括歌曲搜索（/yt <关键词>）带交互式编号结果、直接下载（支持videoId和YouTube/YouTube Music链接）、歌词获取（/ytlyric）、多地区榜单（全球/美国/日本/韩国/英国/香港/台湾）通过/yt chart查看、自动链接识别（youtube.com/youtu.be/music.youtube.com链接自动下载）、Inline模式（后台下载+edit_inline_media无缝发送音频）、Redis缓存（缓存命中直接发送音频）、yt-dlp主下载（pytubefix自动备用）、大文件上传（>50MB通过Kurigram MTProto）和并发下载限制（信号量=4）。命令：/yt、/ytmusic、/ytlyric。(需要白名单)
🗺️ 地图服务: 智能位置搜索和导航系统，支持自动语言检测 - 中文用户使用高德地图API，英文用户使用Google Maps API。功能包括全面位置搜索（详细地点信息、评分和类型）、附近服务推荐（餐厅、医院、银行、加油站、超市、学校、酒店）、路线规划（逐步导航指示和预计时间）、地理编码（地址转坐标）、逆地理编码（坐标转地址）、交互式按钮界面（单一/map命令）、会话管理（多步骤操作）、Redis缓存（不同数据类型采用适当TTL）和自动删除所有消息。支持文本输入、位置分享和坐标查询，配备全面的错误处理。(需要白名单)
📱 社交媒体解析 (完整解析功能): 白名单用户/群组可用 - 支持20+平台（抖音、快手、B站、YouTube、TikTok、小红书、Twitter/X、Instagram、Facebook、微博等）的视频、图片、图文解析。功能包括命令模式（/parse <链接>）和群组自动监听模式（管理员可通过/admin启用/禁用）、AI内容总结、视频分割（FFmpeg）、图床上传、Telegraph发布、语音转录和平台Cookie配置。所有高级功能可选启用。(需要白名单)
✈️ 航班服务: 基于Google Flights API的智能航班搜索和预订信息系统。具备多语言机场识别（中文、英文、IATA代码）、全球机场覆盖（亚洲、欧洲、美洲、大洋洲）、智能机场匹配（自动选择最佳机场）、实时航班数据（价格分析和预订选项）、智能路线规划（时区计算和航班距离信息）、全面航空公司覆盖（多预订渠道）和Telegraph集成（详细航班列表显示）。支持混合语言输入，如北京 New York或吉隆坡 Bangkok，自动转换为最佳机场对（PEK↔JFK、KUL↔BKK）。(需要白名单)
🏨 酒店服务: 基于Google Hotels API的智能酒店搜索和预订信息系统。具备多语言位置识别（中文、英文、特定区域）、全球酒店覆盖支持世界主要城市、智能位置匹配自动区域选择、实时酒店数据（价格分析和预订选项）、全面住宿信息包含评分、设施和描述、灵活日期处理自动解析入住退房日期、交互式排序筛选（价格/评分选项）、Telegraph集成详细酒店列表显示和智能住宿时长分析。支持混合语言输入，如北京、Tokyo、Kepong、Times Square NYC等，自动位置解析。(需要白名单)
🎬 电影和电视剧信息: 经过完全重构的统一按钮界面系统，提供直观便捷的交互体验。具备三平台数据整合（TMDB + JustWatch + Trakt）、全面搜索功能、详细电影/电视剧信息（海报、评分）、交互式季集浏览（用户输入选择）、一键访问推荐、评价、视频、相关内容和流媒体平台。增强功能包括Telegraph集成（长内容显示）、统一排行榜系统（热门/即将上映/正在播出内容）、智能会话管理（多步骤交互）和全面缓存（自动清理）。所有功能通过简单的/movie、/tv、/person和/chart命令访问，无需记忆复杂子命令。(需要白名单)
🪙 加密货币价格: 查询实时加密货币价格，支持自定义数量和货币转换，并显示 24 小时和 7 天的价格变化率。新功能: 交互式排行榜系统，包含热门搜索币种、涨跌幅排行榜、市值排行榜和交易量图表 - 全部由CoinGecko免费API提供支持（无需API密钥）。功能包括智能缓存、刷新功能和统一菜单界面。(需要白名单)
💳 BIN查询: 查询信用卡BIN（银行识别号）信息，包括卡片品牌、类型、发卡银行和国家等详细信息。(需要白名单)
🌦️ 天气预报: 提供详细、多格式的天气预报（实时、多日、每小时、分钟级降水和生活指数）。(需要白名单)
💱 汇率转换: 实时汇率查询，支持数学表达式计算（如 /rate USD 1+2*3）。(需要白名单)
🎮 Steam 价格: Steam 游戏、捆绑包多区域价格对比和综合搜索功能。(需要白名单)
📱 应用商店: 查询 App Store（详细内购项目定价）和 Google Play（内购价格范围）的应用价格和内购信息。(需要白名单)
🔍 网络诊断工具: 全面的网络分析和故障排查工具包。功能包括IP信誉检测（AbuseIPDB多密钥轮询和ipapi.is集成，提供滥用评分和威胁情报）、MAC地址厂商查询（使用IEEE OUI数据库进行硬件识别）、域名解析（A/AAAA记录查询和地理位置数据）、网站可用性监控（HTTP状态码和响应时间测量）、全球延迟测试（覆盖6大洲20+节点的网络性能分析）、MTR路由追踪（15跳路径分析，包含丢包率和延迟统计）、WARP检测（Cloudflare WARP出口IP识别）和Inline模式支持（在任何聊天中快速诊断）。支持IP地址（IPv4/IPv6）、MAC地址（多种格式）、域名和URL，具备智能输入类型检测和全面的错误处理。(需要白名单)
🔐 管理系统: 完善的管理员权限系统和用户/群组白名单管理。
📊 用户缓存与统计: 缓存用户数据并进行命令使用统计。
🛡️ AI反垃圾: 基于OpenAI GPT-4o-mini的智能垃圾信息检测系统，支持群组级别配置、基于加群时间和活跃度的自动用户验证、可自定义垃圾分数阈值、全面的日志记录和统计分析、全局统计仪表板、Telegraph集成日志查看和自动数据清理。功能包括对新用户的智能检测同时尊重已验证成员、详细的垃圾分析（包含原因和模拟文本）、封禁/禁言操作，以及完整的管理面板集成（支持单群组和跨群组分析）。

🚀 快速开始

基础命令 (本地开发)

# 安装依赖
pip install -r requirements.txt

# 运行机器人
python main.py

# 手动清理日志
python cleanup_logs.py

Docker 部署 (推荐)

# 使用 Docker Compose 启动所有服务
docker-compose up -d

# 查看机器人容器的日志
docker-compose logs -f appbot

# 停止所有服务
docker-compose down

⚙️ 配置 (`.env`)

所有配置都通过 .env 文件进行管理。你必须将 .env.example 复制为 .env 并填写所需的变量。

变量	描述	默认/示例
`BOT_TOKEN`	（必需）来自 @BotFather 的 Telegram Bot Token。
`SUPER_ADMIN_ID`	（必需）拥有所有权限的机器人主要所有者的用户ID。
`CMC_API_KEY`	（可选） CoinMarketCap的API Key，用于启用 `/crypto` 命令。
`BIN_API_KEY`	（可选） DY.AX的API Key，用于启用 `/bin` 命令。
`TMDB_API_KEY`	（可选） TMDB的API Key，用于启用 `/movie` 和 `/tv` 命令。
`TRAKT_API_KEY`	（可选） Trakt的API Key，用于增强电影/电视剧统计和热门趋势数据。
`GOOGLE_MAPS_API_KEY`	（可选） Google Maps的API Key，用于 `/map` 命令（英文用户）。
`AMAP_API_KEY`	（可选）高德地图的API Key，用于 `/map` 命令（中文用户）。
`SERPAPI_KEY`	（可选） SerpAPI的API Key，用于启用 `/flight` 航班服务命令。
`QWEATHER_API_KEY`	（可选）和风天气的API Key，用于启用 `/tq` 命令。
`EXCHANGE_RATE_API_KEYS`	（可选） openexchangerates.org的API Key，用于启用 `/rate` 命令。多个密钥用逗号分隔。
`ENABLE_USER_CACHE`	（可选）启用用户缓存系统 (`true`/`false`)。	`false`
`USER_CACHE_GROUP_IDS`	（可选）用逗号分隔的群组ID，用于监控用户缓存。留空则监听所有机器人加入的群组。	(空 - 监听所有群组)
`DB_HOST`	数据库的主机名。必须是 `mysql`。	`mysql`
`DB_PORT`	数据库的内部端口。	`3306`
`DB_NAME`	数据库的名称。必须与 `docker-compose.yml` 中的设置匹配。	`bot`
`DB_USER`	数据库的用户名。必须与 `docker-compose.yml` 中的设置匹配。	`bot`
`DB_PASSWORD`	（必需）数据库的密码。必须与 `docker-compose.yml` 中的设置匹配。	`your_mysql_password`
`REDIS_HOST`	缓存服务的主机名。必须是 `redis`。	`redis`
`REDIS_PORT`	Redis 的内部端口。	`6379`
`DELETE_USER_COMMANDS`	设为 `true` 以启用自动删除用户命令的功能。	`true`
`USER_COMMAND_DELETE_DELAY`	删除用户命令前的延迟时间（秒）。使用 `0` 表示立即删除。	`5`
`LOG_LEVEL`	设置日志级别 (`DEBUG`, `INFO`, `WARNING`, `ERROR`)。	`INFO`
`LOAD_CUSTOM_SCRIPTS`	设为 `true` 以启用从 `custom_scripts/` 目录加载脚本的功能。	`false`
`OPENAI_API_KEY`	（可选） OpenAI的API Key，用于AI反垃圾检测功能。设置后功能自动启用。需要在 `/admin` 面板中为特定群组手动开启检测。
`REDDIT_CLIENT_ID`	（可选） Reddit的Client ID，用于启用 `/reddit` 命令（OAuth模式）。从Reddit App创建页面获取。
`REDDIT_CLIENT_SECRET`	（可选） Reddit的Client Secret，用于启用 `/reddit` 命令（OAuth模式）。从Reddit App创建页面获取。
`REDDIT_API_MODE`	（可选） Reddit API模式：`oauth`（默认，需要CLIENT_ID/SECRET）或 `json`（JSON endpoint，TLS指纹伪装+WARP代理，无需API key）。	`oauth`
`ABUSEIPDB_API_KEY`	（可选） AbuseIPDB API密钥，用于 `/scan` 命令的IP信誉检测。支持多个Key轮询（逗号分隔）。

配置由 utils/config_manager.py 中的 BotConfig 类管理，该类支持设置缓存时长、自动删除开关、功能开关和性能参数。

配置文件

配置由 utils/config_manager.py 中的 BotConfig 类管理，支持：

各项服务的缓存时长设置
消息自动删除设置
功能开关设置
性能参数设置

🎯 命令示例

公开命令 (所有用户和群组可用)

# 流媒体服务价格
/nf          # Netflix全球价格
/ds US       # 美国Disney+价格
/sp          # Spotify全球价格
/max         # HBO Max全球价格
/xbox        # Xbox Game Pass全球价格（PC Game Pass套餐Top 10）
/xbox US     # 美国Xbox Game Pass价格
/xbox ultimate  # Xbox Game Pass Ultimate套餐全球Top 10
/xbox US TR IN  # 多国查询（美国、土耳其、印度）
# Inline模式: @bot xbox$ - PC Game Pass套餐Top 10
# Inline模式: @bot xbox ultimate$ - Ultimate套餐Top 10
# Inline模式: @bot xbox US TR$ - 指定地区查询

# 用户信息查询
/when 123456789           # 通过用户ID查询
/when @username           # 通过用户名查询
/when username            # 通过用户名查询（不带@）
/when                     # 回复用户消息后使用
/id                       # 获取用户/群组ID
/id                       # 回复消息后使用

# 时间和时区查询
/time                     # 显示时间命令帮助
/time 北京                # 北京当前时间
/time 日本                # 日本当前时间
/time 美国                # 美国当前时间
/convert_time 中国 14:30 美国    # 将下午2:30从中国时间转换为美国时间
/timezone                 # 查看支持的时区列表

# 新闻聚合
/news                     # 交互式新闻源选择界面
/newslist                 # 显示所有新闻源和分类
/newslist zhihu           # 获取知乎热榜（默认10条）
/newslist zhihu 5         # 获取知乎热榜前5条
/newslist github 15       # 获取GitHub趋势前15条
/hotnews                  # 快速获取多源热门新闻汇总

# WHOIS和DNS查询（增强DNS记录和Telegraph集成）
/whois google.com         # 域名WHOIS + DNS记录（A、AAAA、MX、NS、CNAME、TXT、SOA、PTR）
/whois 8.8.8.8           # IP地址信息，包含WHOIS注册信息 + 实际地理位置
/whois AS15169            # ASN信息查询
/whois .com               # TLD信息，包含IANA数据
/dns github.com           # 仅DNS记录查询（A、AAAA、MX、NS、CNAME、TXT、SOA、PTR）

# 烹饪助手（统一菜谱界面）
/recipe                   # 交互式菜单，包含所有烹饪功能
/recipe 红烧肉             # 直接搜索菜谱（按菜名或食材）
# 菜单功能包括：菜谱搜索、分类浏览、随机推荐、每日菜单规划、智能膳食规划

# 表情包娱乐
/meme 3                  # 获取3个随机表情包

# Reddit 帖子解析
/reddit https://reddit.com/r/python/comments/xxx/  # 解析单个帖子（支持图片、视频、图集、AI总结）
/reddit hot                                        # 全站热门帖子
/reddit hot python                                 # r/python 热门帖子
/reddit top                                        # 全站今日Top
/reddit top week                                   # 全站本周Top
/reddit top python week                            # r/python 本周Top
/reddit new python                                 # r/python 最新帖子
# 支持时间范围: hour, day, week, month, year, all
# 支持AI总结（中文翻译）和列表AI翻译功能
# Inline模式: @bot reddit <链接>$ - 在任何聊天中快速解析Reddit帖子
# 双模式API: OAuth（默认）或 JSON endpoint（TLS指纹伪装+WARP代理）

# 网络诊断工具
/scan 8.8.8.8            # IP地址信誉检测（ipapi.is + AbuseIPDB）
/scan 00:1A:2B:3C:4D:5E  # MAC地址厂商查询
/scan google.com         # 域名解析 + IP信息
/scan https://example.com # 网站可用性检测
/scan latency google.com # 全球延迟测试（6大洲节点）
/scan mtr google.com     # MTR路由追踪（显示15跳）
/scan warp               # 查看WARP出口IP信息
# Inline模式: @bot scan <目标>$ - 支持IP/MAC/域名/URL查询
# 延迟和MTR测试在Inline模式下点击后执行

/meme 5                  # 获取5个随机表情包（1-20范围）
/meme                    # 显示帮助和使用指南

# 股票金融（Yahoo Finance实时数据）
/finance                 # 显示金融主菜单和分类功能
/finance AAPL            # 通过股票代码搜索苹果股票
/finance Tesla           # 通过公司名称搜索特斯拉
/finance 6033.KL         # 搜索马来西亚股票（国油气体）
/finance Maybank         # 通过部分公司名称搜索
# 交互功能: 股票排行榜（15类）、分析师评级、财务报表

# 燃油价格（全球和中国）
/fuel                    # 显示燃油价格帮助和使用说明
/fuel my                 # 马来西亚燃油价格（汽油+柴油）
/fuel china              # 中国省份排行榜（92/95/98/柴油）
/fuel us sg th           # 多国查询（美国、新加坡、泰国）
# 功能: 全球排行榜、本地货币显示、CNY转换、GlobalPetrolPrices.com实际价格日期

# 社交媒体解析
/platforms               # 查看支持的20+平台列表（所有用户可用）

白名单专享命令

# 智能航班搜索和预订（多语言机场识别）
/flight                        # 航班服务交互式菜单
/flight 北京 洛杉矶 2024-12-25     # 中文城市名（自动转换PEK→LAX）
/flight 吉隆坡 普吉 2024-12-25 2024-12-30  # 往返航班（KUL→HKT）
/flight Shanghai Tokyo 2024-12-25  # 混合语言输入（PVG→NRT）
/flight PEK LAX 2024-12-25     # 直接使用IATA代码
/flight Jakarta Bangkok 2024-12-25  # 英文城市名（CGK→BKK）
# 交互功能：价格分析、预订选项、多城市规划、机场信息

# 智能酒店搜索和预订（多语言位置识别）
/hotel                         # 酒店服务交互式帮助
/hotel 北京                    # 中文城市，支持区域选择
/hotel 东京 2024-12-25          # 单日期（自动退房次日）
/hotel Tokyo 2024-12-25 2024-12-28  # 入住和退房日期
/hotel Kepong 25 28           # 当月日期（25号-28号）
/hotel "Times Square NYC" 2024-12-25  # 具体位置
/hotel Bangkok 01-20 01-25    # 月-日格式（当年）
# 交互功能：价格排序、评分排序、详细列表、地图查看

# BIN查询
/bin 123456
/bin 12345678

# 加密货币价格（增强排行榜功能）
/crypto                        # 交互式加密货币菜单和排行榜
/crypto btc                    # 直接价格查询
/crypto eth 2 usd             # 自定义数量和货币
# 交互功能：热门币种、涨跌幅、市值、交易量排行榜

# 汇率转换（支持数学表达式）
/rate USD 100
/rate EUR JPY 50
/rate USD 1+1*2          # 支持数学表达式计算

# 天气预报（支持多种格式）
/tq 北京                # 当前天气和预报
/tq 东京 7                # 7天天气预报
/tq 上海 24h             # 24小时逐时预报
/tq 广州 indices         # 生活指数查询

# 电影和电视剧（统一按钮界面）
/movie 复仇者联盟            # 搜索电影，交互式按钮界面
/tv 权力的游戏              # 搜索电视剧，交互式按钮界面
/chart                     # 统一排行榜 - 热门、即将上映、正在播出
/person 汤姆·汉克斯          # 搜索演员导演，按钮界面

# Steam游戏价格和捆绑包
/steam 赛博朋克          # 游戏价格查询
/steam "荒野大镖客" US      # 多区域游戏价格
/steamb "Valve Complete"  # Steam捆绑包价格
/steams cyberpunk         # 综合搜索（游戏+捆绑包）

# 应用商店（含内购价格信息）
/app 微信                  # App Store: 详细内购项目和价格（支持iOS/iPadOS/macOS/tvOS/watchOS/visionOS）
/app -ipad Procreate       # iPad专属搜索
/app -mac "Final Cut Pro"  # Mac专属搜索
/gp WeChat                # Google Play: 内购价格范围和CNY转换
# 注: Apple Store显示具体内购项目价格；Google Play显示价格范围（如"每件$0.99-$99.99"）
# 平台参数: -iphone, -ipad, -mac, -tv, -watch, -vision（默认: -iphone）

# Apple服务
/aps iCloud

# 社交媒体解析（白名单用户/群组）
/parse https://www.douyin.com/video/xxxxx  # 解析抖音视频
/parse https://www.bilibili.com/video/xxxxx # 解析B站视频
/parse https://youtu.be/xxxxx               # 解析YouTube视频
/parse https://twitter.com/user/status/xxxxx # 解析Twitter/X帖子
/parse https://www.xiaohongshu.com/xxxxx    # 解析小红书内容
# 或者回复一条包含链接的消息后使用 /parse 进行解析
# 支持: 抖音、快手、B站、YouTube、TikTok、小红书、Twitter/X、Instagram、Facebook、微博等20+平台

管理员命令

# 用户和群组管理
/add 123456789            # 添加用户到白名单（也可通过回复使用）
/addgroup                 # 添加当前群组到白名单
/admin                    # 打开管理员面板（交互式）

# AI反垃圾管理（通过 /admin 面板）
# - 为特定群组启用/禁用反垃圾功能
# - 查看单群组统计（检测次数、垃圾消息数、封禁数、误报数）
# - 查看全局统计（跨所有群组的7天和30天汇总数据）
# - 查看最近检测日志，长日志自动使用Telegraph集成
# - 配置垃圾分数阈值和检测参数
# - 自动每周数据清理（日志保留30天、统计保留90天、非活跃用户保留60天）

# 社交媒体解析管理（通过 /admin 面板）
# - 为白名单群组启用/禁用自动解析功能
# - 启用后群组中发送的链接会自动检测并解析
# - 支持20+平台的自动检测和解析
# - 查看解析统计和使用情况

# 数据点管理
/listpoints [limit]       # 列出已知数据点（默认显示10个，含统计信息）
/addpoint <用户ID> <日期> [备注] # 添加新的数据点（格式：YYYY-MM-DD）
/removepoint <用户ID>     # 删除指定数据点

# 用户缓存管理
/cache                    # 查看用户缓存状态和统计信息
/cache username           # 检查特定用户是否已缓存
/cache @username          # 检查特定用户是否已缓存
/cache 123456789          # 检查特定用户ID是否已缓存
/cleanid                  # 清理所有用户ID缓存
/cleanid 30               # 清理30天前的用户缓存

# 统一缓存管理
/cleancache               # 交互式缓存管理菜单
/cleancache all           # 清理所有服务缓存
/cleancache memes         # 清理表情包缓存
/cleancache news          # 清理新闻缓存
/cleancache crypto        # 清理加密货币缓存
/cleancache movie         # 清理电影/电视缓存
/cleancache steam         # 清理Steam缓存
/cleancache weather       # 清理天气缓存（所有类型）
/cleancache cooking       # 清理烹饪菜谱缓存
/cleancache whois         # 清理WHOIS查询缓存
/cleancache app           # 清理App Store缓存
/cleancache netflix       # 清理Netflix缓存
/cleancache spotify       # 清理Spotify缓存
/cleancache disney        # 清理Disney+缓存
/cleancache max           # 清理HBO Max缓存
/cleancache rate          # 清理汇率缓存
/cleancache bin           # 清理BIN查询缓存
/cleancache google_play   # 清理Google Play缓存
/cleancache apple_services # 清理Apple服务缓存
/cleancache finance       # 清理股票金融数据缓存
/cleancache fuel          # 清理燃油价格缓存
/cleancache social_parser # 清理社交媒体解析缓存
/cleancache reddit        # 清理Reddit缓存

# 命令列表管理
/refresh_all             # 管理员：刷新所有用户和群组的命令列表
/refresh                 # 用户：刷新自己的命令列表（修复新功能可见性问题）

📖 点击展开以查看完整的架构、技术细节和最佳实践

🛠️ 架构总览

核心组件

主应用 (main.py): 处理异步初始化、依赖注入和生命周期管理。
命令模块 (commands/): 每个服务都有自己的模块，通过工厂模式注册并进行权限控制。
工具模块 (utils/):
- config_manager.py: 配置管理。
- cache_manager.py, redis_cache_manager.py: 缓存管理。
- mysql_user_manager.py: 用户和权限的数据库操作。
- task_scheduler.py, redis_task_scheduler.py: 任务调度。
- permissions.py: 权限系统。
数据存储:
- Redis: 用于缓存和消息删除调度。
- MySQL: 用于用户数据和权限管理。

关键设计模式

命令工厂: 用于统一的命令注册和权限处理。
依赖注入: 核心组件通过 bot_data 传递。
异步编程: 完全支持所有I/O操作的 async/await。
基于装饰器的错误处理: 统一处理命令的错误。
直接异步权限检查: 复杂的适配器层已被移除，MySQL操作现在是直接异步的。

🗄️ 数据库结构

users: 用户基本信息
admin_permissions: 管理员
super_admins: 超级管理员
user_whitelist: 用户白名单
group_whitelist: 群组白名单
admin_logs: 管理员操作日志
command_stats: 命令使用统计

数据库结构定义在 database/init.sql 中，并在应用首次运行时自动创建。

🔐 权限系统

架构优化

项目已从SQLite兼容性适配器完全迁移到统一的 MySQL + Redis 架构：

直接异步权限检查: utils/permissions.py 直接从 context.bot_data['user_cache_manager'] 获取MySQL管理器。
统一数据存储: 所有权限数据都存储在MySQL中，防止不一致。
性能提升: 移除了同步到异步的复杂性，提高了响应速度。

权限级别

公开访问: 所有用户和群组（不论是否在白名单中）都可以访问流媒体服务价格查询 (/nf, /ds, /sp) 和用户信息命令 (/when, /id)。只需将机器人添加到任意群组即可启用这些功能。
白名单访问: 高级功能需要白名单权限，包括加密货币价格、汇率转换、天气预报、Steam价格、BIN查询、电影电视信息和应用商店查询。联系获取白名单访问或未来服务计划。
管理员: 存储在MySQL的 admin_permissions 表中。
超级管理员: 通过 SUPER_ADMIN_ID 环境变量配置。

🧩 扩展机器人

自定义脚本

将Python脚本放置在 custom_scripts/ 目录中，并设置 LOAD_CUSTOM_SCRIPTS=true 以自动加载它们。脚本可以访问：

application: Telegram Application 实例。
cache_manager: Redis 缓存管理器。
rate_converter: 货币转换器。
user_cache_manager: 用户缓存管理器。
stats_manager: 统计管理器。

新命令开发

在 commands/ 目录中创建一个新模块。
使用 command_factory.register_command() 注册新命令。
设置适当的权限级别。
在 main.py 中注入任何必要的依赖。

📊 日志与监控

日志管理

日志文件: logs/bot-YYYY-MM-DD.log
日志轮转: 10MB 大小限制，保留5个备份。
日志级别: 支持 DEBUG, INFO, WARNING, ERROR。
定期清理: 通过 cleanup_logs.py 或计划任务执行。

监控功能

命令使用统计
用户活动监控
错误日志记录
性能指标收集

⚡ 性能优化

缓存策略

Redis缓存: 用于高频数据，如价格信息和天气位置查询。
统一缓存管理: 通过 redis_cache_manager.py 管理。
智能缓存: 不同服务的缓存时长可配置。
数学表达式缓存: 汇率转换中数学表达式的安全评估和缓存。

任务调度

Redis任务调度器: 支持计划性、周期性任务。
消息删除: 自动清理临时消息。
缓存清理: 定期清除过期缓存。

连接管理

连接池: 用于MySQL和Redis。
异步客户端: 使用 httpx 进行异步HTTP请求。
优雅关闭: 优雅地清理资源并关闭连接。

💡 开发最佳实践

错误处理: 使用 @with_error_handling 装饰器。
日志记录: 使用适当的日志级别。
权限检查: 使用 @require_permission(...) 装饰器。
异步权限: 通过 context.bot_data['user_cache_manager'] 获取用户管理器。
缓存: 使用Redis缓存以避免重复请求。
异步代码: 对所有I/O密集型操作使用 async/await。
配置: 通过环境变量管理所有设置。
数据库查询: 使用参数化查询以防止SQL注入。

🔍 故障排查

常见问题

数据库连接失败: 检查MySQL的配置和连接。
Redis连接失败: 检查Redis服务的状态。
权限错误: 确保用户在白名单或管理员列表中。
命令无响应: 检查日志文件以查找错误。
天气命令失败: 请确保在 .env 文件中正确设置了 QWEATHER_API_KEY，并且该密钥是有效的。
BIN查询失败: 请确保在 .env 文件中正确设置了 BIN_API_KEY，并且你的API配额充足。

调试技巧

设置 LOG_LEVEL=DEBUG 以获取详细日志。
使用 docker-compose logs -f appbot 查看实时日志。
检查Redis缓存状态。
验证数据库表结构和数据。

📜 架构迁移说明 (v2.0 - 最新)

移除的组件:

utils/compatibility_adapters.py - SQLite 兼容性适配器
utils/redis_mysql_adapters.py - 混合适配器
utils/unified_database.py - 统一的SQLite数据库
其他SQLite相关文件

架构优化:

统一了基于 MySQL + Redis 的架构。
实现了直接的异步权限检查，移除了复杂的适配器层。
提升了性能和代码可维护性。
解决了一个白名单群组用户无法使用机器人的问题。

迁移要点:

所有权限数据现在都存储在MySQL中。
Redis用于缓存和消息删除调度。
MySQL和Redis的连接详情必须在 .env 文件中配置。

🆕 最新更新

加密货币排行榜增强功能 (最新)

CoinGecko集成: 将排行榜功能迁移到CoinGecko免费API，排行榜功能无需API密钥
交互式菜单系统: 类似finance模块的全新统一界面，支持按钮导航和实时数据
多种排行榜分类: 热门搜索币种、24小时涨跌幅排行榜、市值排行榜和交易量图表
智能双API策略: CoinGecko用于排行榜（免费），CoinMarketCap用于单币价格查询（付费）
增强的数据显示: 全面的币种信息，包含价格、涨跌幅、市值排名和实时时间戳
缓存集成: 智能缓存系统，不同数据类型采用不同TTL，集成统一缓存管理
用户体验: 清晰的markdown格式、刷新功能和自动删除保持聊天清洁
开箱即用: 排行榜功能无需API配置即可正常工作

股票金融功能集成 (最新)

新增 /finance 命令: 由Yahoo Finance API提供的全面金融市场数据和实时股票价格
15类排行榜: 完整的股票和基金排行榜，包括日涨跌幅、最活跃股票、成长科技股、低估值股票和6类共同基金
多市场支持: 美国、香港、中国、马来西亚股票，支持灵活的股票代码格式
智能股票搜索: 支持股票代码（AAPL、6033.KL）和公司名称（Apple、Tesla、Maybank）多语言匹配
高级金融数据: 分析师评级（买入/卖出/持有）、财务报表（损益表、资产负债表、现金流量表）
分类界面设计: 独立的股票排行榜（9类）和基金排行榜（6类），交互式按钮导航
智能缓存系统: 智能Redis缓存，不同数据类型采用不同TTL（股票信息5分钟、排行榜3分钟、搜索结果10分钟）
自动删除管理: 所有用户命令和机器人消息自动删除，保持聊天界面清洁
实时市场数据: 当前价格、日涨跌、成交量、市值、市盈率和交易所信息
技术集成: yfinance库集成，pandas数据处理和全面错误处理

表情包功能集成

新增 /meme 命令: 从memes.bupt.site API获取随机表情包，支持1-20个表情包请求
参数验证: 智能输入验证，提供清晰的错误消息和使用指南
自动删除系统: 表情包图片15分钟后自动删除，保持聊天清洁
智能缓存: Redis驱动的缓存系统，可配置TTL，提升性能
后备支持: 直接图片发送失败时的链接式后备显示
统一缓存管理: 集成到 /cleancache 系统，便于缓存管理
错误处理: 全面的错误处理，包含加载指示器和用户反馈
Pydantic验证: 使用Pydantic模型进行类型安全的API响应解析
每周清理: 通过 memes_weekly_cleanup 设置可配置的每周缓存清理

统一缓存管理系统 (最新)

单一命令界面: 将20+个单独的 *_cleancache 命令统一为 /cleancache 系统
交互式菜单: 按钮式服务选择，清晰分类和状态反馈
命令行支持: 通过 /cleancache [服务] 为高级用户提供直接缓存清理
特殊处理: 自动处理复杂缓存结构（如天气的7个前缀）
全面覆盖: 包含所有服务 - 表情包、新闻、加密货币、电影、steam、天气、烹饪、whois、应用商店、流媒体服务、汇率和BIN
管理员权限: 安全的仅管理员访问，完善的错误处理和日志记录
实时反馈: 缓存清理操作期间的即时状态更新
服务映射: 清晰的服务名称映射，提供更好的用户体验

命令刷新系统 (之前功能)

智能命令列表管理: 新增 /refresh_all 管理员命令，可刷新所有用户和群组的命令列表
用户自助服务: /refresh 命令允许任何用户独立解决命令可见性问题
Telegram缓存解决方案: 解决新功能添加时Telegram客户端命令缓存问题
全局+个人更新: 同时更新全局默认命令和个人用户/群组命令列表
帮助集成: 在帮助和开始命令中自动提供命令可见性问题的解决指导
新功能推送: 简化Permission.NONE新功能向所有用户的部署流程
减轻管理员负担: 用户可自行解决命令显示问题，无需联系管理员

增强的WHOIS与IP地理位置功能

双信息系统: WHOIS注册数据 + IP地址服务器实际地理位置
IP-API.com集成: 实时IP地理位置服务，提供准确的服务器位置数据
全面的位置详情: 国家带国旗、地区、城市、邮政编码、坐标和时区
ISP和网络信息: 来自地理位置服务的实际ISP、组织和AS号码
智能字段分类: 注册信息与实际位置的独立显示部分
增强的国家显示: 使用现有country_data集成显示国旗和中文国家名称
智能云服务检测: 自动检测云服务提供商（微软、亚马逊、谷歌）并提供说明注释
错误处理与回退: 地理位置服务不可用时的优雅降级
速率限制合规: 遵守IP-API.com免费套餐45次/分钟的限制
缓存集成: Redis缓存WHOIS和地理位置数据，支持可配置的TTL
用户友好的说明: 清晰区分"📍 注册位置"和"🌍 实际位置"，便于理解

时间和时区功能 (最新功能)

公开时间查询: 所有用户可用 - 使用国家名称、代码、城市或IANA时区标识符查询任意时区的当前时间
时区转换: 在不同时区间转换时间，智能解析各种时区格式
全面的时区支持: 支持200+城市、190+国家，完整的IANA时区数据库集成
国家数据集成: 利用现有的country_data.py实现一致的国旗显示和本地化国家名称
智能输入识别: 接受中英文国家名称、ISO国家代码、主要城市名称和标准IANA时区标识符
交互式帮助系统: 上下文感知帮助，提供完整的IANA时区文档链接
缓存系统: Redis驱动的时区差异和位置查询缓存，优化性能
Markdown V2格式: 完全符合Telegram格式要求，正确转义特殊字符

数据点管理系统 (最新功能)

JSON存储架构: 替换硬编码数据点，使用灵活的JSON文件存储系统
实时统计展示: 显示总数、已验证和估算数据点的统计信息
动态管理功能: 支持通过Telegram命令添加、删除和查看数据点
Docker卷持久化: 确保数据在容器重启后保持完整
向后兼容性: 与现有估算算法完全兼容，无需迁移

基于角色的访问控制 (最新版本)

普遍公开访问: 所有用户和群组都可以使用流媒体服务价格和用户信息查询功能，无任何限制
群组集成: 将机器人添加到任意 Telegram 群组即可为所有成员启用公开功能
增强的帮助系统: 根据用户权限级别显示不同的帮助内容
改进的用户体验: 明确区分免费功能和高级功能
管理员管理工具: 通过 /add、/addgroup 和交互式 /admin 面板提供全面的用户/群组白名单管理
白名单政策更新: 申请目前暂不开放，未来考虑推出付费服务计划

电影电视功能

统一按钮界面系统: 完全重新设计，采用交互式按钮实现直观导航
3平台数据整合: 结合TMDB、JustWatch和Trakt API提供全面的电影/电视剧信息
JustWatch流媒体排行榜: 实时流媒体平台排名，整合到统一的/chart系统中
交互式内容访问: 通过按钮界面一键访问推荐、评价、视频、观看平台
智能会话管理: 季集选择等多步骤交互，支持用户输入
增强搜索: 智能电影/电视剧/人物搜索，全面结果展示
丰富详情: 海报、评分、演员、剧组、预告片和观看平台，完全整合
社区统计: Trakt集成提供观看数、收藏统计和社区参与数据
Telegraph集成: 无缝长内容显示，包含评价、演员表、详细信息
统一排行榜系统: 所有热门、即将上映、正在播出内容整合到/chart命令
简化命令: 仅需4个主要命令（/movie、/tv、/person、/chart）替代25+个旧命令
季集导航: 交互式季集浏览，提供上下文信息
平台可用性: 显示流媒体平台，智能地理位置相关性
数据源透明: 在所有显示中清晰标识数据源（📊 TMDB、📺 JustWatch、🎯 Trakt）
数据源透明: 所有显示中清晰标注数据来源（📊 TMDB、📺 JustWatch、🎯 Trakt）
多语言支持: 中英文内容后备支持，提供更好覆盖
实时更新: JustWatch数据包含时间戳和数据新鲜度指标

用户信息查询功能

增强 /when 命令 支持用户名查询的Telegram用户注册日期估算
多种查询方式 支持直接ID输入、用户名查询（@username或username）和回复消息查询
智能ID算法 使用线性插值结合真实数据点进行估算
用户分级系统 根据账号年龄分类用户（新兵蛋子、不如老兵、老兵等）
Markdown安全特性 包含特殊字符转义功能
精确年龄计算 使用年月差值计算逻辑
增强 /id 命令 用于获取用户和群组ID
用户缓存系统 提升用户名到ID解析的性能

用户缓存管理系统

全新用户缓存基础设施 采用MySQL存储和Redis性能优化
灵活的群组监控 通过 ENABLE_USER_CACHE 和 USER_CACHE_GROUP_IDS 设置 - 留空则监听所有群组
管理员缓存调试 使用 /cache 命令查看缓存统计、用户表大小和用户查询
灵活的缓存清理 使用 /cleanid 命令支持基于时间和完全清理
自动用户数据收集 从所有监控群组消息中自动收集用户名到ID的映射
增强的用户名支持 在 /when 命令中利用缓存用户数据

Steam游戏功能

多格式游戏搜索: /steam 查询单个游戏的多区域价格
捆绑包价格查询: /steamb 查询Steam捆绑包价格和内容信息
综合搜索功能: /steams 同时搜索游戏和捆绑包的综合结果
区域价格对比: 多国价格对比，帮助找到更优惠的价格
智能缓存系统: 智能缓存机制提升性能表现
统一缓存管理: 集成到 /cleancache steam 命令进行缓存控制

BIN查询功能

新增 /bin 命令 用于信用卡BIN信息查询
全面的数据展示 包括卡片品牌、类型、发卡银行和国家
智能缓存系统 提升性能表现
统一缓存管理 通过 /cleancache bin 命令
中文本地化支持 卡片品牌和国家名称中文显示
环境变量配置 通过 BIN_API_KEY 进行配置

📚 API依赖

OpenAI API: 用于基于GPT-4o-mini模型的AI反垃圾检测
CoinMarketCap API: 用于加密货币价格数据
CoinGecko API: 用于加密货币排行榜、热门币种和市场数据（免费套餐，无需API密钥）
DY.AX BIN API: 用于信用卡BIN信息查询
TMDB API: 用于电影和电视剧信息查询，集成Telegraph支持
Trakt API: 用于增强电影/电视剧统计、热门趋势数据和社区洞察
JustWatch API: 用于流媒体平台排行榜、图表和平台可用性数据
和风天气API: 用于天气预报数据
Steam API: 用于游戏价格信息
Google Maps API: 用于位置搜索、附近场所、路线规划和地理编码服务（英文用户）
高德地图API: 用于位置搜索、附近场所、路线规划和地理编码服务（中文用户）
SerpAPI: 用于航班搜索和预订信息，通过Google Flights集成提供多语言机场识别，以及酒店搜索和预订信息，通过Google Hotels集成提供多语言位置识别
IP-API.com: 用于IP地理位置和实际服务器位置数据（免费服务）
Yahoo Finance API: 用于实时股票价格、市场数据、排行榜、分析师评级和财务报表
网易云音乐API: 用于歌曲搜索、下载、歌词和元数据，通过EAPI加密
各种流媒体服务API: 用于订阅价格查询

📊 数据来源

本项目利用以下开源项目进行数据收集和处理：

新闻源: newsnow - 新闻聚合和热门内容
TLD信息: iana_tld_list - IANA顶级域名数据
烹饪菜谱: HowToCook - 菜谱数据库和膳食规划
Netflix价格: netflix-pricing-scraper - 全球Netflix订阅价格
Disney+价格: disneyplus-prices - Disney+订阅价格数据
Spotify价格: spotify-prices - Spotify订阅价格信息
HBO Max价格: hbo-max-global-prices - HBO Max全球价格数据
Xbox Game Pass价格: xbox-game-pass-prices - Xbox Game Pass全球订阅价格（PC和Ultimate套餐）
燃油价格: fuel-price-tracker - 全球163国和中国31省燃油价格
网易云音乐API: Music163Api-Go - 网易云音乐API参考实现
网易云音乐Bot: Music163bot-Go - 网易云音乐Telegram Bot参考

🤝 贡献

欢迎提交贡献、问题和功能请求。请随时查看问题页面。

许可证

该项目根据 MIT 许可证授权。

FilesExpand file tree

README.zh-CN.md

Latest commit

History