> Recommandé dans `.env` (même répertoire que `docker-compose.yml`) :
> `COOKIE_SECRET=<chaîne aléatoire d'au moins 32 octets>` (générer avec `openssl rand -hex 32`)

> Ce mode est entièrement compatible avec les mises à niveau et fonctionne immédiatement.
> Si WS n'est pas routé, l'application bascule automatiquement vers le polling HTTP.

#### Scénario B : WebSocket en temps réel (recommandé avec reverse proxy)```yaml
services:
  neko-master:
    image: foru17/neko-master:latest
    container_name: neko-master
    restart: unless-stopped
    ports:
      - "3000:3000" # Web UI
      - "3002:3002" # WebSocket (for Nginx / Tunnel forwarding)
    volumes:
      - ./data:/app/data
      # Local MMDB (optional, files should be downloaded into ./geoip)
      - ./geoip:/app/data/geoip:ro
    environment:
      - NODE_ENV=production
      - DB_PATH=/app/data/stats.db
      - COOKIE_SECRET=${COOKIE_SECRET}

Ouvrez <http://localhost:3000> pour commencer.

Si vous utilisez le fichier Compose intégré au dépôt (par défaut `3000/3001/3002`), exécutez la même commande.

### Option 2 : Docker Run```bash
# Generate a fixed cookie secret first (for session persistence)
export COOKIE_SECRET="$(openssl rand -hex 32)"

Ouvrez <http://localhost:3000> pour commencer.

> Le frontend utilise `/api` en same-origin par défaut, donc le port 3001 n'est généralement pas requis en externe.
> Pour le WS en temps réel, votre reverse proxy/tunnel doit pouvoir atteindre le port `3002`. Sinon, l'application bascule sur un polling HTTP d'environ 5s.

> Pour `docker run`, modifiez les ports externes en utilisant directement les mappings `-p`.
> Uniquement si vous utilisez un accès WS direct (sans reverse proxy) et que le port WS externe n'est pas `3002`, passez également `-e WS_EXTERNAL_PORT=<external-ws-port>`.
>
> Mode de recherche MMDB local (optionnel) : montez `-v $(pwd)/geoip:/app/data/geoip:ro`,
> puis basculez la source sur Local dans `Settings -> Preferences -> IP Lookup Source`.

### Option 3 : Script en un clic

Détecte automatiquement les conflits de ports et configure tout :```bash
# Using curl
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

# Or using wget
wget -qO- https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

Ouvrir <http://localhost:3000> pour configurer.

> En mode source : le collecteur écoute sur `3001/3002`, le web écoute sur `3000` par défaut.
> Si vous avez modifié `API_PORT` (pas 3001), définissez `API_URL` en conséquence (par exemple `API_URL=http://localhost:4001`) afin que la réécriture `/api` du web cible la bonne API.
> `apps/collector/.env.local` a la priorité sur `apps/collector/.env`.

## 🤖 Déploiement de l'agent

Utilisez le mode Agent lorsque vous souhaitez un service Neko Master centralisé et plusieurs appareils distants (OpenWrt, Linux, macOS) collectant les données de la passerelle locale. L'agent s'exécute à proximité de la passerelle, récupère les données et les rapporte au panneau — le panneau ne se connecte jamais directement à la passerelle.

Types de passerelles pris en charge : **Clash / Mihomo** (WebSocket en temps réel) et **Surge v5+** (interrogation HTTP).

### Installation rapide (commande générée par l'interface)

1. Dans le tableau de bord, allez dans `Settings → Backends`, ajoutez un backend `Agent`, sélectionnez le type de passerelle
2. Cliquez sur **"View Agent Script"** et copiez la commande d'installation en une ligne, puis exécutez-la sur l'hôte cible :```bash
# Clash / Mihomo gateway example
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/install.sh \
  | env NEKO_SERVER='http://your-panel:3000' \
        NEKO_BACKEND_ID='1' \
        NEKO_BACKEND_TOKEN='ag_xxx' \
        NEKO_GATEWAY_TYPE='clash' \
        NEKO_GATEWAY_URL='http://127.0.0.1:9090' \
        sh

# Surge gateway example
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/install.sh \
  | env NEKO_SERVER='http://your-panel:3000' \
        NEKO_BACKEND_ID='2' \
        NEKO_BACKEND_TOKEN='ag_yyy' \
        NEKO_GATEWAY_TYPE='surge' \
        NEKO_GATEWAY_URL='http://127.0.0.1:9091' \
        sh

> Le script détecte automatiquement une installation existante — si `neko-agent` est déjà présent, il ajoute uniquement la nouvelle instance sans re-télécharger.
> Plusieurs instances peuvent fonctionner sur le même hôte (avec des `NEKO_INSTANCE_NAME` différents), chacune pointant vers une passerelle différente.

### Documentation de l'agent

- [Vue d'ensemble](https://github.com/foru17/neko-master/blob/main/docs/agent/overview.en.md) : architecture, comparaison Direct vs Agent, modèle de sécurité
- [Démarrage rapide](https://github.com/foru17/neko-master/blob/main/docs/agent/quick-start.en.md) : configuration de bout en bout, de l'interface utilisateur à l'agent en fonctionnement
- [Guide d'installation](https://github.com/foru17/neko-master/blob/main/docs/agent/install.en.md) : méthodes d'installation, démarrage automatique systemd / launchd
- [Configuration](https://github.com/foru17/neko-master/blob/main/docs/agent/config.en.md) : référence complète des options et variables d'environnement
- [Flux de publication](https://github.com/foru17/neko-master/blob/main/docs/agent/release.en.md) : politique de versionnage et de compatibilité
- [Dépannage](https://github.com/foru17/neko-master/blob/main/docs/agent/troubleshooting.en.md) : erreurs courantes et solutions

## 📖 Première utilisation

![Première utilisation](https://assets.kitploit.com/production/public/readmes/55481/574559c63ee5ba0aa6edfe15b7b451eeb203754122a3fa5c422f8342d2437879/55102606ffce9740febe5ee0afcdeb22ab67516f8219f7cf8dd6d0798ede4f45-display-v1.webp)

### Connecter Clash / Mihomo

1. Ouvrez <http://localhost:3000>
2. La boîte de dialogue **Configuration de la passerelle** apparaîtra lors de la première visite
3. Renseignez les informations de connexion de votre passerelle réseau (par exemple, OpenClash) :
   - **Nom** : Nom personnalisé (par exemple, « Passerelle maison »)
   - **Type** : Sélectionnez `Clash / Mihomo`
   - **Hôte** : Adresse du backend de la passerelle (par exemple, `192.168.101.1`)
   - **Port** : Port du backend de la passerelle (par exemple, `9090`)
   - **Token** : À renseigner si un Secret est configuré, sinon laisser vide
4. Cliquez sur « Ajouter un backend » pour enregistrer
5. Le système commencera automatiquement à collecter et analyser les données de trafic

> 💡 **Obtenir l'adresse de la passerelle** : Accédez au panneau de contrôle de votre passerelle (par exemple, OpenClash) → Activez « Contrôle externe » → Copiez l'adresse de l'API

### Connecter Surge

![Configuration de l'API HTTP Surge](https://assets.kitploit.com/production/public/readmes/55481/9cc7414a5acad5b6c3f5fadccd072b50f0b552b305ff5003024a3d1304bb9ec4/bae0f4f4debf30de5fdf5331b6befad02135ba827c5812c1e4fdf33614c3aede-display-v1.webp)

Neko Master prend en charge la connexion aux passerelles Surge pour une visualisation complète de la chaîne de règles et l'analyse du trafic.

#### 1. Activer l'API HTTP de Surge

Activez l'API distante HTTP dans votre configuration Surge :```ini
[General]
http-api = 127.0.0.1:9091
http-api-tls = false
http-api-web-dashboard = true

Puis redémarrez :```bash
docker compose down
docker compose up -d

> Remarque : si vous utilisez un accès WS direct (sans reverse proxy) et que le port WS externe n'est pas `3002`, définissez `WS_EXTERNAL_PORT=<external-ws-port>`.

### Solution 3 : Utiliser un script en un clic```bash
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

Utilisez `openssl rand -hex 32` pour générer `COOKIE_SECRET`.

Recommandations supplémentaires :

1. Montez un stockage persistant (par exemple `./data:/app/data`) pour éviter la perte de données et de secrets.
2. Si vous utilisez un accès WS direct et que le port WS externe n'est pas `3002`, définissez `WS_EXTERNAL_PORT` en conséquence.
3. Si le port/l'adresse de l'API change dans le déploiement source, mettez également à jour `API_URL`.
4. Pour la recherche MMDB locale, montez `./geoip:/app/data/geoip:ro` et changez la source dans `Settings -> Preferences -> IP Lookup Source`.
5. Les fichiers MMDB sont volumineux et ne sont pas inclus dans l'image. Téléchargez-les et placez-les dans `./geoip` avec des noms fixes :
   `GeoLite2-City.mmdb`, `GeoLite2-ASN.mmdb` (requis), et `GeoLite2-Country.mmdb` (optionnel).
   Source recommandée : <https://github.com/P3TERX/GeoLite.mmdb>.

> Les détails avancés de l'Agent (installation, configuration, publication, compatibilité) sont maintenus sous `docs/agent/*`.

## 🗄️ ClickHouse (Optionnel)

SQLite est le moteur de stockage par défaut de Neko Master et convient à la plupart des utilisateurs.
Envisagez d'activer ClickHouse si vous avez besoin de :

- Très grands ensembles de données (des centaines de milliers d'entrées de domaines/IP)
- Requêtes d'agrégation rapides sur de longues périodes (≥ 7 jours)
- Séparation des statistiques historiques du stockage de configuration/métadonnées

> ClickHouse est entièrement optionnel. SQLite reste le magasin de configuration et de métadonnées, que ClickHouse soit activé ou non.

### Aperçu de l'architecture

Lorsque ClickHouse est activé, le système entre en **mode double écriture** :```
BatchBuffer.flush()
    │
    ├──→ SQLite (config / metadata, always written)
    └──→ ClickHouse (stats traffic data, dual-write)
           └── Buffer tables → SummingMergeTree async merge

> Les données ClickHouse sont persistées dans `./data/clickhouse`, séparément du répertoire de données principal de l'application.

Si vous utilisez un **`docker-compose.yml` personnalisé** (comme dans les scénarios A/B ci-dessus), ajoutez manuellement le bloc de service ClickHouse :```yaml
services:
  neko-master:
    # ... your existing config ...
    environment:
      # append to existing environment section:
      - CH_ENABLED=${CH_ENABLED:-0}
      - CH_HOST=${CH_HOST:-clickhouse}
      - CH_PORT=${CH_PORT:-8123}
      - CH_DATABASE=${CH_DATABASE:-neko_master}
      - CH_USER=${CH_USER:-neko}
      - CH_PASSWORD=${CH_PASSWORD:-neko_master}
      - CH_WRITE_ENABLED=${CH_WRITE_ENABLED:-0}
      - STATS_QUERY_SOURCE=${STATS_QUERY_SOURCE:-sqlite}
    networks:
      - neko-master-network

  clickhouse:
    image: clickhouse/clickhouse-server:24.8
    container_name: neko-master-clickhouse
    restart: unless-stopped
    profiles: ["clickhouse"]
    ports:
      - "${CH_EXTERNAL_HTTP_PORT:-8123}:8123"
      - "${CH_EXTERNAL_NATIVE_PORT:-9000}:9000"
    volumes:
      - ./data/clickhouse:/var/lib/clickhouse
    environment:
      - CLICKHOUSE_DB=${CH_DATABASE:-neko_master}
      - CLICKHOUSE_USER=${CH_USER:-neko}
      - CLICKHOUSE_PASSWORD=${CH_PASSWORD:-neko_master}
      - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1
    networks:
      - neko-master-network
    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:8123/ping || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

networks:
  neko-master-network:
    driver: bridge

Redémarrer :```bash
docker compose --profile clickhouse up -d

Surveillez les journaux de `[ClickHouse Writer]` pour confirmer la réussite des écritures.

#### Phase 2 : Basculer la source de lecture```env
STATS_QUERY_SOURCE=auto        # Smart routing: recent data from CH, historical from SQLite
# or
STATS_QUERY_SOURCE=clickhouse  # Force all reads to ClickHouse

#### Phase 4 (facultatif) : mode CH uniquement

Une fois que ClickHouse fonctionne de manière stable, arrêtez les écritures de statistiques SQLite :```env
CH_ONLY_MODE=1

Redémarrez et tout revient en mode SQLite pur. Les données historiques restent intactes.

---

## 🌐 Reverse Proxy & Tunnel

Approche recommandée : garder Web et WS sous le même domaine, avec un routage par chemin :
`/` → `3000`, `/_cm_ws` → `3002`.

### Exemple standard Nginx```nginx
server {
  listen 443 ssl http2;
  server_name neko.example.com;

  location / {
    proxy_pass http://<neko-master-host>:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }

  location ^~ /_cm_ws {
    proxy_pass http://<neko-master-host>:3002;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;
    proxy_buffering off;
  }
}

### Exemple standard de tunnel Cloudflare

`~/.cloudflared/config.yml` :```yaml
tunnel: <your-tunnel-name-or-id>
credentials-file: /path/to/<credentials>.json

ingress:
  - hostname: neko.example.com
    path: /_cm_ws*
    service: http://localhost:3002
  - hostname: neko.example.com
    path: /*
    service: http://localhost:3000
  - service: http_status:404

Pour les routes gérées par le tableau de bord Zero Trust (mode jeton), configurez les deux mêmes routes et placez `/_cm_ws*` au-dessus de `/*`.

### Notes clés

1. N'utilisez pas `ws` (sans barre oblique initiale) comme chemin WS ; cela peut correspondre de manière excessive et provoquer `/_next/static/...` → `426 Upgrade Required`
2. La route WS doit être au-dessus du catch-all `/*`
3. `NEXT_PUBLIC_WS_URL` est facultatif par défaut ; s'il est personnalisé, redémarrez le frontend/conteneur après les modifications
4. Le mappage de `3000` uniquement fonctionne toujours, mais bascule vers l'interrogation HTTP (~5s), avec une réactivité en temps réel moindre
5. Les échecs de `beacon.min.js` (script d'analyse Cloudflare) sont généralement sans rapport avec le flux de données API/WS de l'application
6. Aucune règle de reverse-proxy `/api` supplémentaire n'est requise dans la plupart des configurations ; le frontend utilise `/api` de même origine et l'application gère le transfert interne vers `3001`

> Remarque : `/_next/static/... 426 Upgrade Required` est courant dans les configurations **reverse proxy / tunnel mal configurées** ; c'est peu fréquent en accès local direct sans proxy.

### Prise en charge multi-architecture

Les images Docker prennent en charge à la fois `linux/amd64` et `linux/arm64`.

### Persistance des données

Les données sont stockées dans `/app/data` à l'intérieur du conteneur. Montez-le sur l'hôte pour éviter toute perte de données :```yaml
volumes:
  - ./data:/app/data

## 🔐 Authentification et sécurité

Neko Master prend en charge l'authentification d'accès pour protéger les données du tableau de bord.

### Base de sécurité pour la production

1. Définissez un `COOKIE_SECRET` fixe (sinon les sessions peuvent être invalidées après un redémarrage).
2. Ne laissez pas `FORCE_ACCESS_CONTROL_OFF=true` activé en fonctionnement normal.
3. Utilisez `SHOWCASE_SITE_MODE=true` uniquement pour les environnements de démonstration publics (les opérations d'écriture sont restreintes).

Exemple :```env
COOKIE_SECRET=<at least 32-byte random string>
# FORCE_ACCESS_CONTROL_OFF=false
# SHOWCASE_SITE_MODE=false

Puis redémarrez :```bash
docker compose down
docker compose up -d

Restaurer :```bash
docker compose down
cp -r ./data-backup-YYYYMMDD/. ./data/
docker compose up -d

## 🛠️ Stack technique

- **Frontend** : [Next.js 16](https://nextjs.org/) + [React 19](https://react.dev/) + [TypeScript](https://www.typescriptlang.org/)
- **Styles** : [Tailwind CSS](https://tailwindcss.com/) + [shadcn/ui](https://ui.shadcn.com/)
- **Graphiques** : [Recharts](https://recharts.org/)
- **i18n** : [next-intl](https://next-intl-docs.vercel.app/)
- **Backend** : [Node.js](https://nodejs.org/) + [Fastify](https://www.fastify.io/) + WebSocket
- **Base de données** : [SQLite](https://www.sqlite.org/) ([better-sqlite3](https://github.com/WiseLibs/better-sqlite3)) + [ClickHouse](https://clickhouse.com/) (facultatif)
- **Build** : [pnpm](https://pnpm.io/) + [Turborepo](https://turbo.build/)

## 🤝 Contribution

Les contributions sont les bienvenues !

- 🐛 [Signaler un bug](https://github.com/foru17/neko-master/issues/new)
- 💡 [Proposer une fonctionnalité](https://github.com/foru17/neko-master/issues/new)
- 🔧 [Contribuer au code](https://github.com/foru17/neko-master/pulls)

Avant d'ouvrir une PR, lisez [CONTRIBUTING.md](https://github.com/foru17/neko-master/blob/main/CONTRIBUTING.md) (workflow, vérifications, exigences i18n/mode sombre).

**Vous développez avec un outil de codage IA ?** (Claude Code, Copilot, Cursor, Codex, ...) Pointez-le vers [AGENTS.md](https://github.com/foru17/neko-master/blob/main/AGENTS.md) — conventions, contrats clés et carte du projet — ainsi que vers les guides de workflow spécifiques aux tâches dans [`.claude/skills/`](https://github.com/foru17/neko-master/blob/main/.claude/skills). Claude Code les détecte automatiquement tous les deux.

## 📄 Licence

[MIT](https://github.com/foru17/neko-master/blob/main/LICENSE) © [foru17](https://github.com/foru17)

---

## ⭐ Historique des étoiles

[![Star History Chart](https://api.star-history.com/svg?repos=foru17/neko-master&type=date&legend=top-left)](https://www.star-history.com/#foru17/neko-master&type=date&legend=top-left)

---

<p align="center">
  <sub>Made with ❤️ by <a href="https://github.com/foru17">@foru17</a></sub><br>
  <sub>If this project helps you, please consider giving it a ⭐</sub>
</p>