Troubleshooting

Diese Seite sammelt typische Probleme beim Betrieb und bei der Benutzung von FreeCAD-PLM.

Beginne bei Fehlern immer mit der Frage: Ist es ein Bedienproblem, ein Datenproblem oder ein Betriebsproblem? Die Web-Oberfläche zeigt viele fachliche Konflikte direkt an. Wenn Jobs nicht laufen oder Seiten nicht laden, helfen die Containerlogs.

Containerstatus prüfen

cd /opt/freecad-plm
docker compose -f docker-compose.image.yml ps

Logs:

docker compose -f docker-compose.image.yml logs -f --tail=200 web
docker compose -f docker-compose.image.yml logs -f --tail=200 worker
docker compose -f docker-compose.image.yml logs -f --tail=300 web worker

Login funktioniert nicht

Prüfe:

• wurde ein Superuser angelegt?
• läuft der Webcontainer?
• ist DJANGO_ALLOWED_HOSTS passend gesetzt?
• rufst du /login/ auf und nicht nur den Django-Admin?

Superuser anlegen:

docker compose -f docker-compose.image.yml exec web python manage.py createsuperuser

CSRF-Verifizierung fehlgeschlagen

Das passiert meist hinter einem Reverse Proxy, wenn Host oder Origin nicht passen.

In .env müssen die öffentlichen Namen stehen:

DJANGO_ALLOWED_HOSTS=plm.example.local,localhost,127.0.0.1
DJANGO_CSRF_TRUSTED_ORIGINS=https://plm.example.local

Danach Web und Worker neu erstellen:

docker compose -f docker-compose.image.yml up -d --force-recreate web worker

Static-Dateien sehen falsch aus oder Admin-CSS fehlt

Typische Ursachen:

• staticfiles/ gehört dem falschen User,
• collectstatic konnte nicht schreiben,
• ein Reverse Proxy leitet /static/ falsch um.

Prüfe die Rechte:

sudo chown -R 1000:1000 staticfiles

Dann Webcontainer neu starten:

docker compose -f docker-compose.image.yml up -d --force-recreate web

Upload ist zu groß

FreeCAD-PLM begrenzt Uploads gegen sehr große Dateien und ZIP-Bomben. Relevante Werte in .env:

PLM_MAX_FCSTD_UPLOAD_BYTES=200000000
PLM_MAX_PROJECT_ZIP_BYTES=500000000
PLM_MAX_ZIP_MEMBERS=2000
PLM_MAX_ZIP_UNCOMPRESSED_BYTES=2147483648
PLM_MAX_ZIP_MEMBER_BYTES=200000000

Wenn ein Reverse Proxy davor sitzt, muss auch dessen Upload-Limit passen, zum Beispiel bei Nginx:

client_max_body_size 512m;

Jobs bleiben wartend

Wenn Analyse, Export oder PNG-Ansichten nicht laufen, prüfe den Worker:

docker compose -f docker-compose.image.yml ps worker
docker compose -f docker-compose.image.yml logs -f --tail=200 worker

Der Worker muss Zugriff auf dasselbe storage/ haben wie der Webcontainer.

Wenn der Worker nicht läuft, können Uploads und Downloads trotzdem funktionieren. Alles, was FreeCADCmd braucht, bleibt dann aber liegen: Analyse, Exporte, PNG-Ansichten und teilweise Viewer-Vorschauen.

FreeCADCmd-Fehler

Prüfe im Worker-Log, ob freecadcmd gefunden wird und die Datei laden kann.

Relevante .env-Werte:

FREECADCMD_COMMAND=freecadcmd
PREVIEW_PNG_WIDTH=400
PREVIEW_PNG_HEIGHT=300
PROCESS_EXPORT_JOBS_INLINE=0

Im normalen Docker-Image sollte der Worker FreeCADCmd enthalten. Das Web-Image enthält FreeCAD bewusst nicht.

Keine neuen Revisionen nach Projekt-ZIP-Import

Ein neuer Projektstand bedeutet nicht automatisch neue Revisionen. Neue Revisionen entstehen nur für modellrelevante Änderungen.

Wenn sich nur technische FreeCAD-Speicherdaten geändert haben, kann FreeCAD-PLM den Stand als fachlich unverändert erkennen.

Prüfe:

• wurde wirklich die geänderte Datei ins ZIP gepackt?
• liegt die geänderte Datei unter demselben relativen Pfad?
• wurde das ZIP neu erzeugt und nicht versehentlich ein alter Stand hochgeladen?
• ist die Änderung im Modell selbst sichtbar?

3MF-Metadaten fehlen

Nicht jede 3MF-Datei enthält Slicer-Konfiguration. Manche Dateien enthalten nur Geometrie und ein Thumbnail.

Wenn Metadaten fehlen:

• prüfe, ob die Datei wirklich aus dem Slicer als Projekt-/Druckdatei gespeichert wurde,
• prüfe, ob es eine Bambu-/Orca-/Prusa-artige 3MF mit Metadata/*.config ist,
• trage wichtige Werte manuell im Uploadformular ein.

Registry-Image aktualisieren

Wenn nach einem neuen Commit Funktionen fehlen, ist oft das Image noch nicht neu gebaut oder der Server hat es noch nicht gezogen.

Update auf dem Server:

cd /opt/freecad-plm
git pull
docker compose -f docker-compose.image.yml pull
docker compose -f docker-compose.image.yml up -d

Docker-Platte voll

Auf Build-Hosts können alte Images und Build-Caches viel Platz belegen:

docker system df
docker image prune -af
docker builder prune -af
docker container prune -f

Diese Befehle entfernen ungenutzte lokale Docker-Daten. Auf einem Produktivhost vorher prüfen, ob keine lokal benötigten Images ausschließlich dort liegen.