Banco de dados e bridge

Leituras suportadas#

A conexão vem ligada por padrão em todos os servidores e não precisa de linha no server.cfg. Para desligá-la em um servidor, abra-o em Servidores e use “Disable connection” no cartão Tosun Connect; o mesmo cartão a liga de novo. Com set tosun_db_bridge_manual "1" no server.cfg, tosun_db_bridge_enabled e tosun_db_bridge_money_write são lidos do server.cfg como antes, e cada um fica desligado se não for "1". Se o espelho completo antigo foi ativado de propósito (ts.panelMirror.enabled = true em configs/anticheat_config.lua), a bridge fica desligada para que esse espelho continue funcionando. Estruturas QBCore/ESX compatíveis oferecem dados selecionados de jogadores, inventário, veículos e registros. Não é um navegador completo do banco.

Consultas limitadas e edição de saldo#

Em repouso consulta o painel via HTTPS a cada cerca de 10 segundos, sem consultar o banco do jogo. Até 25 resultados por página e uma tarefa por vez. A edição de saldo online (definir pelo painel o dinheiro em mãos ou no banco de um personagem conectado) vem ligada por padrão. Podem usá-la usuários do painel com papel admin ou owner (permissão de economia). O personagem precisa estar online e o saldo atual esperado precisa conferir; caso contrário, retorna stale_balance e nada muda. O painel mostra um resumo para confirmação antes de enviar, e cada pedido vai para o registro de auditoria. Define o total, não soma. Resultado incerto nunca é repetido automaticamente; confira primeiro o saldo no jogo. Para parar as leituras e a edição de saldo em um servidor, use “Disable connection” no cartão Tosun Connect. Para manter as leituras sem edição de saldo, use o modo manual: set tosun_db_bridge_manual "1" e set tosun_db_bridge_enabled "1", sem set tosun_db_bridge_money_write "1".

Conectar pelo servidor existente#

A ponte usa a conexão oxmysql atual. O painel envia tarefas compatíveis por HTTPS; o servidor executa localmente e devolve dados selecionados. Não precisa copiar a senha MySQL para o site nem abrir a porta do banco para a internet.

1. A conexão vem ativada por padrão em todos os servidores; com tosun-ac 9.6.14 ou posterior, não é preciso ativá-la. Para desligá-la em um servidor: Servidores → o servidor → cartão Tosun Connect → “Disable connection”. Se o espelhamento completo antigo estiver ativado de propósito com ts.panelMirror.enabled = true em configs/anticheat_config.lua, a ponte fica desligada automaticamente para que o espelhamento antigo continue funcionando.
2. Com tosun-ac 9.6.14 ou posterior, nenhuma linha no server.cfg é necessária para a conexão; mantenha apenas set tosun_ac_license com a licença correta. As linhas antigas tosun_db_bridge_enabled e tosun_db_bridge_money_write passam a ser ignoradas e podem ser apagadas; um servidor que ainda usa um pacote anterior precisa delas até o novo pacote ser instalado. A edição de saldo online também vem ativada por padrão e fica restrita a usuários do painel com papel admin ou owner.
3. Permita HTTPS de saída para admin.tosundev.com, verifique o console e solicite uma lista pequena de jogadores.

# Execute no console do servidor:
tosunac_db_status

Site da comunidade só com a licença#

O site da sua comunidade lê os dados do jogo pela mesma conexão Tosun Connect. Se o servidor não tiver configurações de banco de dados do jogo no painel, o site não precisa de usuário MySQL, GRANT nem da porta 3306 aberta: as páginas Jogadores, Banimentos, Detecções do anticheat e Logs carregam os dados do servidor de jogo quando são abertas.

Neste modo o site não pode pesquisar, filtrar, desbanir, adicionar banimentos nem editar dinheiro e inventários. Para remover um banimento, use /ts unban <banID> no jogo ou ts unban <banID> no console do servidor. Cada página é uma nova solicitação respondida em cerca de 10 segundos; se o servidor de jogo estiver offline ou a conexão estiver desligada no cartão Tosun Connect, a página informa isso em vez de mostrar uma lista vazia.

Nomes, empregos, saldos, inventários e modelos de veículos exigem tosun-ac 9.6.17 ou superior no servidor de jogo. Com pacotes antigos, alguns servidores MySQL/MariaDB retornam apenas o ID do personagem.

A conexão direta com o banco de dados do jogo é opcional. Adicione-a só se quiser pesquisa e edição no site: crie um usuário de banco de dados que só possa se conectar a partir do endereço IP do servidor do painel Tosun (o suporte pode confirmá-lo), conceda SELECT, INSERT, UPDATE e DELETE no banco do jogo, libere a porta 3306 apenas para esse endereço e informe os dados nas configurações de banco de dados do servidor em Servidores (Direct MySQL · Advanced). O painel só os salva após um teste de conexão bem-sucedido. Sem esses dados, a configuração só com licença continua em uso.

• Jogadores: 25 personagens por página com ID do personagem, nome e emprego. A equipe também vê dinheiro e banco.
• A equipe (moderador ou acima) pode clicar em um personagem para ver o status online, os saldos e o inventário, e carregar os veículos desse personagem.
• Banimentos e detecções do anticheat: 25 registros por página, somente leitura. As detecções aparecem da mais antiga para a mais recente; os banimentos, na ordem do ID de banimento.
• Os totais do painel inicial para jogadores, banimentos e detecções mostram “—”: a conexão não tem operação de contagem, então nenhum número é estimado.

Dados disponíveis e limites#

Leituras incluem jogadores, detalhes de personagem, seus veículos, banimentos e detecções. QBCore/Qbox normalmente usam players e player_vehicles; ESX users e owned_vehicles. Colunas e índices precisam ser compatíveis. ready não comprova que uma tabela personalizada pode ser lida.

Inventários retornam campos selecionados, dados armazenados limitados e até 100 entradas percorridas. Metadados arbitrários, stashes e todas as tabelas próprias não são espelhados. Um inventário truncado é parcial: ausência no resultado não prova ausência de item. Use as ferramentas do inventário do jogo para investigação completa.

Entender estado e carga#

Em repouso consulta o painel aproximadamente a cada dez segundos sem ler o banco do jogo. Só uma tarefa executa por vez. Páginas têm até 25 resultados e cursor; avance em vez de recarregar a primeira página. Metadados solicitados ficam em cache cinco minutos.

• oxmysql_unavailable: confira início e conexão.
• unsupported_framework / schema_unavailable: verifique framework, tabelas e colunas.
• unsupported_index: peça revisão da chave necessária; não adicione índices às cegas em um servidor ocupado.
• request_expired / estado antigo: confira conectividade e idade antes de nova leitura.

• Frameworks
• Medir desempenho

Alterar saldos conscientemente#

A edição de saldo online vem ativada por padrão. Usuários do painel com papel admin ou owner (permissão de economia) podem definir o dinheiro ou o banco de um personagem online compatível depois de ver o resumo de confirmação. Define saldo absoluto, sem somar a quantia a cada repetição. O saldo atual esperado é comparado; se não bater, retorna stale_balance e nada muda. Cada pedido é registrado no log de auditoria.

Não há alternativa de SQL offline. A operação incerta permanece registrada para evitar repetição automática. Não dê o papel admin ou owner a funcionários que só inspecionam. Para parar a edição de saldo em um servidor, use “Disable connection” no cartão Tosun Connect dele (isso também para as leituras) ou o modo manual com set tosun_db_bridge_manual "1": tosun_db_bridge_enabled e tosun_db_bridge_money_write passam a ser lidos do server.cfg e cada um fica desligado a menos que esteja em "1".

1. Leia personagem e saldo, confirme o valor final e execute uma vez.
2. Com stale_balance, releia: o jogador pode ter gasto ou recebido dinheiro.
3. Com unknown_outcome, pare e compare saldo ao vivo e registros. Não repita sem esclarecer o primeiro resultado.

• API e credenciais

Separar listas guardadas de detalhes atuais#

A lista de jogadores lê linhas guardadas de personagens; não é um fluxo contínuo ao vivo. O detalhe pode substituir saldos guardados por valores online do framework suportado e ler os itens atuais desse jogador no ox_inventory, quando disponíveis. Selecione character_id permanente, não um número de sessão lembrado. No painel, confira saldos indisponíveis e o aviso de inventário incompleto antes de interpretar zeros ou assumir lista completa. Desenvolvedores podem examinar os indicadores balance_available e inventory_truncated correspondentes. Campo indisponível ou inventário parcial não comprova dinheiro ou objetos perdidos. Os veículos mostram campos armazenados selecionados, sem provar que o veículo esteja gerado ou numa sessão de garagem ativa.

1. Compare um personagem conhecido com o jogo num horário registrado, incluindo estado online e conta escolhida.
2. Se houver diferença, confira identidade, consulta de lista ou detalhe e indicadores de disponibilidade antes de agir.
3. Após reconectar ou trocar personagem, solicite novo detalhe em vez de reutilizar o resultado anterior.

Paginar investigações em vez de despejar a base#

A fila aceita três solicitações pendentes ou assumidas por servidor e doze novas por minuto. Um trabalho vale por 120 segundos; resultados são temporários e ficam elegíveis para limpeza cinco minutos após a expiração do trabalho, sem horário de exclusão garantido. Os limites servem à administração dirigida, não à coleta automática completa. Use os controles de paginação do painel; desenvolvedores seguem has_more e next_cursor só na mesma operação e personagem. Uma página seguinte vazia difere de uma consulta falhada. Chaves únicas e índices de proprietário de veículos são verificados para recusar estruturas incompatíveis com segurança. Não renomeie colunas ou adicione índices em produção apenas para silenciar erros sem avaliar aplicação e plano de consulta.

1. Leia uma página do painel por vez. Numa integração própria, guarde cursor e operação juntos e avance só quando has_more for verdadeiro.
2. Em queue_full ou rate_limited, aguarde trabalhos abertos em vez de reabrir as mesmas telas repetidamente.
3. Peça ao responsável pela base que avalie unsupported_index numa cópia; metadados podem ficar em cache cinco minutos.

Pausar acesso sem apagar operações incertas#

Para inspeção, conceda só as leituras necessárias; apenas os papéis admin e owner podem editar saldos. Para parar a conexão de um servidor, abra Servidores → o servidor → cartão Tosun Connect e escolha “Disable connection”; isso para todas as leituras e edições de saldo desse servidor, e o mesmo cartão a reativa. Se precisar de leituras sem edição de saldo, use o modo manual: adicione set tosun_db_bridge_manual "1" e set tosun_db_bridge_enabled "1" ao server.cfg e deixe tosun_db_bridge_money_write sem definir ou em "0". No modo manual, os dois valores são lidos do server.cfg e cada um fica desligado a menos que esteja em "1"; por isso, o modo manual sem set tosun_db_bridge_enabled "1" também interrompe as leituras. O painel marca trabalhos pendentes ou assumidos como falhados; uma escrita de dinheiro assumida recebe unknown_outcome porque o efeito pode ter ocorrido. O registro de operações do jogo não é cache descartável. Apagar KVP para forçar nova tentativa pode remover a evidência contra repetição. Revise também o acesso aos dados capturados: o bridge não torna privados imagens ou logs compartilhados publicamente.

1. Antes de desconectar, deixe leituras terminarem e investigue dinheiro incerto usando saldo atual e auditoria.
2. Depois confira painel e tosunac_db_status; não apresente uma nova inspeção enfileirada como concluída.
3. Ao reativar pelo cartão, comece com uma leitura e não edite saldos até revisar permissões, capacidades e operações incertas.

# Server console / Sunucu konsolu:
tosunac_db_status

Verifique o esquema sem alterar dados dos jogadores#

Para schema_unavailable ou unsupported_index, confirme primeiro que está selecionado o banco realmente usado pelo jogo. O exemplo abaixo lê somente nomes e tipos de colunas; não altera saldos, inventários ou veículos. Esta não é uma etapa obrigatória de instalação. Um administrador de banco autorizado pode executá-lo na sua ferramenta privada habitual ao investigar o erro. Não envie SQL à ponte do painel: ela aceita apenas operações definidas.

As leituras QBCore/Qbox exigem citizenid, money, job e charinfo em players; ESX exige identifier, accounts e job em users. Encontrar a tabela não basta. A chave do personagem deve ter um tipo compatível e um índice único de uma única coluna completa.

As leituras de veículos também verificam índices adequados ao proprietário e à chave do veículo. Isso evita forçar consultas caras. Não renomeie uma tabela de garagem personalizada para esconder o erro; peça antes aos desenvolvedores da garagem e do framework uma avaliação de compatibilidade.

• Anote o código do erro, versão do framework e leitura afetada.
• Compare colunas e índices; não envie linhas de jogadores ao suporte.
• Avalie mudanças numa cópia de teste. O cache do esquema pode não reconhecer a nova estrutura imediatamente.

SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
  AND TABLE_NAME IN ('players', 'users', 'player_vehicles', 'owned_vehicles')
ORDER BY TABLE_NAME, ORDINAL_POSITION
LIMIT 128;

O personagem aparece, mas a lista de veículos está vazia#

Imagine que um personagem selecionado na lista abre corretamente, mas nenhum veículo aparece. Diferencie primeiro um resultado concluído com sucesso de uma tarefa que falhou. Uma lista vazia bem-sucedida significa que essa leitura não retornou registros correspondentes; não prova que o jogador não tenha veículos em nenhum sistema. query_failed, schema_unavailable e unsupported_index não são listas vazias.

Confirme que selecionou o mesmo character_id permanente. Um número de sessão que muda ao reconectar não substitui a chave do personagem. QBCore/Qbox identifica o proprietário por player_vehicles.citizenid; ESX usa owned_vehicles.owner. Se uma garagem personalizada usa outra tabela ou outro formato, a ponte padrão não descobre esses registros automaticamente.

Selecionar o personagem errado numa conta com vários personagens pode causar sintoma semelhante. Peça ao responsável autorizado pela garagem que verifique o registro de um veículo conhecido no jogo. Alterar saldos, recriar veículos ou limpar a tabela original não é necessário para o diagnóstico.

• Registre ID do servidor, referência do personagem parcialmente ocultada, horário e status da tarefa.
• Se houver outra página, continue com o mesmo personagem; não transfira o cursor para outro.
• Informe ao suporte se houve uma lista vazia bem-sucedida ou um código exato de erro; remova dados pessoais.

Separe números, texto e campos indisponíveis#

A ponte não reproduz uma linha bruta; normaliza campos suportados para tipos e comprimentos definidos. Dinheiro de personagem é lido de números JSON. Por exemplo, 1200 e "1200" têm tipos armazenados diferentes; um script convertendo dinheiro em texto pode tornar o saldo indisponível. Saldo indisponível aparece como — no painel; isso não significa saldo zero. O inventário seleciona nome, rótulo, quantidade, slot e qualidade; metadados arbitrários, conteúdo de stash e contas empresariais ficam fora desse resultado.

Valores selecionados de veículo, como combustível, motor e estado, podem voltar como texto; não calcule comparações só pela formatação. O comprimento de esquema char/varchar das chaves suportadas é no máximo 96; a chave transmitida também se limita a 96 bytes, um limite diferente para caracteres multibyte; int, bigint e mediumint também são aceitos. Uma chave binária própria não é presumida padrão. Textos longos e inventário podem ser truncados; omissão não significa exclusão. Peça confirmação do formato original antes de diagnosticar campo ausente. Avalie conversões pelo contrato de dados do jogo em testes, sem alterar produção apenas para preencher a tela.

Conclua a escrita com um exemplo concreto#

Numa correção autorizada e aprovada, imagine elevar o dinheiro de um personagem conectado de 1200 para 1250. O total final é 1250; digitar 50 define cinquenta no saldo em vez de acrescentar cinquenta. Confira dinheiro ou banco e relacione a identidade persistente ao detalhe recente ao vivo. A confirmação mostra personagem, conta e passagem do valor atual ao novo total. O valor final é inteiro não negativo; moedas próprias e saldos empresariais não substituem essa operação.

Não encerre a aceitação quando entra na fila. Verifique no resultado concluído o mesmo personagem e conta com before=1200 e after=1250, depois leia normalmente o estado atual. Gastos posteriores podem alterá-lo sem justificar reenvio automático. Investigue a suposição desatualizada de stale_balance e o efeito não verificado de unknown_outcome. Guarde referência, horário e resumo sem dados sensíveis. Havendo incerteza, não envie nova escrita antes de reavaliar saldo real e objetivo da correção.

Um prazo de resposta não cancela o SQL#

A espera padrão por uma resposta SQL é de 5.000 ms. query_timeout encerra a espera do painel; a consulta real ainda pode estar em execução. A capacidade SQL continua ocupada até o primeiro callback real, e outra leitura retorna query_busy. Uma resposta atrasada não altera a visualização anterior. Se nenhum callback chegar, o prazo não libera a capacidade automaticamente. O administrador do servidor deve verificar a conexão e o banco de dados; reiniciar o recurso não prova que o SQL foi cancelado.

Somente o proprietário do servidor pode, se quiser, adicionar a linha set abaixo ao server.cfg. O valor é limitado a 1.000–10.000 ms; um número inválido ou infinito usa 5.000 ms. Esta configuração não acelera o SQL nem repete consultas automaticamente.

A edição de saldo online vem ativada por padrão para usuários do painel com o papel admin ou owner (permissão de economia); no modo manual (set tosun_db_bridge_manual "1") ela fica desligada a menos que tosun_db_bridge_money_write seja "1". Exige um personagem compatível online e confirmação no painel. A operação substitui apenas o total em dinheiro ou banco depois de verificar o saldo atual esperado; nunca recorre a gravações SQL offline. unknown_outcome ou uma ambiguidade de conexão nunca é repetido automaticamente. Verifique o saldo ao vivo e os registros de auditoria antes de outra gravação; não apague registros KVP de operações incertas para forçar uma repetição.

set tosun_db_bridge_query_timeout_ms "5000"

Um único SQL na base correta#

tosun-ac/INSTALL.sql é o único ponto de importação SQL no novo ZIP. Não importe outra cópia antiga do esquema. O destino é a base do jogo FiveM/oxmysql, não a base de contas e tema do site alugado. Colunas antigas em falta são reparadas antes dos valores padrão; bans e ajustes personalizados são preservados.

1. Faça backup da base do jogo e confirme o nome.
2. Importe apenas INSTALL.sql em HeidiSQL/phpMyAdmin ou indique explicitamente a base no comando mysql.
3. tosunac_db_check verifica uma consulta e tosunac_db_status o estado da ponte. A ponte vem ativa por padrão e não exige nenhuma linha no server.cfg. enabled=false é normal no modo manual (set tosun_db_bridge_manual "1") sem tosun_db_bridge_enabled "1", ou se o espelho completo antigo (ts.panelMirror.enabled = true em configs/anticheat_config.lua) foi ativado de propósito; a licença não cria uma ligação MySQL.
4. A conexão do painel (Tosun Connect) e a edição de saldo online vêm ativas por padrão. Não adicione tosun_db_bridge_enabled nem tosun_db_bridge_money_write ao server.cfg; a partir do pacote 9.6.14, linhas antigas são ignoradas e podem ser apagadas (pacotes mais antigos ainda precisam delas até você instalar o pacote atual). Só usuários do painel com papel admin ou owner definem saldos: o personagem precisa estar online, o saldo esperado precisa coincidir (senão stale_balance e nada muda), o painel mostra um resumo para confirmar antes do envio, cada pedido vai para o registro de auditoria e um resultado incerto nunca é repetido automaticamente; confira antes o saldo no jogo. Define o total, não soma. Para desligar toda a conexão em um servidor (isso interrompe todas as leituras do painel e todas as edições de saldo): Painel → Servidores → o servidor → cartão Tosun Connect → Disable connection; você pode religá-la no mesmo cartão. Guarde a senha apenas no servidor de jogo.

mysql -u YOUR_DB_USER -p YOUR_GAME_DATABASE < tosun-ac/INSTALL.sql

# txAdmin console:
tosunac_db_check
tosunac_db_status