参考 / 设置
Telegram · 部署
可在 Windows、Linux、macOS 或 Docker 环境中将 TgWitness 作为服务运行,通过 HTTPS 访问,并支持备份和更新。
英语 · 俄语 · 乌克兰语 · 西班牙语 · 葡萄牙语(巴西) · 土耳其语 · 阿拉伯语 · فارسی · 乌尔都语 · हिन्दी · 印尼语 · 越南语 · 简体中文
选择安装方式#
若使用便携包,请从
GitHub Releases 解压 TgWitness-<version>-windows-amd64-portable.zip。若采用其他方法,请下载并解压源代码 ZIP 文件或克隆
代码库,然后在项目目录下运行以下命令:
| 安装 | 开始 | 在后台运行吗? |
|---|---|---|
| Windows 便携版 | TgWitness.cmd |
不;请保持窗口打开。 |
| 原生 Windows 版 | Start.cmd |
不;请使用可选的登录任务以实现后台运行。 |
| 原生支持 Linux/macOS | sh start.sh |
不;请使用 systemd/launchd 进行后台运行。 |
| 在任何受支持的主机上运行 Docker | docker compose up -d --build --wait |
是的,只要 Docker 守护进程正在运行。 |
| Windows 版 Docker 辅助工具 | scripts\Docker.cmd |
是的;该辅助程序会等待 Web 服务器的运行状态。 |
| Linux/macOS 上的 Docker 辅助工具 | sh scripts/docker-start.sh |
是的;该辅助程序会等待 Web 服务器的运行状态。 |
关于第三方应能进行核查的云服务器——该服务器通过 服务商的 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。
本地计算机#
在 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 及其固定依赖项,
以及三个启动器:
| 文件 | 目的 |
|---|---|
TgWitness.cmd |
启动面板;额外选项将被直接传递,例如 TgWitness.cmd --port 8790 |
TgWitness-Demo.cmd |
在 data\demo 启动合成演示 |
TgWitness-Check.cmd |
在不启动的情况下运行就绪性检查 |
已将固定的俄语形态学词典和 PDF 颜色配置文件打包,以便
离线使用。打包仅允许在依赖项
data 目录内包含其已知的文件路径;若这些目录中出现意外文件,将导致构建失败。
将整个压缩包解压到可写入的文件夹中,例如 Documents\TgWitness;请勿
在 ZIP 文件内部或 Program Files 文件夹中运行该程序。运行时使用隔离的模块路径,
因此其他 Python 安装以及 PYTHONPATH 均不会对其产生影响。 数据保存在
该软件包的data文件夹中。若需更新,请停止 TgWitness,将新版本解压到一个新的
文件夹中,然后将data文件夹复制过去。
在 64 位 Windows 系统上使用 Python 3.12 自行构建:
python tools/build_portable.py
容器#
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。导出构建
改在持久化分区 /data 上使用每个工作区的 temporary-exports/ 目录。请在此处预留空间
以满足同时进行的导出操作、日志/WAL 增长、媒体文件及备份的需求。
启动器使用 deploy/constraints.txt 来锁定符合条件的运行时依赖项版本。
Docker 和高保障服务器根据 deploy/requirements.lock 和
deploy/build.lock 文件,使用 pip --require-hashes 进行安装:每个包文件必须与提交记录中的 SHA-256
值相匹配,因此若 PyPI 或镜像站点上的文件被替换,则会被拒绝。 仅提供源代码的
包(如 jieba、pyaes)由启动器、Windows 可移植构建器及 Dockerfile
使用 deploy/build.lock 中锁定的 setuptools(--no-build-isolation)进行构建,
因此 pip 不会解析一个单独的、未锁定的构建环境。 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
地址;该文件仅包含见证文件。
安装已发布的镜像#
将 deploy/env.example 复制到 .env。将 TGWITNESS_IMAGE 设置为发布版本,使用
小写形式的仓库路径,例如:
TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.9.3
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 并输入面板令牌。准备就绪性
涵盖容器;证书签发和外部可达性取决于 DNS
和防火墙。如果 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。
在更新后检查面板访问权限、账户身份、观察状态及覆盖范围。 重启后,TgWitness将恢复保存的Telegram更新位置,并 请求更新过程中遗漏的更新内容。如果未来版本更改了存储格式, 回滚可能需要使用更新前的备份。
远程服务器#
请将服务限制在回环接口内并使用 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 访问日志记录。请将日志与数据目录一同保护,并在共享前进行审查。
重启与数据缺失#
系统会保留上次请求的监控状态。如果监控处于活动状态, 启动时将尝试重新连接并恢复所选消息源。手动暂停会清除 该意图。重启失败的情况会被记录并显示在面板中。
TgWitness 将该账户及每个频道的 Telegram 更新位置 (pts、qts、seq 和 date)存储在工作区保险库中,并在下次启动时恢复。 随后,客户端会请求进程停止期间错过的更新,而 定期重新检查会恢复错过的消息,并记录 Telegram 已不再 返回的已保存消息。对话框会在启动时重新加载。 每次启动都会记录上一次的 日志头、离线边界以及恢复时的更新位置。 监控程序每10秒检查一次连接状态,并每分钟发送一次心跳 (更多工具 → 参数 → 每隔一次记录活跃状态)。 断开连接和静默期将作为覆盖缺口记录,并附带原因说明。 历史快照作为独立的当前历史观测结果,与实时记录并存。
媒体队列存储在每个工作区的 SQLite 数据库中。消息及其任务 将原子提交。中断的运行中任务将在启动时恢复并重试。 每次下载有120秒的基础超时,外加按256 KiB/s 速率计算的文件大小所需时间,以及 每种附件类型有 1–2,000 MiB 的限制;超时、速度和重试设置位于更多工具 → 参数中。收集器 会跳过大小未知的文件。暂停操作会保留队列中的任务。重试使用原始的 已观察到的文件描述符,绝不会使用后续编辑消息的最新版本。 临时故障有重试次数限制;媒体 FloodWait 暂停状态在重启后仍会保留。 媒体恢复与 Telegram 更新恢复是分开的,无法重建已消失的文件。
备份、恢复与容量#
tgwitness backup FOLDER
会在控制面板持续运行的同时复制数据目录:
先复制检查点,然后通过在线备份 API 复制 SQLite 文件,接着复制键、媒体和
配置文件,因此任何被复制的检查点都不会比被复制的日志更新。backup-manifest.json
列出了每个文件的 SHA-256 值以及日志头。 要恢复,请停止 TgWitness 并用该文件夹替换
整个数据目录。下次启动时会记录日志是从较旧的副本中恢复的
。该记录会将日志与存储在
TGWITNESS_STATE_DIR
中的日志头进行比较,该目录位于数据目录之外:即
Compose 中的 tgwitness-state
卷、systemd 单元中的 /var/lib/tgwitness-state
,以及其他情况下的用户本地状态文件夹
。如果没有可写状态文件夹,则无法检测到恢复操作,日志会记录一次相关提示。
如果不执行该命令,请在复制整个数据目录(包括 vault.key、 signing.enc、credentials.enc、SQLite 数据库/WAL 文件、media、token、checkpoints 以及所有 profiles/ 子目录)之前停止该进程。 在目标服务停止运行时 还原完整的副本。若保险库密钥缺失或 签名密钥不匹配,将导致启动失败;请勿通过重新生成密钥来强制访问。
请将秘密备份加密并设置访问控制。证据 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 文件。
该面板显示队列中/失败的媒体文件、最旧的待处理媒体文件、可用磁盘空间、Telegram 请求暂停情况,以及访问状态未确认的来源。这些诊断信息并非 完整的端到端交付监控。工作区共享一个进程;一个活动频繁的账户仍可能 影响其他工作区。 独立的工作进程、数据保留/轮换、持久化更新 恢复以及完整的部署认证功能依然存在。控制面板的范围访问权限已在 “访问与权限”部分中记录;独立检查点相关内容详见《 见证指南》。