部署

英语 · 俄语 · 乌克兰语 · 西班牙语 · 葡萄牙语（巴西） · 土耳其语 · 阿拉伯语 · فارسی · 乌尔都语 · हिन्दी · 印尼语 · 越南语 · 简体中文

选择安装方式#

若使用便携包，请从 GitHub Releases 解压 TgWitness-<version>-windows-amd64-portable.zip。若采用其他方法，请下载并解压源代码 ZIP 文件或克隆 代码库，然后在项目目录下运行以下命令：

关于第三方应能进行核查的云服务器——该服务器通过 服务商的 API 创建，不使用 SSH，仅可通过 Cloudflare Tunnel 访问——请参阅 “高可信度部署”。

原生启动程序会生成一个私有.venv，并安装已固定的依赖项。 Docker会在镜像内部构建这些依赖项，无需主机端的Python。首次 设置需要互联网连接。 若未检测到 Python 3.11 及以上版本，Start.cmd 会在 为当前 Windows 用户安装 Python 3.12 之前征得用户同意（使用 winget，否则在验证 Python 软件基金会签名后使用 python.org 安装程序）；该过程绝不会请求 管理员权限。Docker 和操作系统服务仍是必备条件。

原生和便携式安装会在其文件夹内使用 data/live。Docker 则使用名为 tgwitness-data 的卷 位于 /data。在您刻意迁移 完整数据目录之前，这些属于独立的安装实例。请勿期望新的 Docker 容器能自动发现原生 账户。

安装要求#

原生安装需要 Python 3.11 或更高版本，并包含 venv 和 ensurepip；首次安装依赖项时需要 互联网连接；以及一个可供 .venv 写入的项目目录。捆绑的控制面板无需 Node.js 或前端构建。请从 您的常规操作系统账户运行启动器；TgWitness 不需要管理员/root 权限。

• Windows：Start.cmd 会先检查 py -3，然后是 python，接着是默认的用户级和 Program Files 安装文件夹，并要求系统版本为 3.11 或更高。如果以上路径均无效，它 将提供上述所述的自动用户级安装选项。py -3 start.py 同样有效。 便携版完全不需要 Python。
• Linux：start.sh 会依次尝试 python3.13、python3.12、python3.11、python3 和 python，若均不匹配，则会输出适用于 apt、dnf、pacman、zypper、apk 或 Homebrew 的安装命令。 Debian/Ubuntu 系统可能需要安装与所选解释器匹配的 python3-venv 软件包。 发行版中较旧的 默认 Python 必须被 Python 3.11 及以上版本替换或补充。
• macOS：请安装最新的 Python 3.11+ 发行版；请勿假设操作系统自带的 解释器符合要求。请使用项目目录中的 python3 start.py。
• Docker：请使用搭载 Compose v2.20 或更高版本的 Docker Engine/Desktop。在 Windows 系统上，Docker Desktop 必须使用 Linux 容器。该容器会自行安装 所需的 Python 依赖项；主机无需单独安装 Python。

请使用持久性本地存储作为数据目录。根据消息、 媒体文件、WAL 增长、导出和备份来规划存储容量；目前尚无基于证据的、适用于所有工作负载的通用最低 磁盘/内存规格。对于没有兼容依赖项轮（wheel）的 CPU 架构和 Python 版本， 可能需要额外的构建工具及其 相应的验证。 “可移植”并不意味着支持所有操作系统或硬件。

已在本机验证 Windows 11/Python 3.12 环境。Linux/macOS/容器配置文件及持续集成（CI） 虽已提供，但尚未在此开发主机上执行。具体范围请参阅 VERIFICATION.md 文件。

本地计算机#

在 Windows 系统上使用 Start.cmd，在 Linux/macOS 系统上使用 sh start.sh。scripts\Setup.cmd 或 sh start.sh --setup-only 可用于 准备运行环境。启动程序在首次使用时会安装依赖项；后续启动 将复用该环境。设置和 Telegram 消息采集需要互联网连接， 但浏览现有记录和生成导出文件可在离线状态下进行。

设置完成后运行 python start.py --check，可在不启动收集器的情况下检查本地依赖项、Ed25519、 存储、密钥配置及监听地址。 使用 --json 获取结构化输出。传入预期的 --data-dir、--host 和 --port。此检查不会安装软件包、创建日志或连接 Telegram； 它并非完整性或覆盖范围的资格认证。启动时会单独验证 现有日志。python start.py --help 同样无需安装。

选项：

运行 start.py 后，请在 Windows 系统上使用 .venv\Scripts\python.exe，在 Linux/macOS 系统上使用 .venv/bin/python 执行辅助命令，或者先激活该环境。 下文中的 python -m ... 示例假设该环境已处于活动状态。

python -m tgwitness --data-dir /path/to/private/data --host 127.0.0.1 --port 8787

环境变量：TGWITNESS_DATA、TGWITNESS_HOST、TGWITNESS_PORT、TGWITNESS_TOKEN。 TGWITNESS_VAULT_KEY_FILE 用于在新安装中选择外部密钥模式；详见下文。 若提供 TGWITNESS_TOKEN，其长度必须至少为 24 个字符；请使用加密 生成的随机值。若未提供，应用程序将在 panel-token.txt 文件中生成一个 256 位的随机令牌。 环境变量覆盖不会重写该文件。请重启以轮换凭据。

数据目录仅允许一个进程拥有。跨平台操作系统文件锁机制可防止 意外的并发写入。请使用一个 Uvicorn 工作进程。控制面板可管理任意数量的 工作区，额外的工作区目录位于 profiles/<id>/ 下。 对于独立的服务实例，请使用独立的目录和端口。SQLite WAL 文件应存储在本地持久化 存储中，而非网络文件系统中。请勿在副本之间共享同一卷。

Windows 便携版#

每个 GitHub 发布版本都包含 TgWitness-<version>-windows-amd64-portable.zip 及其 .sha256。其中包含来自 python.org 的官方可嵌入式 Python 3.12 运行时 （校验和固定在 tools/build_portable.py 中）、TgWitness 及其固定依赖项， 以及三个启动器：

将整个压缩包解压到可写入的文件夹中，例如 Documents\TgWitness；请勿 在 ZIP 文件内部或 Program Files 文件夹中运行该程序。运行时使用隔离的模块路径， 因此其他 Python 安装以及 PYTHONPATH 均不会对其产生影响。 数据保存在 该软件包的data文件夹中。若需更新，请停止 TgWitness，将新版本解压到一个新的 文件夹中，然后将data文件夹复制过去。

在 64 位 Windows 系统上使用 Python 3.12 自行构建：

python tools/build_portable.py

构建程序会验证运行时校验和，将受限依赖项安装到 软件包中，使用嵌入式解释器运行就绪性检查，并将 ZIP 文件和校验和写入 dist/。

容器#

docker compose up -d --build --wait

这将为 /data 创建一个命名持久卷。 Web 端口映射至 127.0.0.1:8787。 该进程以 UID 10001 身份运行，且已移除 权限，根文件系统为只读，而 /data 和 /tmp 目录可写。 --wait 在返回前会检查 Web 服务器的运行状态；它不会建立 Telegram 授权或消息投递。 提供的辅助程序在构建完成后采用 180 秒的就绪超时 设置。初始依赖项的下载可能需要更长时间。

两个基础 Compose 文件均使用项目名称 tgwitness，因此将新版本 解压到另一个目录时，系统不会自动选择新的数据卷。请确保该项目仅有一个 部署处于活动状态。对于独立安装，请使用唯一的 docker compose -p NAME ... 以及不同的主机端口，并在更新时保留这两个配置。 对于使用不同项目名称的旧部署，请继续使用其原始 名称并添加 -p；docker compose ls 会列出现有项目。

将 deploy/env.example 复制到 .env，并将 TGWITNESS_PORT 修改为使用不同的回环 端口。例如，TGWITNESS_PORT=8788 将控制面板暴露在 http://127.0.0.1:8788；容器仍监听 8787 端口。.env 被 Git 忽略。

获取初始令牌：

docker compose exec tgwitness cat /data/panel-token.txt

常用命令：

docker compose ps
docker compose logs --tail 100 -f
docker compose stop
docker compose up -d --wait

restart: unless-stopped 会在收集器崩溃或 Docker 守护进程 重启后自动重启收集器。在 Linux 服务器上，请使用您所用发行版的 服务管理器（通常为 sudo systemctl enable --now docker）启用 Docker 自动启动。在 Windows/macOS 上，请启用 Docker Desktop 的“登录时启动”设置。桌面注销、休眠或 Docker Docker 守护进程都可能中断数据采集。明确停止的容器将保持 停止状态，直到您再次启动它。

在示例配置中，/tmp 分区的上限为 512 MiB。导出构建 改用每个工作区的 temporary-exports/ 路径，将其映射到持久化 /data 分区。请在此处预留空间 以满足同时导出、日志/WAL 增长、媒体文件及备份的需求。 启动器使用 deploy/constraints.txt 来锁定符合要求的运行时依赖项版本。 Docker 和高保障服务器根据 deploy/requirements.lock 和 deploy/build.lock 文件，通过 pip --require-hashes 进行安装：每个包文件必须与提交中记录的 SHA-256 值相匹配，因此若 PyPI 或镜像站点上的文件被替换，则会被拒绝。 Python 基础 镜像和操作系统软件包仍需通过独立的发布资格认证。

除非您打算销毁日志和密钥，否则请勿使用 `docker compose down -v` 命令。 容器健康状况报告反映的是 Web 服务器的可用性，而非 Telegram 捕获是否成功。 请检查控制面板中的采集器状态、心跳、错误及覆盖事件。

独立见证者简介#

可选的 witness 服务会在其自身的 容器中运行一个独立的见证节点，该节点在 witness-data 卷中拥有独立的密钥和日志，而收集器仅拥有一个只读 的见证令牌。在控制面板的“见证”页面上创建该令牌，将其 与机器人令牌和频道一起添加到 .env，然后启动配置文件：

docker compose --profile witness up -d          # deploy/compose/compose.image.yaml: same flag
docker compose logs witness                     # witness key fingerprint

该服务通过 Compose 网络内的收集器访问，地址为 http://tgwitness:8787 （TGWITNESS_WITNESS_COLLECTOR 会覆盖该地址，例如 /profiles/<workspace ID> 用于 另一个工作区）。若要使用由他人运行的独立服务器上的见证文件，请在该服务器上使用 deploy/compose/compose.witness.yaml ，并将 TGWITNESS_WITNESS_COLLECTOR 设置为收集器的 HTTPS 地址；该文件仅包含见证文件。

安装已发布的镜像#

该网站将在发布工作流 成功完成且 GHCR 包配置公开后上线。存储库的所有者/名称并未硬编码 到此源代码树中。请使用该发布版工作流摘要中显示的图片。

将 deploy/env.example 复制到 .env。将 TGWITNESS_IMAGE 设置为发布版本，使用 小写形式的仓库路径，例如：

TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.7.0
TGWITNESS_PORT=8787

请单独运行此文件，而非运行 compose.yaml：

docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait
docker compose --project-directory . -f deploy/compose/compose.image.yaml exec tgwitness cat /data/panel-token.txt

主机上无需源代码构建、Python 或编译器。发布工作流 针对 Linux AMD64 和 ARM64 容器，包括 Docker Desktop 的 Linux 虚拟机。 请使用版本标签或工作流摘要中的 ghcr.io/owner/repository@sha256:...。 未配置latest标签的动态更新或无人值守的应用程序升级。当 项目名称相同时，镜像和源代码变体将使用相同的数据卷。

服务器上的自动 HTTPS 配置#

请使用搭载 Docker 的服务器、您自行管理的域名以及持久的本地存储空间。 将域名的 A/AAAA 记录指向该服务器；仅当 IPv6 可访问该服务器时才发布 AAAA 记录。 允许入站 TCP 80 和 443 端口，以及用于证书签发的出站 DNS/HTTPS 流量。 其他服务不得已占用这些端口。

将 deploy/env.example 复制到 .env，并设置主机名（不包含协议或路径）：

TGWITNESS_DOMAIN=watch.your-domain.org

使用 HTTPS 覆盖层开始源代码构建：

docker compose -f compose.yaml -f deploy/compose/compose.https.yaml up -d --build --wait
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml exec tgwitness cat /data/panel-token.txt

docker compose --project-directory . -f deploy/compose/compose.image.yaml -f deploy/compose/compose.https.yaml up -d --wait

对于已发布的图像，请改用 deploy/compose/compose.image.yaml 作为第一个文件。保留 两个 -f 参数，以便后续使用状态、日志、更新和停止命令。

Caddy 负责获取和续期证书，将 HTTP 重定向至 HTTPS，并将 请求转发至私有 Compose 网络上的收集器。证书状态 拥有独立的持久化卷。收集器的直接主机端口仅限回环访问。 提供的 Caddy 配置未启用访问日志记录。

打开 https://watch.your-domain.org 并输入面板令牌。准备就绪 并不意味着证书已签发或外部可达。如果 HTTPS 尚未 就绪，请检查 DNS、防火墙规则以及：

docker compose -f compose.yaml -f deploy/compose/compose.https.yaml logs --tail 100 caddy

提供的 Caddy 镜像遵循其 2-alpine 标签。拉取操作会刷新该镜像； 若需固定基础设施版本，请在部署中固定一个经过测试的摘要。

更新与备份#

在更新过程中保留 Compose 项目名称和数据量。首先停止 收集器并进行完整备份。对于默认的基于源代码的部署：

docker compose stop
docker compose cp tgwitness:/data ../tgwitness-backup-before-update

每次请使用存储库之外的新备份目标，并将其作为 账户访问材料加以保护。示例路径仅供参考；请使用您自己的私有备份 位置。复制整个目录，包括隐藏文件、所有工作区、密钥、 日志和媒体文件。如果已配置外部保险库主密钥，请将其单独备份。 证据 ZIP 文件并非可恢复的应用程序备份。对于 HTTPS，若需保留其证书/账户状态，还应保留 Caddy 卷。

若要进行源代码部署，请获取最新发布文件并运行：

docker compose up -d --build --wait

若需部署镜像，请将 TGWITNESS_IMAGE 替换为所需版本，然后运行：

docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait

请也使用您安装环境中的 Compose 文件来执行上述停止/复制命令。 请保留 .env、自定义配置以及相同的项目名称。down 会保留命名 卷；down -v 会将其删除。请勿在不同操作系统 或 Python 版本之间复制 .venv。若需进行原生更新，请先停止 TgWitness，备份其完整数据 目录，替换源文件，并在启动前运行 python start.py --setup-only。

更新后，请检查控制面板访问权限、账户身份、监控状态及覆盖范围。 重启不会恢复遗漏的 Telegram 更新。如果未来版本更改了存储格式， 回滚可能需要使用更新前的备份。

GitHub 自动发布#

将该项目推送到已启用 Actions 的 GitHub 仓库后，发布工作流即可投入使用。当发布 GitHub Release（包括预发布版本）时，该工作流会自动运行。仅推送草稿或标签 不会发布软件包。

1. 设置软件包版本和变更日志，然后发布一个标记为 v 加上确切的 pyproject.toml 版本（例如 v0.7.0）的发布版本。
2. 该工作流会验证标签，并运行适用于 Windows/Linux/macOS 的通用 Python、 general/account-import/QR 浏览器、源代码包以及 Docker 检查。此外，还会在 这三种操作系统上使用 Python 3.12 进行全新的原生安装测试。
3. 通过上述检查后，系统会在 QEMU 环境下对 ARM64 镜像进行烟雾测试，将 AMD64/ARM64 镜像发布至 ghcr.io/<lowercase-owner>/<lowercase-repository>:<version>， 并将源代码 ZIP 包、校验和及 Python wheel 文件附加到发布包中。另有一项 Windows 任务负责构建并附加可移植 ZIP 包及其校验和。
4. 首次发布后，请打开 GHCR 包设置，并将可见性 设为“公开”（Public），以便匿名拉取图像。仅拥有公开的源代码仓库 并不能保证容器包也会公开。组织政策必须 允许发布包。该工作流使用 GITHUB_TOKEN；注册表 密码或 VPS 凭据不应存放在仓库中。

仅通过本地准备工作尚无法确保远程工作流的成功。ARM64 仿真仅为初步验证，并非原生硬件或实时 Telegram 环境的认证。 此功能可自动完成版本打包；启动服务器仍需使用 Compose 命令及其域名/主机先决条件。当新版本发布时，现有服务器不会被 自动升级或重启。

远程服务器#

请将服务限制在回环接口内并使用 SSH 隧道，或在 反向代理处终止 HTTPS 连接。基础 Compose 文件仅限本地使用；可选的 deploy/compose/compose.https.yaml 覆盖层提供 Caddy 以支持配置好的域名。 请勿在 URL 和代理日志中暴露承载令牌。反向代理应限制 请求大小和连接速率。请勿将明文 HTTP 暴露到互联网上。

deploy/ 目录中提供了 systemd、Windows 登录任务、macOS 用户代理以及 Caddy 的示例。 安装前请审查并调整其路径。 这些仅为模板，并非本地执行的平台配置。常规启动程序不会 注册任何后台服务或任务。

在 Windows 系统上，以无窗口模式启动 pythonw.exe 时，启动/服务器诊断信息将存储在 数据目录下的 logs/server.log 中（每文件 5 MiB，包含两个轮换备份）。 控制台模式启动时会保留控制台日志。两种模式下 均禁用 HTTP 访问日志记录。请将日志与数据目录一同保护，并在共享前进行审查。

重启与数据缺失#

系统会保留上次请求的监控状态。如果监控处于活动状态， 启动时将尝试重新连接并恢复所选消息源。手动暂停会清除 该意图。重启失败的情况会被记录并显示在面板中。

StringSession 保留授权状态，但不保留 Telethon 的持久化更新/实体状态。 对话记录会在启动时重新加载。Telegram/Telethon 可在运行过程中恢复部分传输中断， 但 TgWitness 不保证在进程重启后能够实现持久化重放。 每次启动时都会记录前一日志头和离线边界。 监视器每 10 秒检查一次连接状态，并每分钟添加一次心跳信号 （参数 → 存活记录间隔）。 短暂的中断可能被忽略；连接的传输通道并不能保证 更新的完整交付。快照是明确的当前历史观察结果，绝非缺失数据的修复。

媒体队列存储在每个工作区的 SQLite 数据库中。一条消息及其对应任务 将以原子方式提交。中断的运行任务将在启动时恢复并重试。 每次下载的基本超时时间为 120 秒，外加按 256 KiB/s 速率计算的文件大小所需时间，且 每种附件类型有 1–2,000 MiB 的限制；超时、速度和重试次数可在“参数”中设置。收集器 会跳过大小未知的文件。暂停操作会保留队列中的任务。 重试使用原始的 已观察到的文件描述符，绝不会使用后续编辑消息的最新版本。 临时故障的重试次数有限；媒体 FloodWait 暂停状态在重启后仍会保留。 媒体恢复与 Telegram 更新恢复是分开的，无法重建已消失的文件。

备份、恢复与容量#

在复制整个数据目录（包括 vault.key、 signing.enc、credentials.enc、SQLite 数据库/WAL 文件、媒体文件、令牌、检查点 以及所有配置文件/子目录）之前，请先停止该进程。 在目标服务停止运行时 还原 完整的副本。若保险库密钥缺失或 签名密钥不匹配，将导致启动失败；请勿通过重新生成密钥来强行访问。

请将秘密备份加密并设置访问控制。证据 ZIP 文件便于携带， 用于审查证据文件，而非应用程序备份或 Telegram 会话备份。 本工具不支持自动保留和删除功能。请预留足够的磁盘空间，以存储所有消息、原始 元数据、媒体文件、临时导出文件及备份。

启动验证并导出流记录，而非加载整个日志。 导出操作会锁定已读快照，同时新的 WAL 写入仍可继续；长时间运行的导出 会保留 WAL 页面，因此磁盘容量依然重要。ZIP 文件的上限为 4 GiB （解压后），以匹配独立验证器的默认设置； 通过“参数 → 最大签名 ZIP” 可提高上限，此类归档文件将使用 verify.py --max-gib N 进行验证。其他格式没有事件计数上限。 支持的浏览器会将响应块流式传输到用户选定的文件中。其他浏览器 最多缓冲 128 MiB，并将更大的传输引导至经过身份验证的 CLI：

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

若要使用其他工作区，请从“导出”→“工作区 ID”中选用 --profile ID； 若要连接远程服务器，请选用 --format zip|jsonl|csv|html 或 --url https://your-server； 若要更改 5 GiB 的传输限制，请选用 --max-mib。仅允许在 回环连接中使用纯文本 HTTP。令牌通过请求头传输，拒绝重定向，现有文件 不会被覆盖，且未完成的下载不会作为已完成文件发布。 如果 TGWITNESS_TOKEN 覆盖了生成的令牌，请使用一个单独受保护的文件 来存储该有效值：panel-token.txt 不会被覆盖操作重写。 该命令的 SHA-256 仅作为传输校验和；请独立验证已签名的 ZIP 文件。

服务器导出文件仍保存在每个工作区的私有temporary-exports/中。 成功导出的文件将被清理。中断的导出文件将在 下次工作区启动时被移除，届时该工作区将保持其专属实例锁定状态。该目录属于 存储威胁/容量模型的一部分；请使用加密数据卷。生产级 的数吉字节级数据传输仍需在目标系统上进行兼容性测试。

该面板显示队列中/失败的媒体文件、最旧的待处理媒体文件、可用磁盘空间、Telegram 请求暂停情况，以及访问状态未确认的来源。这些诊断信息并非 完整的端到端交付监控。工作区共享一个进程；一个活动频繁的账户仍可能 影响其他工作区。 独立的工作进程、数据保留/轮换、持久化更新 恢复以及完整的部署认证功能依然存在。控制面板的范围访问权限已在 “访问与权限”部分中记录；独立检查点相关内容详见《 见证指南》。

连接与保护选项#

连接路径按工作区设置，应在授权前进行配置。 SOCKS5/HTTP CONNECT 使用固定的 python-socks 依赖项。MTProxy 使用 Telethon 的 实验性随机中间传输协议；不支持 Fake TLS ee 密钥。 直接回退取决于所选的 IP 模式：“隐藏 IP”模式不允许直接回退；显式回退模式在延迟后允许直接回退；隧道/VPN 模式允许直接路由，但不会建立 VPN。这并非全系统范围的网络策略。

对于新安装，TGWITNESS_VAULT_KEY_FILE 应指向一个单独受保护的随机 主密钥文件。请在容器外的 /data 目录下以只读方式挂载该文件。请将每个工作区的 vault.external.json 公开盐元数据与主密钥分别妥善保存。 现有本地保险库需要进行有计划的迁移；设置此变量不会 自动将其转换。消息/媒体存储和导出内容未经过应用程序加密。 请根据需要使用加密卷和足够的私有临时存储空间。

详细操作流程：连接/安全设置及 运行模式。