# Telegram · 快速入门

Canonical page: https://phishdestroy.io/tgwitness/zh/docs/reference/quickstart/

安装和启动 TgWitness 的所有方法：Windows 安装包、Python、Docker 以及综合演示，并附带初步测试。

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/zh/llms.txt)

安装和启动 TgWitness 的所有方法：Windows 安装包、Python、Docker 以及综合演示，并附带初步测试。

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![入门指南](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2)

**英语** · [俄语](https://github.com/phishdestroy/TgWitness/blob/main/docs/ru/QUICKSTART.md) · [乌克兰语](https://github.com/phishdestroy/TgWitness/blob/main/docs/uk/QUICKSTART.md) · [西班牙语](https://github.com/phishdestroy/TgWitness/blob/main/docs/es/QUICKSTART.md) · [葡萄牙语（巴西）](https://github.com/phishdestroy/TgWitness/blob/main/docs/pt/QUICKSTART.md) · [土耳其语](https://github.com/phishdestroy/TgWitness/blob/main/docs/tr/QUICKSTART.md) · [阿拉伯语](https://github.com/phishdestroy/TgWitness/blob/main/docs/ar/QUICKSTART.md) · [فارسی](https://github.com/phishdestroy/TgWitness/blob/main/docs/fa/QUICKSTART.md) · [乌尔都语](https://github.com/phishdestroy/TgWitness/blob/main/docs/ur/QUICKSTART.md) · [हिन्दी](https://github.com/phishdestroy/TgWitness/blob/main/docs/hi/QUICKSTART.md) · [印尼语](https://github.com/phishdestroy/TgWitness/blob/main/docs/id/QUICKSTART.md) · [越南语](https://github.com/phishdestroy/TgWitness/blob/main/docs/vi/QUICKSTART.md) · [简体中文](https://github.com/phishdestroy/TgWitness/blob/main/docs/zh/QUICKSTART.md)

TgWitness 是一款用于监控您账户可访问的 Telegram 群组和频道的独立应用程序， 它在本地运行并拥有独立的数据目录。

**初次访问？**[请先体验演示](https://phishdestroy.io/tgwitness/zh/docs/reference/quickstart/#explore-the-interface)，然后再连接账户。 [选择代理、见证人、导出或服务器设置的相关指南](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)。 [GitHub Actions 捕获](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md)（预览）功能可在您自己的 GitHub 分支中运行捕获任务，而无需本地安装。

## 安装并启动

引导式安装程序自带 Python 环境，并在安装前会检查包哈希值和发布 签名。再次运行该程序将更新现有安装。

**Linux / macOS：**

```
curl -fsSL https://get.destroy.tools/install.sh | bash
```

**Windows（PowerShell 或命令提示符）：**

```
powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex"
```

在 Ubuntu 服务器上，请以 root 身份运行以安装后台服务；在桌面系统上，请 以普通用户身份运行。在 Ubuntu 上，安装程序会显示控制面板地址和访问密钥； 在 macOS 和 Windows 上，本地控制面板会在您的浏览器中自动打开。请继续执行下方的**连接 Telegram** 步骤。[安装、验证和更新部分](https://phishdestroy.io/tgwitness/zh/docs/reference/installation/)涵盖了服务器访问选项、 运行脚本前的检查、更新及卸载操作。

### 其他方法

GitHub 发布版本、源代码和 Docker 镜像均可作为安装程序的替代方案。便携式 下载包将在发布构建版本发布后提供：

| 主机 | 无需安装 | 来源：Python 3.11+ | Docker：Engine/Desktop 搭配 Compose 2.20+ |
| --- | --- | --- | --- |
| Windows | 从 GitHub Releases 中提取 `TgWitness-<version>-windows-amd64-portable.zip`，双击 `TgWitness.cmd` | 双击 `Start.cmd` | 双击 `scripts\Docker.cmd` |
| Linux / macOS | — | `sh start.sh` | `sh scripts/docker-start.sh` |

对于源码方式，请[下载并解压当前的 `main` 分支](https://github.com/phishdestroy/TgWitness/archive/refs/heads/main.zip)， 或克隆仓库：

```
git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness
```

如果未找到合适的 Python，`Start.cmd` 会提议为您的 Windows 用户安装 Python 3.12（通过 winget 或带签名的 python.org 安装程序）。如果缺少 Python，`start.sh` 会打印 适用于您的 Linux 发行版或 macOS 的确切安装命令。 首次从源码启动会自动创建 `.venv` 并安装依赖项。

Docker 负责构建应用程序并在后台启动它；无需在主机上安装 Python。当 容器运行正常时，`scripts\Docker.cmd` 和 `scripts/docker-start.sh` 会输出控制面板地址和令牌。在所有受支持的主机上，相应的 Docker 命令如下：

```
docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt
```

打开 **http://127.0.0.1:8787**。使用 Docker 辅助程序或第二个 Docker 命令生成的令牌，或者在便携式或源代码安装中读取 **data/live/panel-token.txt 文件**。继续执行下方的 **“连接 Telegram**”步骤。 原生安装和 Docker 安装使用独立的存储空间； 启动 Docker 不会导入现有的原生日志。

对于服务器，[部署](https://phishdestroy.io/tgwitness/zh/docs/reference/deployment/)涵盖自动 HTTPS、重启、 发布图片、更新和备份。

## 探索界面

1. 在便携包中运行 **TgWitness-Demo.cmd** ，在 Windows 源 文件夹中运行 **scripts\Demo.cmd** ，或在 Linux/macOS 上运行 `sh start.sh --demo` 。首次从源代码启动会先创建 `.venv` 并安装依赖项。
2. 访问 **http://127.0.0.1:8787**。
3. 本地演示会自动打开示例日志。无需复制令牌即可直接进行本地访问。

演示消息均为虚构。演示模式无法连接真实的 Telegram 账户。

## 连接 Telegram

> [!警告] **请使用专用账户。**Telegram 可能会因请求 量过大而限制或永久封禁账户，无论请求来自何种客户端。请连接专门用于 观察的账户，而非个人或重要账户，并在 专用账户上创建 API ID / 哈希值。

1. 如果原生演示程序正在运行，请将其停止，并运行 **Start.cmd** 或 `sh start.sh`。 否则，请继续运行上文启动的实时安装程序。
2. 使用面板令牌登录。新工作区将打开[初始设置界面](https://phishdestroy.io/tgwitness/zh/docs/reference/settings/)。 选择**仅下载**、**关注聊天**或**案件证据**。
3. 请检查连接状态。如有需要，请配置您自己的代理；连接 设置在配置完成后仍可使用。
4. 在 **Connect Telegram** 中，选择一个电话号码、一个二维码、账户文件（TData、 `.session`、StringSession、账户 JSON）或完整的授权密钥。系统提示时，请完成 Telegram 确认、验证码及双重验证密码的输入。
5. 请核对显示的账户，选择聊天群组并检查您的设置。在 最后一个屏幕上点击完成。对于**仅下载**选项**，开始导出**将启动一次性的 导出操作并打开导出页面以显示进度；此操作不会启用持续观察功能。

配置完成后**，聊天→选择**可更改所选聊天。 **设置**控制 数据收集和文件；**更多工具→来源**提供详细来源列表 （标准或专家级别）。[面板指南](https://phishdestroy.io/tgwitness/zh/docs/reference/panel/)描述了六个主要 部分及其上下文控制项。

**API ID + Hash** 为可选项：工作区使用其已保存或导入的配对， 或来自内置池中的有效配对。若要使用您自己的应用，请将一组 `API ID:API Hash`配对粘贴到 API ID 字段中。对于 **Auth key**，请粘贴全部 512 个十六进制 字符，并选择提供的 DC ID。用户 ID 为可选项，若输入则会进行验证。

API 凭据用于识别您的应用程序；它们本身并不能 授权任何账户。私人群组无需公开用户名，但您的账户必须具备访问权限。

对于现有账户，请参阅[账户和会话格式](https://phishdestroy.io/tgwitness/zh/docs/reference/accounts/)：该 面板支持 Telethon StringSession、Telethon/Pyrogram SQLite、单账户 TData ZIP 以及受支持的账户 JSON 格式。请同时选择一个会话及其对应的 JSON 文件， 点击**检查文件**，然后**点击连接账户**。QR 登录功能也 可用，且具有相同的可选 API 设置。 TDLib、机器人会话以及 CSV/JSON 账户清单均不支持。

对于多个账户，请使用**账户 → 导入账户**并选择其受支持的 会话文件。配套的 JSON 文件按基本名称（basename）配对；每个导入的账户 都会获得各自的工作区。请参阅[批量导入与账户组](https://phishdestroy.io/tgwitness/zh/docs/reference/accounts/#bulk-import-and-account-groups)。

要添加另一个账户，请点击账户选择器旁边的**+**号，或使用 **账户 → 添加账户**。工作区拥有独立的会话、 日志、密钥、数据源和队列。切换视图时，其他收集器将继续运行。 在此安装环境中，同一个 Telegram 账户不能分配给两个工作区。 工作区的数量没有限制；它们共享一个进程，因此容量取决于机器性能。

实时面板令牌用于保护您对 Telegram 授权及已保存 材料的访问权限；它与 Telegram API 凭据相互独立。只有明确启动的、 直接访问的本地演示版本才会自动获得访问权限。远程/代理演示版本仍使用 `data/demo/panel-token.txt`。

## 查看与导出

- **日志：**可按来源和事件类型搜索和筛选记录。
- 选择一项事件，查看其原始记录、来源信息及保存的版本。
- 编辑详情显示可用的编辑前/编辑后内容。删除详情显示 最后捕获的内容（如有）；未知行为者仍为未知。
- **导出格式：**带签名的 ZIP、JSONL、CSV 以及离线 HTML。
- **完整聊天导出**（**聊天 → 导出聊天**，**或导出 → 捕获或导出一个 聊天**）：将一个聊天的全部可见 历史记录下载为包含 `chat.json`（Telegram 导出风格）和可读 `chat.html` 的签名包。私聊功能仅在账户为成员时有效。这是当前的 快照，并非已删除或先前编辑过的消息的重建。使用 `python verify.py chat-export.zip --fingerprint TRUSTED_SHA256` 验证 副本。
- **保存检查点：**将签名日志的边界保持在收集器之外。
- **下载签名运行收据：**保留收集器的程序/版本记录。
- **准备时间戳请求：**向时间戳授权机构发起离线请求； 按照 [TIMESTAMP.md](https://phishdestroy.io/tgwitness/zh/docs/reference/timestamp/) 中的说明获取并验证响应。
- **验证日志：**检查事件签名和链节。ZIP 导出功能还会检查媒体文件。

支持的浏览器可将大型导出文件直接保存到指定文件中。其他浏览器 最多缓存 128 MiB。在服务器运行期间，流式 CLI 支持 更大规模的下载，而无需缓存整个响应：

```
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
```

若需使用其他工作区，请通过**导出 → 工作区 ID**添加`--profile ID`。 若需连接远程服务器，请添加`--url https://your-server`。默认传输限制为 5 GiB；可通过`--max-mib`调整该限制。 签名 ZIP 内容默认具有单独的 4 GiB 未压缩 验证限制（通过**更多工具 → 参数**可提高该限制；使用 `verify.py --max-gib N` 验证此类归档文件）。请使用可信的验证器副本、 独立保留的密钥指纹以及（作为证据的最低要求）时间戳 权威机构的根证书（`--tsa-ca`）来验证归档文件。

## 查看安装指南

```
python start.py --setup-only
python start.py --check
python start.py --check --json
```

`--check`用于检测本地依赖项、签名支持、存储、密钥配置以及 监听地址。该工具不会安装任何内容，也不会连接到Telegram。若端口 已被占用，可能意味着已有另一个实例正在运行。请使用另一个`--port`实例，或先停止当前实例。

启动程序将安装到`.venv`目录下。辅助的`python -m tgwitness...`命令必须 在Windows系统上使用`.venv\Scripts\python.exe`，或在Linux/macOS系统上使用`.venv/bin/python`， 除非该环境已激活。

## 会话、保护与操作

一个封闭且一致的 Telethon SQLite `.session` 文件可通过以下命令在本地转换： `python -m tgwitness.sessions account.session --out account.tgwitness-session`，随后 可在**更多工具→账户→文件中**加载。还支持直接文件导入和二维码登录。有关登录格式、SOCKS5、 HTTP CONNECT、MTProxy 及外部主密钥的信息，请参阅 [CONNECTION-SECURITY.md。](https://phishdestroy.io/tgwitness/zh/docs/reference/connection/)

**暂停观察**将停止数据采集。**锁定**仅关闭浏览器访问权限。 关闭标签页不会终止采集进程。停止该进程才会中断 数据采集；历史快照无法还原所有遗漏的编辑或删除操作。 了解[数据采集在事件策略、附件队列、 账户隔离及重启行为方面的运作原理](https://phishdestroy.io/tgwitness/zh/docs/reference/collection/)。

会话和密钥均经过加密。消息内容、媒体文件和导出数据需要使用 加密磁盘或卷。使用可信密钥验证日志签名，并单独保存检查点。 审查所选采集模式下的 捕获记录、外部时间凭证和环境证明。

请阅读 [OPERATIONS.md](https://phishdestroy.io/tgwitness/zh/docs/reference/operations/) 了解备份/恢复操作，阅读 [DEPLOYMENT.md](https://phishdestroy.io/tgwitness/zh/docs/reference/deployment/) 了解托管方案，并访问 [deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md) 查看服务示例。已安装的 控制面板还包含一份离线设置指南，地址为 `/guide.html`。

实际验证情况及现有局限性 记录在 [VERIFICATION.md](https://phishdestroy.io/tgwitness/zh/docs/reference/verification/) 和 [READINESS.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/READINESS.md) 中。
