FAQ und Fehlersuche
Allgemein
Ist MSK Shortener kostenlos?
Ja. Die gehostete Instanz unter s.msk-scripts.de ist für alle kostenlos. Der Quellcode steht unter AGPL-3.0, du kannst ihn also auch unter deiner eigenen Domain betreiben.
Brauche ich ein Konto?
Nein. MSK Shortener hat bewusst kein Nutzersystem. Der Lösch-Token, den du beim Anlegen bekommst, ist das, womit du einen Link später wieder entfernst. Nur wer über die API Links anlegt, braucht einen API-Key, siehe weiter unten.
Kann ich einen Kurzlink auf ein anderes Ziel umbiegen?
Nein. Links sind unveränderlich. Um das Ziel zu ändern, löschst du den alten Link mit dem Lösch-Token und legst einen neuen mit demselben eigenen Code an.
Wie lange lebt ein Link?
So lange du willst. Das Feld expiresAt ist optional, ein Link ohne Ablauf bleibt aktiv,
bis du ihn löschst. Setzt du einen, muss es ein gültiger ISO-8601-Zeitpunkt in der Zukunft
sein.
Kann ich einen gelöschten oder abgelaufenen Link wiederherstellen?
Nein. Löschen ist endgültig, ob von Hand oder durch Ablauf. Die zugehörige Klickstatistik verschwindet mit.
Kann ich sehen, wer meine Links angeklickt hat?
Nein, und das ist der Sinn der Sache. Die Statistik zeigt zusammengefasste Zahlen zu Browser, Betriebssystem, Gerät und Verweisquelle, aber niemals die Identität eines einzelnen Besuchers. IPs sind mit einem Geheimnis gehasht, vollständige User-Agents werden nie gespeichert.
Gehen Kurzlinks kaputt, wenn sich das Ziel ändert?
Ja. MSK Shortener speichert die URL genau so, wie du sie eingereicht hast. Verschwindet das Ziel, führt der Kurzlink auf eine kaputte Seite. Eine eingebaute Prüfung der Linkgesundheit gibt es nicht.
Die API benutzen
Wo ist mein API-Key?
Den bekommst du vom Betreiber. Wer über die API Links anlegen will, braucht einen Key, der
mit msks_ beginnt. Ausgestellt werden Keys nur auf dem Server, eine Registrierung oder
Selbstbedienung gibt es nicht. Die gehostete Instanz s.msk-scripts.de gibt keine Keys an andere aus, dort kürzt du Links über die Website. Hostest du MSK Shortener
selbst, legst du einen mit sudo bash /opt/msk-shortener/scripts/api-key.sh create "<label>"
an, siehe Installation. Links nachschlagen, Passwörter prüfen
und mit dem Lösch-Token löschen geht weiterhin ohne Key.
Warum bekomme ich 429 Too Many Requests?
Du hast eine Grenze erreicht. Welche, steht im Feld code der Antwort, und wie viele
Sekunden du warten musst, im Header Retry-After, sofern er mitkommt. Es gibt diese
Grenzen:
- Anlegen mit API-Key: 120 pro Stunde je Key (
key-limit) - Anlegen aus dem Formular: 20 pro Stunde je IP-Hash (
rate-limit) und 20 je IP-Adresse und 24 Stunden (daily-limit) - Prüfen (Passwort): 10 je 5 Minuten und IP-Hash, als Schutz gegen Durchprobieren
Betreibst du eine eigene Instanz und brauchst mehr, ändere API_KEY_CREATE_PER_HOUR,
RATE_LIMIT_CREATE_PER_HOUR oder DAILY_LINKS_PER_IP in der .env.
Wie lösche ich einen Link über die API?
Schick ein DELETE /api/links/:code mit dem Lösch-Token als Bearer-Header:
curl -X DELETE https://s.msk-scripts.de/api/links/msk \
-H "Authorization: Bearer dk_a7c4f2..."
Warum lehnt die API meine URL mit „Interne / private Adressen sind nicht erlaubt" ab?
Du wolltest eine URL kürzen, die auf einen privaten IP-Bereich oder auf localhost zeigt. Das ist der SSRF-Schutz, siehe Datenschutz und Sicherheit. Der Kürzer ist nur für öffentliche Ziele gedacht.
Warum lehnt die API meinen Link mit 422 ab?
Das Ziel ist an der Zielprüfung hängen geblieben. Links auf den Kürzer selbst, auf andere
URL-Kürzer, auf nackte IP-Adressen und auf Hostnamen, die wie Phishing-Seiten gebaut sind,
werden abgelehnt, im Formular genauso wie mit API-Key. Welche Prüfung es war, steht im Feld
code: own-link, shortener, ip-host oder phishing. Einzelheiten unter
Bedienung.
Bekomme ich eine Liste aller Links, die ich angelegt habe?
Nein. Es gibt keinen Verlauf je Nutzer, die Datenbank weiß nicht, welche Links „dir" gehören. Sichere die Lösch-Token bei dir, wenn du einen persönlichen Verlauf willst.
Selbst hosten
502 Bad Gateway von Apache
Apache erreicht den Node-Prozess nicht. Prüfe:
sudo systemctl status msk-shortener
sudo journalctl -u msk-shortener -n 100
sudo ss -tlnp | grep 3011
Startet der Dienst nicht, schau ins Journal. Die häufigsten Ursachen sind:
- fehlende oder falsche Werte in der
.env, vor allemDB_*undIP_HASH_SECRET - die Datenbank verweigert die Verbindung
- Port
3011ist schon von einem anderen Prozess belegt
Port 3011 ist belegt
Stoppe entweder den störenden Prozess oder ändere den Port an drei Stellen: in der .env
(PORT=3014), in der package.json (next start -p 3014) und im Apache-vHost
(ProxyPass http://localhost:3014/). Danach beide Dienste neu starten.
„Cannot find module" nach dem Deploy
Meist ist npm ci fehlgeschlagen oder node_modules/ fehlt. Im Projektverzeichnis:
sudo rm -rf node_modules
sudo npm ci
sudo npm run build
sudo systemctl restart msk-shortener
Datenbankfehler beim Start
Error: Access denied for user 'msk_shortener'@'localhost'
Die Zugangsdaten in der .env passen nicht zu denen in MariaDB. Prüfe es, indem du dich von
Hand anmeldest:
mysql -u msk_shortener -p msk_shortener
Klappt das nicht, lege den Nutzer neu an, siehe Installation.
IP_HASH_SECRET is required beim Start
Du hast das Geheimnis in der .env nicht gesetzt. Erzeuge eines:
openssl rand -hex 32
Trag es in die .env ein und starte den Dienst neu.
Änderst du IP_HASH_SECRET nachträglich, gelten alle bestehenden Hashes der
Ratenbegrenzung und der Klicks als „andere Besucher". Daten verlierst du dabei nicht, nur
die Kontinuität im Fenster der Ratenbegrenzung.
Das Formular kürzt keine Links
In Produktion braucht das Formular Cloudflare Turnstile. Fehlen CAPTCHA_SITE_KEY und
CAPTCHA_SECRET_KEY in der .env, kürzt es nichts und antwortet mit 503 und
code: "captcha-unavailable". Lege im Cloudflare-Dashboard ein Turnstile-Widget für den
Hostnamen deiner Instanz an, trag beide Schlüssel in die .env ein und starte den Dienst
neu. Die Testschlüssel von Cloudflare funktionieren nur außerhalb der Produktion. Siehe
Installation.
Ratenbegrenzung von Let's Encrypt erreicht
Hast du beim Ausprobieren mit certbot die Grenze gerissen, nimm zum Testen die Staging-Umgebung:
sudo certbot --apache --staging -d s.example.com
Sobald die Einrichtung sicher steht, führst du es ohne --staging aus und bekommst das
echte Zertifikat.
Die Migration ist mittendrin abgebrochen
Der Migrationslauf ist wiederholbar. Erfolgreich ausgeführte Dateien stehen in der Tabelle
_migrations. Repariere die fehlerhafte SQL-Datei und führe npm run migrate erneut aus,
bereits angewandte Migrationen werden übersprungen.
Wie sichere ich vor einem Update?
Mit dem beiliegenden Skript:
sudo bash /opt/msk-shortener/deployment/scripts/backup.sh
Es legt einen SQL-Dump mit Datum im Dateinamen unter /opt/msk-shortener/backups/ ab.
Standardmäßig bleiben 14 Tage erhalten.
Kann ich MSK Shortener und MSK Paste auf demselben Server betreiben?
Ja, das ist der übliche Aufbau. Sie nutzen verschiedene Ports (3011 und 3012), getrennte
Datenbanken und getrennte Apache-vHosts. Die Installationsskripte sind darauf ausgelegt,
nebeneinander zu bestehen.
Funktionen
Warum werden beliebige Protokolle wie ftp:// oder magnet: nicht unterstützt?
Akzeptiert werden nur http:// und https://, weil das für einen öffentlichen Kürzer die
sichersten Voreinstellungen sind. Andere Schemata zuzulassen hieße, dass jemand Opfer auf
Dateifreigaben oder tief in Apps hinein umlenken kann. Brauchst du das für eine private
Installation wirklich, steht die Prüfung in src/lib/validation.ts und lässt sich lockern.
Warum gibt es keine Linkvorschau über OG-Tags?
Um datenschutzfreundlich und schlank zu bleiben. Eine Vorschau würde bedeuten, dass der Kürzer bei jedem Kurzlink die Ziel-URL abruft. Das verrät erstens Klick-Metadaten an den Zielserver und öffnet zweitens trotz Eingabefilter eine SSRF-Angriffsfläche.
Kommen eigene Domains noch dazu?
Im jetzigen Aufbau nicht. Der Kürzer geht von einer einzigen Basis-URL je Instanz aus
(NEXT_PUBLIC_BASE_URL). Willst du für ein anderes Publikum eine andere Kurzdomain,
betreibe eine zweite Instanz.
Kann ich Links stapelweise importieren oder exportieren?
Über die Oberfläche nicht, aber die REST-API lässt sich für beide Richtungen skripten. Zum stapelweisen Anlegen brauchst du einen API-Key, ein Key kürzt bis zu 120 Links pro Stunde:
# Stapelweise anlegen
while read url; do
curl -sS -X POST https://s.msk-scripts.de/api/links \
-H "Authorization: Bearer $MSK_SHORTENER_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg u "$url" '{url: $u}')" \
| jq -r '"\(.shortUrl) \(.deleteToken)"'
done < urls.txt
Bei einer eigenen Instanz ist direktes SQL der einfachste Weg zum Export:
SELECT short_code, original_url, expires_at, click_count FROM links;
Gibt es ein Kommandozeilenwerkzeug?
Offiziell noch nicht. Auf der Seite zur REST-API steht eine kleine Bash-Funktion
(mskshort()), die du in deine ~/.bashrc legen kannst. Ein richtiges Werkzeug ist geplant.
Kommst du trotzdem nicht weiter?
- Mach ein Issue auf GitHub auf
- Komm in den Discord von MSK Scripts
- Bei Sicherheitsproblemen schau auf die Seite Datenschutz und Sicherheit