DBSync: Installieren und konfigurieren

Verwenden Sie diese Anleitung, wenn FiveNet Charaktere, Fahrzeuge und andere Daten aus Ihrer Gameserver-Datenbank übernehmen soll, ohne dass der FiveNet-Server direkten Datenbankzugriff benötigt.

Schließen Sie zuerst FiveNet konfigurieren ab, damit Datenbank, NATS-Verbindung, öffentliche URL und Sync-API-Token eingerichtet sind.

Warum DBSync erforderlich ist

DBSync ist die Komponente, die Charaktere, Fahrzeuge und andere Gameserver-Daten aus Ihrer Gameserver-Datenbank nach FiveNet überträgt.

Ohne DBSync kann FiveNet seine eigenen Daten nicht mit den von Ihrem Gameserver erzeugten Daten synchron halten.

Dies ist die Standardkonfiguration für FiveNet, einschließlich FiveNet-Cloud-Bereitstellungen.

Voraussetzungen

FiveNets DBSync (fivenet CLI) ist verfügbar für:

• Windows
  • amd64 - Typische Windows-Server laufen auf dieser Architektur.
• Linux
  • amd64 - Typische Linux-Server laufen auf dieser Architektur.
  • arm64 - Die neuere 64-Bit-ARM-Architektur, die häufig in Raspberry Pi 4 und anderen ARM-basierten Servern zu finden ist.

Datenbank

DBSync unterstützt derzeit nur MySQL-kompatible Datenbanken. Wenn Ihr Gameserver ein anderes Datenbanksystem wie MongoDB verwendet, kann DBSync aktuell nicht genutzt werden.

Schneller Einrichtungsablauf

1. Installieren Sie die fivenet-Binary.
2. Erstellen und bearbeiten Sie dbsync.yaml.
3. Aktivieren Sie die FiveNet-Sync-API und konfigurieren Sie mindestens ein Sync-Token in Ihrer zentralen config.yaml.
4. Testen Sie fivenet dbsync manuell.
5. Sobald die Synchronisierung zuverlässig funktioniert, richten Sie DBSync als Dienst ein.

Architektur

      ---
config:
  theme: dark
  layout: elk
---
flowchart TD
    FiveM["FiveM-Server"] -->|1. Daten schreiben| GameserverDB("MySQL FiveM")
    GameserverDB <-.->|2. Daten lesen| DBSync["FiveNet DBSync"]
    DBSync["FiveNet DBSync"] <-..->|3. Daten streamen| FiveNetServer
    DBSync["FiveNet DBSync"] --->|3. Daten senden| FiveNetServer
    FiveNetServer -.-|4. Daten umschreiben und speichern| FiveNetDB("MySQL FiveNet")

    

Installation

Um DBSync zu installieren, führen Sie die folgenden Schritte aus:

1. Laden Sie die neueste Version der fivenet-Binary oder -Exe aus dem offiziellen FiveNet-Repository herunter und entpacken Sie sie. Verwenden Sie die Befehle für Ihre Plattform oder laden Sie das passende Archiv manuell von der Release-Seite herunter:
   Linux amd64Windows amd64

   curl -LO https://github.com/fivenet-app/fivenet/releases/latest/download/fivenet-linux-amd64.tar.gz
   tar -xzf fivenet-linux-amd64.tar.gz
   

2. Erstellen Sie ein eigenes Verzeichnis für die DBSync-Binary bzw. -Exe und die Konfigurationsdateien.
   LinuxWindows

   mkdir -p /opt/fivenet/dbsync
   mv fivenet config.example.yaml dbsync.example.yaml /opt/fivenet/dbsync/
   chmod +x /opt/fivenet/dbsync/fivenet
   

3. Optional: Fügen Sie die fivenet-Binary Ihrem System-PATH hinzu, damit Sie sie von überall ausführen können.
   LinuxWindows

   echo 'export PATH="/opt/fivenet/dbsync:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   

4. Benennen Sie die Datei dbsync.example.yaml in dbsync.yaml um.
   LinuxWindows

   cd /opt/fivenet/dbsync
   mv dbsync.example.yaml dbsync.yaml
   

5. Bearbeiten Sie die Datei dbsync.yaml, um DBSync zu konfigurieren. Sie können dazu jeden Texteditor verwenden, zum Beispiel:
   LinuxWindows

   nano dbsync.yaml
   

   • Folgen Sie dem Konfigurationsabschnitt weiter unten.
6. Stellen Sie sicher, dass die Sync-API in Ihrer zentralen FiveNet-config.yaml aktiviert ist und mindestens ein Sync-Token konfiguriert wurde. Siehe Konfigurationsdatei-Referenz.
7. Sie können DBSync nun mit dem Befehl fivenet dbsync ausführen.

Als Dienst einrichten

Um DBSync dauerhaft auszuführen, empfiehlt es sich, ihn als Dienst auf Ihrem Server einzurichten. So kann er automatisch beim Booten starten und leichter verwaltet werden.

Öffnen Sie ein Terminal oder eine Eingabeaufforderung und navigieren Sie in das Verzeichnis, das die fivenet-Binary enthält:

cd /pfad/zu/fivenet/verzeichnis

Set-Location 'C:\pfad\zu\fivenet\verzeichnis'

Folgen Sie anschließend den plattformspezifischen Anweisungen unten, um den DBSync-Dienst zu installieren, zu starten, zu stoppen oder zu deinstallieren.

Dienst installieren

Um DBSync als Dienst zu installieren, befolgen Sie diese Schritte:

Unter Linux kopieren Sie die fertige Konfigurationsdatei dbsync.yaml vor der Installation des Dienstes nach /etc/fivenet. Dadurch verwendet der DBSync-Dienst beim Start die richtige Konfigurationsdatei.

sudo mkdir -p /etc/fivenet
sudo cp dbsync.yaml /etc/fivenet/dbsync.yaml
sudo fivenet dbsync install

fivenet dbsync install

Sie können den DBSync-Dienst anschließend mit den folgenden Abschnitten verwalten.

Dienst starten / stoppen

Um den DBSync-Dienst zu starten oder zu stoppen, verwenden Sie folgende Befehle:

sudo fivenet dbsync start
sudo fivenet dbsync stop

# Oder systemd direkt verwenden
sudo systemctl start fivenet-dbsync
sudo systemctl stop fivenet-dbsync

fivenet dbsync start
fivenet dbsync stop

# Oder die Windows-Diensteverwaltung direkt verwenden
Start-Service fivenet-dbsync
Stop-Service fivenet-dbsync

Dienst deinstallieren

Um den DBSync-Dienst zu deinstallieren, führen Sie folgenden Befehl aus:

sudo fivenet dbsync uninstall

fivenet dbsync uninstall

Konfiguration

DBSync wird in der Datei dbsync.yaml konfiguriert. Die folgenden Abschnitte behandeln die wichtigsten Bereiche.

Zielkonfiguration

Der Abschnitt destination: definiert, wie DBSync sich mit Ihrer FiveNet-Instanz verbindet. Beispiel:

destination:
  # Host + Port Ihrer FiveNet-Instanz (erfordert HTTPS/gültige TLS-Zertifikate, außer `insecure` ist auf `true` gesetzt)
  url: "fivenet.example.com"
  token: "IHR_SYNC_API_TOKEN"
  # TLS-Prüfung deaktivieren (nicht empfohlen)
  insecure: false
  # Das Sync-Intervall kann auch pro Tabelle im Abschnitt `tables:` festgelegt werden
  syncInterval: 5s

Quellkonfiguration

Der Abschnitt source: enthält die Verbindungsdaten Ihrer Gameserver-Datenbank. Beispiel:

# Änderungen an der Quelle erfordern einen Neustart von dbsync
source:
  # Details unter https://github.com/go-sql-driver/mysql#dsn-data-source-name
  # Bitte beachten Sie, dass der Parameter `parseTime` immer auf true gesetzt wird
  dsn: "DB_USER:DB_PASS@tcp(DB_HOST:DB_PORT)/DB_NAME?collation=utf8mb4_unicode_ci&loc=Europe%2FBerlin"

Synchronisierungsstatus speichern

DBSync speichert seinen Synchronisierungsstatus standardmäßig in einer Datei namens dbsync.state.yaml. Diese Datei verfolgt den zuletzt synchronisierten Datenstand. Bewahren Sie sie dauerhaft auf, damit nach einem Neustart nicht alles erneut vollständig synchronisiert werden muss.

Bevor Sie DBSync starten, stellen Sie sicher, dass die Sync-API aktiviert ist und ein Sync-API-Token in Ihrer zentralen FiveNet-config.yaml konfiguriert wurde.

Der Tabellenabschnitt dient dazu, die Abfragen für die Tabellen zu definieren, die mit FiveNet synchronisiert werden sollen. Siehe die Beispiele weiter unten für ESX und QBCore.

Wenn Sie ein anderes Framework verwenden, passen Sie die Abfragen entsprechend an.

Datenbankbenutzer für die Quelle

Der Datenbankbenutzer benötigt nur Lesezugriff auf die Gameserver-Datenbank. Beispielabfragen zum Erstellen eines separaten Benutzers und zum Gewähren von Lesezugriff finden Sie unten. Ersetzen Sie Benutzername, Passwort und Datenbankname vor der Verwendung:

CREATE USER 'fivenet_dbsync'@'localhost' IDENTIFIED BY 'IHR_DBSYNC_BENUTZER_PASSWORT';
GRANT SELECT ON `ihre_gameserver_db`.* TO 'fivenet_dbsync'@'localhost';

Tabellenabfragen

Die Abfragen für jede Tabelle müssen die von DBSync erwarteten Spalten zurückgeben. Benutzerbezogene Felder müssen beispielsweise als user.COLUMN zurückgegeben werden, etwa user.id, user.firstname und user.lastname.

Es ist besonders wichtig, konsistente Werte für id und identifier von Benutzern bzw. Charakteren zurückzugeben. Das Feld id identifiziert den Benutzer in der Quelldatenbank, während identifier von FiveNet verwendet wird, um Charaktere mit Konten zu verknüpfen. So können auch mehrere Charaktere einem Konto zugeordnet werden, zum Beispiel char1:LICENSE und char2:LICENSE, die beide zu einem Konto gehören, das nur LICENSE speichert.

Arbeitsfähige Startpunkte für gängige Frameworks finden Sie im Abschnitt Beispielkonfigurationen.

Verwendung

Um DBSync manuell auszuführen, verwenden Sie die fivenet-Binary wie folgt:

fivenet dbsync

fivenet dbsync --help

Beispielkonfigurationen

ESX-Framework

tables:
  jobs:
    enabled: true
    tableName: "jobs"
    columns:
      name: "name"
      label: "label"

  jobGrades:
    enabled: true
    tableName: "job_grades"
    columns:
      jobName: "job_name"
      grade: "grade"
      name: "name"
      label: "label"

  licenses:
    enabled: true
    tableName: "licenses"
    columns:
      type: "type"
      label: "label"

  users:
    enabled: true
    tableName: "users"
    updatedTimeColumn: "last_seen"
    columns:
      id: "id"
      identifier: "identifier"
      group: "group"
      firstname: "firstname"
      lastname: "lastname"
      dateOfBirth: "dateofbirth"
      sex: "sex"
      height: "height"
      job: "job"
      jobGrade: "job_grade"
      phoneNumber: "phone_number"
    ignoreEmptyNames: true

  userLicenses:
    enabled: true
    tableName: "user_licenses"
    columns:
      type: "type"
      ownerIdentifier: "owner"

  vehicles:
    enabled: true
    tableName: "owned_vehicles"
    updatedTimeColumn: "updated_at"
    columns:
      ownerIdentifier: "owner"
      plate: "plate"
      type: "type"

QBCore-Framework

tables:
  jobs:
    # Muss die Spalten `name`, `label` zurückgeben
    enabled: false
    query: |
      SELECT
        `jobs`.`name` AS `job.name`,
        `jobs`.`label` AS `job.label`
      FROM
        `jobs`
      ORDER BY `name`;
      LIMIT $limit;

  jobGrades:
    # Muss die Spalten `job_name`, `grade`, `label` zurückgeben (mit `WHERE`-Bedingung für den `job_name` (`$jobName`))
    enabled: false
    query: |
      SELECT
        `job_grades`.`job_name` AS `job_grade.job_name`,
        `job_grades`.`grade` AS `job_grade.grade`,
        `job_grades`.`label` AS `job_grade.label`
      FROM
        `job_grades`
      WHERE
        `job_name` = $jobName
      ORDER BY `job_grade.job_name`, `job_grade.grade`
      LIMIT $limit;

  licenses:
    # Muss die Spalten `type`, `label` zurückgeben
    enabled: false
    query: |
      SELECT
        `licenses`.`type` AS `license.type`,
        `licenses`.`label` AS `license.label`
      FROM
        `licenses`
      ORDER BY `license.type`
      LIMIT $limit;

  users:
    enabled: false
    #updatedTimeColumn: "last_seen"
    # Die Identifier-Spalte sollte eine sinnvolle Kombination von Werten sein, wenn ein Multichar-System verwendet wird.
    # Beispielsweise ist ein ESX-ähnliches Identifier-Layout in diesem Fall sinnvoll: `charX:LICENSE`
    query: |
      SELECT
        `players`.`id` AS `user.id`,
        CONCAT(`players`.`cid`, ':', `players`.`citizenid`) AS `user.identifier`,
        'user' AS `user.group`,
        JSON_UNQUOTE(JSON_EXTRACT(`players`.`charinfo`, '$.firstname')) AS `user.firstname`,
        JSON_UNQUOTE(JSON_EXTRACT(`players`.`charinfo`, '$.lastname')) AS `user.lastname`,
        JSON_UNQUOTE(JSON_EXTRACT(`players`.`charinfo`, '$.birthdate')) AS `user.dateofbirth`,
        JSON_UNQUOTE(JSON_EXTRACT(`players`.`charinfo`, '$.height')) AS `user.height`,
        JSON_UNQUOTE(JSON_EXTRACT(`players`.`job`, '$.name')) AS `user.job`,
        JSON_UNQUOTE(JSON_EXTRACT(`players`.`job`, '$.grade.level')) AS `user.job_grade`,
        JSON_UNQUOTE(JSON_EXTRACT(`players`.`charinfo`, '$.gender')) AS `user.sex`,
        JSON_UNQUOTE(JSON_EXTRACT(`players`.`charinfo`, '$.phone')) AS `user.phone_number`
        `players`.`last_updated` AS `user.updated_at`
      FROM
        `players`
      $whereCondition
      ORDER BY `user.updated_at` ASC, `user.id` ASC
      LIMIT $limit;
    # Wenn kein Nachname zurückgegeben wird, kann der Vorname in zwei Teile aufgeteilt werden
    splitName: true
    # Geburtsdatum wenn möglich in das gewünschte Ausgabeformat umwandeln
    # Mögliche Datumsformat-Layouts finden Sie in der Go-`time`-Dokumentation: https://pkg.go.dev/time#Layout
    dateOfBirth:
      formats:
        - "2006-01-02" # 2000-10-18 = YYYY-MM-DD
        - "02/01/2006" # 09/06/1993 = MM/DD/YYYY
        - "02.01.2006" # 01.08.1982 = DD.MM.YYYY
      outputFormat: "02.01.2006" # DD.MM.YYYY
    valueMapping:
      sex:
        fallback: 'm'
        values:
          '1': 'f'

  userLicenses:
    # Muss die Spalten `type`, `owner` zurückgeben
    enabled: false
    query: |
      SELECT
        `user_licenses`.`type` AS `user_license.type`,
        `user_licenses`.`owner` AS `user_license.owner`
      FROM
        `user_licenses`
      WHERE
        `owner` = $identifier
      LIMIT $limit;

  vehicles:
    # Muss die Spalten `owner_id` (DB-Benutzer-ID) oder `owner_identifier`, `plate`, `type`, `model` zurückgeben
    enabled: true
    query: |
      SELECT
        IF(`player_vehicles`.job_vehicle=0, `players`.`id`, NULL) AS `vehicle.owner_identifier`,
        `player_vehicles`.`plate` AS `vehicle.plate`,
        'Fahrzeug' AS `vehicle.type`,
        `player_vehicles`.`vehicle` AS `vehicle.model`,
        IF(`player_vehicles`.`job_vehicle`=1, `players`.`id`, NULL) AS `vehicle.job`,
        `player_vehicles`.`updated_at` AS `vehicle.updated_at`
      FROM
        `player_vehicles`
        LEFT JOIN `players` ON (`players`.`citizenid` = `player_vehicles`.`citizenid`)
      $whereCondition
      ORDER BY `vehicle.updated_at` ASC, `vehicle.plate` ASC
      LIMIT $limit;

Als Systemd-Unit oder Dienst ausführen

Es wird empfohlen, DBSync als Dienst auf Ihrem Server auszuführen. Unter Linux können Sie zum Beispiel eine systemd-Unit-Datei erstellen:

[Unit]
Description=FiveNet DBSync Service
After=network.target

[Service]
ExecStart=/path/to/fivenet dbsync
Restart=always
User=fivenet
Group=fivenet

[Install]
WantedBy=multi-user.target

Speichern Sie diese Datei als /etc/systemd/system/fivenet-dbsync.service und aktivieren und starten Sie den Dienst anschließend:

sudo systemctl enable fivenet-dbsync
sudo systemctl start fivenet-dbsync

Häufige Probleme und Fragen

Fehlermeldung: error during sync stream, restarting in a second

Diese Meldung bedeutet, dass die DBSync-Verbindung zur FiveNet-Instanz geschlossen oder unterbrochen wurde. Wenn dies nur gelegentlich passiert, ist es in der Regel unkritisch, da DBSync automatisch versucht, die Verbindung wiederherzustellen.

Lang laufende Verbindungen können durch Firewalls, Load-Balancer oder andere Netzwerkgeräte getrennt werden, was zu dieser Meldung führen kann.

Wie man Off-Duty-Jobs behandelt

Wenn Ihr Job-Framework separate Off-Duty-Jobs wie off_police verwendet, können Sie dies in der jobs- und users-Tabellenkonfiguration mit Filtern behandeln.

Beispiel:

tables:
  jobs:
    filters:
      # Beispiel-Filter, um Jobs zu verwerfen, die mit "off_" beginnen
      # Dies ist nützlich in Kombination mit den `users:`-Jobfiltern unten,
      # wenn "Off-Duty"-Jobs auf ihren eigentlichen Jobnamen zurückgeschrieben werden sollen
      #
      # "drop" bedeutet in diesem Zusammenhang, dass dbsync den Job nicht an FiveNet sendet
      - pattern: '^off_'
        action: drop
# [...]
  users:
    # Filter können bestimmte Werte verändern, bevor sie an FiveNet gesendet werden
    filters:
      jobs:
        # Beispiel: `off_police` -> `police`
        - pattern: '^off_'
          # Das Muster suchen und mit `action: replace` ersetzen ...
          action: replace
          # ... durch einen leeren String (`replacement: ''`)
          replacement: ''