Fluxos de trabalho e operações

Para sua primeira conexão, utilize contas e formatos de sessão. Para obter uma explicação sobre versões salvas, políticas de eventos e lacunas, consulte como funciona a coleta. Este guia aborda a operação diária e a recuperação.

Fluxo de trabalho do operador#

Diagrama em formato de texto

1. Escolha o armazenamento e a proteção da chave → Abra o painel com seu token
2. Abra o painel com seu token → Selecione um espaço de trabalho
3. Selecione um espaço de trabalho → Configurar rota direta ou via proxy
4. Configurar rota direta ou via proxy → Insira o número de telefone ou selecione arquivos / QR
5. Insira o número de telefone ou selecione arquivos / QR → Verifique a identidade da conta e selecione os grupos acessíveis
6. Verifique a identidade da conta e selecione os grupos acessíveis → Salve as políticas de eventos e anexos e, em seguida, inicie a observação
7. Salve as políticas de eventos e anexos e, em seguida, inicie a observação → Monitorar erros, acesso, filas e disco
8. Monitorar erros, acesso, filas e disco → Manter pontos de verificação independentes
9. Manter pontos de verificação independentes → Exportar e verificar o material

Autorização, conectividade de transporte, acesso a um grupo e integridade da entrega são propriedades distintas. Um status de conexão verde não implica que todos os eventos tenham sido capturados.

Compartilhe o trabalho sem compartilhar a chave principal#

Acesso Aberto para fornecer a um revisor ou analista seu próprio token. Escolha as contas e os chats que eles podem acessar e, em seguida, permita a visualização, a exportação ou ações operacionais. Um operador que inicia ou interrompe a coleta precisa de acesso a todo o espaço de trabalho; um revisor pode ter acesso restrito a um único chat. Limites de sessão, validade e regras de IP são independentes da autorização da conta do Telegram. Consulte acesso e permissões.

Utilize “Sessões abertas” para encerrar uma conexão ou revogar o acesso a fim de encerrar todas as suas sessões. O console do administrador reúne as atividades dos processos atuais em todas as áreas de trabalho. O encerramento da sessão mantém a coleta em execução.

Modos de execução#

O acesso à demonstração local é aberto automaticamente, sem a necessidade de inserção manual de token. Ele utiliza um recurso válido durante toda a duração do processo, restrito exclusivamente ao acesso direto por loopback a uma demonstração sintética isolada; o token do painel principal não é divulgado. Espaços de trabalho reais e o acesso à demonstração remota ou via proxy mantêm a autenticação por token. O acesso à demonstração não concede nenhuma autorização no Telegram.

Categorias de monitoramento#

Em Fontes → Configurações de captura → Escolha quais alterações preservar, selecione novas mensagens, edições, notificações de exclusão, atualizações de reações e eventos de participação de forma independente. A configuração padrão mantém todas as categorias. A opção “Mensagens, edições e exclusões” mantém o contexto original ao desativar atualizações separadas de reações e de membros. “Todas as atividades visíveis” restaura todas as cinco. As predefinições alteram o formato; pressione “Salvar configurações de monitoramento” para aplicar.

A política salva se aplica a todas as fontes selecionadas naquele espaço de trabalho. Outros espaços de trabalho mantêm suas próprias configurações. Cada alteração efetiva registra valores assinados de “antes” e “depois” ; a política atual também é incluída nos recibos de processo e nos registros de início de observação . Desativar uma categoria não exclui observações anteriores. Reativá-la não recupera as alterações perdidas. Nesta versão, não há substituição de categoria por grupo.

Mantenha as novas mensagens ativadas quando o conteúdo anterior for relevante: um aviso de exclusão não pode recuperar texto que nunca foi capturado. Registros operacionais/de cobertura e outros eventos de serviço em grupo são sempre retidos. Instantâneos explícitos do histórico são separados da seleção de categorias em tempo real e podem incluir mensagens de serviço. Essas configurações não ocultam metadados de reações/membros incorporados a um objeto do Telegram que, de outra forma, teria sido capturado.

Um instantâneo do histórico pode colocar anexos na fila enquanto estiver em pausa. Inicie a observação para processá-los. Estar na fila não significa que foram baixados. Um arquivo original indisponível não é substituído por uma versão editada mais recente; os resultados são registrados separadamente.

O botão “Lock” limpa o acesso do navegador e os campos secretos, mas mantém a coleta em execução. Fechar uma aba também mantém o processo em execução. Interromper o processo ou serviço em Python interrompe a coleta, independentemente do estado do navegador.

A exclusão de um espaço de trabalho adicional interrompe seu coletor e remove seus dados locais. Se um arquivo bloqueado ou um erro no sistema de arquivos interromper a remoção, o painel relatará a falha e manterá o espaço de trabalho listado como indisponível (DeletionPending). Feche os programas que estejam mantendo seus arquivos e tente novamente a exclusão. Reiniciar o TgWitness mantém esse espaço de trabalho desativado e não recria seu diário ou suas chaves parcialmente removidos. Uma exclusão bem-sucedida é registrada somente após a remoção do diretório; cópias exportadas ou armazenadas em backup separadamente permanecem sujeitas à sua própria política de retenção.

Notificações#

Abra “Fontes” → “Notificações” → “Alertas” e um resumo diário. O TgWitness utiliza o Apprise para enviar alertas para o Matrix, Telegram, Discord, Slack, ntfy, e-mail e outros serviços compatíveis. É possível adicionar vários destinos a um único espaço de trabalho.

1. Insira uma URL de destino do Apprise por linha. Utilize o catálogo de serviços e os formatos de URL correspondentes ao seu serviço.
2. Ative a opção “Enviar notificações” e, em seguida, selecione alertas de problemas, alterações nos chats monitorados e um resumo diário. A hora do resumo utiliza a hora do servidor.
3. Ative a opção “Incluir trechos curtos” se desejar que o texto salvo de mensagens excluídas e editadas apareça nos alertas.
4. Clique em “Salvar notificações” e, em seguida, em “Enviar teste” para verificar a entrega.

Para seu próprio receptor, utilize o webhook JSON do Apprise. Por exemplo, jsons://notify.example.org/tgwitness envia JSON por HTTPS para esse ponto de extremidade. Este é um exemplo fictício; substitua-o pelo seu próprio destino.

Os destinos e as configurações pertencem ao espaço de trabalho selecionado. As notificações de alteração abrangem suas fontes monitoradas, incluindo bate-papos recém-adicionados. O sino na barra superior também lista problemas recentes e alterações nos bate-papos.

Na demonstração, os controles de notificação estão visíveis, mas o envio está desativado. Configure a entrega em um espaço de trabalho real. As notificações utilizam a rota Direct, SOCKS5 ou HTTP desse espaço de trabalho; o MTProxy não pode transmiti-las. Destinos que não sejam HTTP, como o SMTP, exigem uma rota direta.

Layout do painel#

O diário apresenta observações, pesquisas e filtros. Uma edição abre as versões capturadas; uma exclusão abre o conteúdo anterior, se disponível. Atribuições desconhecidas permanecem explícitas. As contagens estão disponíveis na seção “Visão geral”; os detalhes da aquisição permanecem no guia local.

Abra uma mensagem editada para comparar suas versões com Alterações no texto ou Lado a lado; Dados brutos mostra os campos salvos. Alterações em links ocultos e botões de bots aparecem separadamente. Abra a pré-visualização de um anexo para inspecionar imagens, áudios ou vídeos salvos; o botão de download mantém o original preservado disponível.

O modo Live atualiza o diário e os chats conforme os registros chegam. Pause-o durante a revisão ou use o botão de novos eventos quando estiver pronto; a coleta continua em execução. Ctrl/Cmd+K encontra ações do painel e pesquisa no diário.

A seção “Fontes” contém o escopo de observação (conversas selecionadas, uma pasta do Telegram ou toda a conta), conversas acessíveis de todos os tipos, fontes selecionadas com estrelas de prioridade, configurações de anexos e reavaliação, além de instantâneos do histórico. As fontes privadas são selecionadas por diálogo/ID sem um link público. O status de acesso descreve a verificação mais recente, e não permissões permanentes.

Filtre as fontes, marque suas caixas de seleção e, em seguida, ative, pause ou marque todas como prioritárias de uma só vez. Na lista de chats disponíveis, Adicionar selecionados usa a sua seleção; Adicionar todos os resultados usa a busca e o filtro de tipo atuais.

A seção “Bate-papos → Pessoas” lista todos aqueles cujas mensagens foram salvas; com os perfis das pessoas ativados para o bate-papo, um clique abre o perfil dessa pessoa com links para os registros do diário.

O Witness cria tokens de testemunho somente leitura, mostra quando cada testemunho foi verificado pela última vez e fornece os comandos e opções para executar um (testemunho independente).

A seção “Parâmetros” contém todos os limites e ritmos do ambiente de trabalho que não constam em outra página: quantos diálogos são lidos, com que frequência a lista de bate-papos é relida, intervalos de heartbeat e checkpoint, o buffer de inicialização, como as novas verificações distribuem suas solicitações (primeiro atraso, bate-papos por passagem, pausa entre bate-papos, mensagens recuperadas e solicitadas novamente), reserva de disco, tempos de espera e novas tentativas de downloads, o que os perfis de usuários procuram (incluindo suas próprias expressões regulares), tamanho e frequência das notificações, limites de instantâneos, arquivos ZIP e downloads no navegador, além de tempos de espera e novas tentativas do cliente do Telegram. Cada campo exibe seu intervalo e valor padrão; os campos alterados são marcados e podem ser restaurados um por um ou todos de uma vez. Cada alteração é registrada como “parameters.changed” com os valores anteriores e posteriores, e os registros de início de observação indicam os valores em vigor. Os valores passam a vigorar a partir de seu próximo uso; os tempos limite e novas tentativas do cliente, a partir da próxima conexão. Intervalos de verificação, tipos e tamanhos de anexos, evidências e intervalos de cópia externa permanecem em suas respectivas páginas e podem assumir qualquer valor dentro de seu intervalo, não apenas as predefinições.

O ícone de sino na barra superior lista problemas e alterações recentes nos chats monitorados; as mensagens não lidas são contabilizadas até serem marcadas como lidas. As alterações são agrupadas por chat e por hora (“12 excluídas, 1 editada, 0 não encontradas”), e problemas como o logout ou disco cheio permanecem na lista, independentemente do volume de atividade nos chats.

A criação da conta começa no campo do número de telefone. Continuar leva diretamente à inserção do código, solicitando credenciais de API somente quando estas estiverem ausentes. QR e importação de arquivo são abas alternativas. As credenciais de API salvas são reutilizadas apenas dentro de seu próprio espaço de trabalho. A tela de entrada não possui barra lateral, estatísticas ou seções de configuração. O ícone de Configurações abre os controles de API, proxy, armazenamento e contas adicionais. Novas instalações começam aqui; contas conectadas sem fontes selecionadas iniciam em “Escolher chats”. Alterar a rota requer observação em pausa e cancela o login inacabado. Um registro existente não pode ser vinculado silenciosamente a uma conta diferente do Telegram.

A exportação verifica a integridade do diário e gera arquivos portáteis. O ID da área de trabalho pode ser passado para a CLI de download. Cada exportação atribui um prefixo completo ao diário; eventos posteriores são incluídos em uma exportação subsequente. Os filtros de pesquisa não alteram o escopo do pacote. Informações detalhadas sobre assinatura e cobertura encontram-se na seção “Verificação e limitações”.

O painel exibe o status do coletor, mídias em fila/com falha, as mídias pendentes mais antigas, espaço livre em disco, pausas nas solicitações e fontes cujo acesso não está confirmado na seção “Integridade do coletor”. Esses detalhes aparecem inicialmente recolhidos e ocultos na seção “Conta”. Um cartão de configuração mostra a próxima etapa: conectar uma conta, escolher fontes ou iniciar a observação. A lista de contas é um instantâneo no momento do carregamento; o espaço de trabalho selecionado é atualizado periodicamente. Este não é um monitor de SLA multiprocessos.

A interface do usuário utiliza recursos locais e renderização de texto para o conteúdo de origem. Os layouts para desktop e para telas estreitas baseados no Chromium foram testados. Esta não é uma certificação completa de acessibilidade; a avaliação de usabilidade por leitores de tela e por usuários humanos continua sendo um trabalho à parte.

Ambientes de implantação#

Portabilidade significa que não há exigência de serviço em nuvem ou compilação de front-end. Cada alvo ainda precisa de dependências compatíveis de Python/criptografia, disco local e acesso à rede. Consulte o arquivo DEPLOYMENT.md e os modelos de serviço.

Os espaços de trabalho compartilham CPU, memória e um ciclo de eventos. Para isolamento de processos, utilize instâncias, portas, diretórios de dados e autorizações de conta distintas. Não há um painel unificado entre instâncias separadas. Nunca direcione vários workers para um único banco de dados.

Verificações iniciais e exportações#

Execute o comando python start.py --check antes de iniciar um ambiente preparado. Adicione o --json para verificações legíveis por máquina ou forneça os parâmetros --data-dir, --host e --port pretendidos. O comando verifica os pré-requisitos sem a necessidade de fazer login no Telegram ou criar um diário. Ele não verifica um diário nem comprova a prontidão para a captura; a verificação do diário é executada durante a inicialização do aplicativo. Uma porta ocupada pode ser simplesmente uma instância já existente.

Os navegadores compatíveis com a API de Acesso ao Sistema de Arquivos salvam as exportações por meio de um fluxo gravável. Outros navegadores armazenam em buffer no máximo 128 MiB. Utilize a CLI de streaming para exportações maiores ou para navegadores sem streaming de arquivos:

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

Adicione --profile ID em “Exports” para um espaço de trabalho secundário. Utilize --url https://server para acesso remoto. O HTTP simples é aceito apenas para destinos de loopback. O token é lido a partir de um arquivo e enviado em um cabeçalho, não sendo exibido nem inserido em uma URL. Redirecionamentos são recusados. Destinos existentes não são sobrescritos. As transferências com falha removem seu arquivo parcial temporário. O SHA-256 relatado é uma soma de verificação da transferência; verifique o arquivo ZIP assinado separadamente com uma impressão digital/ponto de verificação confiável.

Backup, restauração e interrupções#

1. Pause a observação e interrompa o processo de forma limpa.
2. Copie todo o diretório de dados: bancos de dados, WAL/SHM, se houver, mídia, credentials.enc, signing.enc, network.enc, chaves/metadados do cofre, token, pontos de verificação e todos os diretórios profiles/.
3. Para o modo de chave externa, preserve separadamente a chave mestra e mantenha cada vault.external.json. A geração de uma nova chave não permite recuperar os segredos antigos.
4. Restaure enquanto o destino estiver parado; configure a chave original, restrinja o acesso e verifique a integridade antes de retomar.
5. Registre o tempo de inatividade e os resultados da verificação. Um instantâneo do histórico não pode comprovar que não ocorreram exclusões durante a interrupção.

Os arquivos ZIP de evidências excluem sessões e chaves privadas e não constituem backups completos do serviço. Quatro elementos são protegidos de maneira diferente:

Um backup completo corresponde ao diretório de dados suspenso descrito acima, e não a uma exportação. Utilize armazenamento protegido e um mecanismo de transferência controlado para ambos. As exportações temporárias do servidor ficam armazenadas no diretório temporary-exports/ de cada espaço de trabalho; as respostas concluídas são eliminadas, e os arquivos de exportação interrompidos são removidos na próxima inicialização, enquanto o bloqueio da instância desse espaço de trabalho estiver ativo.

A restauração da conexão não garante a recuperação de alterações intermediárias. Tarefas de mídia persistentes e a posição de atualização do Telegram sobrevivem à reinicialização; consulte o formato de evidência.

Capacidade e retenção#

Limites padrão, todos alteráveis em “Parâmetros”: as primeiras 1.000 conversas, 500 mensagens por instantâneo, 4 GiB de conteúdo ZIP assinado não compactado (arquivos maiores requerem verify.py --max-gib N) e um fallback do navegador de 128 MiB. Anexos ocupam de 1 a 2.000 MiB por tipo em Fontes → Anexos. A CLI de download tem como padrão 5 GiB transferidos. O espaço em disco disponível pode ser um limite inferior. Reserve espaço para registros, mídia, WAL, exportações temporárias e backups. As exportações utilizam o volume de dados em vez do limite de 512 MiB do Compose (/tmp).

Meça eventos por segundo, tempo de espera na fila, bytes de mídia e latência do disco, em vez de contar apenas os grupos. Benchmarks locais sintéticos não garantem a entrega no Telegram. Não há exclusão automática de retenção. A remoção da parte final de um registro invalida sua relação com os pontos de verificação retidos.

Já existem verificações prioritárias: as fontes marcadas com estrela são verificadas a cada 15 minutos por padrão, as demais a cada 6 horas (consulte os níveis de verificação). Existem exportações protegidas por senha, conforme descrito acima. Aceitação em tempo real do Telegram/proxy, reprodução duradoura, registro de administração e sondagem de reações, workers isolados, criptografia do registro local e da mídia pelo próprio TgWitness e revisão independente continuam sendo trabalhos separados. O acesso restrito está documentado em “Acesso e permissões”. Consulte READINESS.md, LIVE_ACCEPTANCE.md e VERIFICATION.md.