> Empfohlen in `.env` (gleiches Verzeichnis wie `docker-compose.yml`):
> `COOKIE_SECRET=<mindestens 32-Byte-Zufallszeichenkette>` (generieren mit `openssl rand -hex 32`)

> Dieser Modus ist vollständig upgrade-kompatibel und funktioniert sofort einsatzbereit.
> Wenn WS nicht geroutet wird, fällt die App automatisch auf HTTP-Polling zurück.

#### Szenario B: Echtzeit-WebSocket (empfohlen mit 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}

Öffne <http://localhost:3000>, um zu starten.

Wenn du die im Repository enthaltene Compose-Datei verwendest (Standard `3000/3001/3002`), führe denselben Befehl aus.

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

git clone https://github.com/soth-ai/soth.git
cd soth
cargo build --release

cargo install soth-cli

docker pull sothai/soth:latest
docker run -it --rm -p 8080:8080 -p 8443:8443 sothai/soth:latest

soth cert generate --ca --output ./certs

soth proxy start --port 8080 --ca-cert ./certs/ca.crt --ca-key ./certs/ca.key

soth rule add --name "block-ads" --pattern "*.doubleclick.net" --action block

[proxy]
listen = "0.0.0.0:8080"
tls_listen = "0.0.0.0:8443"
ca_cert = "./certs/ca.crt"
ca_key = "./certs/ca.key"

[proxy.upstream]
timeout = 30
max_connections = 1000

[logging]
level = "info"
format = "json"
output = "./logs/soth.log"

[rules]
directory = "./rules"
hot_reload = true

[store]
backend = "sqlite"
path = "./data/soth.db"

[observe]
metrics_enabled = true
metrics_port = 9090
tracing_enabled = true

name: "block-ads"
description: "Block known advertising domains"
enabled: true
priority: 100

match:
  host:
    - "*.doubleclick.net"
    - "*.googlesyndication.com"
  method:
    - GET
    - POST

action:
  type: block
  status: 403
  body: "Blocked by Soth"

soth cert generate --ca --output ./certs --common-name "Soth CA" --validity 3650

soth cert generate --host "example.com" --ca-cert ./certs/ca.crt --ca-key ./certs/ca.key --output ./certs

soth cert list --directory ./certs

soth cert revoke --serial "1234567890" --ca-cert ./certs/ca.crt --ca-key ./certs/ca.key

[observe]
tracing_enabled = true
otlp_endpoint = "http://localhost:4317"

{
  "timestamp": "2024-01-15T10:30:00Z",
  "level": "info",
  "message": "Request intercepted",
  "method": "GET",
  "host": "example.com",
  "path": "/api/users",
  "status": 200,
  "duration_ms": 45
}

use soth_sdk::{Rule, Request, Action, Result};

pub struct BlockUserAgent;

impl Rule for BlockUserAgent {
    fn name(&self) -> &str {
        "block-user-agent"
    }

    fn matches(&self, req: &Request) -> bool {
        req.headers
            .get("user-agent")
            .map(|ua| ua.contains("curl"))
            .unwrap_or(false)
    }

    fn action(&self) -> Action {
        Action::Block {
            status: 403,
            body: Some("Blocked by Soth SDK".to_string()),
        }
    }
}

use soth_sdk::{Plugin, Context, Result};

pub struct MyPlugin;

#[async_trait::async_trait]
impl Plugin for MyPlugin {
    async fn on_request(&self, ctx: &mut Context) -> Result<()> {
        ctx.log_info("Processing request");
        Ok(())
    }

    async fn on_response(&self, ctx: &mut Context) -> Result<()> {
        ctx.log_info("Processing response");
        Ok(())
    }
}

┌─────────────────────────────────────────┐
│              soth-cli                   │
│         (Command-line interface)        │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│              soth-proxy                 │
│         (Proxy server binary)           │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│              soth-mitm                  │
│         (MITM proxy library)            │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│              soth-core                  │
│      (Core types and traits)            │
└─────────────────────────────────────────┘

git clone https://github.com/soth-ai/soth.git
cd soth
cargo build
cargo test

cargo test --all-features

cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings

Öffne <http://localhost:3000>, um zu starten.

> Das Frontend verwendet standardmäßig `/api` mit gleichem Ursprung, daher ist Port 3001 extern normalerweise nicht erforderlich.
> Für Echtzeit-WS muss dein Reverse-Proxy/Tunnel Port `3002` erreichen können. Falls nicht, fällt die App auf ~5s HTTP-Polling zurück.

> Bei `docker run` ändere die externen Ports direkt über `-p`-Mappings.
> Nur wenn du direkten WS-Zugriff verwendest (kein Reverse-Proxy) und der externe WS-Port nicht `3002` ist, übergib zusätzlich `-e WS_EXTERNAL_PORT=<external-ws-port>`.
>
> Lokaler MMDB-Lookup-Modus (optional): mounte `-v $(pwd)/geoip:/app/data/geoip:ro`,
> wechsle dann die Quelle auf Local in `Settings -> Preferences -> IP Lookup Source`.

### Option 3: Ein-Klick-Skript

Erkennt automatisch Portkonflikte und konfiguriert alles:```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

Öffne <http://localhost:3000> zur Konfiguration.

> Im Quellmodus: Der Collector lauscht auf `3001/3002`, das Web lauscht standardmäßig auf `3000`.
> Wenn du `API_PORT` geändert hast (nicht 3001), setze `API_URL` entsprechend (zum Beispiel `API_URL=http://localhost:4001`), damit das Web-`/api`-Rewrite auf die korrekte API zeigt.
> `apps/collector/.env.local` hat Vorrang vor `apps/collector/.env`.

## 🤖 Agent-Bereitstellung

Verwende den Agent-Modus, wenn du einen zentralisierten Neko Master-Dienst und mehrere entfernte Geräte (OpenWrt, Linux, macOS) möchtest, die lokale Gateway-Daten sammeln. Der Agent läuft in der Nähe des Gateways, ruft Daten ab und meldet sie an das Panel — das Panel verbindet sich nie direkt mit dem Gateway.

Unterstützte Gateway-Typen: **Clash / Mihomo** (WebSocket-Echtzeit) und **Surge v5+** (HTTP-Polling).

### Schnellinstallation (UI-generierter Befehl)

1. Gehe im Dashboard zu `Settings → Backends`, füge ein `Agent`-Backend hinzu, wähle den Gateway-Typ aus
2. Klicke auf **"View Agent Script"** und kopiere den einzeiligen Installationsbefehl, führe ihn dann auf dem Zielhost aus:```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

> Das Skript erkennt automatisch eine vorhandene Installation — wenn `neko-agent` bereits vorhanden ist, wird nur die neue Instanz hinzugefügt, ohne erneut herunterzuladen.
> Mehrere Instanzen können auf demselben Host ausgeführt werden (unterschiedlicher `NEKO_INSTANCE_NAME`), die jeweils auf ein anderes Gateway verweisen.

### Agent-Dokumentation

- [Übersicht](https://github.com/foru17/neko-master/blob/main/docs/agent/overview.en.md): Architektur, Vergleich Direct vs. Agent, Sicherheitsmodell
- [Schnellstart](https://github.com/foru17/neko-master/blob/main/docs/agent/quick-start.en.md): End-to-End-Einrichtung von der UI bis zum laufenden Agent
- [Installationsanleitung](https://github.com/foru17/neko-master/blob/main/docs/agent/install.en.md): Installationsmethoden, systemd / launchd Autostart
- [Konfiguration](https://github.com/foru17/neko-master/blob/main/docs/agent/config.en.md): vollständige Referenz zu Flags und Umgebungsvariablen
- [Release-Ablauf](https://github.com/foru17/neko-master/blob/main/docs/agent/release.en.md): Versionierung und Kompatibilitätsrichtlinie
- [Fehlerbehebung](https://github.com/foru17/neko-master/blob/main/docs/agent/troubleshooting.en.md): häufige Fehler und Lösungen

## 📖 Erste Verwendung

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

### Clash / Mihomo verbinden

1. Öffne <http://localhost:3000>
2. Beim ersten Besuch erscheint der Dialog **Gateway-Konfiguration**
3. Gib die Verbindungsinformationen für dein Netzwerk-Gateway (z. B. OpenClash) ein:
   - **Name**: Benutzerdefinierter Name (z. B. „Home Gateway")
   - **Typ**: Wähle `Clash / Mihomo`
   - **Host**: Backend-Adresse des Gateways (z. B. `192.168.101.1`)
   - **Port**: Backend-Port des Gateways (z. B. `9090`)
   - **Token**: Ausfüllen, wenn Secret konfiguriert ist, andernfalls leer lassen
4. Klicke auf „Add Backend", um zu speichern
5. Das System beginnt automatisch mit dem Sammeln und Analysieren von Verkehrsdaten

> 💡 **Gateway-Adresse ermitteln**: Gehe zu deinem Gateway-Kontrollpanel (z. B. OpenClash) → Aktiviere „External Control" → Kopiere die API-Adresse

### Surge verbinden

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

Neko Master unterstützt die Verbindung mit Surge-Gateways für vollständige Regelketten-Visualisierung und Verkehrsanalyse.

#### 1. Surge HTTP API aktivieren

Aktiviere die HTTP-Remote-API in deiner Surge-Konfiguration:```ini
[General]
http-api = 127.0.0.1:9091
http-api-tls = false
http-api-web-dashboard = true

Dann neu starten:```bash
docker compose down
docker compose up -d

> Hinweis: Wenn Sie direkten WS-Zugriff verwenden (kein Reverse-Proxy) und der externe WS-Port nicht `3002` ist, setzen Sie `WS_EXTERNAL_PORT=<external-ws-port>`.

### Lösung 3: Ein-Klick-Skript verwenden```bash
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

Verwende `openssl rand -hex 32`, um `COOKIE_SECRET` zu generieren.

Zusätzliche Empfehlungen:

1. Binde persistenten Speicher ein (zum Beispiel `./data:/app/data`), um Daten- und Secret-Verlust zu vermeiden.
2. Wenn du direkten WS-Zugriff verwendest und der externe WS-Port nicht `3002` ist, setze `WS_EXTERNAL_PORT` entsprechend.
3. Wenn sich der API-Port/die API-Adresse im Quell-Deployment ändert, aktualisiere auch `API_URL`.
4. Für lokale MMDB-Lookups binde `./geoip:/app/data/geoip:ro` ein und wechsle die Quelle unter `Settings -> Preferences -> IP Lookup Source`.
5. MMDB-Dateien sind groß und nicht im Image enthalten. Lade sie herunter und lege sie in `./geoip` mit festen Namen ab:
   `GeoLite2-City.mmdb`, `GeoLite2-ASN.mmdb` (erforderlich) und `GeoLite2-Country.mmdb` (optional).
   Empfohlene Quelle: <https://github.com/P3TERX/GeoLite.mmdb>.

> Erweiterte Agent-Details (Installation, Konfiguration, Release, Kompatibilität) werden unter `docs/agent/*` gepflegt.

## 🗄️ ClickHouse (Optional)

SQLite ist die Standard-Speicher-Engine von Neko Master und funktioniert gut für die meisten Benutzer.
Erwäge die Aktivierung von ClickHouse, wenn du Folgendes benötigst:

- Sehr große Datensätze (Hunderttausende von Domain-/IP-Einträgen)
- Schnelle Aggregationsabfragen über lange Zeiträume (≥ 7 Tage)
- Trennung von historischen Statistiken von der Konfigurations-/Metadaten-Speicherung

> ClickHouse ist vollständig optional. SQLite bleibt unabhängig davon, ob ClickHouse aktiviert ist, der Konfigurations- und Metadatenspeicher.

### Architekturübersicht

Wenn ClickHouse aktiviert ist, wechselt das System in den **Dual-Write-Modus**:```
BatchBuffer.flush()
    │
    ├──→ SQLite (config / metadata, always written)
    └──→ ClickHouse (stats traffic data, dual-write)
           └── Buffer tables → SummingMergeTree async merge

> ClickHouse-Daten werden in `./data/clickhouse` persistiert, getrennt vom Haupt-Datenverzeichnis der App.

Wenn Sie eine **benutzerdefinierte `docker-compose.yml`** verwenden (wie in Szenario A/B oben), fügen Sie den ClickHouse-Serviceblock manuell hinzu:```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

Neustart:```bash
docker compose --profile clickhouse up -d

Starten Sie und beobachten Sie die `[ClickHouse Writer]`-Logs, um erfolgreiche Schreibvorgänge zu bestätigen.

#### Phase 2: Lesequelle wechseln```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 (optional): Nur-CH-Modus

Sobald ClickHouse stabil läuft, stoppen Sie die SQLite-Statistik-Schreibvorgänge:```env
CH_ONLY_MODE=1

Neustart, und alles kehrt in den reinen SQLite-Modus zurück. Historische Daten bleiben intakt.

---

## 🌐 Reverse Proxy & Tunnel

Empfohlener Ansatz: Web und WS unter derselben Domain belassen, mit Pfad-Routing:
`/` → `3000`, `/_cm_ws` → `3002`.

### Nginx Standardbeispiel```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;
  }
}

### Cloudflare Tunnel Standardbeispiel

`~/.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

Für Zero Trust Dashboard-verwaltete Routen (Token-Modus) konfigurieren Sie dieselben zwei Routen und halten Sie `/_cm_ws*` über `/*`.

### Wichtige Hinweise

1. Verwenden Sie nicht `ws` (ohne führenden Schrägstrich) als WS-Pfad; dies kann zu einer Überübereinstimmung führen und `/_next/static/...` → `426 Upgrade Required` verursachen
2. Die WS-Route muss über dem Catch-all `/*` liegen
3. `NEXT_PUBLIC_WS_URL` ist standardmäßig optional; bei Anpassung Frontend/Container nach Änderungen neu starten
4. Die alleinige Zuordnung von `3000` funktioniert weiterhin, fällt jedoch auf HTTP-Polling (~5s) zurück, mit geringerer Echtzeit-Reaktionsfähigkeit
5. `beacon.min.js`-Fehler (Cloudflare-Analytics-Skript) stehen typischerweise nicht im Zusammenhang mit dem API-/WS-Datenfluss der App
6. In den meisten Setups ist keine zusätzliche `/api`-Reverse-Proxy-Regel erforderlich; das Frontend verwendet same-origin `/api` und die App übernimmt die interne Weiterleitung an `3001`

> Hinweis: `/_next/static/... 426 Upgrade Required` ist häufig in **fehlkonfigurierten Reverse-Proxy-/Tunnel**-Setups anzutreffen; es ist ungewöhnlich bei direktem lokalem Zugriff ohne Proxy.

### Multi-Architektur-Unterstützung

Docker-Images unterstützen sowohl `linux/amd64` als auch `linux/arm64`.

### Datenpersistenz

Daten werden in `/app/data` innerhalb des Containers gespeichert. Mounten Sie es auf den Host, um Datenverlust zu verhindern:```yaml
volumes:
  - ./data:/app/data

## 🔐 Authentifizierung & Sicherheit

Neko Master unterstützt Zugriffsauthentifizierung zum Schutz der Dashboard-Daten.

### Produktions-Sicherheitsgrundlage

1. Setzen Sie ein festes `COOKIE_SECRET` (andernfalls können Sitzungen nach einem Neustart ungültig werden).
2. Lassen Sie `FORCE_ACCESS_CONTROL_OFF=true` im Normalbetrieb nicht aktiviert.
3. Verwenden Sie `SHOWCASE_SITE_MODE=true` nur für öffentliche Demo-Umgebungen (Schreibvorgänge sind eingeschränkt).

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

Dann neu starten:```bash
docker compose down
docker compose up -d

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

## 🛠️ Tech-Stack

- **Frontend**: [Next.js 16](https://nextjs.org/) + [React 19](https://react.dev/) + [TypeScript](https://www.typescriptlang.org/)
- **Styling**: [Tailwind CSS](https://tailwindcss.com/) + [shadcn/ui](https://ui.shadcn.com/)
- **Diagramme**: [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
- **Datenbank**: [SQLite](https://www.sqlite.org/) ([better-sqlite3](https://github.com/WiseLibs/better-sqlite3)) + [ClickHouse](https://clickhouse.com/) (optional)
- **Build**: [pnpm](https://pnpm.io/) + [Turborepo](https://turbo.build/)

## 🤝 Mitwirken

Beiträge sind willkommen!

- 🐛 [Bug melden](https://github.com/foru17/neko-master/issues/new)
- 💡 [Feature vorschlagen](https://github.com/foru17/neko-master/issues/new)
- 🔧 [Code beitragen](https://github.com/foru17/neko-master/pulls)

Bevor du einen PR öffnest, lies [CONTRIBUTING.md](https://github.com/foru17/neko-master/blob/main/CONTRIBUTING.md) (Workflow, Checks, i18n/Dark-Mode-Anforderungen).

**Entwickelst du mit einem KI-Coding-Tool?** (Claude Code, Copilot, Cursor, Codex, ...) Verweise es auf [AGENTS.md](https://github.com/foru17/neko-master/blob/main/AGENTS.md) — Konventionen, zentrale Verträge und die Projektübersicht — sowie auf die aufgabenspezifischen Workflow-Anleitungen in [`.claude/skills/`](https://github.com/foru17/neko-master/blob/main/.claude/skills). Claude Code erkennt beides automatisch.

## 📄 Lizenz

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

---

## ⭐ Star-Verlauf

[![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>Wenn dir dieses Projekt hilft, zieh bitte in Betracht, ihm einen ⭐ zu geben</sub>
</p>