Neko Master est l’un de ces projets conçus pour répondre à une nécessité très précise : comprendre ce qui se passe sur un réseau local sans mettre en place une infrastructure de surveillance lourde ni dépendre de services externes. Son objectif est un tableau de bord moderne permettant de visualiser et analyser le trafic réseau en temps réel, pensé pour des environnements de passerelle locale avec un support pour plusieurs backends.

Ce projet, publié sur GitHub par foru17 sous licence MIT, se définit comme un outil d’analyse et de visualisation du trafic. Ses créateurs précisent toutefois qu’il ne donne pas accès au réseau ni aux abonnements proxy, ni connecte plusieurs réseaux entre eux. Il collecte uniquement des données de l’environnement réseau de l’utilisateur et les présente de manière structurée pour faciliter l’observation, l’audit et l’analyse.

L’idée est particulièrement adaptée à des environnements utilisant OpenClash, Clash/Mihomo ou Surge, où une passerelle gère déjà le trafic et les règles, mais où il manque souvent une interface conviviale pour repérer les tendances, domaines, IP, nœuds, connexions ou comportements en temps réel.

Ce que propose Neko Master

La promesse principale de Neko Master est la visibilité. Le tableau de bord permet de suivre le trafic avec mises à jour en temps réel via WebSocket, d’analyser des tendances sur des fenêtres de 30 minutes, 1 heure ou 24 heures, de consulter la consommation par domaine, de vérifier les IP associées, d’accéder aux informations ASN et de géolocalisation, ainsi que d’analyser la distribution du trafic par nœud proxy.

Il inclut aussi un support PWA, un mode clair et sombre, une commutation entre anglais et chinois, ainsi qu’une capacité à monitorer simultanément plusieurs instances de backend. Cette dernière fonctionnalité s’avère surtout utile pour des utilisateurs avancés ou de petites réseaux distribués, qui ne souhaitent pas se limiter à une seule passerelle.

Ce design ne vise pas à remplacer les outils professionnels d’observabilité, comme SIEM ou NetFlow. Sa valeur réside dans la fourniture d’une couche visuelle claire pour des utilisateurs qui gèrent leur propre réseau, des laboratoires domestiques, des gateways personnels, des routeurs sous OpenWrt ou de petits environnements nécessitant un aperçu rapide de ce qui se passe.

Déploiement avec Docker et mode agent

Neko Master propose plusieurs méthodes d’installation. La recommandation principale est d’utiliser Docker Compose, avec une configuration minimale qui expose le port 3000 pour l’interface web. Pour une expérience en temps réel avec WebSocket, il est également possible d’exposer le port 3002 et de le router via un proxy inverse ou un tunnel. En cas d’indisponibilité de WebSocket, l’application bascule automatiquement au polling HTTP toutes les quelques secondes.

Le projet permet aussi un lancement via docker run, une installation avec un script en une seule commande ou son exécution à partir du code source avec pnpm. En environnement de production, la documentation recommande de fixer une variable COOKIE_SECRET avec une chaîne aléatoire d’au moins 32 octets, de persister le volume de données, et de ne pas exposer inutilement certains ports internes.

L’un des aspects les plus intéressants est le mode agent. Il permet d’avoir un panneau central Neko Master et plusieurs appareils distants collectant des données proches de chaque gateway. L’agent s’installe sur OpenWrt, Linux ou macOS, recueille les informations locales et les envoie au panneau. L’avantage est de ne pas nécessiter une connexion directe entre le panneau et chaque gateway, simplifiant ainsi les scénarios multi-sites ou réseaux plus fermés.

Sur des gateways Clash/Mihomo, le système peut utiliser WebSocket pour un flux en temps réel. Avec Surge v5 ou supérieur, la collecte se fera via HTTP polling, avec un retard d’environ deux secondes selon la documentation.

SQLite par défaut et ClickHouse pour de gros volumes

Neko Master utilise SQLite comme moteur de stockage principal, ce qui est logique pour la majorité des utilisateurs : simplicité, pas besoin de gérer une base de données externe, avec stockage des configurations, métadonnées et statistiques sans complexifier le déploiement.

Pour de très gros volumes, une intégration optionnelle avec ClickHouse est prévue. La documentation le recommande lorsque l’on doit gérer des centaines de milliers de domaines ou IP, effectuer des agrégations rapides sur de longues périodes, ou séparer le stockage de l’historique de trafic de celui des configurations.

Le mode ClickHouse fonctionne en écriture hybride : SQLite continue de stocker la configuration et les métadonnées, tandis que ClickHouse enregistre les statistiques de trafic. La source de lecture peut être configurée sur SQLite, ClickHouse ou en automatique. Une migration progressive est aussi proposée : d’abord écrire dans les deux systèmes tout en lisant uniquement sur SQLite, puis activer la lecture automatique ou depuis ClickHouse, et enfin, en option, basculer en mode exclusivement ClickHouse avec fallback automatique en cas de défaillance.

Cette approche est logique car elle ne contraint pas tous les utilisateurs à déployer ClickHouse dès le départ. Ceux qui veulent un panneau local restent sur SQLite, tandis que ceux qui ont besoin d’analyse historique plus poussée disposent d’un chemin d’expansion.

Reverse proxy, sécurité et limites du projet

La documentation recommande d’héberger la partie web et WebSocket sous le même domaine avec des routes précises : / vers le port 3000 et /_cm_ws vers le 3002. Elle fournit des exemples pour Nginx et Cloudflare Tunnel, et met en garde contre des erreurs courantes, comme une mauvaise configuration de la route WebSocket ou une utilisation de routes qui interfèrent avec les fichiers statiques de Next.js.

Concernant la sécurité, Neko Master supporte une authentification pour protéger l’accès au panneau. La documentation recommande de fixer COOKIE_SECRET, de ne pas activer FORCE_ACCESS_CONTROL_OFF sauf en mode récupération, et d’utiliser SHOWCASE_SITE_MODE uniquement dans des démos publiques où les opérations sensibles sont limitées.

Il est crucial de comprendre ce que Neko Master n’est pas : il ne s’agit pas d’un service proxy, il ne vend pas d’accès aux nœuds, ne crée pas de connectivité entre réseaux et ne remplace pas les contrôles de sécurité d’une organisation. C’est un outil de visualisation et d’analyse basé sur des données recueillies dans l’environnement de l’utilisateur. Cette délimitation permet d’éviter les malentendus, surtout que plusieurs composants du projet peuvent s’intégrer avec des gateways couramment utilisés dans des configurations proxy.

Un outil intéressant pour réseaux domestiques avancés et petits laboratoires

L’architecture se compose d’une application web Next.js, d’un service collector en Node.js utilisant Fastify et WebSocket, d’un agent en Go, d’un stockage SQLite avec option ClickHouse, et d’un paquet partagé de types et utilitaires. Le frontend utilise Next.js 16, React 19, TypeScript, Tailwind CSS, shadcn/ui, Recharts et next-intl.

Ce mélange le positionne dans une catégorie bien précise : ce n’est ni un utilitaire en ligne de commande ni un tableau de bord d’entreprise lourd, mais une application web moderne pour utilisateurs techniques. Elle est adaptée pour les administrateurs de petits réseaux, passionnés d’OpenWrt, utilisateurs de Clash/Mihomo ou Surge, labos domestiques, ou toute équipe recherchant une interface graphique simple et efficace pour surveiller leur gateway.

La présence optionnelle de ClickHouse et d’un agent distant montre que le projet souhaite aller au-delà d’un simple tableau de bord. La documentation couvre d’ailleurs l’installation, les ports, les variables, le proxy inverse, l’authentification, la récupération de tokens, les sauvegardes, l’architecture et le dépannage.

Comme toute outil réseau, son adoption doit se faire avec prudence. Il est conseillé de vérifier quels données sont collectées, comment elles sont protégées, qui accède au panneau, quels ports sont exposés, et si la passerelle permet des connexions depuis le conteneur ou l’agent. La visibilité est précieuse, mais un panneau mal sécurisé peut révéler des informations sensibles sur la navigation, les domaines consultés, les nœuds employés et les tracés du trafic.

Neko Master répond à un besoin réel : rendre le trafic réseau compréhensible sans nécessiter une infrastructure complexe. Pour des réseaux domestiques avancés ou de petits environnements techniques, il peut devenir un outil très pratique. Son principal attrait réside dans sa simplicité de déploiement, son interface moderne, son fonctionnement en temps réel, son support multi-gateway et sa capacité à évoluer vers ClickHouse si la volumétrie de données augmente.

Questions fréquentes

Qu’est-ce que Neko Master ?
Neko Master est un tableau de bord open source permettant de visualiser et analyser le trafic réseau en temps réel dans des environnements de passerelle locale.

Servir comme proxy ou service Internet ?
Non. Le projet précise qu’il ne fournit pas de services proxy, d’abonnement ou de connectivité entre réseaux. Il se limite à analyser les données de l’environnement de l’utilisateur.

Quels gateways sont supportés ?
La documentation mentionne la compatibilité avec Clash/Mihomo via WebSocket en temps réel, et Surge v5+ via HTTP polling.

Peut-on l’utiliser avec plusieurs gateways ?
Oui. Neko Master supporte plusieurs backends et propose aussi un mode agent pour collecter des données à distance.

Faut-il obligatoirement utiliser ClickHouse ?
Non. SQLite est la solution de stockage par défaut. ClickHouse est une option pour gérer de très gros volumes de données ou réaliser des analyses historiques approfondies.