Dateien selbst hochladen

Aus dem Panel

Dateien, dann Datei hochladen. Was du wählst, landet im gerade geöffneten Ordner, und du bekommst den Link zurück. Identische Bytes werden einmal gespeichert, ein erneuter Upload kostet also nichts.

Token erstellen

Tokens, dann Neuer Token. Binde ihn an einen Server statt an den ganzen Workspace, damit ein geleakter Key nicht überall schreiben kann. Das Secret wird nur einmal gezeigt.

Das API-Token beginnt mit fd_live_. Es ist nicht der Agent-Key fda_live_ aus der server.cfg: Der verbindet nur die Resource fivedock, und die Upload-API nimmt ihn nicht an.

files:write lädt hoch, files:read liest zurück, files:delete löscht, folders:write legt Ordner an, usage:read liest Speicher und Traffic. logs:write ist für Fehler aus einer App, nicht für Dateien.

Upload über HTTP

Schick die Datei als multipart/form-data an POST /api/v3/file, dieselbe Adresse, die auch Fivemanage nutzt. path ist der Ordner, der bei Bedarf angelegt wird, und filename überschreibt den Namen aus dem Dateiteil.

curl -X POST https://api.fivedock.dev/api/v3/file \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "path=/branding"

{
  "status": "ok",
  "data": { "id": "8Kq2nR4t", "url": "https://cdn.fivedock.dev/f/8Kq2nR4t.png" },
  "url": "https://cdn.fivedock.dev/f/8Kq2nR4t.png",
  "filename": "logo.png",
  "mime_type": "image/png",
  "size": 48213,
  "fivedock": {
    "fileUrl": "https://cdn.fivedock.dev/f/8Kq2nR4t.png",
    "deduplicated": false,
    "folder": "/branding"
  }
}

url ist der CDN-Link, fertig für einen Loading Screen oder ein Discord-Embed, und er funktioniert, sobald die Antwort da ist. fivedock.deduplicated sagt dir, dass die Bytes schon gespeichert waren, es wurde also nichts Neues berechnet. Die Antwort oben ist gekürzt.

Benannte Dateien und feste Links

Gib einer Datei einen Key, etwa items/burger.png, und sie ist unter einem Link erreichbar, der sich nie ändert: https://cdn.fivedock.dev/o/my-city/items/burger.png, wobei my-city der Kurzname deines Workspace ist. Lädst du wieder mit demselben Key hoch, wird die Datei hinter dem Link ersetzt. So tauschst du ein Inventar-Icon oder ein Loading-Screen-Bild, ohne ein Skript oder die Datenbank anzufassen.

curl -X POST https://api.fivedock.dev/api/v3/file \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "key=items/burger.png"

# served at https://cdn.fivedock.dev/o/my-city/items/burger.png
# run it again with a new burger.png and the same link shows the new file

Keys kommen aus dem Feld key der Upload-API, aus „Dateinamen behalten“ im Panel, aus Archiven und vom S3-Endpunkt, wo ein Objekt unter s3://my-city/items/burger.png die Datei mit dem Key items/burger.png ist. Im Panel steht eine Datei mit Key im Ordner ihres Keys, hier /items.

Die ersetzte Datei wird noch 7 Tage aufbewahrt und dann endgültig gelöscht. Links mit Key werden 5 Minuten gecacht, Spieler sehen eine neue Version also nach etwa 5 Minuten. Jede Datei behält außerdem ihren eigenen /f/-Link, dessen Inhalt sich nie ändert.

Keys aus Dateinamen räumen wir für dich auf: Leerzeichen werden zu -, jedes andere Zeichen, das ein Key nicht enthalten darf, zu _. Ein Key, den du selbst an die API schickst, muss schon den Regeln folgen, sonst wird er abgelehnt.

Einen ganzen Ordner als .zip oder .rar hochladen

Zieh eine .zip oder .rar auf das Upload-Feld im Panel oder schick sie an POST /api/v3/file/archive, und jede Datei darin wird gespeichert. „Dateinamen behalten“ ist bei Archiven standardmäßig an, burger.png, entpackt nach items, bekommt also den festen Link …/o/my-city/items/burger.png. Ordner im Archiv bleiben erhalten.

curl -X POST https://api.fivedock.dev/api/v3/file/archive \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "path=items"

Ein Archiv darf bis zu 512 MiB groß sein, mit höchstens 5.000 Dateien und 4 GiB entpackt. Dateien, die wir nicht speichern können, etwa in einem Format, das wir nicht annehmen, oder mit Passwort, kommen mit Grund in einer Liste zurück. Größere Mengen synchronisierst du über den S3-Endpunkt.

Aus dem eigenen Uploader in HTML und JS

Leg niemals ein Token in clientseitiges JavaScript: wer die Seite öffnet, liest es und lädt in deinen Workspace hoch. Nimm die Datei auf deinem eigenen Server entgegen und halte das Token dort.

// your server, never the browser: the token stays here
app.post('/upload', upload.single('file'), async (req, res) => {
  const body = new FormData();
  body.append('file', new Blob([req.file.buffer]), req.file.originalname);
  body.append('path', '/player-shots');

  const answer = await fetch('https://api.fivedock.dev/api/v3/file', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.FIVEDOCK_TOKEN}` },
    body,
  });
  res.json(await answer.json());
});

// your page talks to your server, which holds the token
const body = new FormData();
body.append('file', input.files[0]);

const answer = await fetch('/upload', { method: 'POST', body });
const file = await answer.json();
image.src = file.url;

Entsteht die Datei in einem Browser oder einer FiveM-NUI-Seite, kann dein Server stattdessen einen Einmal-Upload-Link erzeugen und den weitergeben. Der Browser lädt direkt zu FiveDock hoch und sieht das Token nie.

Geht es dir darum, dass Spieler dir Dateien schicken, ganz ohne eigenen Code, nimm stattdessen ein Upload-Portal: eine öffentliche Seite, pro Adresse limitiert, mit Tageslimit und Moderation davor.

Der S3-kompatible Endpunkt

Dasselbe Token ist auch eine S3-Zugangsberechtigung, rclone, die aws CLI und die meisten Backup-Tools können also darauf schreiben. Nutze Path-Style-Adressierung.

rclone config create fivedock s3 \
  provider=Other \
  endpoint=https://s3.fivedock.dev \
  access_key_id=AKFD… \
  secret_access_key=… \
  force_path_style=true \
  region=auto

rclone copy ./branding fivedock:my-city/branding

aws --endpoint-url https://s3.fivedock.dev \
  s3 cp logo.png s3://my-city/branding/logo.png

Jedes Objekt, das du ablegst, ist eine Datei mit Key, s3://my-city/branding/logo.png ist also unter https://cdn.fivedock.dev/o/my-city/branding/logo.png erreichbar.

Ordner und Aufbewahrung

Leg im Panel Ordner an und verschieb Dateien zwischen ihnen. Der Key einer Datei wandert mit: items/a.png, verschoben nach /icons, wird zu icons/a.png, und ist dieser Key schon vergeben, wird das Verschieben für diese Datei abgelehnt. Die Dateiliste hat eine Listen- und eine Rasteransicht, eine Suche nach Namen und Filter für Typ und Hinzufügedatum: letzte 24 Stunden, 7 Tage, 30 Tage oder gesamter Zeitraum.

Jeder Ordner hat eine Aufbewahrungsregel, die festlegt, wann seine Dateien gelöscht werden.

Das Hochgeladene ausliefern

Jede Datei bekommt einen CDN-Link, der funktioniert, sobald der Upload geantwortet hat. Dateien werden beim Upload freigegeben; nimmt die Moderation eine später herunter, antwortet ihr Link mit 404. Mit der Hotlink-Liste unter Einstellungen legst du fest, welche Seiten deine Dateien einbetten dürfen.