FAQ für den appleJuice Server

1. Was machen die Server?

Vermitteln Download-, Upload- und Suchanfragen der Clients untereinander
Verwalten gemeinsam den Index des gesamten Netzwerkes (Hashtable)
Verwalten eine Whitelist der erlaubten Cores

Die Server stellen keine Dateien zur Verfügung.

3.1 Benötigt der Server Java?

Nein. Ab Version 0.95.x ist der Server in Go geschrieben und benötigt keine Java-Laufzeit. Verwende das passende Paket für dein Betriebssystem und deine Prozessorarchitektur. Nur die ältere Java-Serverreihe 0.85.x benötigt Java 25.

3.2 Welche Ports braucht der Server?

Der Server nutzt drei TCP-Ports. In der server.json werden zwei davon festgelegt:

port: Verbindung der Cores zum Server, beispielsweise 9855.
port + 1: Verbindung zwischen Servern, im Beispiel 9856. Dieser Port wird automatisch abgeleitet.
webport: Web-Oberfläche, beispielsweise 8001.

Die beiden Server-Ports müssen für andere Cores bzw. Server über Router und Firewall erreichbar sein.

Die Web-Oberfläche erreichst du bei lokalem Betrieb mit webport 8001 unter http://127.0.0.1:8001/, sofern die Bind-Adresse dies zulässt.

Gib den Web-Port nur für benötigte Zugriffe frei. Für Zugriffe über das Internet sollte ein HTTPS-Reverse-Proxy vorgeschaltet werden; der Server selbst verwendet HTTP.

3.3 Was bedeuten die Farben in der Web-Oberfläche?

Anzeige	Bedeutung
Grüner Punkt	Zu diesem Server besteht gerade eine offene TCP-Verbindung.
Grauer Punkt	Gerade keine offene TCP-Verbindung. Das bedeutet nicht, dass der Server offline ist.
Farben im Routing-Balken	Jede Farbe kennzeichnet einen Server und dessen Anteil am Hash-Raum. Dieselbe Farbe erscheint in Serverliste und Legende.
Schraffierter Routing-Anteil	Der zugehörige Server gilt momentan als inaktiv.

Verbindungen zwischen Servern sind meist kurz. Viele graue Punkte sind deshalb normal. Die Routing-Anteile beschreiben Hash-Bereiche, nicht Dateimengen oder Traffic.

3.4 Glossar

Begriff	Bedeutung
Routing table / Hashtable	Aufteilung des Hash-Raums auf die zuständigen Server. Die angezeigte Zeit ist der Erstellungszeitpunkt der Tabelle.
I-Time	Erstellungszeitpunkt der Whitelist eines Servers. Sie legt erlaubte Core-Builds und das Mindestprotokoll fest.
Last seen	Zeit seit dem letzten Lebenszeichen. Als aktiv gelten Server mit einem Lebenszeichen innerhalb der letzten fünf Minuten.
Refs	Einträge im Dateiindex, die auf diesen Server verweisen. Referenzierte Server werden nicht aus der Liste entfernt.
Rep	Erreichbarkeitsbewertung: Eine erfolgreiche Verbindung bringt 20 Punkte (höchstens 10 insgesamt), ein Fehlversuch kostet 50. Server mit negativer Bewertung erhalten keinen Hash-Bereich.
Queue	Protokollbefehle, die auf die nächste Verbindung zu diesem Server warten.
Tasks	Anzahl der Go-Goroutines im Systembereich. Der Klammerwert zieht offene Verbindungen ab und ist nur ein grober Anhaltspunkt, keine genaue Aufschlüsselung.
Hash share	Anteil am Hash-Raum, nicht Anteil an Dateien oder Traffic.

3.5 Wie kann ich die Meldungen mitloggen?

Die Web-Oberfläche zeigt die letzten 1.000 Logzeilen. Unter Windows gibt es bei aktiviertem Tray zusätzlich ein Logfenster.

Für eine dauerhafte Datei kannst du den Server unter Linux oder macOS im Terminal starten und die Ausgaben umleiten:

./ajserver -notray >> aj.txt 2>&1

Die Datei aj.txt wird im aktuellen Arbeitsverzeichnis angelegt bzw. ergänzt. Mit -notray ist dieses Verzeichnis auch der Standard-Datenordner; mit -data /pfad/zum/datenordner kannst du ihn ausdrücklich festlegen.

Bei Docker findest du die Ausgaben über docker logs <Containername>.

3.6 Wie kann ich noch Informationen vom Server abrufen?

Zusätzlich zur Web-Oberfläche stellt der Server folgende HTTP-Endpunkte am webport bereit:

/info.json: Serverstatus als JSON
/serverlist.json: bekannte Server als JSON
/metrics: Messwerte für Prometheus
/log: letzte Logzeilen als JSON
/healthz: Health-Check ohne Anmeldung

Bis auf /healthz benötigen diese Endpunkte HTTP Basic Auth mit webuser und webpw aus der server.json. Beispiel bei lokalem Betrieb: http://127.0.0.1:8001/info.json.

/info.xml gibt es ab 0.95.x nicht mehr. Verwende die JSON-Endpunkte statt HTML-Dateien der Web-Oberfläche auszulesen.

4.1 Beim Serverstart öffnet sich kein Fenster

Unter Linux und macOS gibt es kein natives Logfenster. Öffne die Web-Oberfläche im Browser, um Status und Log zu sehen.

Unter Windows öffnet sich bei aktiviertem Tray ein Logfenster. Über Show console im Tray-Menü kannst du es wieder einblenden. Das Schließen-Kreuz blendet es nur aus; Exit im Tray beendet den Server.

Mit -notray oder AJ_NOTRAY=1 läuft der Server ohne Tray und natives Logfenster. Starte ihn zur Fehlersuche im Terminal und prüfe die dortigen Ausgaben. Die Web-Oberfläche bleibt verfügbar, sobald der Server erfolgreich gestartet ist.

4.3 Der Server beendet sich gleich nach dem Start

Starte den Server im Terminal und lies die Fehlermeldung. Prüfe insbesondere:

Belegter Port: port, port + 1 und webport müssen frei sein. Prüfe, ob bereits eine Instanz läuft.
Bind-Adresse: bindip muss zu einer lokalen Netzwerkschnittstelle passen oder 0.0.0.0 sein.
Konfiguration: Prüfe die JSON-Syntax und die in der Fehlermeldung genannten Werte in server.json.
Datenordner: Mit -data /pfad/zum/datenordner kannst du den gewünschten Ordner ausdrücklich auswählen. Der Server benötigt dort passende Datei- und Verzeichnisrechte.

Eine vorhandene server.xml wird nur dann importiert, wenn noch keine server.json existiert. Änderungen an der XML-Datei wirken danach nicht mehr.

Der Zeitabgleich verwendet NTP. Der Zeitserver wird über timeserver konfiguriert; der alte Java-Parameter --usemyNTP gilt nicht für den Go-Server.

4.4 Der Server benötigt zu viel Speicher oder wird beendet

Prüfe das Serverlog und die Meldungen des Betriebssystems bzw. Containers auf Speichermangel. Beachte auch gesetzte Speicherlimits für den Dienst oder Container.

Die Web-Oberfläche zeigt unter Memory used den belegten Go-Heap und unter Memory system den von der Go-Laufzeit angeforderten Speicher einschließlich Reserven. Letzteres ist nicht der tatsächliche physische Speicherverbrauch des Prozesses.

Der Go-Server kennt keinen Java-Parameter -Xmx. GOMEMLIMIT ist ein weiches Speicherziel der Go-Laufzeit, keine feste Obergrenze für den gesamten Prozess.

4.5 Verbindungslimits vom Betriebssystem

Jede offene Netzwerkverbindung benötigt einen Dateideskriptor. Das verfügbare Limit hängt von Betriebssystem und Startumgebung ab; es beträgt nicht überall 1024.

Unter Linux zeigt ulimit -n das Limit der aktuellen Shell. Eine Erhöhung gilt für anschließend aus dieser Shell gestartete Prozesse und darf das harte Limit nicht überschreiten.

Bei einem systemd-Dienst ist LimitNOFILE maßgeblich, bei Docker die Einstellung --ulimit nofile=... bzw. ulimits in Compose. Prüfe die Grenzen der tatsächlichen Startumgebung statt nur die einer separaten Login-Shell.

4.6 Ich kann die Web-Oberfläche nicht öffnen

Bei lokalem Betrieb und webport 8001 lautet die Adresse http://127.0.0.1:8001/. Prüfe in der server.json:

bindip: Bei 0.0.0.0 lauscht der Server auf allen lokalen IPv4-Adressen. Bei einer einzelnen Adresse musst du diese verwenden; 127.0.0.1 funktioniert dann nur, wenn genau diese Adresse eingestellt ist.
webport: Verwende den eingestellten Port und prüfe Firewall bzw. Docker-Portfreigabe.
webuser und webpw: Diese Zugangsdaten werden für HTTP Basic Auth benötigt. Es gibt keinen zusätzlichen Administratorzugang mit der Server-IP als Passwort.

Nach Änderungen an der Konfiguration ist ein Neustart nötig. Der Server selbst spricht HTTP; für HTTPS ist ein Reverse-Proxy erforderlich, der auch WebSocket-Verbindungen für /ws weiterleitet.

4.7 Ich sehe in der Web-Oberfläche nur meinen Server

Dem Server fehlen bekannte andere Server. Prüfe im Log, ob der Abruf der öffentlichen Serverliste fehlgeschlagen ist oder über APPLEJUICE_SERVERLIST_URL abgeschaltet wurde.

Du kannst in der Web-Oberfläche unter Servers einen Server aus der Serverliste mit Host und Core-Port hinzufügen. Für die Verbindung zwischen Servern wird automatisch der nächste Port verwendet.

Kommt weiterhin kein Kontakt zustande, prüfe DNS-Auflösung, Firewall und Erreichbarkeit beider Server-Ports. Einzelne graue Verbindungspunkte sind kein Beleg für Isolation; siehe Punkt 3.3.

4.8 Warum sehe ich nur wenige Verbindungen zu anderen Servern?

Die Serverliste zeigt bekannte Server, nicht nur offene Verbindungen. Verbindungen werden bei Bedarf für Routing-Tabellen, Quellenanfragen und andere Protokollaufgaben aufgebaut und sind meist kurz.

Viele graue Punkte bedeuten deshalb nicht, dass andere Server fehlen oder offline sind. Prüfe Last seen, die Routing-Tabelle und das Log, statt dauerhaft offene Verbindungen zu allen Servern zu erwarten.

Wenn tatsächlich nur der eigene Server in der Liste steht, siehe Punkt 4.7.

4.9 Wie ändere ich die Konfiguration?

Bearbeite die server.json im verwendeten Datenordner und starte den Server anschließend neu. Der Go-Server hat keinen reload-Befehl für die Konfiguration.

Mit -data oder AJ_DATA_DIR kannst du den Datenordner ausdrücklich wählen. Bei aktivem Tray ist der Standard ~/appleJuice/server, ohne Tray das Arbeitsverzeichnis.

Eine vorhandene server.xml wird einmalig importiert, wenn noch keine server.json existiert. Umgebungsvariablen zur Serverkonfiguration werden nur verwendet, wenn beide Dateien fehlen.

Der Konsolenbefehl infofile lädt ausschließlich die Whitelist neu, nicht die Serverkonfiguration.