Como avaliar, testar e manter scripts FiveM

Este guia prático sobre como manter scripts FiveM é para proprietários de servidores, desenvolvedores e líderes de QA. Você terá uma "Cidade de Testes" semelhante à de produção no Docker, uma lista de verificação de aceitação que pode ser executada de ponta a ponta, um modelo quantitativo de pontuação de risco e uma rubrica de verificação de fornecedores que evita dores de cabeça.

Resumo

• Gire para cima Cidade de Teste (Docker) para isolar e comparar qualquer script com segurança.
• Execute o Lista de verificação de aceitação antes que um centavo mude de mãos.
• Use o Pontuação de risco (0–100) para decidir enviar/manter/rejeitar.
• Vendedores veterinários com o Rubrica do Fornecedor (não pule isso).
• Se for comprar, prefira lojas de boa reputação — veja nossas escolhas: Melhores Lojas Tebex.

---

Parte 1 — “Test City” (Docker) para garantia de qualidade de scripts segura e repetível

O que você ganha

• FXServer em contêiner + MariaDB (+ Administrador)
• Limpar servidor.cfg com oxmysql e recursos básicos
• Montado em encadernação recursos/personalizados onde você solta o script em teste
• Nomes/portas de rede determinísticos para strings de banco de dados simples

Baixe test-city.zip (Github)

Modo de usar:

1. Descompactar → cd test-city
2. Cópia .env.exemplo para .env e defina seu CHAVE_DE_LICENÇA (e credenciais de banco de dados, se preferir).
3. Derrubar oxmysql em dados do servidor/recursos/[autônomo]/oxmysql/.
4. Coloque o script em teste em dados do servidor/recursos/personalizado/ / e adicione garantir para servidor.cfg.
5. docker compose build && docker compose up -d → conectar via Direct Connect para host local:30120.

Pré-requisitos: Docker + Docker Compose, uma chave de licença cfx e um oxmysql cópia do recurso (coloque em dados do servidor/recursos/[autônomo]/oxmysql).

Layout de pasta

test-city/ ├─ docker-compose.yml ├─ fxserver/ │ ├─ Dockerfile │ └─ entrypoint.sh ├─ server-data/ │ ├─ server.cfg │ └─ resources/ │ ├─ [standalone]/oxmysql/ # coloque o oxmysql aqui │ └─ custom/ # coloque o script em teste aqui (por exemplo, myscript/) └─ .env

.env (exemplo)

LICENSE_KEY=changeme_cfx_license_key MYSQL_DATABASE=fivem MYSQL_USER=fivem MYSQL_PASSWORD=fivempw MYSQL_ROOT_PASSWORD=rootpw FX_ARTIFACT_URL=https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/LATEST.tar.xz # Dica: substitua por uma URL de artefato específica em que você confia para reprodutibilidade.

docker-compose.yml

version: "3.9"

networks:
  testcity:

volumes:
  db_data:

services:
  db:
    image: mariadb:10.11
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
    command: >
      --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
      --innodb_buffer_pool_size=256M
    volumes:
      - db_data:/var/lib/mysql
    networks: [testcity]

  adminer:
    image: adminer:4
    restart: unless-stopped
    ports:
      - "8080:8080"
    networks: [testcity]
    depends_on: [db]

  fxserver:
    build:
      context: ./fxserver
      args:
        FX_ARTIFACT_URL: ${FX_ARTIFACT_URL}
    restart: unless-stopped
    environment:
      LICENSE_KEY: ${LICENSE_KEY}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    depends_on: [db]
    networks: [testcity]
    ports:
      - "30120:30120/udp"
      - "30120:30120/tcp"
      - "40120:40120/tcp" # txAdmin (optional)
    volumes:
      - ./server-data:/opt/fivem/server-data

fxserver/Dockerfile

FROM debian:bookworm-slim

ARG FX_ARTIFACT_URL
ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y --no-install-recommends 
    xz-utils curl ca-certificates tini bash && 
    rm -rf /var/lib/apt/lists/*

# Fetch & extract FXServer artifact (URL provided via build-arg)
RUN mkdir -p /opt/fivem && 
    curl -fsSL "$FX_ARTIFACT_URL" -o /opt/fivem/fx.tar.xz && 
    tar -xJf /opt/fivem/fx.tar.xz -C /opt/fivem && 
    rm -f /opt/fivem/fx.tar.xz

# Non-root
RUN useradd -ms /bin/bash fivem
USER fivem

WORKDIR /opt/fivem
COPY --chown=fivem:fivem ../server-data /opt/fivem/server-data
COPY --chown=fivem:fivem entrypoint.sh /entrypoint.sh

ENTRYPOINT ["/usr/bin/tini","--"]
CMD ["/bin/bash","/entrypoint.sh"]

fxserver/ponto de entrada.sh

#!/usr/bin/env bash set -euo pipefail # Fornece string de BD para oxmysql via server.cfg (já definida lá), # apenas garante que o BD esteja acessível antes da inicialização para evitar erros de spam. echo "Aguardando banco de dados..." until nc -z db 3306; do sleep 1; done echo "BD pronto." # Executa o FXServer com nosso server.cfg # A maioria dos artefatos do Linux envia um run.sh na raiz do artefato. exec bash /opt/fivem/run.sh +exec /opt/fivem/server-data/server.cfg

Se o seu artefato usar um caminho de iniciador diferente, ajuste a última linha de acordo (por exemplo, /opt/fivem/alpine/opt/cfx-server/run.sh).

dados do servidor/servidor.cfg (enxuto, pronto para testes)

# ---------- Identity ----------
sv_licenseKey "%LICENSE_KEY%"            # injected by env in entrypoint command or replace manually
sv_hostname "Test City — Script QA"
sets tags "qa,testing,fivemx"
sv_maxclients 2
onesync on
sv_scriptHookAllowed 0
sv_enforceGameBuild 3095

# ---------- Networking ----------
endpoint_add_tcp "0.0.0.0:30120"
endpoint_add_udp "0.0.0.0:30120"

# ---------- Database (oxmysql) ----------
set mysql_connection_string "mysql://%MYSQL_USER%:%MYSQL_PASSWORD%@db:3306/%MYSQL_DATABASE%?charset=utf8mb4"

# ---------- Core / Base resources ----------
ensure mapmanager
ensure chat
ensure spawnmanager
ensure sessionmanager
ensure hardcap
ensure baseevents

# ---------- Datastore ----------
ensure oxmysql

# ---------- Under test ----------
# Drop your script folder into resources/custom/<scriptname> and enable here:
# ensure myscript

# ---------- QA helpers ----------
# Verbose logging in dev
setr con_minSeverity info

# Enable txAdmin panel (optional)
setr txAdminPort 40120

Habilite seu script: copie-o para dados do servidor/recursos/personalizado/myscript/ e adicione garantir meu script para o bloco inferior.

Execute-o

cd test-city docker compose build docker compose up -d # Administrador em http://localhost:8080 (servidor: db, usuário: fivem, senha: fivempw) # Conectar cliente FiveM → Conexão direta: your-docker-host:30120

---

Parte 2 — Lista de verificação de aceitação do roteiro (não pule)

Use isso sempre. Copie para o seu rastreador e marque os itens.

A. Pré-voo (antes da instalação)

• Tipo de fonte: Código aberto / parcialmente aberto / somente custódia.
• Dependências listadas: estrutura (ESX/QBCore/QBOX), boi_lib, oxmysql, PoliZona, etc.
• fxmanifest.lua: lua54 'sim', correto jogo 'gta5', versão_fx não antigo.
• Documentação: etapas de instalação, exemplos de configuração, permissões, localidades, conflitos conhecidos.
• Licença/Termos de Serviço: direitos de uso, política de reembolso, atualizações, canal de suporte.

B. Instalabilidade

• Nenhum erro de console em garantir: nenhum rastreamento de pilha ou spam de ativos ausentes.
• Não nativos depreciados spam.
• Carregamentos de configuração limpos: sem erros de sintaxe JSON/Lua.
• Migrações de banco de dados: crie tabelas uma vez; reinicializações não reaplicam nem interrompem.

C. Funcional

• Essencial fluxos de trabalho: caminho feliz testado (por exemplo, compra, fluxo de trabalho, criação).
• Casos extremos: entradas erradas, permissões ausentes, quantidades fora do intervalo.
• Localização: nenhuma sequência de caracteres codificada se as localidades forem prometidas.
• Permissões: comandos de equipe/administrador restritos; sem acesso livre do lado do cliente.

D. Desempenho (cliente e servidor)

• resmon: ocioso ≤ 0,10 ms, ativo ≤ 0,50 ms (cliente).
• Saúde do servidor: sem avisos de problemas longos sob uso normal.
• Consultas ao BD: sem loops apertados; instruções preparadas usadas; N+1 mínimo.

E. Segurança

• Validação do lado do servidor: cada evento do servidor valida fonte, permissões e tipos de entrada.
• Nenhuma confiança no cliente: mudanças de dinheiro/inventário somente pela lógica do servidor.
• Nenhuma avaliação/cadeia de carga/código remoto padrões.
• Antiabuso: limites de taxa/limitações em endpoints de spam.
• Integridade do depósito em garantia: sem backdoors em carregadores de configuração não-escrow.

Bom padrão de evento (exemplo):

RegisterNetEvent('myscript:buy', function(item, amount) local src = source if type(item) ~= 'string' or type(amount) ~= 'number' or amount < 1 then return end if not HasPermission(src, 'shop.buy') then return end local xPlayer = GetPlayer(src) -- adaptador de framework if not xPlayer then return end -- valida preço no lado do servidor, verifica limites de estoque, faz DB em uma transação end)

F. Compatibilidade e Limpeza

• Adaptadores de estrutura presentes (ESX/QBCore/QBOX) ou claramente declarado sem suporte.
• Nenhum vazamento global, nomes de eventos exclusivos, sem suposições de nomes de recursos.
• Desinstalar limpo: remover o recurso não quebra os outros.

---

Parte 3 — Modelo de pontuação de risco quantitativo (0–100)

Use isso para decidir "enviar/manter/rejeitar". Quanto menor, melhor.

Fator	Peso	Como pontuar (0=bom → 5=ruim)
Desempenho	0.20	resmon ocioso: 0=≤0,10ms, 1=≤0,20, 3=≤0,50, 5=>0,50; picos adicionam +1
Segurança	0.25	0=todos os limites de taxa + validados pelo servidor; 3=algumas lacunas; 5=confia no cliente / eventos inseguros
Estabilidade	0.15	0=sem erros; 3=avisos ocasionais; 5=erros/problemas frequentes
Compatibilidade	0.10	0=adaptadores/testes; 3=apenas uma estrutura; 5=quebra dependências comuns
Manutenibilidade	0.10	0=documentação/registro de alterações/versões semânticas; 5=sem documentação/abandonado
Cadeia de suprimentos/Fornecedor	0.20	0=reputável, histórico, reembolsos; 5=desconhecido, sem política

Fórmula

Pontuação de Risco = 100 * Σ(peso_i * (pontuação_i / 5))

Bandas e Ações

• 0–24 (baixo): Enviar para preparação, monitorar.
• 25–49 (Moderado): Correções necessárias antes do lançamento.
• 50–74 (Alto): Esperar; solicitar patches do fornecedor ou substituir.
• 75–100 (Crítico): Rejeitar.

Exemplo

• Perf=1, Sec=3, Estabilidade=1, Compat=1, Manutenção=2, Fornecedor=1
• Risco = 100*(.2*.2 + .25*.6 + .15*.2 + .1*.2 + .1*.4 + .2*.2) = 34 → Moderado

---

Parte 4 — Rubrica de verificação de fornecedores (pontuação de 0 a 5 para cada um, quanto maior for melhorar)

Critério	Como é o "bom"	Notas
Identidade e Histórico	Marca clara, anos de atividade, manuseio consistente	Evite lojas de produtos descartáveis
Documentação	Instalar + configurar + permissões + solução de problemas	Ajuda com capturas de tela/gifs
Atualizar cadência	Log de alterações, versões semânticas, confirmações/lançamentos recentes	Trimestral+ está bom
Qualidade de suporte	SLAs de tickets/Discord, correções reproduzíveis, não apenas “reiniciar”	Respostas de exemplo
Transparência de Emissão	Problemas públicos conhecidos e roteiro	Honestidade > perfeição
Clareza sobre reembolso/ToS	Período de reembolso, condições, termos de licença	Sem padrões escuros
Prova de teste	Vídeo de preparação, métricas de desempenho, lista de estruturas	Melhor ainda: servidor de demonstração
Segurança Higiene	Menciona verificações do lado do servidor, sem chaves sensíveis, sem avaliação	Pergunte sobre auditorias
Política de compatibilidade	ESX/QBCore/QBOX declarado, adaptadores, matriz de versão	Construções apoiadas pelo estado
Preço e valor	Justo em termos de complexidade, sem paywalls de dependência	Cuidado com as armadilhas de upsell

Pontuação da rubrica (0–50):

• 40–50: Forte — fornecedor preferencial
• 30–39: Aceitável — monitor
• 20–29: Fraco — prossiga com cautela
• <20: Evitar

Dica profissional: Faça uma referência cruzada com marketplaces confiáveis. Comece aqui: Melhores Lojas Tebex.

---

Parte 5 — Manual de Manutenção (Após o Envio)

1. Fixação de versão: lançamentos de script de bloqueio + versões de dependência (por exemplo, oxmysql, boi_lib).
2. Primeira preparação: todas as atualizações chegam Cidade de Teste; execute a lista de verificação de aceitação novamente.
3. Backups e reversão: Instantâneo do banco de dados + arquivos de recursos antes de cada atualização. Mantenha um Rollback.md com passos exatos.
4. Teste de fumaça de CI (opcional, recomendado): conexão de cliente sem interface + macro de comando para atingir os fluxos principais; analisar o console do servidor em busca de erros.
5. Métricas operacionais: mantenha um registro simples por script: média de respostas (ocioso/ativo), contagem de erros/sessão, notas de incidentes.
6. Disciplina de registro de alterações: exigir registros de alterações do fornecedor; manter suas próprias notas de integração.
7. Eventos programados sem risco: atualizar fora dos horários de pico; anunciar janelas de manutenção.

---

Parte 6 — Modelos que você pode copiar

A. Plano de Teste (por script)

# Script Test Plan — <name> <version>

## Context
Framework(s): ESX/QBCore/QBOX
Dependencies: oxmysql vX, ox_lib vY, PolyZone vZ
DB Migrations: yes/no
Escrow: yes/no

## Functional Cases
- [ ] Case 1:
- [ ] Case 2:
- [ ] Negative 1:

## Performance
resmon idle: ____ ms
resmon active: ____ ms (scenario: ______)

## Security Checks
- [ ] All server events validate source/perm/input
- [ ] Rate limits present
- [ ] No client-trusted money/inventory mutations

## Logs & Errors
Paste snippet (server + F8): 

## Result
Pass/Fail + Notes

B. Rollback.md (esqueleto)

# Rollback — <date> <script> <from→to>

1) Disable script: `stop <resource>`
2) Restore resource files from backup: <path>
3) Restore DB snapshot: <path/command>
4) Restart FXServer
5) Verify: console clean, perf normal, flows ok

C. Modelo de Problema

**Resumo** O que aconteceu versus o esperado, com registros de data e hora. **Etapas de reprodução** 1) ... 2) ... **Ambiente** Construção do artefato: Estrutura e versões: Versão do script: Outras dependências: **Logs** Console do servidor: F8: **Anexos** Telas/vídeo, se possível.

---

Como usar este guia com eficiência

1. Cidade de teste Bootstrap uma vez, mantenha-o limpo.
2. Para cada script candidato:
   • Cair em recursos/personalizado/, habilitar em servidor.cfg.
   • Execute o Lista de verificação de aceitação.
   • Calcular o Pontuação de Risco.
   • Verifique o vendedor com o Rubrica do Fornecedor.
3. Se for aprovado, entre na preparação; caso contrário, solicite correções ou vá embora.

---

Precisa de mais guias de testes? Confira a seção