blob: 7d9a2733dbedd1baebc5237d2f6729344e67dd69 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
# TROUBLESHOOTING
## Objectif
Fournir une procedure de diagnostic et resolution rapide des incidents.
## Symptomes frequents
- Echec connexion Keycloak
- Refus d'acces media (403)
- Erreur token/JWT
- Indisponibilite stockage media
- Decalage horaire VM / erreurs de validation temporelle (token, TLS)
## Checklist de diagnostic initial
1. Identifier l'environnement impacte.
2. Verifier l'etat des services.
3. Consulter les logs applicatifs et IAM.
4. Reproduire le probleme avec un cas minimal.
## Checklist express: `photos.arauco.online` inaccessible
Executer dans cet ordre pour isoler rapidement le point de blocage.
```bash
# 1) DNS: le domaine doit pointer vers l'IP de araucaria (Caddy)
dig +short photos.arauco.online
# 2) Reachability 443 depuis client
curl -vkI https://photos.arauco.online
# 3) Caddy actif et sans erreur de config sur araucaria
sudo caddy validate --config /etc/caddy/Caddyfile && sudo systemctl status caddy --no-pager
# 4) Port 443 ecoute sur araucaria
sudo ss -lntp | grep :443
# 5) Backend viewer-bff reachable depuis araucaria
curl -I http://192.168.99.23:8082/health
```
Interpretation rapide:
- (1) vide ou mauvaise IP: corriger dnsmasq.
- (2) timeout/refused: route/firewall/Caddy KO.
- (3) echec validate: corriger Caddyfile.
- (4) rien sur 443: Caddy non demarre ou bind incorrect.
- (5) backend KO: service viewer-bff/route VM a corriger.
## Matrice cause probable -> action
| Symptom | Cause probable | Verification | Action corrective |
| --- | --- | --- | --- |
| 401/403 | Role/groupe manquant | Inspecter claims JWT | Corriger mapping roles/groupes |
| Timeout | Service indisponible | Healthcheck et reseau | Redemarrer service / corriger reseau |
| Token invalide | Mauvaise config OIDC | Verifier issuer/audience | Corriger configuration client |
| 401 sur viewer-bff | Token absent/non transfere | Verifier header Authorization | Rejouer avec Bearer token valide |
| `denied` pull image `media-access-api` | Image distante invalide/inaccessible | Verifier `MEDIA_ACCESS_API_IMAGE` et dossier `media-access-api/` | Utiliser build local compose et relancer avec `--build` |
| Scripts tests KO sous WSL (`bash\r`) | Fins de ligne CRLF | `file tests/*.sh`, message `/usr/bin/env: bash\r` | Convertir en LF (`sed -i 's/\r$//' tests/*.sh`) et rejouer |
| Heure incoherente | NTP non synchronise | `timedatectl`, `chronyc tracking` | Configurer chrony vers `araucaria` |
| Nom DNS local non resolu | Record dnsmasq absent/invalide | `dig +short <host>.arauco.online` | Corriger fichier dnsmasq puis restart service |
| HTTPS KO via domaine | Caddy non charge / vhost invalide | `caddy validate`, `journalctl -u caddy` | Corriger Caddyfile puis reload Caddy |
## Procedure de resolution
1. Isoler la cause racine.
2. Appliquer la correction minimale.
3. Valider la resolution.
4. Documenter l'incident et la correction.
## Escalade
- Niveau 1:
- Niveau 2:
- Niveau 3:
## Post-mortem court
- Impact:
- Cause racine:
- Correctif:
- Prevention:
## Template d'incident
- Utiliser `docs/TEMPLATE_INCIDENT.md` pour chaque incident.
- Copier le template, le remplir, puis referencer l'entree dans `docs/CHANGELOG_OPERATIONS.md`.
## Historique incidents resolus
- Date:
- Incident:
- Resolution:
## Cas pratique: erreur 403 sur media protege
### Contexte
- Date: 2026-03-07
- Environnement: dev
- Symptome: utilisateur authentifie, mais acces refuse sur `GET /media/{id}` (403)
### Diagnostic
1. Token JWT decode: role `media_reader` absent.
2. Mapping Keycloak verifie: groupe `consultants` non mappe vers role applicatif.
3. Logs API confirment: `missing required role media_reader`.
### Correction appliquee
1. Ajouter mapper de groupe dans Keycloak (`consultants` -> `media_reader`).
2. Forcer reconnexion utilisateur pour emettre un nouveau token.
3. Rejouer le test d'acces sur le meme media.
### Validation
- Avant correctif: 403 confirme.
- Apres correctif: 200 confirme.
- Aucun impact detecte sur les autres roles.
### Prevention
- Ajouter test automatique de non-regression RBAC (cas 200/403).
- Exiger verification des mappers lors de creation de nouveau groupe.
## Cas pratique: DNS local medias non resolu
### Contexte
- Symptome: `photos.arauco.online` ne repond pas ou resolve une mauvaise IP.
### Diagnostic
1. Verifier fichier `/etc/dnsmasq.d/20-medias-araucaria.conf`.
2. Verifier syntaxe: `sudo dnsmasq --test`.
3. Verifier service: `sudo systemctl status dnsmasq --no-pager`.
4. Verifier resolution: `dig +short photos.arauco.online`.
### Correction appliquee
1. Corriger les records `host-record` vers l'IP de `araucaria` (Caddy).
2. Redemarrer `dnsmasq`.
3. Vider cache DNS poste client si necessaire.
### Validation
- `dig +short photos.arauco.online` retourne l'IP de `araucaria`.
- Acces URL de service valide.
## Cas pratique: domaine HTTPS indisponible via Caddy
### Contexte
- Symptome: `https://photos.arauco.online` indisponible alors que le service local repond.
### Diagnostic
1. Verifier Caddy: `sudo caddy validate --config /etc/caddy/Caddyfile`.
2. Verifier etat: `sudo systemctl status caddy --no-pager`.
3. Verifier logs: `sudo journalctl -u caddy -n 100 --no-pager`.
4. Verifier backend: `curl -I http://192.168.99.23:8082/health`.
### Correction appliquee
1. Corriger le bloc de vhost dans Caddyfile.
2. Recharger: `sudo systemctl reload caddy`.
3. Rejouer le test HTTPS.
## Cas pratique: erreur `denied` sur `media-access-api`
### Contexte
- Symptome: `docker compose up` echoue avec `Head https://ghcr.io/... denied`.
### Diagnostic
1. Verifier la variable: `grep MEDIA_ACCESS_API_IMAGE .env.dev`.
2. Verifier la presence du code local: `ls -la media-access-api`.
3. Verifier compose: `media-access-api` doit avoir un bloc `build`.
### Correction appliquee
1. Garder/mettre `MEDIA_ACCESS_API_IMAGE=local/media-access-api:dev`.
2. S'assurer que `media-access-api/` contient `Dockerfile` + code.
3. Relancer: `docker compose --env-file .env.dev -f compose.photoprism-secure.dev.yml up -d --build`.
|
