Tham khảo / Thiết lập
Telegram · Hướng dẫn bắt đầu nhanh
Tất cả các phương thức cài đặt và khởi chạy TgWitness: gói phần mềm dành cho Windows, Python, Docker và bản demo tổng hợp, kèm theo các bước kiểm tra ban đầu.
Tiếng Anh · Tiếng Nga · Tiếng Ukraina · Tiếng Tây Ban Nha · Tiếng Bồ Đào Nha (Brazil) · Tiếng Thổ Nhĩ Kỳ · Tiếng Ả Rập · Tiếng Ba Tư · Tiếng Urdu · Tiếng Hindi · Tiếng Indonesia · Tiếng Việt · Tiếng Trung giản thể
TgWitness là một ứng dụng độc lập dùng để theo dõi các nhóm và kênh Telegram mà tài khoản của quý vị có quyền truy cập. Ứng dụng này chạy cục bộ với thư mục dữ liệu riêng.
Lần đầu truy cập? Hãy khám phá bản demo trước khi kết nối tài khoản. Chọn hướng dẫn về proxy, nhân chứng, xuất dữ liệu hoặc thiết lập máy chủ. GitHub Actions capture (bản xem trước) thực thi quá trình capture trong chi nhánh GitHub của riêng bạn thay vì cài đặt cục bộ.
Cài đặt và bắt đầu#
Trình cài đặt có hướng dẫn đi kèm với Python riêng và kiểm tra băm gói cũng như chữ ký bản phát hành trước khi cài đặt. Chạy lại trình cài đặt này sẽ cập nhật bản cài đặt hiện có.
Linux / macOS:
curl -fsSL https://get.destroy.tools/install.sh | bash
Windows (PowerShell hoặc Command Prompt):
powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex"
Trên máy chủ Ubuntu, hãy chạy với quyền root để cài đặt dịch vụ chạy nền; trên máy tính để bàn, hãy chạy với tư cách người dùng thông thường. Trên Ubuntu, trình cài đặt sẽ hiển thị địa chỉ bảng điều khiển và khóa truy cập; trên macOS và Windows, bảng điều khiển cục bộ sẽ mở trong trình duyệt của bạn. Tiếp tục tại phần Kết nối Telegram bên dưới. Phần Cài đặt, xác minh và cập nhật bao gồm các tùy chọn truy cập máy chủ, kiểm tra tập lệnh trước khi chạy, cập nhật và gỡ bỏ.
Các phương pháp khác#
Các bản phát hành trên GitHub, mã nguồn và Docker là các lựa chọn thay thế cho trình cài đặt. Các bản tải xuống di động sẽ có sẵn sau khi bản dựng phát hành được công bố:
| Máy chủ | Không cần cài đặt bất kỳ phần mềm nào | Từ nguồn: Python 3.11 trở lên | Docker: Engine/Desktop với Compose 2.20 trở lên |
|---|---|---|---|
| Windows | Trích xuất tệp TgWitness-<version>-windows-amd64-portable.zip từ GitHub Releases, nhấp đúp vào tệp TgWitness.cmd |
Nhấp đúp vào Start.cmd |
Nhấp đúp vào scripts\Docker.cmd |
| Linux / macOS | — | sh start.sh |
sh scripts/docker-start.sh |
Đối với các phương pháp dùng mã nguồn, hãy tải xuống và giải nén nhánh main hiện tại
hoặc sao chép (clone) kho lưu trữ:
git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness
Start.cmd đề xuất cài đặt Python 3.12 cho người dùng Windows của bạn nếu không
tìm thấy Python phù hợp (qua winget, hoặc trình cài đặt có chữ ký số từ python.org). start.sh sẽ in ra
lệnh cài đặt chính xác cho bản phân phối Linux hoặc macOS của bạn nếu thiếu Python.
Lần khởi chạy từ mã nguồn đầu tiên sẽ tự động tạo .venv và cài đặt các gói phụ thuộc.
Docker sẽ biên dịch ứng dụng và khởi chạy nó ở chế độ nền; không cần phải cài đặt Python trên máy chủ.
scripts\Docker.cmd và scripts/docker-start.sh sẽ hiển thị địa chỉ bảng điều khiển và mã thông báo khi
container hoạt động bình thường. Các lệnh Docker tương ứng trên mọi hệ điều hành được hỗ trợ là:
docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt
Mở trang http://127.0.0.1:8787. Sử dụng mã thông báo được tạo bởi trình trợ giúp Docker hoặc lệnh Docker thứ hai, hoặc truy cập tệp data/live/panel-token.txt đối với bản cài đặt di động hoặc từ nguồn. Tiếp tục tại phần “Kết nối Telegram” bên dưới. Các bản cài đặt gốc và Docker sử dụng bộ nhớ lưu trữ riêng biệt; việc khởi động Docker sẽ không nhập nhật ký gốc hiện có.
Đối với máy chủ, quá trình triển khai bao gồm kích hoạt HTTPS tự động, khởi động lại hệ thống, các hình ảnh được công bố, các bản cập nhật và sao lưu.
Khám phá giao diện#
- Vui lòng chạy tệp
`TgWitness-Demo.cmd`
trong gói di động, tệp `scripts\Demo.cmd`
trong thư mục nguồn của Windows
hoặc tệp `
sh start.sh --demo` trên hệ điều hành Linux/macOS. Khi khởi chạy từ nguồn, hệ thống sẽ tự động tạo tệp `.venv` và cài đặt các thành phần phụ thuộc. - Truy cập http://127.0.0.1:8787.
- Bản demo cục bộ sẽ tự động mở sổ nhật ký mẫu. Không cần sao chép mã thông báo để truy cập trực tiếp tại địa phương.
Các tin nhắn trong phần demo là hư cấu. Chế độ demo không thể kết nối với tài khoản Telegram thực tế.
Kết nối với Telegram#
[!CẢNH BÁO] Sử dụng các tài khoản chuyên dụng. Telegram có thể hạn chế hoặc cấm vĩnh viễn các tài khoản do lượng yêu cầu mà họ coi là quá mức, bất kể khách hàng là ai. Hãy kết nối các tài khoản được chuẩn bị sẵn cho việc quan sát thay vì các tài khoản cá nhân hoặc có giá trị, và tạo ID API / băm trên một tài khoản chuyên dụng.
- Nếu bản demo gốc đang chạy, hãy dừng nó lại và chạy tệp Start.cmd hoặc
sh start.sh. Nếu không, hãy tiếp tục chạy bản cài đặt trực tiếp đã được khởi động ở trên. - Sử dụng mã thông báo bảng điều khiển để đăng nhập. Một không gian làm việc mới sẽ mở ra để thực hiện thiết lập ban đầu. Chọn Chỉ tải xuống, Theo dõi các cuộc trò chuyện hoặc Bằng chứng cho một vụ việc.
- Kiểm tra lại kết nối. Cấu hình proxy của riêng bạn nếu cần; các cài đặt kết nối vẫn có sẵn sau khi thiết lập.
- Tại Connect Telegram, hãy chọn số điện thoại, mã QR, tệp tài khoản (TData,
.session, StringSession, tệp JSON tài khoản) hoặc một khóa ủy quyền hoàn chỉnh. Vui lòng hoàn tất xác nhận Telegram, nhập mã và mật khẩu xác thực hai bước khi được yêu cầu. - Kiểm tra tài khoản được hiển thị, chọn các cuộc trò chuyện và xem lại cài đặt của bạn. Hoàn tất từ màn hình cuối cùng. Đối với tùy chọn Chỉ tải xuống, Bắt đầu xuất sẽ khởi động quá trình xuất một lần và mở phần Xuất để hiển thị tiến trình; tùy chọn này không kích hoạt tính năng quan sát liên tục.
Sau khi thiết lập, mục Chats → Choose sẽ thay đổi các cuộc trò chuyện đã chọn. Cài đặt điều khiển việc thu thập và tệp tin; More tools → Sources cung cấp danh sách nguồn chi tiết ở mức Standard hoặc Expert. Hướng dẫn bảng điều khiển mô tả sáu phần chính và các điều khiển theo ngữ cảnh của chúng.
API ID + Hash là tùy chọn: không gian làm việc sử dụng cặp đã lưu hoặc nhập sẵn,
hoặc một cặp hoạt động từ nhóm tích hợp sẵn. Để sử dụng ứng dụng của riêng bạn, hãy dán một
cặp API ID:API Hash vào trường API ID. Đối với khóa xác thực (Auth key), hãy dán toàn bộ 512 ký tự thập lục phân
và chọn DC ID được cung cấp. ID người dùng là tùy chọn và sẽ được kiểm tra nếu được nhập.
Thông tin đăng nhập API dùng để xác định ứng dụng của quý vị; chúng không tự động cấp quyền truy cập cho tài khoản nào cả. Các nhóm riêng tư không yêu cầu tên người dùng công khai, nhưng tài khoản của quý vị phải có quyền truy cập.
Đối với các tài khoản hiện có, hãy xem các định dạng tài khoản và phiên: bảng điều khiển hỗ trợ Telethon StringSession, Telethon/Pyrogram SQLite, TData ZIP cho một tài khoản duy nhất và định dạng JSON tài khoản được hỗ trợ. Chọn một phiên cùng với tệp JSON đi kèm, nhấn Kiểm tra tệp, sau đó nhấn Kết nối tài khoản. Đăng nhập qua mã QR cũng có sẵn với các cài đặt API tùy chọn tương tự. TDLib, phiên bot và danh sách tài khoản CSV/JSON không được hỗ trợ.
Đối với nhiều tài khoản, hãy sử dụng Tài khoản → Nhập tài khoản và chọn các tệp phiên được hỗ trợ của chúng. Các tệp JSON đi kèm được ghép nối theo tên cơ sở (basename); mỗi tài khoản được nhập sẽ có không gian làm việc riêng. Xem nhập hàng loạt và nhóm tài khoản.
Để thêm một tài khoản khác, nhấn vào biểu tượng + bên cạnh trình chọn tài khoản hoặc sử dụng Tài khoản → Thêm tài khoản. Các không gian làm việc có các phiên, nhật ký, khóa, nguồn và hàng đợi riêng biệt. Việc chuyển đổi chế độ xem sẽ không làm gián đoạn hoạt động của các bộ thu khác. Cùng một tài khoản Telegram không thể được gán cho hai không gian làm việc trong cài đặt này. Không có số lượng cố định cho các không gian làm việc; chúng chia sẻ chung một tiến trình, do đó dung lượng phụ thuộc vào máy tính.
Mã thông báo bảng điều khiển trực tiếp bảo vệ quyền truy cập vào các thông tin ủy quyền Telegram và tài liệu đã lưu trữ
của quý vị; mã này tách biệt với thông tin đăng nhập API của Telegram. Chỉ bản demo cục bộ được khởi chạy rõ ràng và
truy cập trực tiếp mới được cấp quyền truy cập tự động. Bản demo từ xa hoặc qua proxy vẫn sử dụng mã
data/demo/panel-token.txt.
Xem lại và xuất dữ liệu#
- Sổ nhật ký: tìm kiếm và lọc các ghi nhận theo nguồn và loại sự kiện.
- Vui lòng chọn một sự kiện để xem bản ghi gốc, thông tin nguồn gốc và các phiên bản đã lưu của sự kiện đó.
- Chi tiết chỉnh sửa hiển thị nội dung trước và sau khi chỉnh sửa (nếu có). Chi tiết xóa hiển thị nội dung được ghi lại lần cuối (nếu có); đối tượng không xác định vẫn được giữ nguyên trạng thái không xác định.
- Các định dạng xuất: tệp ZIP có chữ ký, JSONL, CSV và HTML ngoại tuyến.
- Xuất toàn bộ cuộc trò chuyện (Chats → Export chat, hoặc Exports → Capture or export one
chat): tải xuống toàn bộ lịch sử hiển thị
của một cuộc trò chuyện dưới dạng gói đã ký kèm tệp
chat.json(theo phong cách xuất Telegram) và tệpchat.htmlcó thể đọc được. Các cuộc trò chuyện riêng tư hoạt động khi tài khoản là thành viên. Đây là bản chụp nhanh hiện tại, không phải bản tái tạo các tin nhắn đã xóa hoặc đã chỉnh sửa trước đó. Xác minh bản sao bằng lệnhpython verify.py chat-export.zip --fingerprint TRUSTED_SHA256. - Lưu điểm kiểm tra: duy trì ranh giới của sổ nhật ký đã được ký số bên ngoài bộ thu thập dữ liệu.
- Tải xuống biên nhận thực thi có chữ ký: lưu giữ bản ghi chương trình/phiên bản của bộ thu thập dữ liệu.
- Chuẩn bị yêu cầu dấu thời gian: chuẩn bị một yêu cầu ngoại tuyến gửi đến cơ quan cấp dấu thời gian; thực hiện theo hướng dẫn trong tệp TIMESTAMP.md để nhận và xác minh phản hồi.
- Xác minh nhật ký: kiểm tra chữ ký sự kiện và các liên kết trong chuỗi. Tính năng xuất dưới dạng ZIP cũng kiểm tra các tệp phương tiện.
Các trình duyệt được hỗ trợ có thể lưu trực tiếp các tệp xuất có dung lượng lớn vào tệp đã chọn. Các trình duyệt khác chỉ có thể lưu tạm tối đa 128 MiB. Trong khi máy chủ đang hoạt động, giao diện dòng lệnh (CLI) truyền trực tiếp hỗ trợ tải xuống các tệp có dung lượng lớn hơn mà không cần lưu tạm toàn bộ phản hồi:
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
Đối với không gian làm việc khác, thêm --profile ID bằng cách sử dụng Exports → Workspace ID.
Đối với máy chủ từ xa, thêm --url https://your-server. Giới hạn truyền tải mặc định là
5 GiB; --max-mib thay đổi giới hạn này. Nội dung ZIP đã ký có giới hạn xác minh riêng là 4 GiB khi giải nén
theo mặc định (More tools → Parameters cho phép tăng giới hạn này; xác minh các tệp lưu trữ này bằng
verify.py --max-gib N). Xác minh tệp lưu trữ bằng cách sử dụng bản sao đáng tin cậy của công cụ xác minh,
dấu vân tay khóa được lưu giữ độc lập và, để đảm bảo bằng chứng tối thiểu, chứng chỉ gốc của
cơ quan cấp dấu thời gian (--tsa-ca).
Xem hướng dẫn cài đặt#
python start.py --setup-only
python start.py --check
python start.py --check --json
--check kiểm tra các phụ thuộc cục bộ, hỗ trợ ký số, bộ nhớ lưu trữ, cấu hình khóa và
địa chỉ lắng nghe. Công cụ này không cài đặt bất kỳ thành phần nào cũng như không kết nối với Telegram. Nếu cổng
đang bận, điều này có thể cho thấy một phiên bản khác đang chạy. Vui lòng sử dụng --port khác hoặc dừng phiên bản hiện tại trước.
Trình khởi chạy sẽ được cài đặt vào thư mục .venv. Các lệnh phụ trợ python -m tgwitness... phải
sử dụng .venv\Scripts\python.exe trên Windows hoặc .venv/bin/python trên Linux/macOS,
trừ khi môi trường đó đã được kích hoạt sẵn.
Các phiên làm việc, biện pháp bảo vệ và quy trình vận hành#
Một tệp .session của Telethon SQLite đóng và nhất quán có thể được chuyển đổi cục bộ bằng lệnh
python -m tgwitness.sessions account.session --out account.tgwitness-session, sau đó
tải lên tại Công cụ khác → Tài khoản → Tệp. Tính năng nhập tệp trực tiếp và đăng nhập qua mã QR cũng có sẵn. Xem
tệp CONNECTION-SECURITY.md để biết các định dạng đăng nhập, SOCKS5,
HTTP CONNECT, MTProxy và khóa chính bên ngoài.
Tạm dừng quan sát sẽ ngừng quá trình thu thập. Chế độ Khóa chỉ chặn quyền truy cập trình duyệt. Đóng tab sẽ không làm dừng quá trình thu thập. Việc dừng quá trình này mới thực sự ngắt quá trình thu thập; bản chụp lịch sử không thể tái tạo lại toàn bộ các thao tác chỉnh sửa hoặc xóa đã bỏ lỡ. Xem cách thức hoạt động của quá trình thu thập đối với các chính sách sự kiện, hàng đợi tệp đính kèm, cách ly tài khoản và hành vi khởi động lại.
Các phiên và thông tin bí mật được mã hóa. Nội dung tin nhắn, phương tiện truyền thông và các tệp xuất ra yêu cầu một đĩa hoặc khối lượng dữ liệu được mã hóa. Xác minh chữ ký nhật ký so với một khóa đáng tin cậy và lưu trữ các điểm kiểm tra riêng biệt. Xem xét các bản ghi thu thập, biên nhận thời gian bên ngoài và chứng nhận môi trường cho chế độ thu thập đã chọn.
Vui lòng tham khảo tệp OPERATIONS.md để biết thông tin về sao lưu/khôi phục, tệp DEPLOYMENT.md
về việc triển khai máy chủ, và thư mục deploy/ để xem các ví dụ về dịch vụ. Bảng điều khiển đã cài đặt
cũng bao gồm hướng dẫn thiết lập ngoại tuyến tại /guide.html.
Quá trình xác minh thực tế và các giới hạn hiện còn tồn tại được ghi chép trong các tệp VERIFICATION.md và READINESS.md.