1. 项目概述与核心价值如果你和我一样每天泡在几十个Telegram群组里从技术讨论到行业八卦信息流像瀑布一样刷个不停那么“信息过载”和“有效信息遗漏”这两个问题你一定深有体会。手动爬楼既费时又容易错过关键讨论而Telegram自带的搜索功能在跨群、跨时段的信息整合面前显得力不从心。这正是我动手打造Telegram_Messages_Helper这个工具的初衷它不是一个简单的消息转发机器人而是一个部署在Docker里的自动化信息处理中枢。简单来说这个工具的核心工作流是这样的它作为一个无头Headless的Telegram客户端在后台运行自动监听你指定的群组将收到的纯文本消息经过一系列智能过滤比如屏蔽广告机器人、过滤关键词、合并长消息后存入PostgreSQL数据库。然后它可以定时调用OpenAI兼容的API比如ChatGPT、Claude或者你自建的模型服务对聚合后的群聊内容进行智能总结提炼出当天或某个时段的核心议题、关键结论和待办事项。最终你可以通过一个简单的Web界面查看原始聊天记录或AI生成的摘要报告甚至可以将这些处理后的数据通过API喂给Dify、Coze这类低代码平台构建更复杂的自动化工作流。这个工具最适合两类人一是重度依赖Telegram群组进行协作、学习或获取信息的团队与个人比如开源项目维护者、加密货币交易者、跨境电商运营或者像我这样的技术博主二是喜欢折腾自动化希望将碎片化信息流转化为结构化知识库的极客。它帮你把“看群”这个被动、耗时的动作变成了一个主动、高效的“信息摄入”过程。2. 核心设计与架构解析2.1 为什么选择“无头客户端数据库AI”的架构市面上有很多Telegram Bot方案但它们大多基于Bot API只能接收发送给Bot的消息或它所在的群组消息且需要将Bot设为管理员。而Telegram_Messages_Helper直接使用Telegram的用户客户端APITelethon库这意味着它是以“你”的身份登录的可以读取你作为成员的所有普通群组和频道消息无需任何额外的群组权限设置适用性更广。选择将消息存入PostgreSQL数据库而非直接处理是出于灵活性和可追溯性的考虑。原始消息的存储形成了一个本地的、可查询的历史记录库。你可以随时进行复杂的SQL查询分析比如“某个关键词在过去一周哪些群组被提及最多”。同时将AI总结作为后置的、可选的环节使得整个流程解耦。你可以先存数据再根据需求决定是否总结、何时总结、用什么模型总结甚至未来可以对接不同的分析引擎。2.2 消息处理流水线从噪声中提取信号消息在入库前会经过一个精心设计的处理流水线目的是在调用昂贵的AI API之前尽可能清洗掉“噪声”提升最终总结的质量和成本效益。来源过滤黑白名单通过环境变量TELEGRAM_WHITELIST_CHAT和TELEGRAM_BLACKLIST_CHAT可以设置群组ID的白名单和黑名单。白名单模式只处理指定群组适合聚焦核心圈子黑名单模式则忽略某些水群或广告群。实操心得我建议初期先不设限制运行几天后从数据库里用SQLSELECT DISTINCT chat_id, chat_name FROM messages;统计所有群组再根据聊天内容的质量来决策这样更精准。内容过滤关键词与机器人环境变量TELEGRAM_FILTER_KEYWORDS可以设置一系列逗号分隔的关键词。任何消息内容中包含这些关键词如“代投”、“菠菜”、“点击领取”等常见广告词整条消息会被直接丢弃。同时所有标记为机器人is_bottrue发送的消息也会被过滤这能有效屏蔽大量的推广Bot。文本规范化为了适配AI模型对输入格式和长度的要求工具会进行两项处理。一是长度截断单条消息超过300字符的部分会被截断这是预防后续API调用时出现“413 Request Entity Too Large”错误的有效手段。二是合并换行将多行文本消息中的换行符\n替换为空格合并为单行这能使后续的聚合文本更紧凑减少无效token占用。媒体消息策略当前版本明确只处理文本消息忽略图片、视频、文件等。这是因为第一对多媒体内容进行AI总结需要额外的OCR、语音识别或视觉理解模块复杂度陡增第二绝大多数有价值的讨论和信息沉淀仍然以文本形式存在。这个设计让核心功能保持轻量和专注。2.3 计划任务与模块化设计项目的可扩展性体现在其模块化的计划任务设计上由script_scheduler.py这个主调度器驱动。你可以像搭积木一样启用或禁用特定功能。任务模块功能描述运行频率与建议script_aggregated.py核心预处理。将原始消息表messages中同一天、同一群组的消息按时间顺序合并成一条聚合文本存入messages_aggregated表。这是AI总结的原料。建议每日凌晨运行一次处理前一天的聊天记录。script_aigc.pyAI总结引擎。读取messages_aggregated表中未总结的记录调用配置的AI API生成摘要并存入summary表。可在聚合任务之后运行。注意如果你打算用Dify/Coze来总结应删除此脚本以防重复消费。script_cleanup.py数据清理。删除messages表中7天前的原始消息控制数据库体积。聚合表和总结表可长期保留。建议每日运行。保留周期可通过环境变量调整。script_sync_wechat.py未来扩展。设计用于同步微信消息实现跨平台信息统一处理。目前尚未发布。暂不可用。这种设计的好处是你可以轻松地替换某个环节。例如你觉得内置的AI总结不够好完全可以禁用script_aigc.py然后写一个自己的脚本从messages_aggregated表取数据调用你更喜欢的模型或服务再将结果写回数据库或推送到别处。3. 从零开始的完整部署与配置指南3.1 前期准备获取Telegram API凭证这是整个项目唯一有“门槛”的步骤。你需要从Telegram官方获取API ID和API Hash。访问 https://my.telegram.org/apps用你的Telegram账号手机号登录。点击 “Create application” 或 “Create new application”。填写应用信息App title和Short name认真填写如 “Personal Message Analyzer”。不要胡乱输入“test”、“aaa”有较高概率被拒绝。Platform选择 “Desktop”。Description简要描述用途如 “A tool to help me organize and summarize group chats for personal knowledge management.”创建成功后页面会显示api_id和api_hash。请立即妥善保存它们只会显示一次。避坑指南申请失败与网络问题这是反馈最多的问题。首先页面卡顿或点提交后报“ERROR”是常态多刷新几次、多试几次。我个人的成功经验是使用与你注册Telegram手机号归属地相同或邻近地区的家庭宽带IP地址进行申请。例如86的手机号使用香港、台湾等地的住宅IP成功率会显著高于某些数据中心IP。一旦登录申请页面尽量不要中途切换IP或频繁刷新否则可能触发风控导致临时封禁。如果失败可以间隔几小时或第二天再试。3.2 基础环境搭建数据库与代码假设你有一台运行Linux的云服务器或本地机器并已安装Docker和Docker Compose。# 1. 克隆项目代码 git clone https://github.com/ShiFangJuMie/Telegram_Messages_Helper.git cd Telegram_Messages_Helper # 2. 准备PostgreSQL数据库 # 如果你没有现成的PostgreSQL可以用Docker快速启动一个与项目容器分开 docker run -d \ --name some-postgres \ -e POSTGRES_PASSWORDyour_strong_password \ -e POSTGRES_DBtelegram_msg \ -p 5432:5432 \ -v /your/data/path:/var/lib/postgresql/data \ postgres:16-alpine # 3. 初始化数据库结构 # 将项目中的SQL文件导入到上一步创建的数据库中 # 首先将SQL文件复制到容器内或通过psql客户端直接连接执行 docker cp app/data/postgres.sql some-postgres:/tmp/ docker exec -it some-postgres psql -U postgres -d telegram_msg -f /tmp/postgres.sql3.3 核心配置详解docker-compose.yml与环境变量项目根目录下的docker-compose.yml是核心配置文件。部署前你需要根据注释仔细修改其中的环境变量。version: 3.8 services: telegram-helper: build: . container_name: telegram_messages_helper restart: unless-stopped depends_on: - db # 如果你选择在compose内联数据库可以启用此项 environment: # Telegram API 核心凭证 - TELEGRAM_API_ID你的API_ID # 必填从 my.telegram.org 获取 - TELEGRAM_API_HASH你的API_HASH # 必填从 my.telegram.org 获取 - TELEGRAM_SESSIONdefault_session # 会话名称用于区分多账号对应生成的 .session 文件 # 数据库连接配置 - DATABASE_URLpostgresql://postgres:your_strong_passwordhost.docker.internal:5432/telegram_msg # 解释如果数据库在宿主机使用 host.docker.internal如果在同一compose内用服务名如 db # 格式postgresql://用户名:密码数据库主机:端口/数据库名 # 消息过滤规则 - TELEGRAM_FILTER_KEYWORDS代投,菠菜,刷单,兼职,加群 # 逗号分隔命中即丢弃整条消息 - TELEGRAM_WHITELIST_CHAT # 群组ID白名单留空则处理所有群。与黑名单二选一 - TELEGRAM_BLACKLIST_CHAT-1001234567890,-1000987654321 # 群组ID黑名单在此列表的群消息将被忽略 # AI总结相关配置 - OPENAI_API_BASEhttps://api.openai.com/v1 # OpenAI兼容API端点 - OPENAI_API_KEYsk-你的OpenAI_API_KEY # API Key - OPENAI_MODELgpt-4o-mini # 模型名称如 gpt-3.5-turbo, claude-3-haiku - AI_SUMMARY_ENABLEDtrue # 是否启用内置AI总结 - PROMPT_FILE/app/prompt.txt # 总结提示词文件路径 # Web访问与安全 - AUTH_CODEyour_secret_auth_code_here # 查看网页的密码务必修改 - WEB_HOST0.0.0.0 # 监听地址 - WEB_PORT5000 # 监听端口 volumes: - ./app:/app # 挂载代码目录方便修改提示词等 - ./session:/app/session # 挂载session文件持久化登录状态 ports: - 5000:5000 # 将容器内5000端口映射到宿主机关键配置解析DATABASE_URL这是最常见的配置错误点。如果PostgreSQL运行在宿主机非Docker容器在Linux/macOS上通常使用host.docker.internal作为主机名在Windows Docker Desktop上也可能是host.docker.internal。如果数据库是另一个Docker容器则使用该容器的服务名。TELEGRAM_FILTER_KEYWORDS这是提升信息质量的关键。建议运行初期先观察从数据库里筛选出高频垃圾词汇再添加到这里。AUTH_CODE用于保护Web查询接口的密码必须修改成高强度随机字符串否则你的聊天记录可能暴露在公网。3.4 登录Telegram账号与获取Chat ID配置完成后启动容器并完成首次登录。# 在项目根目录下构建镜像并启动 docker compose up -d # 查看容器日志确认无报错 docker compose logs -f # 进入容器内部交互环境 docker exec -it telegram_messages_helper bash # 在容器内执行初始化登录脚本 python setup.py接下来脚本会引导你完成登录输入手机号格式为国家代码 手机号例如86 13912345678。输入验证码Telegram会向你的官方客户端发送一个5位数的登录验证码。输入二次验证密码如果设置了这是你在Telegram中设置的“两步验证”密码。登录成功后控制台会打印出你加入的所有群组和对应的Chat ID列表格式如Group Title: 技术交流群 | Chat ID: -1001680975xxx。请务必记录下你感兴趣的群组的Chat ID那个负数的数字用于后续配置黑白名单。重要提示首次登录后会在容器内的/app/session目录对应宿主机挂载的./session下生成一个你的session名.session文件。这个文件包含了你的登录凭证请妥善备份。以后重建容器时只要这个文件在且环境变量TELEGRAM_SESSION一致就无需重新登录。3.5 验证与使用重启容器登录并配置好黑白名单如果需要后重启容器使配置生效。docker compose restart查看原始消息打开浏览器访问http://你的服务器IP:5000/?auth你设置的AUTH_CODEpage1。你应该能看到被抓取并处理后的群聊消息列表按时间倒序排列。page参数用于分页start_date可以查看特定日期的记录。查看AI总结访问http://你的服务器IP:5000/summary?auth你设置的AUTH_CODE。这里会展示由script_aigc.py生成的每日群聊摘要。如果尚未生成请确认该脚本已启用并等待其下一次计划执行。4. 高级使用技巧与深度定制4.1 与Dify/Coze等平台集成构建智能工作流Telegram_Messages_Helper的Web接口设计初衷就是为外部系统提供数据。你可以禁用内置的AI总结将原始数据或聚合数据提供给更强大的工作流平台。操作步骤禁用内置总结在docker-compose.yml中设置AI_SUMMARY_ENABLEDfalse并删除或重命名app/script_aigc.py文件防止token浪费。在Dify中创建工作流添加一个HTTP请求节点URL配置为http://你的助手地址/?authxxxalltruestart_date{YYYY-MM-DD}。可以使用alltrue获取当天所有原始消息或直接调用/summary接口获取已聚合但未总结的数据。将获取到的文本可能是很长的JSON数组作为输入连接到一个LLM节点。在LLM节点中设计更精细的提示词。例如你可以要求模型按“技术问题”、“市场动态”、“社区活动”等类别对信息进行分类总结或者提取出具体的待办事项Action Items。LLM的输出可以再连接到一个邮件发送或Webhook节点将每日摘要定时推送到你的邮箱或团队协作工具如Slack、钉钉。优势利用Dify/Coze的可视化编排和更强大的模型生态如支持长上下文的Claude 3.5 Sonnet你可以实现比内置脚本更复杂、更贴合业务需求的总结逻辑比如跨群组主题聚合、情感分析、趋势预测等。4.2 优化提示词以获得更佳总结效果内置的AI总结效果很大程度上取决于prompt.txt文件中的提示词。默认的提示词可能比较通用你可以根据群组类型进行定制。打开并编辑app/prompt.txt文件你是一个专业的群聊内容分析助手。请根据以下提供的群聊记录生成一份简洁明了的每日总结。 聊天记录 {text} 请按照以下格式组织你的总结 1. **核心议题**列出今天讨论最集中的2-3个主要话题。 2. **关键结论/进展**针对每个核心议题总结出重要的结论、达成的共识或取得的进展。 3. **待解决问题/疑问**记录下讨论中提出的、但尚未解决的新问题或疑问。 4. **重要资源/链接**提取聊天中分享的重要文档、链接、工具等资源。 5. **活跃参与者**提及今天发言最积极或贡献关键信息的几位成员。 总结要求 - 语言精炼使用中文。 - 避免罗列聊天记录原文进行概括和提炼。 - 如果某个议题讨论内容较少或无关紧要可以忽略。定制化建议针对技术社区可以增加“代码片段/解决方案”部分专门提炼讨论中出现的有效代码或技术方案。针对市场/资讯群可以增加“市场情绪分析”或“关键数据/事件”部分提炼群体观点和重要新闻。调整语气和格式如果你希望总结更口语化或者需要以Markdown、HTML格式输出以便直接发布可以修改提示词中的格式和语言要求。4.3 数据库结构与自定义查询理解数据库结构能让你发挥数据的最大价值。主要的三张表如下messages存储原始的单条消息。包含id,chat_id,chat_name,sender_name,message,timestamp等字段。messages_aggregated存储按天、按群聚合后的长文本。包含id,chat_id,chat_name,date,combined_text等字段。combined_text就是准备喂给AI的“原料”。summary存储AI生成的总结。包含id,chat_id,chat_name,date,summary_text,model_used等字段。你可以直接连接数据库执行自定义分析-- 查看过去一周最活跃的10个群组 SELECT chat_name, COUNT(*) as msg_count FROM messages WHERE timestamp NOW() - INTERVAL 7 days GROUP BY chat_name ORDER BY msg_count DESC LIMIT 10; -- 查找所有群组中讨论过“Docker”的对话 SELECT chat_name, sender_name, message, timestamp FROM messages WHERE message LIKE %Docker% ORDER BY timestamp DESC; -- 导出某个群组上个月的AI总结用于月度报告 SELECT date, summary_text FROM summary WHERE chat_name 我的技术群 AND date DATE_TRUNC(month, CURRENT_DATE - INTERVAL 1 month) AND date DATE_TRUNC(month, CURRENT_DATE);5. 故障排查与常见问题实录即使按照指南操作在实际部署中仍可能遇到各种问题。以下是我在长期使用和维护中积累的常见问题及解决方案。5.1 容器启动失败或持续重启问题现象docker compose up -d后docker compose logs显示数据库连接错误或Python依赖错误。排查步骤检查数据库连接确认DATABASE_URL环境变量完全正确。可以尝试在宿主机上用psql或telnet测试是否能连通数据库主机和端口。检查网络模式如果数据库在宿主机确保Docker容器能访问宿主机网络。对于Linux可能需要使用--networkhost模式或配置正确的host.docker.internalDocker Desktop默认支持但某些Linux原生Docker需额外配置。检查依赖首次构建镜像 (docker build) 可能因网络问题失败。可以手动进入项目目录执行docker build --no-cache .重新构建。5.2 收不到任何消息问题现象Web界面能打开但消息列表为空。排查步骤确认登录状态检查./session目录下是否有.session文件并查看容器日志确认没有登录相关的报错。可以重新运行docker exec -it ... python setup.py尝试重新登录。检查群组Chat ID确保你希望监听的群组不在TELEGRAM_BLACKLIST_CHAT中或者如果设置了TELEGRAM_WHITELIST_CHAT群组ID必须在其中。Chat ID必须是setup时打印的完整负数ID。查看实时日志运行docker compose logs -f telegram-helper然后在你监听的群组里发一条消息。观察日志中是否有“New message from ... ”之类的输出。如果没有可能是Telethon库的会话问题尝试删除session文件重新登录。5.3 AI总结失败413错误或内容空洞问题现象summary表为空或容器日志显示调用AI API时返回413错误或总结内容非常简短敷衍。解决方案针对413错误请求体过大优化过滤强化TELEGRAM_FILTER_KEYWORDS过滤更多垃圾信息。检查聚合文本长度在数据库中查询messages_aggregated表的combined_text字段长度。如果某个群组某天的聊天记录极长超过数万字符考虑将其加入黑名单或手动分拆。升级模型/调整代理如项目FAQ所述普通GPT-4o的上下文窗口有限。可以尝试使用支持更长上下文的模型如Claude 3系列或者通过deanxv/coze-discord-proxy这类项目访问具有更大上下文能力的版本。同时确保OPENAI_API_BASE指向正确的、支持你所用模型的端点。针对内容空洞优化提示词默认的prompt.txt可能不适合你的群聊风格。参考4.2节根据群聊内容特点技术讨论、商务交流、社群闲聊定制更具体、要求更明确的提示词。检查输入质量AI总结的质量取决于输入文本的质量。如果原始聊天记录本身就很水、碎片化严重总结结果自然不会好。考虑调整过滤规则只保留高质量群组。5.4 Web界面无法访问或报错问题现象浏览器访问http://IP:5000显示连接被拒绝、500内部错误或认证失败。排查步骤检查端口映射确认docker-compose.yml中的ports: - 5000:5000配置正确且宿主机5000端口未被其他程序占用。检查防火墙如果使用云服务器确保安全组/防火墙规则允许对5000端口的入站访问。检查认证码确认URL中的auth参数值与AUTH_CODE环境变量完全一致包括大小写。查看应用日志在容器日志中查找Flask应用启动时的错误信息常见的有数据库连接失败、导入模块错误等。5.5 如何迁移或备份备份关键数据Session文件备份./session目录下的所有.session文件。这是你的登录凭证丢失后需要重新登录。数据库使用pg_dump命令备份整个telegram_msg数据库。docker exec some-postgres pg_dump -U postgres telegram_msg backup.sql配置文件备份你修改过的docker-compose.yml和app/prompt.txt。迁移到新服务器在新服务器上安装Docker和Docker Compose。克隆项目代码恢复备份的docker-compose.yml和prompt.txt。启动一个新的PostgreSQL容器并导入备份的数据库文件。将备份的.session文件放入新服务器的./session目录。修改docker-compose.yml中的DATABASE_URL指向新数据库。启动项目容器 (docker compose up -d)。由于session文件存在通常无需重新登录。这个工具在我自己的信息管理流水线中已经稳定运行了半年多它成功地将我从每日数小时的“爬楼”中解放出来让我能通过几分钟阅读AI摘要就把握多个技术社区的动态。最大的体会是前期花点时间精细配置过滤规则和提示词后期收益是巨大的。一个常见的误区是一开始就追求全自动和完美总结其实更好的路径是先让工具跑起来收集原始数据然后基于真实数据去分析优化过滤关键词和黑白名单最后再调整AI总结的提示词让它产出对你真正有用的摘要。