docs(cache): add comprehensive cache configuration and permission handling guides
- Introduce `cache-configuration.md` for detailed instructions on cache setup, permission troubleshooting, and best practices. - Add `cache-permissions-quick-fix.md` for concise resolutions to common permission errors. - Include a detailed `FILECACHE_PERMISSION_FIX_PLAN.md` outlining solutions for permission-related issues. - Enhance `docker-entrypoint.sh` with permission fixes for multi-user caches. - Update `Makefile` with cache clear commands for local and staging environments. - Improve `FileCache` for graceful degradation on permission errors, ensuring reliability under multi-user scenarios.
This commit is contained in:
244
docs/deployment/cache-configuration.md
Normal file
244
docs/deployment/cache-configuration.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# Cache Configuration & Permissions
|
||||
|
||||
## ?bersicht
|
||||
|
||||
Diese Dokumentation beschreibt die Konfiguration und Berechtigungsverwaltung f?r das FileCache-System auf Staging und Production-Servern.
|
||||
|
||||
## Problem-Background
|
||||
|
||||
Das FileCache-System speichert Cache-Dateien in `/var/www/html/storage/cache`. In Multi-User/Process-Umgebungen k?nnen Permission-Probleme auftreten, wenn:
|
||||
|
||||
- Cache-Dateien von verschiedenen Prozessen/Usern erstellt werden
|
||||
- Owner/Group-Mismatch zwischen erstellenden und l?schenden Prozessen
|
||||
- Falsche Berechtigungen auf Cache-Dateien oder Verzeichnissen
|
||||
|
||||
### Gel?ste Probleme
|
||||
|
||||
? **Bug-Fix**: `FileStorage::delete()` pr?ft jetzt nur noch Verzeichnis-Rechte (nicht Datei-Rechte)
|
||||
? **Graceful Degradation**: FileCache f?ngt Permission-Exceptions und arbeitet weiter
|
||||
? **Robuste Fehlerbehandlung**: Cache funktioniert auch bei Permission-Problemen
|
||||
|
||||
## Berechtigungen
|
||||
|
||||
### Verzeichnis-Berechtigungen
|
||||
|
||||
Das Cache-Verzeichnis sollte folgende Berechtigungen haben:
|
||||
|
||||
```bash
|
||||
# Verzeichnis: 775 (rwxrwxr-x)
|
||||
# - Owner: rwx (read, write, execute)
|
||||
# - Group: rwx (read, write, execute)
|
||||
# - Others: r-x (read, execute)
|
||||
chmod 775 /var/www/html/storage/cache
|
||||
```
|
||||
|
||||
### Datei-Berechtigungen
|
||||
|
||||
Cache-Dateien werden mit folgenden Berechtigungen erstellt:
|
||||
|
||||
```php
|
||||
// 0644 (rw-r--r--)
|
||||
// - Owner: rw- (read, write)
|
||||
// - Group: r-- (read)
|
||||
// - Others: r-- (read)
|
||||
```
|
||||
|
||||
**Wichtig**: F?r das L?schen von Dateien werden nur **Verzeichnis-Rechte** ben?tigt, nicht Datei-Rechte!
|
||||
|
||||
## Docker Entrypoint-Script
|
||||
|
||||
Das Entrypoint-Script (`docker/php/docker-entrypoint.sh`) setzt automatisch die korrekten Berechtigungen:
|
||||
|
||||
```bash
|
||||
# Fix ownership for all storage directories (including mounted volumes)
|
||||
if [ -d /var/www/html/storage ]; then
|
||||
chown -R appuser:appuser /var/www/html/storage 2>/dev/null || true
|
||||
chmod -R 775 /var/www/html/storage 2>/dev/null || true
|
||||
fi
|
||||
```
|
||||
|
||||
### Wichtig f?r Staging/Production
|
||||
|
||||
1. **Named Volumes**: Docker erstellt Named Volumes als root - das Entrypoint-Script fixiert Ownership nach dem Mount
|
||||
2. **Wartezeit**: `sleep 1` stellt sicher, dass Docker Volumes gemountet hat
|
||||
3. **Graceful Degradation**: `|| true` stellt sicher, dass das Script nicht bei Permission-Fehlern abbricht
|
||||
|
||||
## Manuelle Fixes
|
||||
|
||||
### Fix Berechtigungen auf Staging/Production
|
||||
|
||||
```bash
|
||||
# Auf dem Server ausf?hren
|
||||
docker exec -it staging-app chown -R appuser:appuser /var/www/html/storage/cache
|
||||
docker exec -it staging-app chmod -R 775 /var/www/html/storage/cache
|
||||
```
|
||||
|
||||
### Fix existierende Cache-Dateien
|
||||
|
||||
```bash
|
||||
# Als root im Container - ermittle User automatisch
|
||||
docker exec -it --user root staging-app bash -c '
|
||||
# Ermittle User aus PHP-FPM Config oder verwende www-data als Fallback
|
||||
USER=$(grep "^user = " /usr/local/etc/php-fpm.d/*.conf 2>/dev/null | head -1 | cut -d"=" -f2 | tr -d " ;")
|
||||
[ -z "$USER" ] && USER="www-data"
|
||||
echo "Using user: $USER"
|
||||
|
||||
# Fix Permissions
|
||||
find /var/www/html/storage/cache -type f -exec chmod 644 {} \;
|
||||
find /var/www/html/storage/cache -type d -exec chmod 775 {} \;
|
||||
chown -R $USER:$USER /var/www/html/storage/cache
|
||||
'
|
||||
```
|
||||
|
||||
### Cleanup nicht l?schbarer Dateien
|
||||
|
||||
Falls nach dem Fix noch Dateien vorhanden sind, die nicht gel?scht werden k?nnen:
|
||||
|
||||
```bash
|
||||
# Als root im Container
|
||||
docker exec -it --user root staging-app bash
|
||||
cd /var/www/html/storage/cache
|
||||
chown -R appuser:appuser .
|
||||
chmod -R 775 .
|
||||
exit
|
||||
```
|
||||
|
||||
## Ansible-Integration
|
||||
|
||||
F?r Ansible-Deployments k?nnen folgende Tasks hinzugef?gt werden:
|
||||
|
||||
```yaml
|
||||
- name: Fix cache directory permissions
|
||||
file:
|
||||
path: "{{ app_storage_path }}/cache"
|
||||
owner: appuser
|
||||
group: appuser
|
||||
mode: '0775'
|
||||
recurse: yes
|
||||
state: directory
|
||||
become: yes
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Problem: Permission denied beim L?schen
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
FilePermissionException: Permission denied for delete on file: ...cache.php (File is not writable)
|
||||
```
|
||||
|
||||
**L?sung**:
|
||||
1. Pr?fe Verzeichnis-Berechtigungen: `ls -ld /var/www/html/storage/cache`
|
||||
2. Pr?fe Owner: `ls -l /var/www/html/storage/cache | head`
|
||||
3. Fix Berechtigungen (siehe oben)
|
||||
|
||||
### Problem: Cache-Dateien werden von verschiedenen Usern erstellt
|
||||
|
||||
**Symptom**: Dateien haben unterschiedliche Owner
|
||||
|
||||
**L?sung**:
|
||||
- Stelle sicher, dass alle PHP-Prozesse als `appuser` laufen
|
||||
- Pr?fe PHP-FPM Pool-Konfiguration
|
||||
- Stelle sicher, dass Entrypoint-Script korrekt l?uft
|
||||
|
||||
### Problem: Cache funktioniert nicht nach Deployment
|
||||
|
||||
**Symptom**: Cache-Operationen schlagen fehl
|
||||
|
||||
**Diagnose**:
|
||||
```bash
|
||||
# Pr?fe Verzeichnis existiert
|
||||
docker exec staging-app ls -la /var/www/html/storage/cache
|
||||
|
||||
# Pr?fe Berechtigungen
|
||||
docker exec staging-app stat /var/www/html/storage/cache
|
||||
|
||||
# Pr?fe Owner
|
||||
docker exec staging-app whoami
|
||||
```
|
||||
|
||||
**L?sung**:
|
||||
- Stelle sicher, dass Entrypoint-Script ausgef?hrt wurde
|
||||
- Manuell Berechtigungen fixen (siehe oben)
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Verzeichnis-Berechtigungen
|
||||
|
||||
- **Verzeichnis**: 775 (rwxrwxr-x) - Group-writable f?r Multi-User
|
||||
- **Dateien**: 644 (rw-r--r--) - Standard f?r Cache-Dateien
|
||||
|
||||
### 2. Owner/Group
|
||||
|
||||
- **Owner**: `appuser` (der User, der PHP-Prozesse ausf?hrt)
|
||||
- **Group**: `appuser` (oder gemeinsame Gruppe f?r alle Prozesse)
|
||||
|
||||
### 3. Monitoring
|
||||
|
||||
?berwache Cache-Verzeichnis auf Permission-Probleme:
|
||||
|
||||
```bash
|
||||
# Finde Dateien mit falschen Owner
|
||||
find /var/www/html/storage/cache -not -user appuser
|
||||
|
||||
# Finde Dateien mit falschen Permissions
|
||||
find /var/www/html/storage/cache -type f -not -perm 644
|
||||
```
|
||||
|
||||
### 4. Cleanup
|
||||
|
||||
Regelm??iges Cleanup von abgelaufenen Cache-Dateien:
|
||||
|
||||
```bash
|
||||
# Manueller Cleanup
|
||||
docker exec staging-app php console.php cache:clear
|
||||
|
||||
# Oder via Cronjob
|
||||
0 2 * * * docker exec staging-app php console.php cache:clear
|
||||
```
|
||||
|
||||
## Code-?nderungen
|
||||
|
||||
### FileStorage::delete()
|
||||
|
||||
**Vorher**: Pr?fte `is_writable()` auf Datei (falsch!)
|
||||
**Nachher**: Pr?ft nur Verzeichnis-Rechte (korrekt!)
|
||||
|
||||
```php
|
||||
// WICHTIG: F?r unlink() braucht man nur Schreibrechte im Verzeichnis!
|
||||
$dir = dirname($resolvedPath);
|
||||
if (! is_writable($dir)) {
|
||||
throw FilePermissionException::delete($path, 'Directory is not writable');
|
||||
}
|
||||
// ENTFERNT: is_writable() Pr?fung auf Datei
|
||||
```
|
||||
|
||||
### FileCache Graceful Degradation
|
||||
|
||||
Alle `delete()` Aufrufe in FileCache fangen jetzt `FilePermissionException`:
|
||||
|
||||
```php
|
||||
try {
|
||||
$this->fileSystem->delete($file);
|
||||
} catch (\App\Framework\Filesystem\Exceptions\FilePermissionException $e) {
|
||||
// Permission denied - continue (graceful degradation)
|
||||
continue;
|
||||
}
|
||||
```
|
||||
|
||||
## Weitere Ressourcen
|
||||
|
||||
- `docs/FILECACHE_PERMISSION_FIX_PLAN.md` - Detaillierter Fix-Plan
|
||||
- `docker/php/docker-entrypoint.sh` - Entrypoint-Script
|
||||
- `src/Framework/Filesystem/FileStorage.php` - FileSystem-Implementierung
|
||||
- `src/Framework/Cache/Driver/FileCache.php` - FileCache-Implementierung
|
||||
|
||||
## Support
|
||||
|
||||
Bei Permission-Problemen:
|
||||
|
||||
1. Pr?fe Logs: `docker logs staging-app | grep -i permission`
|
||||
2. Pr?fe Berechtigungen: `docker exec staging-app ls -la /var/www/html/storage/cache`
|
||||
3. Fix manuell: Siehe "Manuelle Fixes" oben
|
||||
4. Pr?fe Code: Stelle sicher, dass neueste Version deployed ist
|
||||
Reference in New Issue
Block a user