kolezka/tg-viewer
GitHub: kolezka/tg-viewer
一款 macOS 上的 Telegram 数据离线提取与浏览工具，支持解密 SQLCipher 数据库、解析 Postbox 格式并通过 Web UI 查看消息、媒体和联系人等数据。
Stars: 5 | Forks: 0
```
████████╗ ██████╗ ██╗ ██╗██╗███████╗██╗ ██╗███████╗██████╔╗
╚══██╔══╝██╔════╝ ██║ ██║██║██╔════╝██║ ██║██╔════╝██╔══██╗
██║ ██║ ███╗█████╗ ██║ ██║██║█████╗ ██║ █╗ ██║█████╗ ██████╔╝
██║ ██║ ██║╚════╝ ╚██╗ ██╔╝██║██╔══╝ ██║███╗██║██╔══╝ ██╔══██╗
██║ ╚██████╔╝ ╚████╔╝ ██║███████╗╚███╔███╔╝███████╗██║ ██║
╚═╝ ╚═════╝ ╚═══╝ ╚═╝╚══════╝ ╚══╝╚══╝ ╚══════╝╚═╝ ╚═╝
```
# Telegram Data Viewer
用于提取、解密和浏览 Telegram 消息（包括已删除的消息和私密聊天）的 macOS 工具包。
## 工作原理
该 pipeline 包含两个阶段：
1. **提取** (`apps/tool/`) — 复制 Telegram 的数据，解密 SQLCipher 数据库，将 Postbox 二进制格式解析为 JSON。
2. **查看** (`apps/api/` + `apps/web/`) — FastAPI 后端提供解析后的 JSON；React + Bun 前端在浏览器中渲染数据。
```
flowchart LR
A["apps/tool/tg-backup.sh
Copy app data"] --> B["apps/tool/tg_appstore_decrypt.py
Decrypt SQLCipher"] B --> C["apps/tool/postbox_parser.py
Parse messages"] C --> D["apps/api + apps/web
Browse in browser"] style A fill:#4a9eff,color:#fff,stroke:none style B fill:#ff6b6b,color:#fff,stroke:none style C fill:#ffa94d,color:#fff,stroke:none style D fill:#51cf66,color:#fff,stroke:none ``` `./tg-viewer full` 通过一条命令运行整个 pipeline。 ## 快速开始 ``` # 1. One-shot setup：创建 .venv/，安装 Python + Bun deps，构建 frontend ./tg-viewer setup source .venv/bin/activate # 2. 完整 pipeline：backup → decrypt → parse → web UI 位于 http://127.0.0.1:5000 ./tg-viewer full # 3. 完成后进行清理 ./tg-viewer clean ``` `./tg-viewer setup` 负责处理一切：为 Python 后端（`apps/api`）和提取工具（`apps/tool`）创建项目本地的 `.venv/`，并为 React 前端（`apps/web`）执行 `bun install && bun run build`。 全新克隆后，你只需要 Python 3.11+、Bun 和正常运行的 Telegram 安装，`setup` 会完成剩下的工作。 ## 命令 | 命令 | 描述 | |---------|-------------| | `./tg-viewer full [DIR]` | 运行完整工作流：备份、解密、解析、Web UI | | `./tg-viewer backup [DIR]` | 创建 Telegram 数据备份 | | `./tg-viewer decrypt DIR` | 解密数据库（App Store `.tempkeyEncrypted`） | | `./tg-viewer parse DIR` | 将 Postbox 二进制格式解析为 messages/peers/conversations | | `./tg-viewer webui DIR` | 启动 Web UI 浏览解析后的数据 | | `./tg-viewer clean` | 删除所有备份、解密和解析后的数据 | | `./tg-viewer setup` | 创建 `.venv/`，安装 Python + Bun 依赖，构建前端 | ## Web UI 在 `http://127.0.0.1:5000` 提供服务。位于 `apps/api/` 的 FastAPI 应用挂载来自 `apps/web/dist/` 的 React bundle，并在 `/api/*` 提供 JSON-over-HTTP API。 | 标签页 | 显示内容 | |-----|---------------| | **Messages** | 所有消息的扁平列表，支持跨所有会话搜索 | | **Chats** | 会话列表，带有类型过滤器（Secret、Cached/Deleted、Users、Channels、Bots、Groups） | | **Media** | 每个缓存文件的网格视图，带有缩略图、类型过滤器和灯箱预览 | | **Users** | 所有 peers，包含姓名、用户名和电话号码 | | **Databases** | 每个账户的解密状态 | ## 支持的 Telegram 版本 | 版本 | 位置 | 状态 | |---------|----------|--------| | App Store | `~/Library/Group Containers/6N38VWS5BX.ru.keepcoder.Telegram` | 完全支持 | | Desktop | `~/Library/Application Support/Telegram Desktop` | 仅支持备份 | | Standalone | `~/Library/Application Support/Telegram` | 仅支持备份 | ## 路线图 计划中支持 macOS App Store 客户端之外的来源： - **iPhone (iOS)** — 从本地 iTunes/Finder 备份（`~/Library/Application Support/MobileSync/Backup/`）提取 Telegram 数据，或从越狱设备的应用容器中提取。目标与 iOS 应用自带的 Postbox 数据库格式相同，因此通过调整路径和采用不同的 keychain 提取步骤，现有的解密和解析 pipeline 的大部分功能应该都能适用。 - **Android** — 在已 root 的设备上通过 ADB 拉取 Telegram 的应用数据（`/data/data/org.telegram.messenger/`），或从完整的设备备份中提取。Android 使用不同的磁盘上 schema（SQLite + `cache4.db`，而不是 Postbox），因此除了现有的解析器外，还需要一个单独的解析器。 - **Telegram Desktop (tdesktop)** — 官方跨平台桌面客户端（与已经支持的 macOS App Store 构建版本不同）。它将数据存储在 `tdata/` 下，并使用其自有的基于 MTProto 的加密方案。目前 `tg-viewer` 仅备份这些目录；完整的解密和解析支持已在路线图中。 ## 环境要求 - 安装了 Telegram 的 macOS 系统 - Python 3.7+ - 依赖项：`sqlcipher3`、`cryptography`、`fastapi`、`uvicorn`、`pydantic` - Bun（用于 React 前端）— 从 [bun.sh](https://bun.sh) 安装 ## 文档 - [docs/usage.md](docs/usage.md) — 分步使用说明和常见场景（重新解析、自定义密码、`--redact`、多账户、jq 查询） - [docs/architecture.md](docs/architecture.md) — 子系统布局、脚本表、解密流程、密钥派生、Postbox schema - [docs/output-format.md](docs/output-format.md) — `parsed_data/` 目录树以及消息和媒体条目的 JSON 结构 - [docs/api.md](docs/api.md) — Swagger / ReDoc / OpenAPI schema endpoints - [docs/troubleshooting.md](docs/troubleshooting.md) — 常见故障模式及修复方法 ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。
Copy app data"] --> B["apps/tool/tg_appstore_decrypt.py
Decrypt SQLCipher"] B --> C["apps/tool/postbox_parser.py
Parse messages"] C --> D["apps/api + apps/web
Browse in browser"] style A fill:#4a9eff,color:#fff,stroke:none style B fill:#ff6b6b,color:#fff,stroke:none style C fill:#ffa94d,color:#fff,stroke:none style D fill:#51cf66,color:#fff,stroke:none ``` `./tg-viewer full` 通过一条命令运行整个 pipeline。 ## 快速开始 ``` # 1. One-shot setup：创建 .venv/，安装 Python + Bun deps，构建 frontend ./tg-viewer setup source .venv/bin/activate # 2. 完整 pipeline：backup → decrypt → parse → web UI 位于 http://127.0.0.1:5000 ./tg-viewer full # 3. 完成后进行清理 ./tg-viewer clean ``` `./tg-viewer setup` 负责处理一切：为 Python 后端（`apps/api`）和提取工具（`apps/tool`）创建项目本地的 `.venv/`，并为 React 前端（`apps/web`）执行 `bun install && bun run build`。 全新克隆后，你只需要 Python 3.11+、Bun 和正常运行的 Telegram 安装，`setup` 会完成剩下的工作。 ## 命令 | 命令 | 描述 | |---------|-------------| | `./tg-viewer full [DIR]` | 运行完整工作流：备份、解密、解析、Web UI | | `./tg-viewer backup [DIR]` | 创建 Telegram 数据备份 | | `./tg-viewer decrypt DIR` | 解密数据库（App Store `.tempkeyEncrypted`） | | `./tg-viewer parse DIR` | 将 Postbox 二进制格式解析为 messages/peers/conversations | | `./tg-viewer webui DIR` | 启动 Web UI 浏览解析后的数据 | | `./tg-viewer clean` | 删除所有备份、解密和解析后的数据 | | `./tg-viewer setup` | 创建 `.venv/`，安装 Python + Bun 依赖，构建前端 | ## Web UI 在 `http://127.0.0.1:5000` 提供服务。位于 `apps/api/` 的 FastAPI 应用挂载来自 `apps/web/dist/` 的 React bundle，并在 `/api/*` 提供 JSON-over-HTTP API。 | 标签页 | 显示内容 | |-----|---------------| | **Messages** | 所有消息的扁平列表，支持跨所有会话搜索 | | **Chats** | 会话列表，带有类型过滤器（Secret、Cached/Deleted、Users、Channels、Bots、Groups） | | **Media** | 每个缓存文件的网格视图，带有缩略图、类型过滤器和灯箱预览 | | **Users** | 所有 peers，包含姓名、用户名和电话号码 | | **Databases** | 每个账户的解密状态 | ## 支持的 Telegram 版本 | 版本 | 位置 | 状态 | |---------|----------|--------| | App Store | `~/Library/Group Containers/6N38VWS5BX.ru.keepcoder.Telegram` | 完全支持 | | Desktop | `~/Library/Application Support/Telegram Desktop` | 仅支持备份 | | Standalone | `~/Library/Application Support/Telegram` | 仅支持备份 | ## 路线图 计划中支持 macOS App Store 客户端之外的来源： - **iPhone (iOS)** — 从本地 iTunes/Finder 备份（`~/Library/Application Support/MobileSync/Backup/`）提取 Telegram 数据，或从越狱设备的应用容器中提取。目标与 iOS 应用自带的 Postbox 数据库格式相同，因此通过调整路径和采用不同的 keychain 提取步骤，现有的解密和解析 pipeline 的大部分功能应该都能适用。 - **Android** — 在已 root 的设备上通过 ADB 拉取 Telegram 的应用数据（`/data/data/org.telegram.messenger/`），或从完整的设备备份中提取。Android 使用不同的磁盘上 schema（SQLite + `cache4.db`，而不是 Postbox），因此除了现有的解析器外，还需要一个单独的解析器。 - **Telegram Desktop (tdesktop)** — 官方跨平台桌面客户端（与已经支持的 macOS App Store 构建版本不同）。它将数据存储在 `tdata/` 下，并使用其自有的基于 MTProto 的加密方案。目前 `tg-viewer` 仅备份这些目录；完整的解密和解析支持已在路线图中。 ## 环境要求 - 安装了 Telegram 的 macOS 系统 - Python 3.7+ - 依赖项：`sqlcipher3`、`cryptography`、`fastapi`、`uvicorn`、`pydantic` - Bun（用于 React 前端）— 从 [bun.sh](https://bun.sh) 安装 ## 文档 - [docs/usage.md](docs/usage.md) — 分步使用说明和常见场景（重新解析、自定义密码、`--redact`、多账户、jq 查询） - [docs/architecture.md](docs/architecture.md) — 子系统布局、脚本表、解密流程、密钥派生、Postbox schema - [docs/output-format.md](docs/output-format.md) — `parsed_data/` 目录树以及消息和媒体条目的 JSON 结构 - [docs/api.md](docs/api.md) — Swagger / ReDoc / OpenAPI schema endpoints - [docs/troubleshooting.md](docs/troubleshooting.md) — 常见故障模式及修复方法 ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。
标签：AV绕过, FastAPI, HTTP工具, OSINT工具, React, Syscalls, Telegram, 安全助手, 数字取证, 数据解密, 自动化脚本, 逆向工具