이 페이지의 일부 내용은 여전히 영어로 되어 있습니다. 번역 후 원본 영어 문구가 변경되었기 때문입니다.
참고 문헌 / 설정
Telegram · 연결, 프록시 및 데이터 보호
인증, 자동 프록시 풀, IP 모드, 대체 정책, 외부 요청 및 비밀 정보 저장.
이 문서는 TgWitness 0.9.3의 동작 및 그 한계를 설명합니다. 인증, 소스 액세스, 네트워크 연결 및 캡처 완전성은 별개의 상태입니다. 로그인 단계, 파일 형식 및 다중 계정에 대해서는 계정 및 세션 형식 섹션부터 시작하십시오. 이벤트 정책 및 재시작 동작에 대해서는 수집 작동 방식 섹션을 참조하십시오.
연결 설정 안내#
‘추가 도구’ → ‘계정’ → ‘연결 경로’에서 관리자는 ‘이 계정’, ‘계정 그룹’ 또는 ‘모든 계정’을 선택한 다음 경로를 지정할 수 있습니다. ‘선택 사항 검토’에서는 영향을 받는 계정 목록이 표시됩니다. ‘준비 및 확인’은 저장된 경로를 변경하지 않고 제안된 경로를 테스트합니다. ‘확인된 연결 적용’은 미리 보기를 검증하고, 필요한 경우 관찰을 일시 중지한 뒤, 경로를 저장하고 이미 실행 중이던 관찰을 재개합니다. 이 기능은 이전에 비활성 상태였던 계정에서는 절대 데이터 수집을 시작하지 않습니다. 기록 다운로드는 일시 중지된 상태로 유지되며 별도로 재개할 수 있습니다. 전환하기 전에 진행 중인 내보내기를 일시 중지하십시오.
그룹 변경 시 기본적으로 각 계정은 기존 경로를 유지합니다. 미리보기에서 의도한 변경 사항이 표시될 때만 해당 옵션을 해제하십시오. 애플리케이션은 각 계정의 결과를 보고하며, 이는 데이터베이스 전반에 걸친 일괄 처리 트랜잭션이 아닙니다. 전환에 실패하면 해당 계정의 이전 설정으로 복원됩니다. 재개 실패는 명시적으로 표시됩니다. 미리 보기는 10분 후에 만료되며, 연결 설정이나 그룹 멤버십 변경 시에는 새로운 확인이 필요합니다.
Apply는 경로, 모드 및 정책이 변경되지 않은 경우, 성공적인 사전 검증 결과를 최대 90초 동안 재사용합니다. 관리형 터널의 경우 여전히 동일한 실행 중인 프로세스가 있어야 합니다. 이전 결과, 변경된 터널 프로세스 및 자동 MTProxy 풀 경로는 다시 확인됩니다. 서명된 애플리케이션 레코드는 원래의 확인 시간을 유지하며, 재사용 여부와 경과 시간을 기록합니다. 각 사전 검증은 임시 비인증 클라이언트를 종료하며, 수집기는 자체 인증된 세션을 사용하여 연결합니다.
| 경로 | TgWitness가 관리하는 항목 |
|---|---|
| 직접 | 호스트로부터의 연결; 외부 호스트 VPN은 감지되거나 강제 적용되지 않습니다. |
| VPN | 계정당 하나의 풀 터널 WireGuard 프로필이 있으며, 이는 로컬 사용자 공간의 SOCKS5 프로세스에 의해 실행됩니다. 호스트 인터페이스나 드라이버는 설치되지 않습니다. |
| 내 프록시 | SOCKS5, HTTP CONNECT 또는 MTProxy 자격 증명. URL을 입력하여 SOCKS5/HTTP 필드를 채울 수 있습니다. 여러 계정을 선택하면 입력한 프록시가 해당 계정들에 공유됩니다. |
| 공개 MTProto | 기존 풀은 Telegram 경로를 할당합니다. 고급 설정에서 별도의 적절한 프록시가 구성될 때까지 외부 요청은 비활성화됩니다. |
| WARP | 선택한 각 계정에 대해 별도의 로컬 터널을 생성하며, WARP 등록 정보와 WireGuard 프로필은 해당 계정의 볼트에 보관됩니다. |
현재 경로 확인은 계정의 세션이 아닌, 새로 생성된 인증되지 않은 텔레그램 전송 경로를 사용합니다.
이 기능은 경로를 통해 계정의 데이터 센터로 전송 연결을 열고,
인증되지 않은 MTProto 왕복 통신을 한 번 수행합니다
(req_pq_multi); 이 과정에서 인증 키가 생성되지 않으며 계정도 사용되지 않습니다.
보고되는 지연 시간은 해당 연결 시간에 왕복 시간을 더한 것이며, 이 확인 과정은
두 부분을 별도로 기록합니다. HTTP를 지원하는 경로의 경우, 해당 경로를 통한
해당 경로를 통한 Cloudflare의 HTTPS 추적을 요청하고, 보고된 출구 IP,
국가, WARP 상태 및 검사 시간을 표시합니다. 추적 결과가
WARP 활성 상태를 보고하지 않는 한 WARP 준비는 실패합니다. 이러한 사전 검사에서는 경로 연결 상태와
관측된 출구 정보를 보고합니다. 아카이브의 수집 및
검증 결과를 통해 캡처된 기록을 검토하십시오. 로컬 프로세스가 실행 중이라는 사실만으로는 출구 검사가 성공한 것으로 간주되지 않습니다.
패널은 최근 5회의 확인 결과를 바탕으로 이동 평균을 계산합니다. 이동 경로는
평균 시간이 5초를 초과하거나 3회 연속으로 확인 시간이 이를 초과할 경우 ‘느림’으로 분류되며,
2회 연속 확인 실패 시 ‘사용 불가’로 분류됩니다. network.slow_route 그리고
network.route_recovered 변경 사항을 기록합니다. 속도가 느린 WARP 경로의 경우, WARP 재시도 기능은
해당 계정의 터널을 다른 Cloudflare WARP 엔드포인트로 재시작하고,
가장 빠른 경로를 유지하며 network.warp_rerolled 이전 및 이후 시간을 함께 기록합니다;
'New WARP identity'는 새로운 WARP 기기를 등록하며, 해당 기기가
더 빠를 때만 유지합니다. 로컬 프록시 주소, 텔레그램 계정 및 해당 세션은
변경되지 않으며, 텔레그램 연결은 재시작된 터널을 통해 다시 연결됩니다. 느린 WARP
경로는 최대 30분에 한 번씩 자동으로 재롤링되며, 이로도
해결되지 않을 경우 추가 재롤링은 운영자의 조치를 기다립니다.
이식 가능한 WARP 및 WireGuard#
이것은 비공식 WARP 통합 로, wgcf 2.3.1 및 wireproxy 1.1.3 를 사용합니다. 관리자는 첫 번째 다운로드 또는 WARP 등록 전에 설정을 명시적으로 수락합니다. 이러한 설정 연결은 GitHub 및 Cloudflare로 직접 연결되며 기기의 IP 주소를 노출시킵니다. 일반 계정 트래픽은 애플리케이션에 도달할 때까지 기존 경로를 유지합니다. Cloudflare가 출구 주소와 국가를 선택하며, 별도의 터널도 동일한 출구 주소를 공유할 수 있습니다. 이 기능에서는 국가 선택, 주기적인 IP 로테이션 및 호스트 전체에 적용되는 VPN 킬 스위치가 제공되지 않습니다.
지원되는 헬퍼 다운로드: Linux 및 macOS x86-64/ARM64, Windows x86-64.
아티팩트는 검토된 소스 코드에 포함된 SHA-256 해시와 대조하여 검증되며,
캐시된 실행 파일은 실행 전에 다시 한 번 확인됩니다. 어떤 헬퍼도
PATH에 추가되거나, 시스템 서비스로 설치되거나, 공개 리스너가 할당되지 않습니다. 모든 파일은
작업 공간의 portable-routes/ 디렉터리와 암호화된 볼트 항목 내에 저장됩니다.
루프백 SOCKS5 리스너는 별도로 생성된 인증 정보가 필요합니다.
비공개 프로필과 WARP 계정 인증 정보는 기존 워크스페이스 볼트로 암호화됩니다. 실행 중일 때, 헬퍼는 소유자 전용 평문 구성 파일이 필요하며, 정상 종료 시 이 파일은 삭제됩니다. 호스트가 다운되면 이 파일이 소유자 전용 데이터 폴더에 남아 있을 수 있습니다. 이는 디스크를 암호화하지 않으며, 관리자로부터 보호하지도 않습니다. 패널의 상위 파이프가 사라지면 슈퍼바이저가 터널을 종료합니다. 실패한 터널은 절대 직접적인 대체 연결을 활성화하지 않습니다. 패널을 재시작하면 선택된 터널이 복원되며, 시작에 실패한 경우 제한된 지연 시간 후에 재시도합니다. Stop 터널 는 관찰도 일시 중지하고 중지된 상태를 유지합니다. Start 터널 는 터널을 시작하며, 준비가 되면 별도로 관찰을 재개합니다.
업로드된 WireGuard 프로필에는 하나의 인터페이스와 하나의 피어, 전체 IPv4 및 IPv6 경로가 포함되어야 하며, 후크, 포함, 환경 변수 대체 또는 추가 리스너가 포함되어서는 안 됩니다. 공개 엔드포인트 주소는 시작 전에 확인 및 고정됩니다. OpenVPN/IPsec 및 사설 엔드포인트의 경우 외부 VPN 또는 SOCKS5 게이트웨이를 사용하십시오.
인증 방법#
API ID와 API 해시는 애플리케이션을 식별하는 용도로 사용되며, 계정 로그인을 대체하지 않습니다. TgWitness에서는 이 정보들이 선택 사항입니다. 우선순위는 다음과 같습니다: 양식에 입력된 쌍, 가져온 계정 JSON의 쌍, 작업 공간에 저장된 쌍, 내장된 50개의 공개 쌍 풀에서 무작위 순서로 시도되며, 텔레그램에서 거부될 경우 자동으로 순환됩니다. 오직 텔레그램 데스크톱 쌍(2040)만이 일치하는 텔레그램 데스크톱 클라이언트 설명과 함께 전송됩니다. my.telegram. org의 API 개발 도구에서 생성한 본인 소유의 쌍은 모든 계정에 사용할 수 있으며, 각 계정은 여전히 고유한 인증 정보를 유지합니다.
| 방법 | 요구 사항 | TgWitness 지원 |
|---|---|---|
| 전화번호, 코드, 선택 사항인 2단계 인증(2FA) | 계정 접속; API 페어 선택 사항 | 패널 로그인 |
| 인증 키 HEX + DC ID | 전체 512자 키 및 DC 1–5 | 'Direct Auth 키' 탭; 인증이 저장되기 전에 선택 사항인 사용자 ID가 확인됩니다. |
| Telethon StringSession | 유효한 세션 문자열 | 패널 로그인 |
Telethon SQLite.session |
완결되고 일관된 문구 | 스키마의 직접 패널 가져오기 7/8; 선택적 오프라인 CLI |
Pyrogram SQLite.session |
종료된 프로덕션 사용자 세션 | 스키마의 직접 패널 가져오기 2/3 |
| Telegram Desktop TData ZIP | 최신 계정 1개; 보호된 경우 로컬 비밀번호 | 체크섬/복호화 검증을 포함한 인메모리 변환 |
| 계정 JSON | 지원되는 API/세션/키 필드 | 메타데이터만으로는 API 인증 정보를 채울 수 없으며, 세션/키 또는 전화번호/QR 코드 로그인이 여전히 필요합니다. |
| QR 로그인 | 공식 텔레그램 앱의 확인 | 로컬 QR 생성, 만료/재시도, 선택적 2단계 인증(2FA) |
| TDLib / Pyrogram StringSession | 기타 라이브러리별 형식 | 지원되지 않음 |
| 봇 토큰 | 자체적인 접근/업데이트 모델을 갖춘 봇 | 이 수집자가 사용하지 않음 |
텔레그램은 SMS 전송 여부를 포함하여 코드 전달 방식을 선택합니다. API 해시는 취소된 세션을 복구하거나 잊어버린 2FA 비밀번호를 대체할 수 없습니다. TgWitness는 로그인 코드나 텔레그램 2FA 비밀번호를 디스크에 영구 저장하지 않습니다.
비공개 소스의 경우, 해당 계정은 이미 접근 권한을 가지고 있어야 합니다. 그룹 사용자 이름은 필요하지 않습니다. 프록시 또는 세션 가져오기는 회원 자격이나 관리자 권한을 부여하지 않습니다. 회원이 가입 전의 기록을 볼 수 있는지 여부는 채팅 설정에 따라 결정됩니다.
Telethon 세션 파일 가져오기#
Telethon SQLite, Pyrogram SQLite, and Telegram Desktop TData use different formats. The panel detects and converts the supported structures; renaming a file is not conversion. Select one session and its companion JSON under Files, press Check files, then Connect account. Up to four matching files and 8 MiB total are accepted. See format limits for TData/JSON details. There is no passcode recovery. Phone/2FA or QR login creates a separate authorization.
선택 사항인 Telethon 전용 명령줄 경로는 계속 사용할 수 있습니다:
- 원본 세션을 사용하는 클라이언트를 중지하고 일관된 복사본을 생성하십시오. 변환기는 WAL/저널이 완료되지 않은 파일을 거부합니다. 검사를 우회하기 위해 해당 파일을 삭제하는 대신, 원본 클라이언트를 올바르게 종료하십시오.
- TgWitness 환경에서 다음 명령을 실행하십시오:
python -m tgwitness.sessions account.session --out account.tgwitness-session
- '계정 추가' → '파일'에서 결과 파일을 불러오거나 해당 문자열을 붙여넣은 후 다음 단계로 진행하십시오.
- 표시된 숫자형 계정 ID를 확인하고, 소스를 선택한 후 관찰을 시작하십시오.
변환된 파일은 암호화되지 않은 계정 접근 비밀번호입니다. 이 정보를 안전한 저장소에 보관하고, 절대로 커밋하거나 제3자 변환 서비스로 전송하지 마십시오. TgWitness는 인증된 세션을 암호화된 볼트에 저장합니다. 세션을 복사한다고 해서 별도의 인증이 생성되는 것은 아닙니다. 복제된 인증 키로 클라이언트를 동시에 실행하여 독립적인 업데이트 전달이 이루어진다고 가정하지 마십시오.
변환 작업은 원본 메시지, 엔티티 캐시 또는 영구적인 업데이트 커서가 아닌 권한을 전달합니다. 또한 프로세스 재시작 시 업데이트 복구 기능을 보장하지 않습니다.
MTProto, Telethon 및 프록시#
MTProto는 텔레그램의 프로토콜입니다. Telethon은 TgWitness가 사용하는 파이썬 클라이언트 라이브러리입니다. MTProxy는 텔레그램 전송 프록시이며, SOCKS5 및 HTTP CONNECT는 일반적인 터널을 제공합니다. 이 중 어느 것도 계정 인증을 대체하지는 않습니다.
로그인하기 전에 [추가 도구] → [계정] → [설정] → [연결 설정] → [연결 경로 변경]에서 각 작업 공간의 경로를 저장하십시오. 새 작업 공간은 기본적으로 ‘자동 MTProxy’ 모드로 설정되며, 공개 목록의 경우 ‘주소 숨기기’가 적용됩니다. ‘직접 연결(Direct)’을 명시적으로 사용했던 기존 작업 공간은 이를 허용하는 모드를 유지합니다.
공식 앱과 마찬가지로, 파일은 메시지를 읽는 연결과는 별도의 연결을 통해 읽힙니다. 계정 자체의 데이터 센터에서는 새로운 MTProto 세션에 해당 계정의 인증 키를 재사용하며, 다른 데이터 센터의 경우 계정이 연결되어 있는 동안 하나의 키가 생성 및 인증되며, 이 키는 메모리에만 저장됩니다. 모든 파일 연결은 계정과 동일한 경로를 사용합니다. 데이터 센터별 연결 수는 ‘매개변수 → 성능 → 'Telegram 데이터 센터당 파일 연결'에서 제한되며, 0으로 설정하면 파일은 계정의 주 연결을 통해서만 읽힙니다. 한 설치 환경의 모든 계정을 통틀어 한 번에 최대 5개의 Telegram 연결만 설정됩니다.
IP 모드#
경로가 연결 방식을 결정합니다. 패널의 ‘계정’ 섹션에 있는 IP 모드 및 IP 보호 기능은 서버 주소가 노출될 수 있는 시점을 결정합니다. 이러한 제어 기능은 VPN을 설치하거나 기기의 모든 트래픽을 라우팅하지는 않습니다.
| 모드 | 텔레그램 | 외부 요청 |
|---|---|---|
주소 숨기기 (hide) |
프록시를 사용하십시오. 작동하는 프록시가 없으면 잠시 기다리십시오. 직접적인 대체 방안은 없습니다. | SOCKS5/HTTP가 필수이며, 해당 프록시가 없는 요청은 거부합니다. |
최후의 수단으로 직접 (fallback) |
자동 MTProxy는 설정된 지연 시간이 지난 후 Direct를 사용할 수 있으며, 이후 정상 작동하는 프록시로 복귀합니다. | 사전 구성된 외부 프록시 또는 계정의 SOCKS5/HTTP 경로를 우선적으로 사용하며, 그렇지 않은 경우 Direct 접속이 허용됩니다. |
터널 또는 VPN 뒤에 위치한 서버 (tunnel) |
직접 경로 및 즉각적인 자동 풀(pool) 대체가 허용됩니다. | 적용 가능한 프록시가 구성되지 않은 경우 직접 접속이 허용됩니다. |
터널 또는 VPN 모드는 사용자가 해당 네트워크를 별도로 관리한다고 가정합니다. 정상적으로 작동하는 터널이 없으면 대상 측에서 서버의 실제 주소를 확인할 수 있습니다. 옵션의 이름이 아닌 실제 네트워크 환경에 따라 모드를 선택하십시오.
경로 선택#
| 경로 | 설정 | 경계 |
|---|---|---|
| 자동 MTProxy | 내장된 목록 또는 연산자 카탈로그 | 작동하는 텔레그램 경로를 유지하며, 직접 대체 경로는 IP 모드에 따라 달라집니다. |
| 직접 | 터널 또는 VPN 모드 | Telethon은 호스트의 네트워크 경로를 사용합니다. |
| SOCKS5 | 호스트, 포트, 선택 사항인 사용자 이름/비밀번호 | python-socks, 원격 대상 DNS 활성화됨 |
| HTTP CONNECT | 호스트, 포트, 선택 사항인 사용자 이름/비밀번호 | 일반 HTTP CONNECT; 프록시 자체에 대한 TLS는 구현되지 않았습니다. |
| MTProxy | 호스트, 포트, 비밀번호 | 실험용 텔레톤 전송 방식; 32자리 16진수 또는 dd + 32자리 16진수 |
가짜 TLS ee 비밀키는 거부됩니다. Telethon 1.45의 정규화 기능은 접두사
및 도메인을 제거할 수 있지만, 이는 가짜 TLS를 구현하는 것은 아닙니다. tg://proxy?server=…&port=…&secret=…
또는 https://t.me/proxy?server=…&port=…&secret=…를 붙여넣고 ‘링크에서 필드 채우기’를 선택하십시오.
이렇게 하면 연결하거나 저장하지 않고도 필드가 유효성 검사되고 채워집니다. 경로를 별도로 검토하고 저장하십시오.
수동 입력 필드는 계속 사용할 수 있습니다. 텔레그램 프록시 링크를 참조하십시오.
설치를 통해 제공되는 공개 프록시#
내장된 목록은 SoliSpirit/mtproto, zakky8/mtproto-proxy-pro, kort0881/telegram-proxy-collector, 3yed-61/MTP-Collector, Therealwh/MTPproxyLIST, KhodeJav/telegram-proxy-collector 및 tgmtproxy/telegram-mtproto-proxy-list입니다. 번들로 제공되는 스냅샷에는 엔드포인트 정보, 출처 출처 및 다운로드 날짜가 포함되어 있습니다. 목록은 입력값이며, 아래의 연결성 검사를 통해 어떤 프록시를 사용할지 결정됩니다.
자동 MTProxy는 텔레그램 전송 연결 상태를 확인하고, 정상 작동하는 프록시를 유지하며 오류가 발생하면 다른 프록시로 전환합니다. 워크스페이스는 충분한 작동 가능한 항목이 있을 경우 서로 다른 프록시를 선호하며, 프록시들은 출구 주소를 공유할 수 있습니다. 오류가 발생한 프록시는 다음 시도를 위해 잠시 대기합니다. 작동하는 프록시가 없는 경우, IP 모드가 수집을 대기해야 하는지 아니면 직접 연결을 사용할 수 있는지를 결정합니다. 프록시를 변경해도 계정은 변경되지 않으며 저널이 삭제되지도 않습니다. 경로 선택 및 변경 사항은 서명된 저널에 기록됩니다.
자동 경로가 활성화된 상태에서는 목록이 매시간 갱신되며, 전송 확인은 기본적으로 10분마다 실행됩니다. 이러한 간격은 설정에서 조정할 수 있습니다. 공개 목록을 업데이트하면 갱신이 요청되며, 목록을 조회하는 것만으로는 저장된 수동 경로가 변경되지 않습니다.
텔레그램 트래픽과 HTTPS 요청은 서로 다른 경로를 사용합니다. 목록 다운로드는
별도의 HTTPS 연결과 제공된 외부 요청 경로를 사용합니다.
'TGWITNESS_PROXY_FEED_PROXY'는 HTTP/SOCKS5 프록시를 통해 해당 경로를 명시적으로 재정의하며,
두 가지 'Compose' 수집기 변형 모두 이를 전달합니다. 백그라운드 풀은 메인 작업 공간을 따릅니다.
텔레그램 세션, API 인증 정보, 패널 토큰 또는 봇 토큰은 피드 제공자에게 전송되지 않습니다.
제공자 이름, 스냅샷 날짜 및 다운로드 경로는 ‘목록 출처’ 항목 아래에 표시됩니다.
MTProxy는 텔레그램 트래픽만 처리합니다. 타임스탬프, 알림, 오프사이트 복사본 및 소스 확인과 같은 워크스페이스 HTTP 작업은 구성된 경우 별도의 SOCKS5/HTTP 프록시를 사용하며, 그 외에는 해당 계정의 SOCKS5/HTTP 경로를 사용합니다. 둘 중 하나도 설정되지 않은 경우, ‘주소 숨기기’ 모드는 요청을 거부하며, 다른 모드에서는 ‘직접 연결’이 허용됩니다. 외부 요청은 비활성화할 수 있습니다. 명시적으로 구성된 피드 다운로드 프록시는 별도의 운영자 오버라이드로 유지됩니다. 독립적인 위트니스 서비스는 자체 경로를 유지합니다.
운영자가 관리하는 비공개 서비스의 경우, 기존 서버 환경 설정인
TGWITNESS_ALLOW_PRIVATE_DESTINATIONS=1은 비공개 목적지를 허용하고
프록시 측 호스트 이름 확인을 유지합니다. 이 설정은 패널에서 활성화할 수 없습니다. 공개 전용
모드는 공개 리졸버에 쿼리를 보내기 전에 .onion 목적지를 거부합니다. Tor onion
서비스를 이용하려면 명시적인 비공개 목적지 설정과 적절한 프록시가 필요합니다.
이 DNS 동작은 외부 HTTP 작업에 적용되며, 텔레그램의 전송 방식에는 적용되지 않습니다.
Cloudflare는 JSON DNS 엔드포인트에 대해 문서화하고 있습니다.
자동 풀 매개변수
'추가 도구(More tools)' → '매개변수(Parameters)' → '자동 MTProxy'에서 오류 임계값, 대기 시간, 계획된 로테이션, 프록시 공유 및 허용되는 폴백 지연 시간을 구성하십시오.
| 제어 | 기본값 |
|---|---|
| 교체 전에 연결이 끊어집니다 | 3분 이내에 10개 완료 |
| 연결 시도당 시도된 프록시 수 | 3 |
| 첫 번째 / 실패 후 최대 재시도 횟수 | 10분 / 6시간 |
| 예정된 교대 근무 | 비활성화됨; 오류 발생 시 켜기 |
| 프록시당 계정 수 | 0: 별도의 항목을 우선적으로 작성하고, 필요한 경우 병합하십시오. 1을 설정하면 해당 항목에 대한 독점적인 처리를 기다립니다. |
| 허용된 직접 대체로 전환되기 전의 지연 시간 | 10분; 주소를 숨겨도 여전히 Direct 접속을 거부함 |
| 피드 새로고침 / 전송 상태 확인 | 60 / 10분; 메인 작업 공간 값이 공유 풀에 적용됩니다. |
서로 다른 프록시들이 하나의 출구 주소를 공유할 수 있습니다. 텔레그램의 제한 사항은 모든 경로에 적용됩니다.
공개 목록을 자체 운영자 카탈로그로 대체하려면 아래의 오버라이드 설정을 구성하십시오.
이 설정은 proxies 배열이 비어 있는 경우를 포함하여 외부 구독을 완전히 비활성화합니다.
빈 카탈로그를
proxy-config/proxies.json
로 복사하고 배포된 공개 엔드포인트를 추가하십시오:
{"format": "tgwitness-proxy-catalog-v1", "proxies": [
{"id": "project-eu", "label": "Project EU",
"link": "tg://proxy?server=REPLACE_HOST&port=443&secret=REPLACE_SECRET"}
]}
예시 값은 반드시 교체해야 합니다. 최대 32개의 고유 항목을 입력할 수 있습니다. 인증된 목록은 공유 비밀번호 없이 레이블/호스트/포트를 반환하며, 하나를 선택하면 해당 자격 증명이 워크스페이스 볼트에 저장됩니다. 명시적인 전송 테스트가 이루어질 때까지 가용성은 검증되지 않은 상태입니다. 형식이 잘못된 카탈로그의 경우 수동 구성이 가능합니다.
네이티브 실행: TGWITNESS_PROXY_CATALOG를 로컬 JSON 경로로 설정합니다. Docker:
docker compose -f compose.yaml -f deploy/compose/compose.proxies.yaml up -d --build
오버레이는 proxy-config를 읽기 전용으로 마운트하며, 파일은 컨테이너 UID 10001이 읽을 수 있어야 합니다.
해당 디렉터리는 Git, Docker 빌드 컨텍스트 및 소스 아카이브에서 제외됩니다. 이
카탈로그는 수집 계정을 구성하며, 위트니스 봇은 MTProxy가 아닌 자체
HTTP/SOCKS5 경로를 사용합니다.
직접 대체 경로는 위의 IP 모드에 따라 결정됩니다. 경로를 변경하기 전에 관찰을 일시 중지하십시오. 저장 시 기존 클라이언트 연결이 끊기고 진행 중이던 로그인이 취소되며, 새 클라이언트는 저장된 경로를 사용합니다. 계정의 저널/세션 바인딩은 유지됩니다. 설정을 변경하면 이전 경로가 대체되므로, 편집 시 프록시 자격 증명을 다시 입력해야 합니다.
인증 정보는 network.enc로 암호화됩니다. API는 사용자 이름,
비밀번호 또는 비밀 키를 반환하지 않습니다. 서명된 기록에는 경로 유형과 인증 정보의
유무가 포함되지만, 엔드포인트와 비밀 키는 제외됩니다. 운영자는 패널에서 엔드포인트를
확인할 수 있습니다. 비밀 키 필드는 저장, 잠금 또는 작업 공간 전환 후 삭제됩니다.
‘텔레그램 연결 테스트’ 기능은 로그인 전에도 이용 가능하며, 해당 경로를 통해 일시적인 비승인 텔레그램 연결을 열고 닫습니다. 이 기능은 IP 확인 웹사이트에 접속하지 않습니다. 테스트 성공 시 전송 연결이 확립된 것일 뿐, 그룹 접근 권한, 완전한 전달 또는 익명성이 보장되는 것은 아닙니다.
이 프록시는 텔레그램 DC 미디어
다운로드를 포함하여 텔레그램 클라이언트의 연결에 적용됩니다. 브라우저, pip, SSH 및 수동으로 실행되는 TSA 도구는 별도의 경로를 따릅니다.
프록시 호스트명은 로컬에서 확인될 수 있습니다. rdns는 대상 호스트명에 영향을 미치며,
텔레그램은 종종 숫자로 된 DC IP를 제공합니다.
SOCKS5 및 일반 HTTP CONNECT는 프록시 인증 정보나 클라이언트-프록시 터널 자체를 암호화하지 않습니다. MTProto는 텔레그램 트래픽을 별도로 보호합니다. 신뢰할 수 없는 네트워크에서는 프록시로 연결되는 적절한 보안 채널을 사용하십시오. 비공개 그룹은 전송 중에 MTProto로 보호되는 클라우드 채팅이며, 종단 간 시크릿 채팅은 별도의 채팅 유형으로, 시크릿 채팅 모듈에 의해 기록됩니다.
암호화 및 서명#
| 계층 | 구현됨 | 운영자의 책임 |
|---|---|---|
| 텔레그램 트래픽 | Telethon MTProto | 플랫폼 신뢰도, 경로 및 가용성 |
| 웹 패널 | 베어러 토큰, 루프백 기본값, 요청 제한 | 원격 접속을 위한 HTTPS 또는 SSH 터널 |
| 비밀 | API 자격 증명, 세션, 프록시 자격 증명 및 서명용 개인 키를 위한 Fernet | 복호화 키와 실행 중인 호스트를 보호하십시오 |
| 볼트 키 | 새 설치용 로컬 키 또는 외부 마스터 키 | 별도의 보안 저장소 및 키 백업 |
| 메시지 및 첨부 파일 | 일반 텍스트 애플리케이션 저장소 | 암호화된 디스크/볼륨 |
| ZIP/JSONL/CSV/HTML | 무결성 검사, 콘텐츠 암호화 없음 | 내보낸 사본 및 전송 내용 보호 |
| 출처 및 시간 | 서명된 기록부, 처리 영수증, RFC 3161 도구 | 신뢰할 수 있는 키, 독립적인 점검 지점/TSA 및 보관 절차 |
계정의 ‘저장소 보호’ 항목에는 이러한 상태가 표시됩니다. 패널 토큰은 암호화 비밀번호가 아닌 액세스 시크릿입니다. 이 토큰은 관리자 권한을 부여하며, 발행된 토큰의 적용 범위는 계정 및 채팅으로 제한될 수 있습니다. 워크스페이스는 호스트 프로세스를 공유하며, 독립된 테넌트가 아닙니다.
BitLocker, LUKS, FileVault 또는 관리형 암호화 볼륨은 각각의 위협 모델에 따라 저장 장치를 보호할 수 있습니다. 잠금 해제된 상태에서 실행 중인 시스템의 관리자는 여전히 데이터를 읽을 수 있습니다. 저장소 계획 시 SQLite WAL/SHM, 미디어, 임시 내보내기 파일, 스왑, 백업 및 브라우저 다운로드 파일을 포함하십시오. Docker 볼륨은 단순히 볼륨이라는 이유만으로 암호화되는 것은 아닙니다.
외부 마스터 키#
새로 설치할 경우, 마스터 키를 데이터 디렉터리 외부에 배치하십시오. 이렇게 해도 기존 로컬 키 볼트가 자동으로 마이그레이션되지는 않습니다. 서비스 ID만 접근할 수 있는 키 디렉터리를 준비한 다음, 다음 명령을 실행하십시오:
python -m tgwitness.security create-master-key /private/keys/tgwitness-master.key
export TGWITNESS_VAULT_KEY_FILE=/private/keys/tgwitness-master.key
python -m tgwitness --data-dir /private/observations/new-case
설치된 프로젝트 환경을 사용하는 PowerShell:
python -m tgwitness.security create-master-key E:\PrivateKeys\tgwitness-master.key
$env:TGWITNESS_VAULT_KEY_FILE = 'E:\PrivateKeys\tgwitness-master.key'
python -m tgwitness --data-dir E:\PrivateData\new-case
Docker에서 파일을 /data 외부(예:
/run/secrets/tgwitness-master.key)에 읽기 전용으로 마운트하고, 환경 변수를 해당 경로로 설정하십시오.
서비스 UID는 해당 파일을 읽을 수 있어야 합니다. 키 바이트가 아닌 경로를
환경/구성 파일을 통해 전달하십시오.
각 워크스페이스에는 무작위로 생성된 공개 솔트(salt)와
HKDF-SHA256을 통해 파생된 고유한 Fernet 키가 할당됩니다. vault.external.json는 마스터 키가 아닌 파생 메타데이터를 저장합니다.
키가 없거나 잘못된 경우, 키를 자동으로 대체하지 않고 시작에 실패합니다. 복구를 위해
솔트 메타데이터와 마스터 키를 모두 보관하십시오.
모든 작업 공간은 동일한 마스터 키에서 파생되며, 이 키가 유출될 경우 전체 설치에 영향을 미칩니다. 실행 중인 프로세스는 비밀 정보를 복호화할 수 있습니다. 이는 HSM이나 암호 KDF가 아닙니다. 무작위 키 대신 임의의 사용자 지정 비밀번호는 허용되지 않습니다.
의도적인 마이그레이션이
구현되고 검증될 때까지는 기존 설치 환경에 대한 기존 키를 유지하십시오. vault.key를 삭제하거나 마스터 키를 교체하면
세션/서명 키에 대한 접근 권한이 상실될 수 있습니다. 암호화된 백업과 키를 별도로 보관하고
격리된 인스턴스에서 복구 테스트를 수행하십시오.