Exploitation et dépannage

Exploitation de KiloCenter — points de terminaison de santé pour KC-Core, KC-Gateway, KC-Identity, problèmes de démarrage courants, diagnostics.

Objectif

Exécutez des vérifications reproductibles pour les problèmes de démarrage, de connectivité et les échecs de flux de messages.

Vérifications de santé

Depuis kilocenter-modules/:

# État de KC-Core
curl -s http://localhost:8086/health

# État de KC-Gateway
curl -s http://localhost:8087/health

# État du service gRPC
grpcurl -plaintext localhost:9090 grpc.health.v1.Health/Check

# Tous les services du conteneur
docker compose ps

Vérifications des ports

Vérifiez que tous les services attendus sont à l'écoute :

lsof -i :80     # KC-Web (mode conteneur)
lsof -i :9090   # KC-Gateway (gRPC-web)
lsof -i :8086   # État de KC-Core
lsof -i :8087   # État de KC-Gateway
lsof -i :5000   # BSSCI
lsof -i :5001   # SCACI
lsof -i :50051  # gRPC interne de KC-Core
lsof -i :5433   # PostgreSQL (Docker)
lsof -i :6379   # Redis
lsof -i :1883   # MQTT (si activé)

Le port 5173 est utilisé uniquement en mode de développement source (serveur de développement Vite).

Opérations en mode conteneur

# Afficher les journaux d’un service
docker compose logs -f kilocenter
docker compose logs -f kc-gateway
docker compose logs -f kc-web

# Redémarrer un seul service
docker compose restart kilocenter

# Vérifier l’état de tous les services
docker compose ps

Fichiers journaux (mode de développement source)

Tous les journaux des services sont écrits dans kilocenter-modules/logs/runtime/:

# Journaux de KC-Core (activité BSSCI, traitement des messages)
tail -f logs/runtime/kc-core.log

# Journaux de KC-Gateway (activité du proxy API)
tail -f logs/runtime/kc-gateway.log

# Journaux de KC-Web (serveur de développement du frontend)
tail -f logs/runtime/kc-web.log

# Rechercher des erreurs dans tous les journaux
grep -E "ERROR|FATAL" logs/runtime/*.log

Vérification de la connexion à la base de données

Vérifiez que PostgreSQL est accessible :

PGPASSWORD=changeme psql -U kilocenter -h localhost -p 5433 -d kilocenter -c "SELECT 1;"

Utilisez le port 5432 à la place de 5433 si PostgreSQL s'exécute directement sur l'hôte (et non via Docker).

Arrêt des services

Mode conteneur :

docker compose down

Mode de développement source :

./stop-all-services.sh

# Arrêter également les conteneurs d’infrastructure
docker compose stop postgres redis mosquitto

Problèmes courants

Symptôme	Cause	Correctif
dial tcp ...5432: connection refused	Incompatibilité du port PostgreSQL	Utilisez 5433 pour Docker, 5432 pour une installation sur l'hôte
KC-Web affiche des erreurs gRPC	KC-Gateway n'est pas en cours d'exécution ou le port est incorrect	Vérifiez KC-Gateway sur le port 9090 ; vérifiez la configuration nginx en mode conteneur
permission denied /var/run/docker.sock	Appartenance au groupe Docker	Exécutez sudo usermod -aG docker $USER et reconnectez-vous
échec du chargement du certificat TLS	Fichiers de certificat manquants ou invalides	Exécutez certgen -- voir Installation
La station de base ne se connecte pas	Le port 5000 de BSSCI n'est pas à l'écoute	Vérifiez que KC-Core a démarré et que les certificats TLS sont configurés
SCACI n'accepte pas de connexions	Manquant scaci_tls bloc de configuration	Vérifiez config/config.docker.yaml contient scaci_host et scaci_tls section
KC-Web renvoie 502 pour les appels gRPC	nginx ne peut pas atteindre kc-gateway:9090	Vérifiez kc-gateway est sain : docker compose ps
start-dev.sh échoue	Les dépendances ne sont pas en cours d'exécution	Démarrez docker compose up -d postgres redis mosquitto d'abord
Bun introuvable	Le runtime Bun n'est pas installé	Installez Bun : curl -fsSL https://bun.sh/install | bash
KC-Web se charge mais n'affiche aucune donnée	KC-Core n'est pas en cours d'exécution ou aucune station de base n'est connectée	Vérifiez les points de terminaison de santé et l'état de la station de base

Séquence de récupération

Mode conteneur :

1. Arrêtez tous les services : docker compose down

2. Démarrez tous les services : docker compose up -d

3. Exécutez les vérifications de santé (voir ci-dessus)

Mode de développement source :

1. Arrêtez tous les services : ./stop-all-services.sh

2. Redémarrez l'infrastructure : docker compose restart postgres redis mosquitto

3. Démarrez les services : ./start-dev.sh

4. Exécutez les vérifications de santé (voir ci-dessus)