23 KiB
Intégration UniFi OS pour Homarr — conception
Date : 2026-09-08
Base : homarr-labs/homarr 2b1a03849 (v1.77.0)
Branche : feat/unifi-os-integration
Statut : conception validée, prête pour le plan d'implémentation
⚠️ Aucune clé d'API ne figure dans ce document. Les clés utilisées pendant la conception ont été fournies hors dépôt et doivent être révoquées en fin de projet.
1. Objectif
Ajouter à Homarr une intégration UniFi OS, en complément — et non en
remplacement — de l'intégration unifiController existante.
L'intégration existante s'authentifie par identifiant/mot de passe et lit
/api/s/{site}/stat/sites, l'API interne de l'ancien Network Controller.
UniFi OS expose depuis la version 9 une API d'intégration officielle,
authentifiée par clé d'API, stable et documentée. C'est celle que cible ce
projet.
L'intégration existante n'est pas touchée. Les deux coexistent.
2. Décisions cadrées
| # | Décision | Justification |
|---|---|---|
| D1 | Fork personnel, pas de PR upstream | Choix de l'auteur. L'issue upstream #4703 demandait cette fonctionnalité et a été fermée par triage automatique, pas par refus technique : la porte reste ouverte pour plus tard. |
| D2 | Hybride local + cloud optionnel | L'API locale ne fournit ni latence ni perte de paquets. L'API cloud Site Manager les fournit. Le cloud reste facultatif pour que l'intégration fonctionne sans compte UI ni accès Internet. |
| D3 | Widget dédié, pas de réutilisation des widgets networkController* |
Le contrat NetworkControllerSummary est taillé pour l'ancienne API. S'y conformer obligerait à inventer des valeurs. Un contrat propre évite ça. |
| D4 | Déploiement par rsync du build standalone | Le LXC exécute déjà un build standalone piloté par systemd. C'est le changement le plus petit possible, donc le plus facile à annuler. |
| D5 | Structure client / mapping / orchestration séparés | Modèle TrueNAS et Synology déjà présents dans le dépôt. Isole le cloud, optionnel et lent, de la partie locale, obligatoire et rapide. |
Conséquence de D3 : on ne modifie pas NetworkControllerSummary. Les champs
latency / ping restent number obligatoires pour unifiController et
opnsense. Aucune régression possible sur les intégrations existantes.
3. Constatations vérifiées sur l'API
Toutes les valeurs ci-dessous ont été relevées sur une console réelle (UniFi Network 10.6.102) le 2026-09-08, et non déduites de la documentation.
3.1 API locale — {url}/proxy/network/integration/v1
Authentification : en-tête X-API-KEY, clé générée dans l'application Network
(Paramètres → Control Plane → Integrations). Une clé du Site Manager cloud est
refusée avec un 401 sur cette API — les deux systèmes de clés sont distincts.
| Endpoint | Renvoie | Relevé |
|---|---|---|
GET /info |
applicationVersion |
10.6.102 |
GET /sites |
id, internalReference, name — aucune statistique |
1 site |
GET /sites/{id}/clients |
type, access.type, name, ipAddress, macAddress, uplinkDeviceId, connectedAt |
51 clients |
| — | limit est plafonné à 200. Une demande à 1000 renvoie limit: 200. |
mesuré |
GET /sites/{id}/devices |
state, model, macAddress, firmwareVersion, firmwareUpdatable, features |
6 équipements |
GET /sites/{id}/devices/{id}/statistics/latest |
uptimeSec, cpuUtilizationPct, memoryUtilizationPct, uplink.{tx,rx}RateBps |
— |
GET /sites/{id}/vpn/servers |
type, enabled |
1 serveur WireGuard actif — non consommé en v1, voir §12 |
GET /sites/{id}/wans |
id, name uniquement — inexploitable pour l'état |
2 WAN |
Types de clients (discriminant type) : WIRED, WIRELESS, VPN,
TELEPORT. Sous-objet access.type : DEFAULT, GUEST.
Filtrage. Supporté, avec une syntaxe préfixe :
✅ and(type.eq('WIRED'),access.type.eq('DEFAULT'))
❌ type.eq('WIRED') and access.type.eq('DEFAULT') → 400 invalid-filter
❌ type.eq('WIRED') & access.type.eq('DEFAULT') → 400 invalid-filter
❌ type.eq('WIRED'),access.type.eq('DEFAULT') → 400 invalid-filter
Combiné à limit=1, il permet d'obtenir un totalCount sans rapatrier les
enregistrements. Utilisé uniquement au-delà de 200 clients (voir §7).
Écart avec la documentation. Ubiquiti ne publie l'OpenAPI que pour
v10.4.57. La console en 10.6.102 renvoie des champs absents de ce spec
(macAddress, uplinkDeviceId sur les clients). Corollaire : on code contre
les réponses réelles, validées par des schémas zod tolérants (passthrough),
et on ne génère pas de client depuis le spec publié.
3.2 API cloud Site Manager — https://api.ui.com
Authentification : en-tête X-API-KEY, clé générée sur unifi.ui.com.
| Endpoint | Utilité |
|---|---|
GET /v1/sites |
Corrélation (meta.gatewayMac), ispInfo, IP publique par WAN, percentages.wanUptime |
POST /v1/isp-metrics/5m/query |
avgLatency, maxLatency, packetLoss, uptime, débits |
Deux contraintes mesurées :
GET /v1/isp-metrics/5msans filtre renvoie 133 Ko (288 points sur 24 h). Il faut passer parPOST .../queryborné dans le temps.- Une fenêtre de 15 min renvoie un tableau vide. Une fenêtre de 3 h fonctionne. Le point le plus récent accuse un retard mesuré de ~27 minutes.
Ces deux faits pilotent le design du cache (§7) et l'affichage de la fraîcheur (§8).
3.3 Corrélation locale ↔ cloud
Une clé Site Manager donne accès à tous les sites du compte UI, y compris des consoles dont l'utilisateur n'est pas propriétaire. Le compte de référence en exposait deux. Prendre les métriques cloud sans discriminer afficherait la latence d'un autre réseau.
Clé de jointure retenue : le MAC du gateway.
LOCAL devices[] → gateway.macAddress aa:bb:cc:11:22:33
CLOUD sites[] → meta.gatewayMac aa:bb:cc:11:22:33 ✅ correspondance
CLOUD sites[] → meta.gatewayMac dd:ee:ff:44:55:66 ✗ autre console du compte
(adresses anonymisées ; la correspondance a été vérifiée sur la console réelle)
Retenu plutôt que le nom du site : un nom se renomme, un MAC non. En l'absence
de correspondance, unifi-sm-api.ts renvoie null et n'essaie aucune
approximation. Un manque visible vaut mieux qu'une donnée silencieusement fausse.
4. Contrat de données
export interface UnifiOsSummary {
site: {
id: string;
name: string;
applicationVersion: string;
};
wan: {
/** Dérivé de l'état du gateway côté local. */
state: "online" | "offline" | "unknown";
/** Débit temps réel de l'uplink du gateway, en bits/s. Local. */
throughput: { txBps: number; rxBps: number } | null;
/** Bloc cloud. `null` si la clé Site Manager n'est pas configurée
* ou si aucun site cloud ne correspond au MAC du gateway. */
isp: {
name: string;
externalIp: string | null;
/** Nullables : le cloud omet ces mesures pour les périodes où le WAN
* était coupé. Un `0` fabriqué s'afficherait comme « 0 ms » à côté d'un
* voyant vert, au moment précis où la connexion est tombée. */
latencyMs: number | null;
maxLatencyMs: number | null;
packetLossPct: number | null;
uptimePct: number | null;
/** Horodatage de la mesure. Rendu obligatoire : toute donnée cloud
* voyage avec sa fraîcheur. */
measuredAt: Date;
} | null;
};
/** `null` si l'appel a échoué. Surtout pas un compteur à zéro : le lecteur
* ne pourrait pas distinguer « échec » de « aucun client connecté ». */
clients: {
total: number;
wired: number;
wireless: number;
vpn: number; // VPN + TELEPORT
guests: number; // access.type === "GUEST", tous types confondus
} | null;
/** `null` si l'appel a échoué, pour la même raison. */
devices: {
total: number;
online: number;
offline: number;
firmwareUpdatable: number;
} | null;
gateway: {
name: string;
model: string;
macAddress: string;
uptimeSec: number | null;
cpuPct: number | null;
memoryPct: number | null;
} | null;
}
measuredAt est obligatoire dans le bloc isp. Le type impose que la
fraîcheur accompagne la donnée cloud : il devient impossible d'afficher une
latence sans savoir de quand elle date.
5. Architecture
5.1 Nouveaux fichiers
packages/integrations/src/unifi-os/
├── unifi-os-integration.ts # extends Integration — orchestre, mappe, dégrade
├── unifi-os-api.ts # client HTTP local
├── unifi-sm-api.ts # client HTTP cloud, optionnel, cache interne
├── unifi-os-types.ts # schémas zod + mappers purs
└── test/
├── unifi-os-types.spec.ts
└── unifi-os-integration.spec.ts
Chaque unité répond à une question unique :
unifi-os-api.ts— comment parler à la console locale ? Endpoints, pagination, résolution dusiteId. Ne connaît pas Homarr.unifi-sm-api.ts— comment parler au cloud ? Fenêtre glissante de 3 h, corrélation par MAC, cache interne. Instancié uniquement si la clé cloud est présente.unifi-os-types.ts— comment valider et transformer ? Schémas zod et fonctions pures. Aucun accès réseau, donc testable sans mock.unifi-os-integration.ts— comment Homarr consomme tout ça ? La seule unité qui connaît la classeIntegration.
5.2 Points d'attache dans le monorepo
| Fichier | Modification |
|---|---|
packages/definitions/src/integration.ts |
Ajouter le secret siteManagerApiKey à integrationSecretKindObject ; ajouter "unifiOs" à integrationCategories ; ajouter le kind unifiOs avec secretKinds: [["apiKey"], ["apiKey", "siteManagerApiKey"]], category: ["unifiOs"], defaultPort: 443 |
packages/definitions/src/widget.ts |
Ajouter le WidgetKind unifiOs |
packages/integrations/src/base/creator.ts |
Enregistrer unifiOs: UnifiOsIntegration |
packages/integrations/src/types.ts |
Exporter ./unifi-os/unifi-os-types |
packages/integrations/src/interfaces/unifi-os-summary/ |
Interface UnifiOsSummaryIntegration |
packages/request-handler/src/unifi-os.ts |
createIntegrationRequestHandler |
packages/api/src/router/widgets/unifi-os.ts + index.ts |
Routeur tRPC |
packages/widgets/src/unifi-os/{index.ts,component.tsx} |
Définition + composant |
packages/widgets/src/{manifest.ts,index.tsx,refetch-intervals.ts} |
Enregistrement |
packages/translation/src/lang/en.json |
Libellés du widget + clé integration.category.unifiOs |
5.3 Pourquoi une catégorie dédiée, et pas networkController
integrationCategories n'est pas une étiquette de présentation, c'est un
mécanisme de câblage. getIntegrationKindsByCategory("networkController")
alimente trois endroits :
widget-integration-map.ts → intégrations proposées par les widgets networkController*
router/widgets/network-controller.ts → middleware tRPC
request-handler/network-controller.ts → typé IntegrationKindByCategory<"networkController">,
appelle getNetworkSummaryAsync()
Déclarer unifiOs dans cette catégorie la rendrait sélectionnable dans les
widgets de l'ancienne intégration et exigerait qu'elle implémente
getNetworkSummaryAsync() — l'interface que la décision D3 écarte
explicitement. Le typage IntegrationKindByCategory transforme cette
contradiction en erreur de compilation, pas en défaut silencieux.
On ajoute donc une catégorie unifiOs. Le dépôt a déjà un précédent de
catégorie mono-intégration : beszel. Une catégorie sans traduction ne casse
rien — beszel n'en a pas — mais on ajoute quand même
integration.category.unifiOs.
Base d'URL. L'utilisateur saisit l'origine de la console
(https://console.exemple.tld). Le client local préfixe systématiquement
/proxy/network/integration/v1. Ce préfixe appartient au client, pas à la
configuration : l'utilisateur n'a pas à le connaître.
Précédent de conception validé : le champ secretKinds accepte plusieurs
jeux alternatifs, et la classe de base expose hasSecretValue(). L'intégration
ntfy utilise déjà exactement ce motif ([["topic"], ["topic", "apiKey"]]).
La clé cloud optionnelle ne demande donc aucun mécanisme nouveau.
Note TLS. La classe de base Integration applique les certificats de
confiance de Homarr à l'URL de l'intégration uniquement. L'appel vers
api.ui.com sort de ce périmètre : c'est du HTTPS public à certificat valide,
un fetch standard suffit. Il ne doit pas passer par
fetchWithTrustedCertificatesAsync, pour ne pas laisser croire que les deux
appels partagent la même configuration.
6. Séquence d'un rafraîchissement
1. GET /info → applicationVersion
2. GET /sites → siteId, name
3. Promise.allSettled([
GET /sites/{id}/clients?limit=200 → comptage par type (voir §7)
GET /sites/{id}/devices → états, firmwares, gateway
])
4. GET /sites/{id}/devices/{gatewayId}/statistics/latest (si gateway trouvé)
5. si clé cloud présente :
unifi-sm-api.getIspMetricsAsync(gatewayMac) → cache 5 min
Promise.allSettled, pas Promise.all. Un endpoint en échec dégrade son
bloc à null ; il ne fait pas tomber le widget entier. L'étape 4 dépend de
l'étape 3 : sans gateway identifié, gateway et wan.throughput valent null
et le reste s'affiche normalement.
7. Cache et gestion d'erreurs
Deux caches de rythmes différents, parce que les deux sources n'évoluent pas à la même vitesse :
| Couche | TTL | Motif |
|---|---|---|
createIntegrationRequestHandler |
60 s | Les compteurs locaux sont vivants |
Cache interne de unifi-sm-api.ts, clé = MAC gateway |
5 min | La donnée cloud ne change que toutes les 5 min et arrive avec ~27 min de retard |
Sans le second cache, on émettrait ~120 appels/h vers api.ui.com pour ~12
valeurs distinctes, avec un risque de limitation de débit. Le motif du cache
statique par instance est déjà utilisé par TrueNasClient.
fallbackToStaleOnError: true sur le handler. Une console injoignable
pendant quelques secondes affiche la dernière valeur connue au lieu d'une tuile
d'erreur — à condition que l'interface signale que la donnée est périmée (§8).
Comptage des clients — règle explicite. L'API plafonne limit à 200
(mesuré). Le comportement est donc conditionné par totalCount, renvoyé dès la
première page :
| Condition | Stratégie | Coût |
|---|---|---|
totalCount ≤ 200 |
La première page contient tout. Comptage en mémoire par type et access.type. |
1 requête |
totalCount > 200 |
Bascule sur des requêtes filtrées limit=1, dont on ne lit que totalCount. |
5 requêtes de taille fixe |
La seconde branche utilise la syntaxe préfixe du §3.1, par exemple
and(type.eq('WIRELESS'),access.type.eq('GUEST')).
On ne pagine pas en boucle : au-delà de 200 clients, rapatrier tous les enregistrements pour n'en garder que des compteurs coûte plus cher que cinq requêtes bornées, et la charge croîtrait avec la taille du réseau.
Écrire les deux branches maintenant est justifié : ce n'est pas de l'optimisation spéculative mais la gestion d'une limite d'API mesurée, qui produirait sinon des compteurs silencieusement faux au-delà de 200 clients.
8. Widget
Disposition retenue : bandeau WAN dominant + lignes (option B des maquettes).
┌────────────────────────────────────────────────┐
│ ● Nom du site │
│ ┌────────────────────────────────────────────┐ │
│ │ ● Internet ↑14,1 ↓3,3 Mb/s │ │
│ │ Nom FAI · 203.0.113.10 │ │
│ │ 11 ms · 0 % perte [27min]│ │
│ └────────────────────────────────────────────┘ │
│ Clients 51 · 44 filaire · 7 Wi-Fi │
│ Équipements 6 / 6 en ligne │
│ ● Firmware 3 à mettre à jour │
│ Network 10.6.102 Gateway up 11 j 16 h │
└────────────────────────────────────────────────┘
Justification : la hiérarchie visuelle suit l'ordre de consultation réel — on regarde d'abord si Internet fonctionne, ensuite le détail.
Le badge de fraîcheur n'est pas cosmétique. Il porte deux rôles distincts : signaler le retard structurel des métriques cloud, et signaler une donnée servie depuis le cache périmé après une erreur. Sans lui, le widget juxtaposerait des données de fraîcheurs très différentes sans le dire.
Comportement dégradé :
| Situation | Rendu |
|---|---|
| Clé cloud absente | Bloc ISP masqué. Le bandeau garde l'état WAN et le débit. |
| Cloud injoignable | Idem, plus un indicateur discret. |
| Aucune correspondance de MAC | Bloc ISP masqué. Jamais la latence d'un autre site. |
| Gateway introuvable | throughput, uptime, CPU/RAM masqués ; clients et équipements affichés. |
| Console injoignable | Dernière valeur connue + badge périmé, puis tuile d'erreur au-delà du TTL. |
Taille. WidgetDefinition n'expose aucune contrainte de taille minimale :
l'adaptation est une affaire de CSS dans le composant. Le bandeau passe en deux
lignes en tuile étroite, et les lignes de détail se réduisent à leurs chiffres.
Rafraîchissement. Entrée dans widgetQueryRefetchIntervals avec
intervalSeconds: 60. Les widgets networkController sont à null — pas de
rafraîchissement automatique — mais les compteurs de clients ont une valeur
d'usage qui justifie l'écart.
9. Tests
| Niveau | Fichier | Couvre | Réseau |
|---|---|---|---|
| Unitaire | unifi-os-types.spec.ts |
Comptage par type et par access.type, agrégation d'états, conversion bps, corrélation par MAC y compris le cas sans correspondance, tolérance aux champs inconnus |
Non |
| Intégration | unifi-os-integration.spec.ts |
Séquence complète sur fixtures capturées, dégradation par bloc, absence de clé cloud, endpoint en échec | Mocké |
| Manuel | script hors CI | Vérification contre une console réelle | Oui |
Le niveau unitaire est le plus important : c'est là que vivent les erreurs de comptage, et c'est le seul qui reste valable si Ubiquiti fait évoluer ses endpoints.
Fixtures. Capturées depuis la console réelle, puis anonymisées — adresses MAC, IP publique, noms de clients et identifiants de site remplacés. Un dépôt ne doit pas porter la cartographie d'un réseau privé.
Multi-site. Une URL locale désigne une console, et l'intégration se limite au premier site qu'elle expose. Une console peut techniquement en héberger plusieurs : le widget affiche donc le nom du site retenu, pour que ce choix soit visible plutôt que subi. Deux tests couvrent les bornes — une console sans aucun site renvoie une erreur explicite au test de connexion, et le nom du site figure dans le contrat.
L'ancienne intégration agrégeait tous les sites, ce qui avait produit l'issue #3222 (valeurs nulles en multi-site). Ne pas agréger supprime la classe de défaut plutôt que de la tester.
10. Phasage
Chaque phase se vérifie seule. C'est ce qui permet de savoir de quel côté chercher quand quelque chose casse.
| Phase | Contenu | Critère de validation |
|---|---|---|
| 0 | Fork, corepack enable, pnpm docker:dev:up, pnpm dev |
Homarr démarre en local |
| 1 | unifi-os-api.ts, unifi-sm-api.ts, types et mappers, tests unitaires |
pnpm test vert, sans réseau |
| 2 | UnifiOsIntegration + enregistrement |
Le test de connexion Homarr passe dans l'interface |
| 3 | request-handler + routeur tRPC | La query renvoie les vraies valeurs |
| 4 | Widget + traductions en |
Le widget s'affiche sur un board local |
| 5 | Build standalone + rsync vers le LXC | Le widget s'affiche en production |
À l'issue de la phase 2, toute la plomberie est prouvée. Une panne en phase 4 est donc nécessairement côté interface.
11. Déploiement
Cible : LXC Ubuntu 24.04, 10.70.1.13, 2 vCPU / 2 Go. Homarr y tourne en build
standalone sous systemd (/opt/homarr, homarr.service,
EnvironmentFile=/etc/homarr/homarr.env), avec nginx et Redis embarqués par
run.sh.
Le build se fait sur le poste de développement (16 cœurs, 60 Go). Le LXC ne peut pas compiler ce monorepo Next.js.
Procédure :
tarde/opt/homarret dump de la base.systemctl stop homarr.rsyncdu build standalone.systemctl start homarr, puis vérification des logs.
Rollback : restauration de l'archive et redémarrage.
Contrôle préalable obligatoire : comparer les migrations de
packages/db/migrations/ avec /opt/homarr/db/migrations/. Elles sont
alignées à 0041_add_right_click_preference.sql au 2026-09-08. Une divergence
rendrait le rollback nettement plus complexe qu'une restauration d'archive.
SECRET_ENCRYPTION_KEY dans /etc/homarr/homarr.env chiffre les secrets
d'intégration en base. Le rsync ne touche pas ce fichier, mais toute
modification rendrait les intégrations existantes illisibles.
12. Hors périmètre
Volontairement exclus de cette spec :
- Widget cloud multi-site (SD-WAN, fabric, vue consolidée de plusieurs
consoles). Idée retenue pour un projet ultérieur, qui réutilisera
unifi-sm-api.ts. Sa mention ici sert à ne pas le construire maintenant. - État des serveurs VPN. L'endpoint existe et fonctionne, mais le contrat §4 n'expose pas de champ pour lui et la disposition retenue au §8 ne l'affiche pas. Le collecter sans l'afficher serait du code mort.
- Actions d'écriture (adoption d'équipement, redémarrage de port, gestion de vouchers). L'API les expose ; l'intégration reste en lecture seule.
- Traduction au-delà de l'anglais. Conséquence de D1.
- Documentation Docusaurus. Conséquence de D1.
- Pull request upstream. Conséquence de D1 ; la structure du code ne l'interdit pas plus tard.
- Modification de l'intégration
unifiController. Elle reste en l'état.
13. Risques
| Risque | Portée | Traitement |
|---|---|---|
L'OpenAPI publié (10.4.57) est en retard sur les consoles |
Élevée — déjà constaté | Schémas zod tolérants, code écrit contre les réponses réelles |
| La clé Site Manager donne accès à tout le compte UI | Sécurité | Cloud optionnel ; corrélation stricte par MAC ; clé de conception à révoquer |
| Retard de ~27 min sur les métriques cloud | Interface | measuredAt obligatoire dans le contrat, badge de fraîcheur dans le widget |
| Un fork diverge à chaque version de Homarr | Maintenance | Modifications concentrées dans un dossier neuf ; seuls les points d'attache du §5.2 touchent l'existant |
Limitation de débit sur api.ui.com |
Fiabilité | Cache interne 5 min |
| Le déploiement casse l'instance de production | Exploitation | Sauvegarde avant rsync, contrôle des migrations, rollback par restauration |