Telegram Search 详细部署教程

一、项目简介

Telegram Search 是一个用于导出并模糊搜索 Telegram 聊天记录的开源工具。它解决了 Telegram 原生搜索对中文支持不佳、无法进行语义搜索等问题。该项目支持智能分词、向量语义搜索、图片语义搜索以及 AI 智能问答等高级功能。

二、部署前准备

1. 获取 Telegram API 凭证

访问 my.telegram.org/apps 登录您的 Telegram 账号，创建一个应用以获取：

TELEGRAM_API_ID：应用 ID（示例：611335）
TELEGRAM_API_HASH：应用 Hash（示例：d524b414d21f4d37f08684c1df41ac9c）

这些凭证是连接 Telegram 所必需的，请妥善保管。

2. 系统要求

组件	版本要求
Node.js	>= 24.13.0
pnpm	10.28.1
Docker（可选）	任意较新版本
Git	任意较新版本

如果使用 Docker 部署，无需单独安装 Node.js 和 pnpm。

三、部署方式

项目支持多种部署方式，您可以根据需求选择最适合的一种。

方式一：Docker Compose（推荐）

这是最快捷的部署方式，适合生产环境使用。

步骤 1：创建工作目录

1 2	mkdir telegram-search cd telegram-search

步骤 2：下载必要文件

1
2
3

curl -L https://raw.githubusercontent.com/groupultra/telegram-search/refs/heads/main/docker/docker-compose.yml -o docker-compose.yml
curl -L https://raw.githubusercontent.com/groupultra/telegram-search/refs/heads/main/docker/.env.example -o .env
curl -L https://raw.githubusercontent.com/groupultra/telegram-search/refs/heads/main/docker/init.sql -o init.sql

步骤 3：配置环境变量

编辑 .env 文件，填入您的 Telegram API 凭证：

# Telegram API 凭证（必需）
TELEGRAM_API_ID=你的_API_ID
TELEGRAM_API_HASH=你的_API_HASH

# 数据库（默认使用 PostgreSQL）
DATABASE_TYPE=postgres
DATABASE_URL=postgresql://postgres:123456@pgvector:5432/postgres

# MinIO 对象存储（可选，媒体文件备份）
MINIO_URL=http://minio:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=telegram-media

步骤 4：启动服务

1	docker compose -f docker-compose.yml up -d

步骤 5：访问应用

打开浏览器访问 http://localhost:3333 即可使用。

方式二：Docker 单容器模式

适合快速体验，使用内置的 PGlite 数据库，无需额外组件。

docker run -d --name telegram-search \
  -p 3333:3333 \
  -e TELEGRAM_API_ID=你的_API_ID \
  -e TELEGRAM_API_HASH=你的_API_HASH \
  ghcr.io/groupultra/telegram-search:latest

若未配置 MinIO，媒体文件将默认保存在容器的 data/media 目录。

方式三：源码开发模式（CLI / Agent 模式）

适合开发者或需要高级命令行操作的场景。

步骤 1：克隆仓库

1 2	git clone https://github.com/groupultra/telegram-search.git cd telegram-search

步骤 2：安装依赖

1	pnpm install

步骤 3：配置环境

1	cp .env.example .env

编辑 .env 文件，填入您的 Telegram API 凭证。

步骤 4：构建 CLI

1 2	pnpm run build:packages pnpm -F @tg-search/cli build

步骤 5：配置并登录 Profile

# 配置 API 凭证
pnpm cli --profile work profile configure --apiId 你的_API_ID --apiHash 你的_API_HASH

# 登录认证（会要求输入手机号和验证码）
pnpm cli --profile work auth login

步骤 6：使用 CLI 操作

# 列出所有聊天会话
pnpm cli --profile work chats list --json

# 同步指定会话的消息（需用户授权 Takeout）
pnpm cli --profile work sync --takeout --chat 会话ID --from 2026-01-01 --to 2026-12-31

# 搜索消息
pnpm cli --profile work search '搜索关键词' --chat 会话ID

# 导出消息为 JSONL 格式
pnpm cli --profile work export --from 2026-01-01 --to 2026-12-31 --output ./telegram-export

重要：批量同步必须使用 --takeout 参数并经过用户明确授权。Telegram 可能会要求您在手机端确认数据导出请求，请留意 Telegram 应用中的通知。

四、重要配置说明

1. 数据库选择

类型	适用场景	配置方式
PGlite	浏览器模式、开发测试	`DATABASE_TYPE=pglite`（默认）
PostgreSQL	生产环境、多用户	`DATABASE_TYPE=postgres` + 配置 `DATABASE_URL`