워크플로우 및 운영

처음 연결할 때는 계정 및 세션 형식을 사용하십시오. 저장된 버전, 이벤트 정책 및 누락에 대한 설명은 수집 방식에서 확인하십시오. 이 가이드는 일상적인 운영 및 복구 절차를 다룹니다.

운영자 워크플로우#

도표를 텍스트로 변환

1. 저장소 및 키 보호 방식 선택 → 토큰을 사용하여 패널 열기
2. 토큰을 사용하여 패널 열기 → 작업 공간 선택
3. 작업 공간 선택 → 직접 경로 또는 프록시 경로 구성
4. 직접 경로 또는 프록시 경로 구성 → 전화번호를 입력하거나 파일을 선택하거나 QR 코드를 스캔하세요
5. 전화번호를 입력하거나 파일을 선택하거나 QR 코드를 스캔하세요 → 계정 신원을 확인하고 접근 가능한 그룹을 선택하세요
6. 계정 신원을 확인하고 접근 가능한 그룹을 선택하세요 → 이벤트 및 첨부 파일 정책을 저장한 후 관찰을 시작하세요
7. 이벤트 및 첨부 파일 정책을 저장한 후 관찰을 시작하세요 → 오류, 액세스, 대기열 및 디스크 모니터링
8. 오류, 액세스, 대기열 및 디스크 모니터링 → 독립적인 검증 지점을 유지합니다
9. 독립적인 검증 지점을 유지합니다 → 자료 내보내기 및 검증

인증, 전송 연결, 그룹 접근 권한 및 전달의 완전성은 서로 다른 속성입니다. 연결 상태가 녹색이라고 해서 모든 이벤트가 캡처되었다는 것을 의미하지는 않습니다.

마스터 키를 공유하지 않고 작업 결과 공유하기#

검토자나 분석가에게 개별 토큰을 부여할 수 있는 ‘오픈 액세스’ 기능. 해당 사용자가 열 수 있는 계정 및 채팅을 선택한 후, 열람, 내보내기 또는 운영 작업을 허용할 수 있습니다. 수집을 시작하거나 중지하는 운영자는 전체 작업 공간에 대한 접근 권한이 필요하며, 검토자는 단일 채팅으로만 접근 권한이 제한될 수 있습니다. 세션 제한, 만료 및 IP 규칙은 텔레그램 계정 인증과 별도로 관리됩니다. 접근 및 권한을 참조하십시오.

'열린 세션' 기능을 사용하여 연결을 종료하거나, 모든 세션에 대한 접근 권한을 취소하여 해당 세션을 모두 종료할 수 있습니다. 관리자 콘솔은 여러 워크스페이스에 걸친 현재 프로세스 활동을 통합하여 표시합니다. 세션을 종료해도 데이터 수집은 계속 실행됩니다.

실행 모드#

로컬 데모 접속은 수동으로 토큰을 입력하지 않아도 자동으로 열립니다. 이 기능은 격리된 합성 데모에 대한 직접 루프백 접속에만 유효한 프로세스 수명 기간 기능을 사용하며, 메인 패널 토큰은 공개되지 않습니다. 실제 작업 공간 및 원격 또는 프록시를 통한 데모 접속은 토큰 인증을 유지합니다. 데모 접속은 텔레그램 권한을 부여하지 않습니다.

모니터링 카테고리#

'소스(Sources)' → '캡처 설정(Capture settings)' → '보존할 변경 사항 선택(Choose which changes to preserve)'에서 새 메시지, 수정, 삭제 알림, 반응 업데이트 및 멤버십 이벤트를 개별적으로 선택할 수 있습니다. 기본 설정은 모든 범주를 보존합니다. '메시지, 수정 및 삭제'를 선택하면 원본 컨텍스트를 유지하면서 별도의 반응/멤버 업데이트는 비활성화됩니다. '모든 표시된 활동'을 선택하면 다섯 가지 항목이 모두 복원됩니다. 사전 설정을 변경하면 양식이 달라지며, '모니터링 설정 저장'을 눌러 적용하십시오.

저장된 정책은 해당 작업 공간에서 선택된 모든 소스에 적용됩니다. 다른 작업 공간은 각자의 설정을 유지합니다. 각 실제 변경 사항에 대해서는 서명된 변경 전/후 값이 기록되며, 현재 정책은 처리 영수증 및 관찰 시작 기록에도 포함됩니다. 카테고리를 비활성화하더라도 이전 관찰 기록은 삭제되지 않습니다. 다시 활성화하더라도 놓친 변경 사항은 복구되지 않습니다. 이 버전에서는 그룹별 범주 재정의 기능이 제공되지 않습니다.

이전 콘텐츠가 중요한 경우 새 메시지 기록을 계속 활성화해 두십시오: 삭제 알림만으로는 처음부터 캡처되지 않은 텍스트를 복구할 수 없습니다. 운영/커버리지 기록 및 기타 그룹 서비스 이벤트는 항상 보존됩니다. 명시적인 기록 스냅샷은 실시간 카테고리 선택과 별개이며, 서비스 메시지가 포함될 수 있습니다. 이러한 설정은 캡처된 텔레그램 객체에 포함된 반응/회원 메타데이터를 삭제하지 않습니다.

기록 내역 스냅샷은 일시 중지된 상태에서도 첨부 파일을 대기열에 추가할 수 있습니다. 처리를 시작하려면 관찰을 시작하십시오. 대기열에 추가되었다고 해서 다운로드가 완료된 것은 아닙니다. 사용할 수 없는 원본 파일은 최신 수정 버전으로 대체되지 않으며, 결과는 별도로 기록됩니다.

'잠금' 기능을 사용하면 브라우저 액세스 및 비밀 필드가 지워지지만, 데이터 수집은 계속 진행됩니다. 탭을 닫아도 프로세스는 계속 실행됩니다. Python 프로세스나 서비스를 중지하면 브라우저 상태와 관계없이 데이터 수집이 중단됩니다.

추가 작업 공간을 삭제하면 해당 수집기가 중지되고 로컬 데이터가 제거됩니다. 잠긴 파일이나 파일 시스템 오류로 인해 제거가 중단된 경우, 패널에 오류가 보고되며 해당 작업 공간은 사용 불가(DeletionPending) 상태로 유지됩니다. 해당 파일을 보유하고 있는 프로그램을 닫은 후 '삭제'를 다시 시도하십시오. TgWitness를 재시작해도 해당 워크스페이스는 중지된 상태로 유지되며, 부분적으로 제거된 저널이나 키는 복원되지 않습니다. 성공적인 삭제는 디렉터리가 제거된 후에만 기록되며, 별도로 내보내거나 백업된 사본은 각각의 보존 정책에 따라 유지됩니다.

알림#

오픈 소스 → 알림 → 경보 및 일일 요약. TgWitness는 Apprise를 사용하여 Matrix, 텔레그램, 디스코드, 슬랙, ntfy, 이메일 및 기타 지원되는 서비스로 경보를 전송합니다. 하나의 워크스페이스에 여러 수신처를 추가할 수 있습니다.

1. 한 줄에 하나의 Apprise 대상 URL을 입력하십시오. 해당 서비스에 맞는 서비스 카탈로그 및 URL 형식을 사용하십시오.
2. '알림 보내기'를 켠 다음, 문제 알림, 모니터링 중인 채팅의 변경 사항 및 일일 요약 중 원하는 항목을 선택하세요. 요약 시간은 서버 시간을 기준으로 합니다.
3. 알림에 삭제 및 수정된 메시지의 저장된 텍스트를 포함하려면 ‘짧은 발췌문 포함’을 켜십시오.
4. '저장' 알림을 누른 다음, '테스트 전송'을 눌러 전송 여부를 확인하세요.

자신만의 수신기를 사용하려면 Apprise의 JSON 웹훅을 활용하십시오. 예를 들어, jsons://notify.example.org/tgwitness는 HTTPS를 통해 해당 엔드포인트로 JSON을 전송합니다. 이는 가상의 예시이며, 실제 목적지로 대체하여 사용하십시오.

목적지와 설정은 선택한 작업 공간에 속합니다. 변경 알림은 새로 추가된 채팅을 포함하여 모니터링 대상 소스 전반을 다룹니다. 상단 바의 종 모양 아이콘은 최근 발생한 문제와 채팅 변경 사항도 표시합니다.

데모에서는 알림 제어 기능이 표시되지만 전송 기능은 비활성화되어 있습니다. 실제 작업 공간에서 전송 설정을 구성하십시오. 알림은 해당 작업 공간의 Direct, SOCKS5 또는 HTTP 경로를 사용하며, MTProxy를 통해 전송할 수 없습니다. SMTP와 같은 비-HTTP 목적지의 경우 직접 경로가 필요합니다.

패널 레이아웃#

저널에는 관찰 내용, 검색 및 필터 기능이 표시됩니다. 편집 시 캡처된 버전이 열리고, 삭제 시 가능한 경우 이전 내용이 표시됩니다. 출처가 불분명한 내용은 명시적으로 표시됩니다. 집계 정보는 ‘개요’에서 확인할 수 있으며, 수집 세부 정보는 로컬 가이드에 기록됩니다.

수정된 메시지를 열어 본문 내 변경 사항 또는 나란히 비교로 버전을 비교할 수 있으며, 원본 데이터는 저장된 필드를 보여줍니다. 숨겨진 링크와 봇 버튼의 변경 사항은 별도로 표시됩니다. 첨부 파일 미리보기를 열어 저장된 이미지, 오디오 또는 비디오를 검사하세요. 다운로드 버튼을 통해 보존된 원본을 계속 사용할 수 있습니다.

Live는 기록이 도착하는 대로 저널과 채팅을 업데이트합니다. 검토하는 동안에는 일시 중지하거나 준비가 되었을 때 새 이벤트 버튼을 사용하세요. 수집은 계속 실행됩니다. Ctrl/Cmd+K는 패널 작업을 찾고 저널을 검색합니다.

'소스' 섹션에는 관찰 범위(선택한 채팅, 텔레그램 폴더 또는 전체 계정), 모든 유형의 접근 가능한 채팅, 우선순위 별표가 지정된 선택된 소스, 첨부 파일 및 재확인 설정, 그리고 기록 스냅샷이 포함됩니다. 비공개 소스는 공개 링크 없이 대화/ID를 통해 선택됩니다. 접근 상태는 영구적인 권한이 아닌 가장 최근의 확인 상태를 나타냅니다.

소스를 필터링하고 체크박스를 선택한 다음 한꺼번에 활성화, 일시 중지 또는 우선순위로 표시하세요. 사용 가능한 채팅 목록에서 선택 항목 추가는 선택한 항목을 사용하며, 일치하는 항목 모두 추가는 현재 검색 및 유형 필터를 사용합니다.

'채팅' → '사람' 메뉴에서는 메시지가 저장된 모든 사용자가 나열되며, 해당 채팅에서 '사람 프로필' 기능이 활성화된 경우 클릭하면 해당 사용자의 프로필이 열리고, 여기에는 기록부 기록으로 연결되는 링크가 포함됩니다.

Witness는 읽기 전용 위트니스 토큰을 생성하고, 각 위트니스가 마지막으로 확인된 시점을 표시하며, 하나의 (독립적인 위트니스)를 실행하기 위한 명령어와 옵션을 제공합니다.

‘매개변수’ 섹션에는 다른 페이지에 기재되지 않은 작업 공간의 모든 제한 사항 및 속도가 포함됩니다: 읽어들이는 대화 수, 채팅 목록 재읽기 빈도, 하트비트 및 체크포인트 간격, 시작 버퍼, 재확인 요청의 분산 방식(첫 지연 시간, 패스당 채팅 수, 채팅 간 일시 정지, 복구 및 재요청된 메시지 수), 디스크 할당량, 다운로드의 타임아웃 및 재시도, 사용자 프로필 검색 조건(사용자 정의 정규식 포함), 알림의 크기 및 빈도, 스냅샷, ZIP 및 브라우저 다운로드 제한, 텔레그램 클라이언트 타임아웃 및 재시도. 각 필드에는 해당 범위와 기본값이 표시되며, 변경된 필드는 표시되어 하나씩 또는 모두 한꺼번에 복원할 수 있습니다. 모든 변경 사항은 이전 및 이후 값과 함께 parameters.changed로 기록되며, 관측 시작 기록에는 현재 적용 중인 값이 명시됩니다. 값은 다음 사용 시점부터 적용되며, 클라이언트 타임아웃 및 재시도는 다음 연결 시점부터 적용됩니다. 재확인 간격, 첨부 파일 유형 및 크기, 증거 자료 및 외부 복사 간격은 별도의 페이지에 표시되며, 사전 설정값뿐만 아니라 해당 범위 내의 모든 값을 지정할 수 있습니다.

상단 바의 알림 아이콘은 모니터링 중인 채팅에서 발생한 최근 문제 및 변경 사항을 나열하며, 미읽은 항목은 읽음으로 표시될 때까지 집계됩니다. 변경 사항은 채팅별 및 시간별로 그룹화되어 표시되며("삭제 12건, 수정 1건, 미검출 0건"), 로그아웃이나 디스크 용량 부족과 같은 문제는 채팅이 아무리 바쁘더라도 목록에 계속 남아 있습니다.

계정 생성은 전화번호 입력란에서 시작됩니다. 계속 진행하면 바로 코드 입력 화면으로 이동하며, API 자격 증명이 없는 경우에만 이를 요청합니다. QR 코드 및 파일 가져오기는 대체 탭으로 제공됩니다. 저장된 API 자격 증명은 해당 워크스페이스 내에서만 재사용됩니다. 입력 화면에는 사이드바, 통계 또는 설정 설명이 없습니다. 설정 아이콘을 클릭하면 API, 프록시, 저장소 및 추가 계정 제어 옵션이 열립니다. 신규 설치는 여기서 시작되며, 선택된 소스가 없는 연결된 계정은 ‘채팅 선택’에서 시작됩니다. 경로를 변경하려면 관찰을 일시 중지해야 하며, 미완료된 로그인은 취소됩니다. 기존 저널은 다른 텔레그램 계정에 자동으로 재연동될 수 없습니다.

내보내기 기능은 저널의 무결성을 확인하고 이식 가능한 파일을 생성합니다. 작업 공간 ID는 다운로드 CLI에 전달할 수 있습니다. 각 내보내기 작업은 전체 저널 접두사를 고정하며, 이후의 이벤트는 다음 내보내기 작업에 포함됩니다. 검색 필터는 패키지 범위를 변경하지 않습니다. 자세한 서명 및 적용 범위 정보는 ‘검증 및 제한 사항’ 섹션에서 확인할 수 있습니다.

이 패널은 ‘수집기 상태’ 항목에서 수집기 상태, 대기 중이거나 실패한 미디어, 가장 오래된 보류 중인 미디어, 사용 가능한 디스크 공간, 요청 일시 중지 및 ‘수집기 상태’ 항목에서 액세스가 확인되지 않은 소스를 보고합니다. 이러한 세부 정보는 처음에는 접혀 있으며 ‘계정’ 탭에서는 숨겨져 있습니다. 설정 카드에는 다음 단계인 계정 연결, 소스 선택 또는 관찰 시작이 표시됩니다. 계정 목록은 로드 시점의 스냅샷이며, 선택된 작업 공간은 주기적으로 새로 고쳐집니다. 이는 다중 프로세스 SLA 모니터가 아닙니다.

UI는 원본 콘텐츠에 대해 로컬 자산과 텍스트 렌더링을 사용합니다. 데스크톱 및 좁은 크로미움 레이아웃에 대한 테스트가 완료되었습니다. 이는 완전한 접근성 인증을 의미하지는 않으며, 스크린 리더 및 인간 중심 사용성 평가는 별도의 작업으로 진행됩니다.

배포 환경#

이식성이 뛰어나므로 필수적인 클라우드 서비스나 프론트엔드 빌드가 필요하지 않습니다. 다만 각 대상 시스템에는 호환되는 Python/암호화 의존성, 로컬 디스크 및 네트워크 액세스 권한이 여전히 필요합니다. DEPLOYMENT.md 및 서비스 템플릿을 참조하십시오.

워크스페이스는 CPU, 메모리 및 이벤트 루프를 공유합니다. 프로세스 격리를 위해서는 서로 다른 인스턴스, 포트, 데이터 디렉터리 및 계정 권한을 사용하십시오. 별도의 인스턴스 간에 통합된 패널은 없습니다. 절대 여러 워커를 하나의 데이터베이스에 연결하지 마십시오.

시작 시 확인 및 내보내기#

준비된 환경을 시작하기 전에 python start.py --check를 실행하십시오. 기계 판독 가능한 검증을 위해 --json를 추가하거나, 의도한 --data-dir, --host 및 --port를 전달하십시오. 이 명령은 텔레그램 로그인이나 저널 생성 없이 필수 조건을 확인합니다. 이 명령은 저널을 검증하거나 캡처 준비 상태를 입증하지 않으며, 저널 검증은 애플리케이션 시작 시 수행됩니다. 사용 중인 포트는 단순히 기존 인스턴스일 수 있습니다.

File System Access API를 지원하는 브라우저는 쓰기 가능한 스트림을 통해 내보내기 데이터를 저장합니다. 그 외의 브라우저는 최대 128 MiB까지 버퍼링합니다. 대용량 내보내기를 하거나 파일 스트리밍 기능을 지원하지 않는 브라우저를 사용하는 경우, 스트리밍 CLI를 사용하십시오:

python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip

자식 작업 공간을 생성하려면 Exports에서 --profile ID 를 추가하십시오. 원격 액세스를 위해서는 --url https://server 를 사용하십시오. 일반 HTTP는 루프백 대상에 대해서만 허용됩니다. 토큰은 파일에서 읽혀 헤더에 포함되어 전송되며, 출력되거나 URL에 포함되지 않습니다. 리디렉션은 허용되지 않습니다. 기존 대상은 덮어쓰지 않습니다. 전송에 실패한 경우 해당 임시 부분 파일이 삭제됩니다. 보고된 SHA-256은 전송 체크섬입니다. 신뢰할 수 있는 지문/체크포인트를 사용하여 서명된 ZIP 파일을 별도로 검증하십시오.

백업, 복원 및 중단#

1. 관찰을 일시 중지하고 프로세스를 깔끔하게 종료합니다.
2. 전체 데이터 디렉터리를 복사하십시오: 데이터베이스, 존재하는 경우 WAL/SHM, 미디어, credentials.enc, signing.enc, network.enc, 볼트 키/메타데이터, 토큰, 체크포인트 및 모든 profiles/ 디렉터리.
3. 외부 키 모드의 경우, 마스터 키를 별도로 보관하고 각 vault.external.json를 유지해야 합니다. 새 키를 생성하더라도 이전의 비밀 정보를 복구할 수는 없습니다.
4. 대상 서비스가 중지된 상태에서 복원하고, 원본 키를 구성하며, 접근을 제한하고, 재개하기 전에 무결성을 확인하십시오.
5. 가동 중단 시간 및 검증 결과를 기록하십시오. 기록 스냅샷만으로는 중단 기간 동안 삭제 작업이 발생하지 않았음을 증명할 수 없습니다.

증거 ZIP 파일에는 세션/개인 키가 포함되지 않으며, 전체 서비스 백업이 아닙니다. 다음 네 가지 항목은 별도로 보호됩니다:

전체 서비스 백업은 앞서 설명한 중지된 데이터 디렉터리이며, 내보내기 파일이 아닙니다. 두 경우 모두 보호된 저장소와 신중한 전송 메커니즘을 사용하십시오. 임시 서버 내보내기 파일은 각 작업 공간의 temporary-exports/에 저장되며, 완료된 응답은 정리되고, 중단된 내보내기 파일은 해당 작업 공간의 인스턴스 잠금이 유지되는 동안 다음 시작 시 제거됩니다.

연결이 복구되었다고 해서 중간에 발생한 변경 사항이 반드시 복원되는 것은 아닙니다. 지속적인 미디어 작업과 텔레그램 업데이트 위치는 재시작 후에도 유지됩니다. 증거 형식을 참조하십시오.

용량 및 보존 기간#

기본 제한 사항(모두 ‘Parameters’에서 변경 가능): 첫 1,000개 대화, 스냅샷당 500개 메시지, 압축 해제 시 4 GiB의 서명된 ZIP 콘텐츠(더 큰 아카이브의 경우 verify.py --max-gib N 필요), 128 MiB의 브라우저 대체 용량. 첨부 파일은 ‘소스 → 첨부 파일’에서 유형당 1~2,000 MiB를 차지합니다. 다운로드 CLI의 기본 전송량은 5 GiB입니다. 사용 가능한 디스크 용량은 이보다 적을 수 있습니다. 저널, 미디어, WAL, 임시 내보내기 및 백업을 위한 공간을 확보하십시오. 내보내기는 Compose의 512 MiB/tmp 대신 데이터 볼륨을 사용합니다.

단순히 그룹 수만 집계하는 대신, 초당 이벤트 수, 큐 체류 시간, 미디어 바이트 수 및 디스크 지연 시간을 측정합니다. 합성 로컬 벤치마크는 텔레그램 메시지 전달을 보장하지 않습니다. 자동 보존 삭제 기능은 없습니다. 저널의 끝부분을 제거하면 보존된 체크포인트와의 연관성이 무효화됩니다.

우선순위 재검증 기능은 이미 구현되어 있습니다: 별표가 표시된 소스는 기본적으로 15분마다, 그 외 소스는 6시간마다 재검증됩니다(재검증 단계 참조). 위에서 설명한 대로 비밀번호로 보호된 내보내기 기능이 제공됩니다. 실시간 텔레그램/프록시 수신, 내구성 있는 재재생, 관리자 로그 및 반응 폴링, 격리된 워커, TgWitness 자체에 의한 로컬 저널 및 미디어 암호화, 그리고 독립적인 검토는 여전히 별도의 작업으로 진행 중입니다. 범위 지정된 접근 권한은 ‘접근 및 권한’ 섹션에 문서화되어 있습니다. READINESS.md, LIVE_ACCEPTANCE.md 및 VERIFICATION.md를 참조하십시오.