참고 문헌 / 설정
Telegram · 빠른 시작
TgWitness를 설치하고 실행하는 모든 방법: Windows 패키지, Python, Docker 및 종합 데모와 초기 점검 절차.
영어 · Русский · 우크라이나어 · Español · 포르투갈어 (브라질) · Türkçe · العربية · فارسی · 우르두어 · हिन्दी · 인도네시아어 · 베트남어 · 간체 중국어
TgWitness는 사용자의 계정이 접근할 수 있는 텔레그램 그룹 및 채널을 모니터링하기 위한 독립형 애플리케이션입니다. 이 애플리케이션은 자체 데이터 디렉터리를 사용하여 로컬에서 실행됩니다.
처음 방문하셨나요? 계정을 연결하기 전에 데모를 살펴보세요. 프록시, 위트니스, 내보내기 또는 서버 설정에 대한 가이드를 선택하세요. GitHub Actions 캡처(미리 보기)는 로컬 설치 대신 사용자의 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 서버에서는 루트 권한으로 실행하여 백그라운드 서비스를 설치하고, 데스크톱에서는 일반 사용자 권한으로 실행하십시오. Ubuntu에서는 설치 프로그램이 패널 주소와 액세스 키를 표시하며, macOS 및 Windows에서는 브라우저에서 로컬 패널이 열립니다. 아래의 텔레그램 연결 단계로 진행하십시오. 설치, 검증 및 업데이트 섹션에서는 서버 액세스 옵션, 실행 전 스크립트 확인, 업데이트 및 제거에 대해 다룹니다.
기타 방법#
GitHub 릴리스, 소스 코드 및 Docker는 설치 프로그램의 대안입니다. 릴리스 빌드가 게시된 후 휴대용 다운로드 파일을 이용할 수 있습니다:
| 호스트 | 설치된 항목 없음 | 출처: Python 3.11 이상 | Docker: Engine/Desktop (Compose 2.20 이상) |
|---|---|---|---|
| Windows | GitHub 릴리스에서 TgWitness-<version>-windows-amd64-portable.zip를 추출한 후, TgWitness.cmd를 더블 클릭하세요. |
Start.cmd를 더블 클릭하세요 |
scripts\Docker.cmd를 더블 클릭하세요 |
| Linux / macOS | — | sh start.sh |
sh scripts/docker-start.sh |
소스 코드 방식의 경우, 현재 main 브랜치를 다운로드하여 압축을 풀거나 저장소를 복제합니다:
git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness
Start.cmd는 적합한 Python을 찾지 못한 경우 Windows 사용자를 위해 Python 3.12 설치를 제안합니다(winget 또는 서명된 python.org 설치 프로그램). start.sh는 Python이 없는 경우 사용 중인 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 파일을 참조하십시오. 아래의 '텔레그램 연결' 단계로 진행하십시오. 네이티브 설치와 Docker 설치는 별도의 저장소를 사용하며, Docker를 시작한다고 해서 기존 네이티브 저널이 가져오지 않습니다.
서버의 경우, 배포 과정에는 자동 HTTPS 설정, 재시작, 공개된 이미지, 업데이트 및 백업이 포함됩니다.
인터페이스 살펴보기#
- 휴대용 패키지에서 TgWitness-Demo.cmd를
, Windows 소스
폴더에서 scripts\Demo.cmd를
, 또는 Linux/macOS에서
sh start.sh --demo를 실행하십시오. 소스에서 처음 실행하면.venv가 생성되고 종속성이 설치됩니다. - http://127.0.0.1:8787을 열어보세요.
- 로컬 데모를 실행하면 샘플 저널이 자동으로 열립니다. 직접 로컬에 액세스하기 위해 토큰을 복사할 필요가 없습니다.
데모 메시지는 가상의 내용입니다. 데모 모드에서는 실제 텔레그램 계정에 연결할 수 없습니다.
텔레그램 연결#
[!경고] 전용 계정을 사용하십시오. 텔레그램은 클라이언트와 관계없이 요청 량이 과도하다고 판단될 경우 계정을 제한하거나 영구적으로 차단할 수 있습니다. 개인용이나 중요한 계정이 아닌 관찰용으로 준비된 계정을 연결하고, 전용 계정에서 API ID/해시를 생성하십시오.
- 기본 데모가 실행 중이라면 중지하고 Start.cmd 또는
sh start.sh를 실행하십시오. 그렇지 않은 경우, 위에서 시작한 라이브 설치 환경을 계속 실행하십시오. - 패널 토큰을 사용하여 로그인하십시오. 첫 설정 시 새로운 작업 공간이 열립니다. 사건에 대해 단순히 다운로드, 채팅 팔로우 또는 증거 중 하나를 선택하십시오.
- 연결 확인을 검토하십시오. 필요한 경우 자체 프록시를 구성하십시오. 연결 설정은 설정 후에도 계속 사용할 수 있습니다.
- Connect Telegram에서 전화번호, QR 코드, 계정 파일(TData,
.session, StringSession, 계정 JSON) 또는 전체 인증 키 중에서 선택하십시오. 요청 시 텔레그램 확인 절차, 인증 코드 및 2단계 비밀번호를 입력하십시오. - 표시된 계정을 확인하고, 채팅을 선택한 후 설정을 검토하십시오. 마지막 화면에서 '완료'를 선택하십시오. '단순 다운로드'의 경우, '내보내기 시작'을 선택하면 일회성 내보내기가 시작되고 진행 상황을 보여주기 위해 '내보내기' 화면이 열립니다. 이 경우 지속적인 관찰 기능은 활성화되지 않습니다.
설치 후, [채팅] → [선택]을 클릭하면 선택된 채팅이 변경됩니다. [설정]에서는 컬렉션과 파일을 관리할 수 있으며, [추가 도구] → [소스]에서는 표준 또는 전문가 수준의 상세한 소스 목록을 확인할 수 있습니다. 패널 안내서에는 6가지 주요 섹션과 각 섹션의 상황에 맞는 제어 기능에 대해 설명되어 있습니다.
API ID + 해시는 선택 사항입니다. 워크스페이스는 저장되거나 가져온 쌍을 사용하거나,
내장 풀에서 작동하는 쌍을 사용합니다. 자체 앱을 사용하려면,
API ID:API Hash 쌍 하나를 API ID에 붙여넣으십시오. 인증 키(Auth key)의 경우, 512개의 16진수
문자를 모두 붙여넣고 제공된 DC ID를 선택하십시오. 사용자 ID는 선택 사항이며, 입력 시 확인됩니다.
API 자격 증명은 귀하의 애플리케이션을 식별하는 용도로 사용되며, 그 자체만으로는 계정에 대한 접근 권한을 부여하지 않습니다. 비공개 그룹의 경우 공개 사용자 이름이 필요하지 않지만, 귀하의 계정이 해당 그룹에 대한 접근 권한을 가지고 있어야 합니다.
기존 계정의 경우, 계정 및 세션 형식을 참조하십시오. 이 패널은 Telethon StringSession, Telethon/Pyrogram SQLite, 단일 계정 TData ZIP 및 지원되는 계정 JSON을 지원합니다. 세션과 해당 JSON 파일을 함께 선택한 후, ‘파일 확인’을 누르고 ‘계정 연결’을 클릭하십시오. QR 로그인도 동일한 선택적 API 설정으로 사용할 수 있습니다. TDLib, 봇 세션 및 CSV/JSON 계정 목록은 지원되지 않습니다.
여러 계정의 경우 계정 → 계정 가져오기를 사용하여 지원되는 세션 파일을 선택하세요. 동반 JSON 파일은 기본 파일 이름(basename)으로 짝지어지며, 가져온 각 계정은 고유한 작업 공간을 갖게 됩니다. 일괄 가져오기 및 계정 그룹을 참조하세요.
다른 계정을 추가하려면 계정 선택기 옆의 +를 누르거나 계정 → 계정 추가를 사용하십시오. 워크스페이스마다 별도의 세션, 저널, 키, 소스 및 큐를 갖습니다. 보기를 전환해도 다른 수집기는 계속 실행됩니다. 이 설치 환경에서는 동일한 텔레그램 계정을 두 개의 워크스페이스에 할당할 수 없습니다. 워크스페이스의 수는 정해져 있지 않으며, 하나의 프로세스를 공유하므로 용량은 시스템 사양에 따라 달라집니다.
라이브 패널 토큰은 텔레그램 인증 정보 및 저장된
자료에 대한 접근을 보호하며, 텔레그램 API 자격 증명과는 별개입니다. 명시적으로 시작되고
직접 액세스된 로컬 데모에만 자동으로 등록됩니다. 원격/프록시 데모의 경우 여전히
data/demo/panel-token.txt를 사용합니다.
검토 및 내보내기#
- 저널: 출처 및 이벤트 유형별로 관측 내역을 검색하고 필터링할 수 있습니다.
- 이벤트를 선택하여 원본 기록, 출처 및 저장된 버전을 확인하세요.
- 편집 내역에는 변경 전후의 내용이 표시됩니다. 삭제 내역에는 마지막으로 캡처된 내용이 있는 경우 해당 내용이 표시되며, 신원이 확인되지 않은 행위자는 여전히 미확인 상태로 남습니다.
- 내보내기 형식: 서명된 ZIP, JSONL, CSV 및 오프라인용 HTML.
- 전체 채팅 내보내기(채팅 → 채팅 내보내기, 또는 내보내기 → 채팅 하나 캡처 또는 내보내기
): 하나의 채팅에서 표시되는 전체
이력을
chat.json(텔레그램 내보내기 형식)과 읽기 가능한chat.html이 포함된 서명된 번들로 다운로드합니다. 비공개 채팅은 해당 계정이 멤버일 때 작동합니다. 이는 현재 스냅샷이며, 삭제되거나 이전에 편집된 메시지를 재구성한 것이 아닙니다.python verify.py chat-export.zip --fingerprint TRUSTED_SHA256명령어로 사본을 검증하십시오. - 체크포인트 저장: 서명된 기록부의 경계를 수집기 외부로 유지하십시오.
- 서명된 실행 영수증 다운로드: 수집기의 프로그램/버전 기록을 보존합니다.
- 타임스탬프 요청 준비: 타임스탬프 인증 기관에 대한 오프라인 요청을 준비합니다. TIMESTAMP.md 문서를 따라 응답을 수신하고 검증합니다.
- 저널 검증: 이벤트 서명 및 체인 링크를 확인합니다. ZIP 파일로 내보낼 경우 미디어 파일도 함께 검증됩니다.
지원되는 브라우저에서는 대용량 내보내기 파일을 선택한 위치에 직접 저장할 수 있습니다. 그 외 브라우저의 경우 최대 128 MiB까지 버퍼링됩니다. 서버가 실행 중일 때, 스트리밍 CLI는 전체 응답을 버퍼링하지 않고도 더 큰 용량의 파일을 다운로드할 수 있도록 지원합니다:
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
다른 작업 공간을 사용하려면 [내보내기](Exports) → [작업 공간 ID](Workspace 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는 로컬 종속성, 서명 지원, 저장소, 키 구성 및
수신 주소를 확인합니다. 이 도구는 아무것도 설치하지 않으며 텔레그램에 연결하지도 않습니다. 포트가
사용 중이라면 다른 인스턴스가 실행 중일 수 있습니다. 다른 --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, 그 후
‘더 많은 도구 → 계정 → 파일’에서 불러올 수 있습니다. 직접 파일 가져오기 및 QR 로그인도 가능합니다. 로그인 형식, SOCKS5,
HTTP CONNECT, MTProxy 및 외부 마스터 키에 대해서는
CONNECTION-SECURITY.md를 참조하십시오.
관찰을 일시 중지하면 수집이 중단됩니다. 잠금 기능은 브라우저 액세스만 차단합니다. 탭을 닫아도 수집 프로세스는 계속 실행됩니다. 프로세스를 중지해야만 수집이 중단되며, 기록 스냅샷만으로는 누락된 모든 수정 또는 삭제 내역을 복원할 수 없습니다. 이벤트 정책, 첨부 파일 대기열, 계정 격리 및 재시작 동작에 대한 수집 방식에 대해 알아보세요.
세션과 비밀 정보는 암호화됩니다. 메시지 내용, 미디어 및 내보내기 파일에는 암호화된 디스크 또는 볼륨이 필요합니다. 신뢰할 수 있는 키를 사용하여 저널 서명을 검증하고 체크포인트를 별도로 보관하십시오. 선택한 수집 모드에 대한 캡처 기록, 외부 시간 영수증 및 환경 증명서를 검토하십시오.
백업/복원 방법은 OPERATIONS.md를, 호스팅 방법은 DEPLOYMENT.md를,
서비스 예시는 deploy/를 참조하십시오. 설치된
패널에는 /guide.html에 오프라인 설정 가이드도 포함되어 있습니다.
실제 검증 결과 및 남아 있는 한계 사항은 VERIFICATION.md 및 READINESS.md에 기록되어 있습니다.