Bxio
90dcbf895c
All checks were successful
Testar e publicar imagem Docker / publish (push) Successful in 26s
53 lines
4.7 KiB
Markdown
53 lines
4.7 KiB
Markdown
# TS6 Botflow
|
|
|
|
Painel local XanaX para gerir bots TeamSpeak, com login Discord e editor visual de flows. Mantém os logótipos originais e o tema flat roxo. As pastas dos projetos de origem permanecem intactas.
|
|
|
|
## Funcionalidades
|
|
|
|
- Dashboard com bots, flows e execuções guardados na base de dados.
|
|
- Editor com blocos arrastáveis, ligações, condições, propriedades, zoom e gravação.
|
|
- Blocos: temporizador, início manual, informações do servidor, clientes, ordenação, limite, preparação de texto, edição da descrição de canal, mensagem, espera e registo.
|
|
- Simulação identificada com dados de exemplo, sem enviar pedidos ao TeamSpeak.
|
|
- Execução manual ou por temporizador, com histórico e resultado de cada passo. Um bot não executa duas vezes em simultâneo.
|
|
- Ligações WebQuery, teste de ligação e API keys cifradas em repouso.
|
|
- Variáveis por bot: `{{variables.nome}}`. Outros valores: `{{server.virtualserver_clientsonline}}`, `{{count}}`, `{{top}}`, `{{text}}` e `{{time}}`.
|
|
- Subtração de duas variáveis numéricas no texto: `{{server.virtualserver_clientsonline - server.virtualserver_queryclientsonline}}` mostra o total online sem os clientes Query. O bloco Informações do servidor deve executar antes. Valores em falta ou não numéricos são assinalados no histórico como erro.
|
|
|
|
O primeiro arranque cria um rascunho **Estatísticas**, desativado, para atualizar a descrição do canal **21** a cada 30 segundos. O top inicial ordena as pessoas atualmente online pela data de entrada; não é um ranking histórico de tempo acumulado.
|
|
|
|
Esta versão não inclui reprodução de música, eventos SSH, webhooks, edição de permissões nem gestão de perfis pelo painel. Cada bot tem um flow. O editor disponibiliza os blocos implementados acima.
|
|
|
|
## Docker / Portainer
|
|
|
|
Para Web editor com imagem construída no Gitea, consultar [deploy/README.md](deploy/README.md) e usar [deploy/bot-stack.yaml](deploy/bot-stack.yaml). Cada push em `main` executa os testes e publica a imagem. Depois do workflow verde, atualizar a stack no Portainer com download da imagem e recriação do container. Restart sozinho não descarrega a nova imagem.
|
|
|
|
Para construir localmente com Docker Compose, usar `compose.yaml`. A aplicação escuta na porta 3080 e preserva os dados num volume montado em `/app/data`.
|
|
|
|
Variáveis de ambiente:
|
|
|
|
- `APP_URL`: endereço do navegador, por exemplo `http://192.168.88.99:3080`.
|
|
- `DISCORD_CLIENT_ID`: ID da aplicação Discord.
|
|
- `DISCORD_CLIENT_SECRET`: segredo OAuth da aplicação.
|
|
- `OWNER_DISCORD_ID`: IDs numéricos dos donos, separados por vírgulas. A stack inclui `376768118535749633,723613831196311603`. Um único ID continua a ser aceite.
|
|
- `ALLOWED_DISCORD_IDS`: IDs de leitores separados por vírgulas. Por defeito, não há leitores. Um ID presente nas duas listas recebe o perfil Dono.
|
|
|
|
No Discord Developer Portal, adicionar o redirect exato `http://192.168.88.99:3080/auth/discord/callback`, ajustando ao `APP_URL`. O navegador e o container precisam de Internet para o OAuth; o site pode continuar apenas na rede local.
|
|
|
|
O **Dono** pode configurar, guardar, simular e executar. O **Leitor** pode consultar. Outras contas são recusadas; as permissões são também verificadas no servidor.
|
|
|
|
## Ligar ao TeamSpeak
|
|
|
|
Entrar com a conta do dono. Em **Ligações**, configurar o endereço WebQuery HTTP/HTTPS, o ID do servidor virtual e a API key TeamSpeak. Por exemplo, `http://teamspeak6:10080` funciona quando ambos os containers partilham uma rede Docker com esse nome resolvível. Testar a ligação, escolher esse servidor na configuração do bot, simular e só depois ativar.
|
|
|
|
O temporizador aceita intervalos a partir de um segundo. A execução seguinte aguarda a conclusão da anterior; pedidos de rede e blocos de espera podem prolongar o intervalo efetivo. A configuração de permissões e proteção contra flood do TeamSpeak deve permitir os pedidos do bot.
|
|
|
|
Sessões e flows usam SQLite no volume. A chave de cifra das API keys fica em `/app/data/credentials.key`; preservar o volume completo nas cópias de segurança. O histórico retém as últimas 500 execuções. Não adicionar `.env` nem dados ao Git.
|
|
|
|
## Desenvolvimento e validação
|
|
|
|
Node 22.15+, mesmas variáveis de ambiente e `npm start`. Executar `npm test` para verificar autenticação, restrições de acesso, persistência, simulação e execução WebQuery com transporte de teste. O build Docker executa os testes antes da publicação.
|
|
|
|
O editor foi verificado em navegador desktop e móvel. A execução no TeamSpeak real depende da ligação e API key configuradas na instalação; os testes locais não alteram o servidor real.
|
|
|
|
A fonte Public Sans é distribuída em `public/fonts` com a licença OFL. Os logótipos foram copiados sem alterações do projeto existente.
|