把 Telegram 聊天记录变成可检索的本地库（telegram-search）

telegram-search 是一个用 TypeScript 写的开源项目，把 Telegram 账号的聊天记录导出到本地 PGlite 或 PostgreSQL，用中文分词加向量语义搜索做检索，还能通过 Bot 直接查。这篇文章梳理它的部署前提、最短上手命令、环境变量、用户实际踩过的坑，以及和同类 Telegram AI 项目的取舍，帮你判断值不值得自己跑一套。

Telegram 自带的搜索对中文几乎不友好。群聊和频道积累到几万条消息之后，想翻出半年前某个人说过的一句话，只能一页页往下滚。消息存得越多，能被找回来的越少。

telegram-search 是 TypeScript 编写的开源工具，把 Telegram 账号的聊天记录导出到本地 PGlite 或 PostgreSQL，再用中文分词与向量语义搜索做检索。

输入是一个 Telegram 账号的会话与消息，通过手机号登录或 Bot 接入；输出是本地数据库里的一份可检索副本，外加一个跑在 3333 端口的网页界面。适合自己攒了大量群聊与频道记录、想按关键词或语义把消息翻出来的人。仓库地址 https://github.com/groupultra/telegram-search ，采用 AGPL-3.0 许可证，主要语言 TypeScript，截止 2026-10 有 4118 个 star、274 个 fork、9 个开放 Issue，最近一次提交在 2026-09-28。

第一次用它需要知道的事

运行环境要 Node 22.18.0 以上。Issue 里有用户用 v22.16.0 启动时报 Unsupported engine: wanted: {"node":">=22.18.0"}，版本低于这条线会在启动阶段被拦。
需要一对 Telegram API 凭据：API ID 与 API Hash 从 my.telegram.org/apps 申请。要用 Bot 功能的话再准备一个由 @BotFather 创建的 token。
登录走手机号加验证码，第一次授权时手机上要能收到码并确认。也就是说这个账号本身得在你手上。
服务器要能连通 Telegram。国内网络环境下通常得配 PROXY_URL，Issue 里有多条关于登录超时的反馈，发帖人都提到自己在用代理。
Docker Compose 方式会一次拉起数据库、MinIO 对象存储和前端三部分，媒体文件走 MinIO 或落到本地 data/media 目录，自建时这两处都要占磁盘。

最短上手路径

建一个空目录并进入：mkdir telegram-search && cd telegram-search。
把三个文件拉到本地，分别是 docker/docker-compose.yml、docker/.env.example（存为 .env）和 docker/init.sql。
启动全部服务：docker compose -f docker-compose.yml up -d。
浏览器打开 http://localhost:3333，在界面里完成登录与同步。
AI 相关能力在应用内按账户配置，路径是「设置 → API」；改完 .env 后要重跑一次 docker compose -f docker-compose.yml up -d 让服务读到新值。

不想自己拼 Compose 文件，也可以直接跑官方镜像：docker run -d --name telegram-search -p 3333:3333 ghcr.io/groupultra/telegram-search:latest。这条路径下如果没有配 MinIO 参数，媒体文件默认保存到本地的 data/media。

它实际上能做哪些事

导出与备份

把聊天记录导出到数据库，兼容 PGlite 与 PostgreSQL 两种后端；用哪种由 DATABASE_TYPE 决定。PGlite 适合单机轻量场景，PostgreSQL 适合已经有 pgvector 的部署。
媒体资源自动备份到 MinIO 对象存储，不需要手动搬运；没配 MinIO 时会落到本地目录。
消息导出过程中同步完成向量嵌入与分词，这样后续检索不用再补一遍索引。代价是导出阶段要调用 embedding 接口，需要先配好可用的端点。

搜索与问答

自动分词加多语言检索，中文能命中。这也是项目最核心的卖点，Telegram 官方搜索在中文上的短板就出在分词。
模糊匹配与向量语义搜索叠加使用，前者管字面命中，后者管「意思接近但用词不同」的句子。
图片语义搜索，用文字描述去找图。这依赖图片 embedding，同样需要可用的向量模型。
RAG 智能问答，直接对着历史上下文提问。它回答的范围限于已经同步进来的聊天记录。

Bot 与辅助功能

通过 Telegram Bot 搜索和导出消息，消息带 deep link，点击能跳回原始对话，网页端也支持右键菜单跳转原消息、移动端同样可用。
未读消息智能摘要，一键汇总全部未读并生成摘要；另有日期范围筛选，可以把搜索范围缩到某一段时间。这两项都依赖已配置的 LLM。

参数速查

仓库的环境变量表里明确写着以下变量全部可选，不填就走默认值。

TELEGRAM_API_ID 与 TELEGRAM_API_HASH：从 my.telegram.org 获取的应用凭据，缺了无法登录。
DATABASE_TYPE：可选 postgres 或 pglite。选 postgres 时再填 DATABASE_URL，形如 postgresql://postgres:123456@pgvector:5432/postgres。
TELEGRAM_BOT_TOKEN：只用 Bot 能力时才需要，从 @BotFather 拿。
PROXY_URL：代理地址，支持 socks5://user:pass@host:port 这类格式。
PORT 与 HOST：后端 HTTP/WebSocket 的监听端口与地址，默认 3333 和 0.0.0.0。
BACKEND_URL：用 Nginx 反代时，/api 和 /ws 的上游后端地址。
MINIO_URL、MINIO_ACCESS_KEY、MINIO_SECRET_KEY、MINIO_BUCKET：对象存储四件套，决定媒体往哪存。

另外仓库提供了一套本地优先的 CLI，走命名 profile 的方式工作：

pnpm cli --profile work profile configure --apiId 123456 --apiHash abcdef
pnpm cli --profile work auth login
pnpm cli --profile work chats list --json
pnpm cli --profile work sync --takeout --chat 123456 --from 2026-01-01 --to 2026-12-31
pnpm cli --profile work export --from 2026-01-01 --to 2026-12-31 --output ./telegram-2026

CLI 的隐私边界在仓库里写得很细：chats list 和 messages list 只做有界的远端读取，不落库；批量同步必须在 sync 命令里显式带上 --takeout，未授权、用户拒绝或 Takeout 初始化失败都会直接停下，不会退回普通的 GetHistory。

输出与结果位置

网页端：Docker 部署后默认在 http://localhost:3333，搜索结果和 AI 问答都在这个界面里看。
媒体文件：配了 MinIO 就进对象存储的 MINIO_BUCKET；没配则落到本地 data/media。
CLI 导出：export 命令按 --output 指定的目录落盘，内容是按月切分的 JSONL 加一份校验清单。仓库明确说明导出包不含媒体二进制、登录 session、向量或密钥，也不会替用户执行 AI 总结。
同步结果写入 profile 各自独立的 PGlite，不同 profile 的数据互不干扰。
CLI 的 stdout 只输出 JSON 结果，Telegram 日志、提示与进度全部走 stderr，方便接进别的脚本。

实际使用中的坑

embedding 端点被强制指向 api.openai.com。有用户反馈无论在配置文件还是网页端设置，embedding 端点都会被改回官方地址，导致没法用第三方站点的 API。该 Issue 已解决。
Nginx 反向代理后网页报 Blocked request. This host ("se.xx.eu") is not allowed。按 Docker 教程部署后用域名访问会被拦，需要把域名加进允许列表。该 Issue 已解决。
手机号登录超时，报 Timeout connecting to Telegram, check your internet connection and try again。发帖人当时开着 clash，本质是网络连通问题。该 Issue 已解决。
Node 版本不够导致启动失败。用 v22.16.0 跑会看到 WARN Unsupported engine，把版本提到 22.18.0 以上即可。该 Issue 已解决。

替代方案一览

下面三个项目都能在 Telegram 场景里发挥作用，但重心不同，放在一起只为方便判断路线。

项目	适合谁	部署方式	主要限制	什么情况下选它更合适	项目地址
telegram-search	手里有大量群聊与频道记录、需要按中文把旧消息翻出来的个人用户，愿意自己跑一套服务	Docker Compose 一次拉起数据库、MinIO 与前端；也可只跑 ghcr.io 上的单个镜像	必须自备 Telegram API ID 与 Hash，登录要手机号收码；embedding 与 LLM 需要另外配置；截至 2026-10 有 9 个开放 Issue	你的核心诉求是把已有的聊天记录变成可检索、可问答的本地库	telegram-search
smixs/iva-agent	想让 Telegram 里的助手长期记住对话内容的人	仓库没有说明	未逐一核实	你要的是常驻在 Telegram 里、记得住事并帮你处理日常的助手	smixs/iva-agent
moltis-org/moltis	想自己托管一个长期在线的个人 agent 服务的用户	仓库没有说明	未逐一核实	你更关心自托管 agent 服务本身，而不是聊天记录的检索	moltis-org/moltis

如果你要的是每天在 Telegram 里跟你对话、替你处理事务的通用助手，telegram-search 并不对路，它的 AI 能力全部围绕你自己的聊天记录做检索和问答，跨平台扩展还停在路线图阶段，目前只写了要支持 Discord 及其他平台。iva-agent 与 moltis 这类项目解决的是另一个层面的问题，用它们来替代不了「把三年群聊翻出来查」这件事；反过来，你要是已经在用某个常驻助手，也没必要为了搜消息换掉它。真正该选 telegram-search 的场景，是你手上有一堆散落在 Telegram 里的历史信息，需要一条能反复检索的通道。

别踩的合规线

这类工具处理的是私人通信数据，边界必须自己守住。仓库里的警示写得很直接：本软件仅供导出和检索个人聊天记录使用，切勿用于任何违法用途，同时项目方声明没有发行任何虚拟货币，遇到相关说法要警惕诈骗。

落到操作上，能同步的应当只有你自己拥有且已登录授权的账号，不要把别人的号、群成员的消息或者你无权访问的频道接进来。批量拉取要按仓库设计的走：由用户在 sync 命令里显式加 --takeout，未授权就停，不要绕过这个确认环节去直接调用接口。Telegram 的 API 使用条款对自动化拉取、数据留存都有约束，违反可能导致账号被封；在部分司法辖区，未经同意导出他人通信内容还可能触及法律风险。

软件本身采用 AGPL-3.0，这个许可证对网络服务有额外要求：如果你修改了代码并以网络服务的形式提供给他人使用，需要向使用者开放修改后的源码。自己搭一套仅供个人检索不算分发，想改成对外服务之前先看清这一条。

什么时候值得用它

你已经在一个 Telegram 账号里积累了大量中文群聊、频道或私聊记录，官方搜索满足不了检索需求，而你又不想把这些内容交到第三方托管服务手里。
你手上有一台能长期开机、愿意用 Docker 跑几个容器的机器，并且能接受为 embedding 和 LLM 单独配置一份 API 凭据。
你需要的是可反复查询的本地索引和基于历史上下文的问答，CLI 导出出来的按月 JSONL 还能接进你自己的归档流程。

焚评：这个项目的量化评分

本项目的选题来自焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.2 分（满分 10）。下表是各维度的得分：

评分维度	得分
热度动量（权重 25%）	10.0 / 10
开发活跃（权重 25%）	9.1 / 10
社区响应（权重 15%）	10.0 / 10
文档质量（权重 15%）	6.7 / 10
发布节奏（权重 10%）	8.9 / 10
风险控制（权重 10%）	10.0 / 10

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。