# Telegram · Introdução rápida

Canonical page: https://phishdestroy.io/tgwitness/pt/docs/reference/quickstart/

Todas as formas de instalar e executar o TgWitness: pacote para Windows, Python, Docker e a demonstração sintética, com as primeiras verificações.

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/pt/llms.txt)

Todas as formas de instalar e executar o TgWitness: pacote para Windows, Python, Docker e a demonstração sintética, com as primeiras verificações.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentação](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![Introdução](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2)

**Inglês** · [Русский](https://github.com/phishdestroy/TgWitness/blob/main/docs/ru/QUICKSTART.md) · [Ucraniano](https://github.com/phishdestroy/TgWitness/blob/main/docs/uk/QUICKSTART.md) · [Espanhol](https://github.com/phishdestroy/TgWitness/blob/main/docs/es/QUICKSTART.md) · [Português (Brasil)](https://github.com/phishdestroy/TgWitness/blob/main/docs/pt/QUICKSTART.md) · [Türkçe](https://github.com/phishdestroy/TgWitness/blob/main/docs/tr/QUICKSTART.md) · [العربية](https://github.com/phishdestroy/TgWitness/blob/main/docs/ar/QUICKSTART.md) · [فارسی](https://github.com/phishdestroy/TgWitness/blob/main/docs/fa/QUICKSTART.md) · [Urdu](https://github.com/phishdestroy/TgWitness/blob/main/docs/ur/QUICKSTART.md) · [Hindi](https://github.com/phishdestroy/TgWitness/blob/main/docs/hi/QUICKSTART.md) · [Bahasa Indonesia](https://github.com/phishdestroy/TgWitness/blob/main/docs/id/QUICKSTART.md) · [Tiếng Việt](https://github.com/phishdestroy/TgWitness/blob/main/docs/vi/QUICKSTART.md) · [Chinês simplificado](https://github.com/phishdestroy/TgWitness/blob/main/docs/zh/QUICKSTART.md)

O TgWitness é um aplicativo independente para monitorar grupos e canais do Telegram aos quais suas contas têm acesso. Ele é executado localmente com seu próprio diretório de dados.

**É sua primeira visita?** [Explore a demonstração](https://phishdestroy.io/tgwitness/pt/docs/reference/quickstart/#explore-the-interface) antes de conectar uma conta. [Escolha um guia](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) para proxies, testemunhas, exportações ou configuração de servidor. [O GitHub Actions capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md) (pré-visualização) executa uma captura em seu próprio fork do GitHub, em vez de uma instalação local.

## Instale e inicie

O instalador guiado inclui seu próprio Python e verifica os hashes dos pacotes e as assinaturas de versão antes da instalação. Executá-lo novamente atualiza uma instalação existente.

**Linux / macOS:**

```
curl -fsSL https://get.destroy.tools/install.sh | bash
```

**Windows (PowerShell ou Prompt de Comando):**

```
powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex"
```

Em um servidor Ubuntu, execute como root para instalar um serviço em segundo plano; em um desktop, execute como seu usuário normal. No Ubuntu, o instalador exibe o endereço do painel e a chave de acesso; no macOS e no Windows, o painel local abre no seu navegador. Continue em **Conectar o Telegram** abaixo. A seção [Instalar, verificar e atualizar](https://phishdestroy.io/tgwitness/pt/docs/reference/installation/) aborda as opções de acesso ao servidor, a verificação do script antes de executá-lo, as atualizações e a remoção.

### Outros métodos

Lançamentos no GitHub, o código-fonte e o Docker são alternativas ao instalador. Os downloads portáteis ficam disponíveis após a publicação de uma versão de lançamento:

| Hospedagem | Nada instalado | Fonte: Python 3.11+ | Docker: Engine/Desktop com Compose 2.20+ |
| --- | --- | --- | --- |
| Windows | Extraia o `TgWitness-<version>-windows-amd64-portable.zip` das versões do GitHub e clique duas vezes no `TgWitness.cmd` | Clique duas vezes em `Start.cmd` | Clique duas vezes em `scripts\Docker.cmd` |
| Linux / macOS | — | `sh start.sh` | `sh scripts/docker-start.sh` |

Para os métodos a partir do código-fonte, [baixe e extraia a branch `main` atual](https://github.com/phishdestroy/TgWitness/archive/refs/heads/main.zip) ou clone o repositório:

```
git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness
```

O `Start.cmd` oferece a instalação do Python 3.12 para o seu usuário do Windows caso nenhuma versão adequada do Python seja encontrada (via winget ou pelo instalador assinado do python.org). O `start.sh` exibe o comando exato de instalação para a sua distribuição Linux ou macOS se o Python estiver ausente. A primeira execução a partir do código-fonte cria o `.venv` e instala as dependências automaticamente.

O Docker compila o aplicativo e o inicia em segundo plano; não é necessário um host Python. `scripts\Docker.cmd` e `scripts/docker-start.sh` exibem o endereço do painel e o token quando o contêiner está em bom estado. Os comandos equivalentes do Docker em todos os hosts compatíveis são:

```
docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt
```

Acesse **http://127.0.0.1:8787**. Utilize o token gerado pelo auxiliar do Docker ou pelo segundo comando do Docker, ou consulte **o arquivo data/live/panel-token.txt** para uma instalação portátil ou de código-fonte. Continue na seção **“Conectar o Telegram”** abaixo. As instalações nativas e via Docker utilizam armazenamento separado; iniciar o Docker não importa um diário nativo existente.

No que diz respeito ao servidor, [a implantação](https://phishdestroy.io/tgwitness/pt/docs/reference/deployment/) abrange HTTPS automático, reinicialização, imagens publicadas, atualizações e backups.

## Explore a interface

1. Execute **o arquivo `TgWitness-Demo.cmd`** no pacote portátil, **o `scripts\Demo.cmd`** na pasta de origem do Windows ou o ``sh start.sh --demo` ` no Linux/macOS. Ao executar o arquivo de origem, o sistema cria primeiro o ``.venv` ` e instala as dependências.
2. Acesse **http://127.0.0.1:8787**.
3. A demonstração local abre automaticamente o diário de amostra. Não é necessária nenhuma cópia do token para acesso local direto.

As mensagens de demonstração são fictícias. O modo de demonstração não permite conectar uma conta real do Telegram.

## Conectar-se ao Telegram

> [!AVISO] **Use contas dedicadas.** O Telegram pode restringir ou banir permanentemente contas por volumes de solicitações que considere excessivos, independentemente do cliente. Conecte contas preparadas para observação, em vez de contas pessoais ou valiosas, e crie um ID de API / hash em uma conta dedicada.

1. Caso a demonstração nativa esteja em execução, interrompa-a e execute **o Start.cmd** ou o `sh start.sh`. Caso contrário, mantenha em execução a instalação ao vivo iniciada acima.
2. Use o token do painel para fazer login. Um novo espaço de trabalho é aberto [na primeira configuração](https://phishdestroy.io/tgwitness/pt/docs/reference/settings/). Escolha **Apenas baixar**, **Acompanhar chats** ou **Evidências para um caso**.
3. Verifique a conexão. Configure seu próprio proxy, se necessário; as configurações de conexão permanecem disponíveis após a instalação.
4. No **Connect Telegram**, escolha um número de telefone, um código QR, arquivos de conta (TData, `.session`, StringSession, JSON da conta) ou uma chave de autorização completa. Preencha a confirmação do Telegram, o código e a senha de duas etapas quando solicitado.
5. Verifique a conta exibida, escolha os chats e revise suas configurações. Conclua na tela final. Para **a opção Apenas baixar**, **Iniciar exportação** inicia uma exportação única e abre a seção Exportações para mostrar seu andamento; isso não habilita a observação contínua.

Após a configuração, **Bate-papos → Escolher** altera os bate-papos selecionados. **Configurações** controla a coleta e os arquivos; **Mais ferramentas → Fontes** fornece a lista detalhada de fontes nos níveis Padrão ou Avançado. O [guia do painel](https://phishdestroy.io/tgwitness/pt/docs/reference/panel/) descreve as seis principais seções e seus controles contextuais.

**O ID da API + Hash** é opcional: o espaço de trabalho usa seu par salvo ou importado, ou um par ativo do conjunto integrado. Para usar seu próprio aplicativo, cole um par `API ID:API Hash` no campo ID da API. Para **a chave de autenticação**, cole todos os 512 caracteres hexadecimais e selecione o ID do DC fornecido. O ID do usuário é opcional e é verificado caso seja inserido.

As credenciais da API identificam seu aplicativo; elas não autorizam uma conta por si só. Grupos privados não exigem nome de usuário público, mas sua conta deve ter acesso.

Para contas existentes, consulte [os formatos de contas e sessões](https://phishdestroy.io/tgwitness/pt/docs/reference/accounts/): o painel aceita Telethon StringSession, Telethon/Pyrogram SQLite, TData ZIP de conta única e JSON de conta compatível. Selecione uma sessão e seu JSON correspondente juntos, clique em **Verificar arquivos** e, em seguida, em **Conectar conta**. O login por QR também está disponível com as mesmas configurações opcionais da API. TDLib, sessões de bots e inventários de contas em CSV/JSON não são suportados.

Para várias contas, use **Contas → Importar contas** e selecione os arquivos de sessão compatíveis. Os arquivos JSON complementares são pareados pelo nome-base; cada conta importada recebe seu próprio espaço de trabalho. Veja [importação em massa e grupos de contas](https://phishdestroy.io/tgwitness/pt/docs/reference/accounts/#bulk-import-and-account-groups).

Para adicionar outra conta, pressione **+** ao lado do seletor de contas ou use **Contas → Adicionar conta**. Os espaços de trabalho possuem sessões, diários, chaves, fontes e filas separadas. A troca de visualizações mantém os outros coletores em execução. A mesma conta do Telegram não pode ser atribuída a dois espaços de trabalho nesta instalação. Não há um número fixo de espaços de trabalho; eles compartilham um único processo, portanto a capacidade depende da máquina.

O token do painel ao vivo protege o acesso às suas autorizações do Telegram e ao material salvo; ele é independente das credenciais da API do Telegram. Apenas uma demonstração local iniciada explicitamente e acessada diretamente recebe acesso automático. Uma demonstração remota ou via proxy continua utilizando o `data/demo/panel-token.txt`.

## Revisão e exportação

- **Registro:** pesquise e filtre observações por fonte e tipo de evento.
- Selecione um evento para examinar seu registro original, atribuição e versões salvas.
- Os detalhes da edição mostram o conteúdo disponível antes e depois. Os detalhes da exclusão mostram o último conteúdo capturado, se houver; um agente desconhecido permanece desconhecido.
- **Formatos de exportação:** ZIP assinado, JSONL, CSV e HTML offline.
- **Exportação completa do chat** (**Chats → Exportar chat**, ou **Exportações → Capturar ou exportar um chat**): baixe todo o histórico visível de um chat como um pacote assinado com `chat.json` (estilo de exportação do Telegram) e um arquivo legível `chat.html`. Chats privados funcionam quando a conta é membro. Trata-se de um instantâneo atual, não de uma reconstrução de mensagens excluídas ou editadas anteriormente. Verifique uma cópia com `python verify.py chat-export.zip --fingerprint TRUSTED_SHA256`.
- **Ponto de verificação:** mantenha o limite do registro assinado fora do coletor.
- **Baixe o comprovante de execução assinado:** preserve o registro do programa e da versão do coletor.
- **Prepare uma solicitação de carimbo de data e hora:** prepare uma solicitação offline para uma autoridade de carimbo de data e hora; siga as instruções do arquivo [TIMESTAMP.md](https://phishdestroy.io/tgwitness/pt/docs/reference/timestamp/) para obter e verificar uma resposta.
- **Verificar o registro:** verifique as assinaturas dos eventos e os elos da cadeia. A exportação em ZIP também verifica os arquivos de mídia.

Os navegadores compatíveis salvam exportações de grande porte diretamente em um arquivo escolhido. Outros navegadores armazenam em buffer no máximo 128 MiB. Enquanto o servidor estiver em execução, a CLI de streaming suporta downloads maiores sem armazenar toda a resposta em buffer:

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

Para outro espaço de trabalho, adicione `--profile ID` usando **Exportações → ID do espaço de trabalho**. Para um servidor remoto, adicione `--url https://your-server`. O limite padrão de transferência é de 5 GiB; `--max-mib` altera esse valor. O conteúdo ZIP assinado tem um limite de verificação separado de 4 GiB descompactado por padrão (**Mais ferramentas → Parâmetros** aumenta esse limite; verifique esses arquivos com `verify.py --max-gib N`). Verifique o arquivo usando uma cópia confiável do verificador, uma impressão digital da chave mantida de forma independente e, no mínimo para fins de evidência, o certificado raiz da autoridade de carimbo de data/hora (`--tsa-ca`).

## Verifique a instalação

```
python start.py --setup-only
python start.py --check
python start.py --check --json
```

O `--check` verifica dependências locais, suporte à assinatura, armazenamento, configuração de chaves e o endereço de escuta. Ele não instala nada nem se conecta ao Telegram. Uma porta ocupada pode significar que outra instância está em execução. Utilize um `--port` diferente ou interrompa-a primeiro.

O iniciador é instalado no `.venv`. Os comandos auxiliares `python -m tgwitness...` devem utilizar o `.venv\Scripts\python.exe` no Windows ou o `.venv/bin/python` no Linux/macOS, a menos que esse ambiente já esteja ativado.

## Sessões, proteção e operação

Um `.session` do Telethon SQLite, fechado e consistente, pode ser convertido localmente com `python -m tgwitness.sessions account.session --out account.tgwitness-session` e, em seguida, carregado em **Mais ferramentas → Conta → Arquivos**. A importação direta de arquivos e o login por QR também estão disponíveis. Consulte [CONNECTION-SECURITY.md](https://phishdestroy.io/tgwitness/pt/docs/reference/connection/) para formatos de login, SOCKS5, HTTP CONNECT, MTProxy e chaves-mestre externas.

**A pausa na observação** interrompe a coleta. **O bloqueio** apenas interrompe o acesso pelo navegador. Fechar uma aba mantém o processo de coleta em execução. Interromper o processo interrompe a coleta; um instantâneo do histórico não pode reconstruir todas as edições ou exclusões perdidas. Veja [como funciona a coleta](https://phishdestroy.io/tgwitness/pt/docs/reference/collection/) em relação a políticas de eventos, filas de anexos, isolamento de contas e comportamento de reinício.

Sessões e segredos são criptografados. O conteúdo das mensagens, mídias e exportações exigem um disco ou volume criptografado. Verifique as assinaturas do diário em relação a uma chave confiável e mantenha os pontos de verificação separadamente. Analise os registros de captura, recibos de tempo externos e atestados de ambiente para o modo de coleta selecionado.

Leia [o arquivo OPERATIONS.md](https://phishdestroy.io/tgwitness/pt/docs/reference/operations/) para informações sobre backup/restauração, [o arquivo DEPLOYMENT.md](https://phishdestroy.io/tgwitness/pt/docs/reference/deployment/) para hospedagem e [a pasta deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md) para exemplos de uso do serviço. O painel instalado também inclui um guia de configuração offline em `/guide.html`.

A verificação efetiva e as limitações remanescentes estão registradas nos arquivos [VERIFICATION.md](https://phishdestroy.io/tgwitness/pt/docs/reference/verification/) e [READINESS.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/READINESS.md).
