Tham khảo / Thiết lập
Telegram · Triển khai
Vui lòng chạy TgWitness dưới dạng dịch vụ trên Windows, Linux, macOS hoặc Docker, thông qua kết nối HTTPS, kèm theo tính năng sao lưu và cập nhật.
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ể
Chọn phương thức cài đặt#
Đối với gói phần mềm di động, vui lòng giải nén tệp TgWitness-<version>-windows-amd64-portable.zip từ
GitHub Releases. Đối với các phương pháp khác, vui lòng tải xuống và giải nén tệp ZIP nguồn hoặc sao chép
kho lưu trữ, sau đó thực thi lệnh sau từ thư mục dự án:
| Cài đặt | Bắt đầu | Công cụ này có chạy ngầm không? |
|---|---|---|
| Gói phần mềm di động dành cho Windows | TgWitness.cmd |
Không; hãy giữ cửa sổ mở. |
| Phiên bản dành riêng cho Windows | Start.cmd |
Không; hãy sử dụng tác vụ đăng nhập tùy chọn để chạy nền. |
| Hỗ trợ bản địa trên Linux/macOS | sh start.sh |
Không; hãy sử dụng systemd/launchd để chạy nền. |
| Docker trên bất kỳ máy chủ nào được hỗ trợ | docker compose up -d --build --wait |
Đúng vậy, miễn là daemon Docker vẫn đang chạy. |
| Trợ lý Docker trên Windows | scripts\Docker.cmd |
Đúng vậy; trình trợ giúp sẽ chờ kiểm tra tình trạng hoạt động của máy chủ web. |
| Trợ lý Docker trên Linux/macOS | sh scripts/docker-start.sh |
Đúng vậy; trình trợ giúp sẽ chờ kiểm tra tình trạng hoạt động của máy chủ web. |
Đối với máy chủ đám mây mà bên thứ ba có thể kiểm tra — được tạo thông qua API của nhà cung cấp, không sử dụng SSH và chỉ có thể truy cập qua Cloudflare Tunnel — xin tham khảo phần triển khai có độ tin cậy cao.
Quá trình khởi động gốc sẽ tạo ra một bản .venv riêng tư và cài đặt các phụ thuộc đã được ghim sẵn.
Docker sẽ xây dựng chúng bên trong hình ảnh, mà không cần Python trên máy chủ. Lần
cài đặt đầu tiên cần có kết nối Internet. Khi không tìm thấy Python 3.11 trở lên, Start.cmd sẽ hỏi ý kiến người dùng trước khi
cài đặt Python 3.12 cho người dùng Windows hiện tại (sử dụng winget, hoặc trình cài đặt từ python.org
sau khi xác minh chữ ký của Python Software Foundation); công cụ này tuyệt đối không yêu cầu
quyền quản trị viên. Docker và các dịch vụ hệ điều hành vẫn là các điều kiện tiên quyết.
Các bản cài đặt gốc và di động sử dụng data/live bên trong thư mục của chúng. Docker sử dụng khối lượng có tên tgwitness-data
tại /data. Đây là các bản cài đặt riêng biệt cho đến khi quý vị chủ động di chuyển
toàn bộ thư mục dữ liệu. Xin lưu ý rằng một container Docker mới sẽ không tự động phát hiện
các tài khoản gốc.
Yêu cầu cài đặt#
Việc cài đặt bản gốc yêu cầu Python 3.11 trở lên cùng với venv và ensurepip, kết nối Internet
để cài đặt các phụ thuộc ban đầu, và một thư mục dự án có quyền ghi cho
.venv. Bảng điều khiển đi kèm không cần Node.js hay quá trình xây dựng giao diện người dùng. Vui lòng chạy trình khởi chạy từ
tài khoản hệ điều hành thông thường của quý vị; TgWitness không yêu cầu quyền quản trị viên/root.
- Hệ điều hành Windows:
Start.cmdsẽ kiểm tra thư mụcpy -3, sau đó làpython, tiếp theo là thư mục cài đặt mặc định theo từng người dùng và thư mục Program Files, đồng thời yêu cầu phiên bản 3.11 trở lên. Nếu không có thư mục nào phù hợp, chương trình sẽ đề xuất phương án cài đặt tự động theo từng người dùng như đã mô tả ở trên.py -3 start.pycũng hoạt động được. Gói phần mềm di động hoàn toàn không cần Python. - Linux:
start.shsẽ thử các phiên bảnpython3.13,python3.12,python3.11,python3vàpython, đồng thời hiển thị lệnh cài đặt tương ứng cho apt, dnf, pacman, zypper, apk hoặc Homebrew nếu không có phiên bản nào đáp ứng yêu cầu. Các hệ thống Debian/Ubuntu có thể cần góipython3-venvtương thích với trình thông dịch đã chọn. Phiên bản Python mặc định cũ hơn của hệ điều hành phân phối đó phải được thay thế hoặc bổ sung bằng Python 3.11 trở lên. - macOS: hãy cài đặt bản phân phối Python 3.11+ mới nhất; không nên cho rằng trình thông dịch do hệ điều hành cung cấp
đáp ứng yêu cầu. Vui lòng sử dụng tệp
python3 start.pytừ thư mục dự án. - Docker: sử dụng Docker Engine/Desktop với Compose phiên bản 2.20 trở lên. Docker Desktop phải sử dụng các container Linux trên Windows. Container sẽ tự cài đặt các thành phần phụ thuộc Python của riêng mình; máy chủ không cần cài đặt Python riêng biệt.
Máy tính cục bộ#
Vui lòng sử dụng Start.cmd trên Windows hoặc sh start.sh trên Linux/macOS. scripts\Setup.cmd hoặc
sh start.sh --setup-only sẽ tiến hành
chuẩn bị môi trường. Trình khởi chạy sẽ cài đặt các thành phần phụ thuộc khi sử dụng lần đầu; các lần khởi chạy sau đó
sẽ tái sử dụng môi trường đã có sẵn. Cần có kết nối Internet để thiết lập và thu thập dữ liệu từ Telegram,
tuy nhiên, việc duyệt qua các bản ghi hiện có và tạo tệp xuất vẫn có thể thực hiện ngoại tuyến.
Vui lòng chạy lệnh `python start.py --check` sau khi thiết lập để kiểm tra các phụ thuộc cục bộ, Ed25519,
bộ nhớ lưu trữ, cấu hình khóa và địa chỉ lắng nghe mà không cần khởi động trình thu thập dữ liệu.
Sử dụng lệnh --json để nhận kết quả đầu ra có cấu trúc. Chuyển các lệnh --data-dir, --host và
--port theo mục đích. Quá trình kiểm tra này không cài đặt gói phần mềm, không tạo nhật ký cũng như không kết nối với Telegram;
đây không phải là quá trình đánh giá tính toàn vẹn hay phạm vi bao phủ. Quá trình khởi động sẽ xác minh riêng biệt
các nhật ký hiện có. Lệnh python start.py --help cũng không yêu cầu cài đặt.
Sau khi chạy tệp start.py, quý vị hãy thực thi các lệnh phụ trợ bằng lệnh `.venv\Scripts\python.exe` trên
Windows hoặc `.venv/bin/python` trên Linux/macOS, hoặc kích hoạt môi trường đó trước tiên.
Các ví dụ `python -m ...` dưới đây giả định rằng môi trường đã được kích hoạt.
python -m tgwitness --data-dir /path/to/private/data --host 127.0.0.1 --port 8787
Biến môi trường: TGWITNESS_DATA, TGWITNESS_HOST, TGWITNESS_PORT, TGWITNESS_TOKEN. TGWITNESS_VAULT_KEY_FILE chọn chế độ khóa bên ngoài cho cài đặt mới; xem Khóa chính bên ngoài. TGWITNESS_TOKEN, nếu được cung cấp, phải chứa ít nhất 24 ký tự; hãy sử dụng một giá trị ngẫu nhiên được tạo bằng thuật toán mã hóa . Nếu không có biến này, ứng dụng sẽ tạo một mã thông báo ngẫu nhiên 256 bit trong tệp panel-token.txt. Việc ghi đè biến môi trường sẽ không ghi đè lên tệp đó. Khởi động lại để xoay vòng thông tin xác thực.
Chỉ có đúng một tiến trình được phép sở hữu một thư mục dữ liệu. Cơ chế khóa tệp trên nhiều nền tảng hệ điều hành sẽ ngăn chặn tình trạng ghi đồng thời vô tình xảy ra. Vui lòng sử dụng một công cụ Uvicorn. Bảng điều khiển có thể quản lý bất kỳ số lượng không gian làm việc nào, với các thư mục không gian làm việc bổ sung nằm trong thư mục profiles/<id>/. Đối với các phiên bản dịch vụ riêng biệt, hãy sử dụng các thư mục và cổng riêng biệt. Các tệp WAL của SQLite phải được lưu trữ trên bộ nhớ lưu trữ cục bộ lâu dài, chứ không phải trên hệ thống tệp mạng. Không được chia sẻ cùng một khối lưu trữ giữa các bản sao.
Gói phần mềm di động dành cho Windows#
Mỗi bản phát hành trên GitHub đều bao gồm TgWitness-<version>-windows-amd64-portable.zip và
.sha256 tương ứng. Bản phát hành này chứa phiên bản runtime Python 3.12 chính thức có thể nhúng từ python.org
(tổng kiểm tra được cố định trong tools/build_portable.py), TgWitness cùng các phụ thuộc được cố định của nó,
và ba trình khởi chạy:
| Tệp | Mục đích |
|---|---|
TgWitness.cmd |
Khởi chạy bảng điều khiển; các tùy chọn bổ sung sẽ được truyền vào, ví dụ: TgWitness.cmd --port 8790 |
TgWitness-Demo.cmd |
Khởi chạy bản demo tổng hợp tại data\demo |
TgWitness-Check.cmd |
Vui lòng thực hiện kiểm tra sẵn sàng mà không cần khởi động |
Từ điển hình thái tiếng Nga được ghim và các cấu hình màu PDF được gói sẵn để
sử dụng ngoại tuyến. Quy trình đóng gói chỉ cho phép các đường dẫn tệp đã biết bên trong các thư mục phụ thuộc
data; các tệp không mong đợi trong các thư mục đó sẽ khiến quá trình xây dựng thất bại.
Vui lòng giải nén toàn bộ tệp lưu trữ vào một thư mục có quyền ghi như Documents\TgWitness; không chạy
chương trình từ bên trong tệp ZIP hoặc từ thư mục Program Files. Môi trường chạy sử dụng đường dẫn mô-đun cách ly,
do đó các bản cài đặt Python khác và thư mục PYTHONPATH sẽ không ảnh hưởng đến nó. Dữ liệu được lưu trữ trong
thư mục data của gói phần mềm. Để cập nhật, hãy dừng TgWitness, giải nén phiên bản mới vào một
thư mục mới và sao chép thư mục data sang đó.
Tự xây dựng trên hệ điều hành Windows 64-bit bằng Python 3.12:
python tools/build_portable.py
Thùng chứa#
docker compose up -d --build --wait
Điều này tạo ra một khối lượng lưu trữ bền vững có tên cho /data.
Cổng web được ánh xạ đến 127.0.0.1:8787. Quy trình chạy với UID 10001, các
quyền hạn bị loại bỏ, hệ thống tệp gốc chỉ đọc, và các thư mục /data và /tmp có thể ghi.
--wait kiểm tra tình trạng hoạt động của máy chủ web trước khi trả về kết quả; quá trình ủy quyền và
giao nhận Telegram hiển thị trên bảng điều khiển. Các hàm trợ giúp được cung cấp sử dụng thời gian chờ sẵn sàng 180 giây
sau khi xây dựng. Việc tải xuống các phụ thuộc ban đầu có thể mất nhiều thời gian hơn mức đó.
Cả hai tệp Compose cơ sở đều sử dụng tên dự án tgwitness, do đó việc giải nén bản phát hành mới
vào một thư mục khác sẽ không tự động chọn một khối dữ liệu mới. Chỉ duy trì một
bản triển khai hoạt động cho dự án đó. Đối với các cài đặt độc lập, hãy sử dụng tên
docker compose -p NAME ... duy nhất cùng cổng máy chủ khác, và giữ nguyên cả hai khi cập nhật.
Đối với một bản triển khai cũ hơn sử dụng tên dự án khác, hãy tiếp tục sử dụng tên ban đầu
của nó cùng với -p; docker compose ls liệt kê các dự án hiện có.
Sao chép deploy/env.example vào .env và thay đổi TGWITNESS_PORT để sử dụng một cổng loopback
khác. Ví dụ: TGWITNESS_PORT=8788 hiển thị bảng điều khiển tại
http://127.0.0.1:8788; container vẫn lắng nghe trên cổng 8787. .env bị Git bỏ qua.
Lấy mã thông báo ban đầu:
docker compose exec tgwitness cat /data/panel-token.txt
Các lệnh hữu ích:
docker compose ps
docker compose logs --tail 100 -f
docker compose stop
docker compose up -d --wait
restart: unless-stopped sẽ khởi động lại trình thu thập sau khi xảy ra sự cố hoặc khi daemon Docker
được khởi động lại. Trên máy chủ Linux, hãy kích hoạt Docker khi khởi động bằng trình quản lý dịch vụ
của bản phân phối hệ điều hành mà quý vị đang sử dụng, thường là sudo systemctl enable --now docker. Trên Windows/macOS, hãy kích hoạt
cài đặt “khởi động khi đăng nhập” của Docker Desktop. Việc đăng xuất khỏi máy tính để bàn, chuyển sang chế độ ngủ hoặc khi daemon
có thể làm gián đoạn quá trình thu thập dữ liệu. Một container bị dừng rõ ràng sẽ vẫn
ở trạng thái dừng cho đến khi quý vị khởi động lại nó.
Trong cấu hình ví dụ, dung lượng của phân vùng /tmp được giới hạn ở mức 512 MiB. Quá trình xuất dữ liệu
sẽ sử dụng thư mục `temporary-exports/` của từng không gian làm việc trên phân vùng /data có tính bền vững thay thế. Hãy dành dung lượng
tại đó cho các tác vụ xuất dữ liệu đồng thời, sự gia tăng của nhật ký/WAL, tệp phương tiện và bản sao lưu.
Trình khởi chạy sử dụng tệp `deploy/constraints.txt` để cố định các phiên bản phụ thuộc thời gian chạy đáp ứng yêu cầu.
Các máy chủ Docker và máy chủ có độ tin cậy cao được cài đặt từ deploy/requirements.lock và
deploy/build.lock bằng lệnh pip --require-hashes: mỗi tệp gói phải khớp với mã SHA-256
được ghi lại trong commit, do đó tệp bị thay thế trên PyPI hoặc máy chủ gương sẽ bị từ chối. Các gói
chỉ cung cấp mã nguồn (jieba, pyaes) được xây dựng bằng setuptools được cố định trong deploy/build.lock
(tùy chọn --no-build-isolation) bởi trình khởi chạy, trình xây dựng di động trên Windows và tệp Dockerfile,
do đó pip không thiết lập một môi trường xây dựng riêng biệt và không được cố định. Hình ảnh cơ sở Python
và các gói hệ điều hành vẫn yêu cầu quá trình kiểm định phiên bản độc lập.
Không sử dụng lệnh `docker compose down -v` trừ khi quý vị có ý định xóa sổ nhật ký và các khóa mã hóa. Báo cáo tình trạng container phản ánh tính khả dụng của máy chủ web, chứ không phải việc ghi lại tin nhắn Telegram thành công. Kiểm tra trạng thái bộ thu thập, tín hiệu hoạt động, lỗi và các sự kiện phạm vi phủ sóng trên bảng điều khiển.
Hồ sơ nhân chứng độc lập#
Dịch vụ witness (tùy chọn) chạy một nhân chứng độc lập trong
thùng chứa riêng của nó, với khóa và nhật ký riêng trong khối lượng witness-data và chỉ có một
mã thông báo nhân chứng chỉ đọc dành cho bộ thu thập. Tạo mã thông báo trong bảng điều khiển tại More tools → Extras → Independent witness, thêm nó
cùng với mã thông báo bot và kênh vào .env, sau đó khởi động cấu hình:
docker compose --profile witness up -d # deploy/compose/compose.image.yaml: same flag
docker compose logs witness # witness key fingerprint
Dịch vụ này kết nối với bộ thu thập (collector) trong mạng Compose tại địa chỉ http://tgwitness:8787
(TGWITNESS_WITNESS_COLLECTOR
sẽ ghi đè lên địa chỉ này; ví dụ: /profiles/<workspace ID>
dành cho
một không gian làm việc khác). Đối với tệp chứng cứ (witness) trên một máy chủ riêng biệt do người khác quản lý, quý vị hãy sử dụng
deploy/compose/compose.witness.yaml
tại đó và thiết lập TGWITNESS_WITNESS_COLLECTOR
thành địa chỉ HTTPS
của bộ thu thập; tệp này chỉ chứa duy nhất tệp chứng cứ.
Cài đặt hình ảnh đã được phát hành#
Sao chép deploy/env.example vào .env. Đặt TGWITNESS_IMAGE thành phiên bản đã được phát hành, bằng cách sử dụng
đường dẫn kho lưu trữ viết thường, ví dụ:
TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.9.3
TGWITNESS_PORT=8787
Vui lòng chạy tệp này một cách độc lập, thay vì sử dụng tệp 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
Không cần xây dựng mã nguồn, Python hay trình biên dịch trên máy chủ. Quy trình phát hành
nhắm đến các container Linux AMD64 và ARM64, bao gồm cả máy ảo Linux của Docker Desktop.
Vui lòng sử dụng thẻ phiên bản hoặc mã ghcr.io/owner/repository@sha256:... từ phần tóm tắt quy trình.
Không có cấu hình nào cho việc di chuyển thẻ latest hay nâng cấp ứng dụng tự động. Các
biến thể hình ảnh và mã nguồn sẽ sử dụng cùng một khối lượng dữ liệu khi tên dự án của chúng trùng khớp.
Tự động kích hoạt HTTPS trên máy chủ#
Vui lòng sử dụng máy chủ chạy Docker, một tên miền do quý vị quản lý và bộ nhớ cục bộ lâu dài. Hướng các bản ghi A/AAAA của tên miền đến máy chủ; chỉ công bố bản ghi AAAA nếu địa chỉ IPv6 truy cập được đến máy chủ đó. Cho phép kết nối TCP 80 và 443 từ bên ngoài vào, cũng như kết nối DNS/HTTPS ra bên ngoài để cấp chứng chỉ. Các dịch vụ khác không được chiếm dụng các cổng này trước đó.
Sao chép deploy/env.example vào .env và thiết lập tên máy chủ, không kèm theo lược đồ hoặc đường dẫn:
TGWITNESS_DOMAIN=watch.your-domain.org
Bắt đầu quá trình biên dịch mã nguồn với lớp phủ 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
Đối với hình ảnh đã được đăng tải, vui lòng sử dụng deploy/compose/compose.image.yaml làm tệp đầu tiên thay thế. Hãy giữ lại
cả hai tham số -f để sử dụng cho các lệnh trạng thái, nhật ký, cập nhật và dừng sau này.
Caddy thực hiện việc lấy và gia hạn chứng chỉ, chuyển hướng HTTP sang HTTPS, đồng thời chuyển tiếp các yêu cầu đến bộ thu thập trên mạng Compose riêng tư. Trạng thái chứng chỉ có khối lượng lưu trữ riêng biệt và bền vững. Cổng máy chủ trực tiếp của bộ thu thập vẫn chỉ hoạt động ở chế độ loopback. Cấu hình Caddy được cung cấp không kích hoạt tính năng ghi nhật ký truy cập.
Mở https://watch.your-domain.org và nhập mã thông báo bảng điều khiển. Chuẩn bị sẵn sàng
bao gồm các thùng chứa; việc cấp chứng chỉ và khả năng kết nối bên ngoài phụ thuộc vào DNS
và tường lửa. Nếu HTTPS chưa sẵn sàng, hãy kiểm tra DNS, các quy tắc tường lửa và:
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml logs --tail 100 caddy
Hình ảnh Caddy được cung cấp đi kèm với thẻ 2-alpine. Việc thực hiện lệnh `pull` sẽ cập nhật hình ảnh đó;
quý vị có thể ghim một bản tóm tắt đã được kiểm thử vào môi trường triển khai của mình nếu cần sử dụng các phiên bản cơ sở hạ tầng cố định.
Cập nhật và sao lưu#
Giữ nguyên tên dự án Compose và dung lượng dữ liệu qua các bản cập nhật. Trước tiên, hãy dừng trình thu thập dữ liệu và thực hiện sao lưu toàn bộ. Đối với triển khai dựa trên nguồn mặc định:
docker compose stop
docker compose cp tgwitness:/data ../tgwitness-backup-before-update
Hãy sử dụng một đích sao lưu mới mỗi lần, nằm bên ngoài kho lưu trữ, và bảo vệ nó như tài liệu truy cập tài khoản. Đường dẫn ví dụ chỉ mang tính minh họa; quý vị hãy sử dụng vị trí sao lưu riêng tư của mình. Sao chép toàn bộ thư mục, bao gồm các tệp ẩn, tất cả không gian làm việc, khóa, sổ nhật ký và phương tiện truyền thông. Nếu đã cấu hình, hãy sao lưu riêng khóa chính của kho lưu trữ bên ngoài. Tệp ZIP chứa bằng chứng không phải là bản sao lưu ứng dụng có thể khôi phục. Đối với HTTPS, hãy lưu giữ thêm các khối lượng Caddy nếu quý vị cần duy trì trạng thái chứng chỉ/tài khoản của nó.
Để triển khai từ mã nguồn, quý vị hãy tải xuống các tệp bản phát hành mới và thực thi lệnh:
docker compose up -d --build --wait
Để triển khai phiên bản hình ảnh, quý vị hãy thay đổi TGWITNESS_IMAGE thành phiên bản mong muốn, sau đó thực thi lệnh:
docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait
Vui lòng sử dụng (các) tệp Compose của bản cài đặt của quý vị cho các lệnh dừng/sao chép nêu trên.
Hãy giữ nguyên .env, cấu hình tùy chỉnh và tên dự án như cũ. down giữ lại các
khối dữ liệu được đặt tên; down -v sẽ xóa chúng. Không sao chép .venv giữa các hệ điều hành
hoặc các phiên bản Python khác nhau. Để cập nhật bản gốc, hãy dừng TgWitness, sao lưu toàn bộ thư mục dữ liệu
của nó, thay thế các tệp nguồn và chạy python start.py --setup-only trước khi khởi động.
Kiểm tra quyền truy cập bảng điều khiển, danh tính tài khoản, trạng thái quan sát và phạm vi phủ sóng sau khi cập nhật. Sau khi khởi động lại, TgWitness sẽ tiếp tục từ vị trí cập nhật Telegram đã lưu và yêu cầu các bản cập nhật bị bỏ lỡ trong quá trình cập nhật. Việc khôi phục có thể yêu cầu bản sao lưu trước khi cập nhật nếu phiên bản tương lai thay đổi định dạng lưu trữ.
Máy chủ từ xa#
Hãy giữ dịch vụ kết nối với loopback và sử dụng đường hầm SSH, hoặc kết thúc kết nối HTTPS tại một
proxy ngược. Tệp Compose cơ bản chỉ hoạt động cục bộ; lớp phủ
deploy/compose/compose.https.yaml (tùy chọn) cung cấp Caddy cho tên miền đã được cấu hình.
Hãy đảm bảo token bearer không xuất hiện trong các URL và nhật ký proxy. Máy chủ proxy ngược nên giới hạn
kích thước yêu cầu và tần suất kết nối. Không được để HTTP thuần túy tiếp xúc với Internet.
Các ví dụ về systemd, tác vụ đăng nhập Windows, trình duyệt người dùng macOS và Caddy được cung cấp trong thư mục deploy/. Vui lòng kiểm tra và điều chỉnh các đường dẫn này trước khi cài đặt. Đây là các mẫu được cung cấp sẵn, không phải các cấu hình nền tảng được thực thi cục bộ. Không có dịch vụ nền hay tác vụ nào được đăng ký bởi trình khởi chạy thông thường.
Trên hệ điều hành Windows, khi khởi chạy pythonw.exe ở chế độ không hiển thị cửa sổ, các thông tin chẩn đoán khởi động/máy chủ sẽ được lưu trữ trong
thư mục logs/server.log thuộc thư mục dữ liệu (5 MiB mỗi tệp, kèm theo hai bản sao lưu luân phiên).
Khi khởi chạy qua giao diện dòng lệnh, hệ thống sẽ lưu lại nhật ký dòng lệnh. Tính năng ghi nhật ký truy cập HTTP bị vô hiệu hóa trong cả
hai chế độ. Quý vị cần bảo vệ các tệp nhật ký cùng với thư mục dữ liệu và kiểm tra kỹ lưỡng trước khi chia sẻ.
Khởi động lại và các khoảng trống#
Trạng thái quan sát được yêu cầu gần nhất sẽ được lưu giữ. Nếu quá trình quan sát đang hoạt động, hệ thống sẽ cố gắng kết nối lại và tiếp tục theo dõi các nguồn đã chọn khi khởi động. Việc tạm dừng thủ công sẽ xóa bỏ ý định đó. Các trường hợp khởi động lại không thành công sẽ được ghi lại và hiển thị trên bảng điều khiển.
TgWitness lưu trữ vị trí cập nhật của Telegram cho tài khoản và cho từng kênh (pts, qts, seq và date) trong kho lưu trữ không gian làm việc và khôi phục chúng khi khởi động lại. Sau đó, client yêu cầu các bản cập nhật bị bỏ lỡ trong thời gian quá trình bị dừng, và việc kiểm tra lại định kỳ sẽ khôi phục các tin nhắn bị bỏ lỡ và ghi lại những tin nhắn đã được lưu mà Telegram không còn trả về nữa. Các cuộc trò chuyện được tải lại khi khởi động. Mỗi lần khởi động đều ghi lại đầu nhật ký trước đó, ranh giới ngoại tuyến và vị trí cập nhật mà nó tiếp tục từ đó. Trình giám sát kiểm tra kết nối mỗi 10 giây và thêm tín hiệu kiểm tra kết nối mỗi phút (Công cụ khác → Thông số → Ghi lại trạng thái hoạt động mỗi). Các trường hợp ngắt kết nối và khoảng thời gian im lặng được ghi lại dưới dạng khoảng trống trong phạm vi phủ sóng kèm theo lý do. Các bản chụp lịch sử được lưu trữ dưới dạng các quan sát lịch sử hiện tại riêng biệt bên cạnh các bản ghi trực tiếp.
Hàng đợi phương tiện được lưu trữ trong cơ sở dữ liệu SQLite của từng không gian làm việc. Một tin nhắn và tác vụ của nó được cam kết nguyên tử. Các tác vụ đang chạy bị gián đoạn sẽ được khôi phục để thử lại khi khởi động. Mỗi lần tải xuống có thời gian chờ cơ bản 120 giây cộng với thời gian tính theo tốc độ 256 KiB/s dựa trên kích thước của tệp, và giới hạn 1–2,000 MiB cho mỗi loại tệp đính kèm; thời gian chờ, tốc độ và số lần thử lại được cấu hình trong Công cụ khác → Thông số. Trình thu thập sẽ bỏ qua các tệp có kích thước không xác định. Việc tạm dừng sẽ giữ nguyên các tác vụ đang xếp hàng. Quá trình thử lại sử dụng mã định danh tệp ban đầu đã quan sát được, chứ không bao giờ sử dụng phiên bản mới nhất của tin nhắn đã được chỉnh sửa sau đó. Các lỗi tạm thời có số lần thử lại giới hạn; việc tạm dừng do quá tải phương tiện (FloodWait) sẽ được duy trì sau khi khởi động lại. Việc khôi phục phương tiện là độc lập với quá trình khôi phục cập nhật Telegram và không thể tái tạo các tệp đã biến mất.
Sao lưu, khôi phục và dung lượng#
tgwitness backup FOLDER
sao chép thư mục dữ liệu trong khi bảng điều khiển vẫn tiếp tục hoạt động:
trước tiên là các điểm kiểm tra (checkpoints), sau đó là các tệp SQLite thông qua API sao lưu trực tuyến, tiếp theo là các khóa, phương tiện và
hồ sơ, do đó không có điểm kiểm tra nào được sao chép mới hơn nhật ký đã sao chép. Tệp backup-manifest.json
liệt kê mã SHA-256 của từng tệp và các đầu nhật ký. Để khôi phục, hãy dừng TgWitness và thay thế
toàn bộ thư mục dữ liệu bằng thư mục đó. Lần khởi động tiếp theo sẽ ghi nhận rằng nhật ký đã được khôi phục
từ một bản sao cũ hơn. Bản ghi này so sánh nhật ký với đầu nhật ký được lưu trữ trong
TGWITNESS_STATE_DIR
, một thư mục nằm ngoài thư mục dữ liệu: khối lượng tgwitness-state
trong
Compose, /var/lib/tgwitness-state
trong các đơn vị systemd, và thư mục trạng thái cục bộ của người dùng
trong các trường hợp khác. Nếu không có thư mục trạng thái có thể ghi, quá trình khôi phục sẽ không được phát hiện và nhật ký sẽ thông báo điều này một lần.
Nếu không có lệnh này, hãy dừng quy trình trước khi sao chép toàn bộ thư mục dữ liệu, bao gồm các tệp vault.key, signing.enc, credentials.enc, cơ sở dữ liệu SQLite và các tệp WAL, phương tiện, mã thông báo, điểm kiểm tra, cùng tất cả các thư mục con trong thư mục profiles. Khôi phục bản sao hoàn chỉnh trong khi dịch vụ đích đang bị dừng. Việc thiếu khóa vault hoặc khóa ký không khớp sẽ khiến quá trình khởi động thất bại; không được tái tạo khóa để buộc truy cập.
Hãy bảo mật các bản sao lưu bằng cách mã hóa và kiểm soát quyền truy cập. Các tệp ZIP chứa bằng chứng có tính di động cao để xem xét các bằng chứng, chứ không phải là bản sao lưu ứng dụng hay bản sao lưu phiên Telegram. Hệ thống không có tính năng xóa tự động theo thời hạn lưu trữ. Quý vị cần lên kế hoạch về dung lượng đĩa cho tất cả tin nhắn, siêu dữ liệu thô, tệp đa phương tiện, các tệp xuất tạm thời và bản sao lưu.
Bắt đầu xác minh và xuất các bản ghi luồng thay vì tải toàn bộ nhật ký.
Việc xuất dữ liệu cố định một bản chụp đọc trong khi các ghi WAL mới vẫn có thể tiếp tục; các quá trình xuất kéo dài
có thể giữ lại các trang WAL, do đó dung lượng đĩa vẫn là yếu tố quan trọng. Các tệp ZIP bị giới hạn ở 4 GiB
khi chưa nén để phù hợp với cài đặt mặc định của trình xác minh độc lập; Thêm công cụ → Thông số → Tệp ZIP có chữ ký lớn nhất
sẽ tăng giới hạn này, và các tệp lưu trữ như vậy được xác minh bằng lệnh verify.py --max-gib N. Các định dạng khác không có giới hạn về số lượng sự kiện.
Các trình duyệt được hỗ trợ truyền các khối phản hồi theo luồng vào tệp do người dùng chọn. Các trình duyệt khác
chỉ đệm tối đa 128 MiB và chuyển các tệp lớn hơn trực tiếp đến CLI đã được xác thực:
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
Sử dụng --profile ID từ mục Xuất → ID Không gian làm việc cho một không gian làm việc khác,
--format zip|jsonl|csv|html, --url https://your-server cho máy chủ từ xa, hoặc
--max-mib để thay đổi giới hạn truyền tải 5 GiB. Giao thức HTTP thuần túy chỉ được phép sử dụng cho
loopback. Các mã thông báo được truyền qua tiêu đề, các yêu cầu chuyển hướng sẽ bị từ chối, các tệp hiện có
sẽ không bị ghi đè, và các tệp tải xuống chưa hoàn tất sẽ không được công bố như các tệp đã hoàn tất.
Nếu TGWITNESS_TOKEN ghi đè lên mã thông báo đã tạo, hãy sử dụng một tệp được bảo vệ riêng biệt
chứa giá trị đang hoạt động đó: tệp panel-token.txt sẽ không bị ghi đè bởi giá trị này.
Giá trị SHA-256 của lệnh này chỉ là tổng kiểm tra truyền tải; quý vị cần xác minh độc lập tệp ZIP đã được ký.
Bảng điều khiển hiển thị các tệp đa phương tiện đang chờ xử lý/thất bại, tệp đa phương tiện đang chờ xử lý lâu nhất, dung lượng đĩa trống, các lần tạm dừng yêu cầu từ Telegram, và các nguồn chưa được xác nhận quyền truy cập. Các chẩn đoán này không phải là một công cụ giám sát việc truyền tải từ đầu đến cuối hoàn chỉnh. Các không gian làm việc chia sẻ chung một quy trình; một tài khoản gây nhiễu vẫn có thể ảnh hưởng đến những tài khoản khác. Các quy trình xử lý riêng biệt, chính sách lưu trữ/xoay vòng, khả năng phục hồi cập nhật bền vững và quy trình đánh giá triển khai đầy đủ vẫn được duy trì. Quyền truy cập bảng điều khiển theo phạm vi được ghi chép trong phần quyền truy cập và quyền hạn; các điểm kiểm tra độc lập được đề cập trong hướng dẫn dành cho nhân chứng.
Các quy trình chi tiết: kết nối/bảo mật và các chế độ hoạt động.