> Recomendado en `.env` (mismo directorio que `docker-compose.yml`):
> `COOKIE_SECRET=<cadena aleatoria de al menos 32 bytes>` (generar con `openssl rand -hex 32`)

> Este modo es totalmente compatible con actualizaciones y funciona sin configuración adicional.
> Si WS no está enrutado, la aplicación recurre automáticamente a HTTP polling.

#### Escenario B: WebSocket en tiempo real (recomendado con proxy inverso)```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}

Abre <http://localhost:3000> para comenzar.

Si utilizas el archivo Compose integrado del repositorio (por defecto `3000/3001/3002`), ejecuta el mismo comando.

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

# Basic scan
python3 kitploit.py -u https://example.com

# Scan with specific modules
python3 kitploit.py -u https://example.com -m sqli,xss

# Scan with proxy
python3 kitploit.py -u https://example.com -p http://127.0.0.1:8080

# Generate report
python3 kitploit.py -u https://example.com -r report.html

# Default configuration
threads: 10
timeout: 30
user_agent: "Mozilla/5.0"
follow_redirects: true
verify_ssl: false
proxy: null
output_dir: "./reports"

Abre <http://localhost:3000> para empezar.

> El frontend usa `/api` del mismo origen por defecto, por lo que el puerto 3001 normalmente no es necesario externamente.
> Para WS en tiempo real, tu proxy inverso/túnel debe poder alcanzar el puerto `3002`. Si no, la aplicación recurre a sondeo HTTP de ~5s.

> Para `docker run`, cambia los puertos externos usando mapeos `-p` directamente.
> Solo si usas acceso directo a WS (sin proxy inverso) y el puerto WS externo no es `3002`, pasa también `-e WS_EXTERNAL_PORT=<external-ws-port>`.
>
> Modo de búsqueda local de MMDB (opcional): monta `-v $(pwd)/geoip:/app/data/geoip:ro`,
> luego cambia la fuente a Local en `Settings -> Preferences -> IP Lookup Source`.

### Opción 3: Script de un solo clic

Detecta automáticamente conflictos de puertos y configura todo:```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

Abre <http://localhost:3000> para configurar.

> En modo fuente: el colector escucha en `3001/3002`, la web escucha en `3000` por defecto.
> Si cambiaste `API_PORT` (no 3001), configura `API_URL` en consecuencia (por ejemplo `API_URL=http://localhost:4001`) para que la reescritura de `/api` de la web apunte a la API correcta.
> `apps/collector/.env.local` tiene prioridad sobre `apps/collector/.env`.

## 🤖 Despliegue del Agente

Usa el modo Agente cuando quieras un servicio Neko Master centralizado y múltiples dispositivos remotos (OpenWrt, Linux, macOS) recopilando datos del gateway local. El agente se ejecuta cerca del gateway, extrae datos y los reporta al panel — el panel nunca se conecta directamente al gateway.

Tipos de gateway soportados: **Clash / Mihomo** (WebSocket en tiempo real) y **Surge v5+** (sondeo HTTP).

### Instalación Rápida (comando generado por la UI)

1. En el panel, ve a `Settings → Backends`, añade un backend `Agent`, selecciona el tipo de gateway
2. Haz clic en **"View Agent Script"** y copia el comando de instalación de una línea, luego ejecútalo en el host de destino:```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

> El script detecta automáticamente una instalación existente — si `neko-agent` ya está presente, solo añade la nueva instancia sin volver a descargarlo.
> Se pueden ejecutar múltiples instancias en el mismo host (con diferente `NEKO_INSTANCE_NAME`), cada una apuntando a un gateway distinto.

### Documentación del Agent

- [Overview](https://github.com/foru17/neko-master/blob/main/docs/agent/overview.en.md): arquitectura, comparación Direct vs Agent, modelo de seguridad
- [Quick Start](https://github.com/foru17/neko-master/blob/main/docs/agent/quick-start.en.md): configuración de extremo a extremo desde la UI hasta el agent en ejecución
- [Install Guide](https://github.com/foru17/neko-master/blob/main/docs/agent/install.en.md): métodos de instalación, autoarranque con systemd / launchd
- [Configuration](https://github.com/foru17/neko-master/blob/main/docs/agent/config.en.md): referencia completa de flags y variables de entorno
- [Release Flow](https://github.com/foru17/neko-master/blob/main/docs/agent/release.en.md): política de versionado y compatibilidad
- [Troubleshooting](https://github.com/foru17/neko-master/blob/main/docs/agent/troubleshooting.en.md): errores comunes y soluciones

## 📖 Primer uso

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

### Conectar Clash / Mihomo

1. Abre <http://localhost:3000>
2. El diálogo **Gateway Configuration** aparecerá en la primera visita
3. Rellena la información de conexión de tu gateway de red (p. ej., OpenClash):
   - **Name**: Nombre personalizado (p. ej., "Home Gateway")
   - **Type**: Selecciona `Clash / Mihomo`
   - **Host**: Dirección del backend del gateway (p. ej., `192.168.101.1`)
   - **Port**: Puerto del backend del gateway (p. ej., `9090`)
   - **Token**: Rellénalo si hay un Secret configurado; de lo contrario, déjalo vacío
4. Haz clic en "Add Backend" para guardar
5. El sistema comenzará automáticamente a recopilar y analizar los datos de tráfico

> 💡 **Obtener la dirección del gateway**: Ve al panel de control de tu gateway (p. ej., OpenClash) → Activa "External Control" → Copia la dirección de la API

### Conectar Surge

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

Neko Master admite la conexión a gateways Surge para la visualización completa de la cadena de reglas y el análisis de tráfico.

#### 1. Activar la API HTTP de Surge

Activa la API remota HTTP en tu configuración de Surge:```ini
[General]
http-api = 127.0.0.1:9091
http-api-tls = false
http-api-web-dashboard = true

Luego reinicia:```bash
docker compose down
docker compose up -d

> Nota: si usas acceso directo por WS (sin proxy inverso) y el puerto WS externo no es `3002`, establece `WS_EXTERNAL_PORT=<external-ws-port>`.

### Solución 3: Usar el script de un solo clic```bash
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

Utilice `openssl rand -hex 32` para generar `COOKIE_SECRET`.

Recomendaciones adicionales:

1. Monte almacenamiento persistente (por ejemplo `./data:/app/data`) para evitar la pérdida de datos y secretos.
2. Si utiliza acceso WS directo y el puerto WS externo no es `3002`, configure `WS_EXTERNAL_PORT` en consecuencia.
3. Si el puerto/dirección de la API cambia en el despliegue de origen, actualice `API_URL` también.
4. Para la búsqueda local de MMDB, monte `./geoip:/app/data/geoip:ro` y cambie la fuente en `Settings -> Preferences -> IP Lookup Source`.
5. Los archivos MMDB son grandes y no están incluidos en la imagen. Descárguelos y colóquelos en `./geoip` con nombres fijos:
   `GeoLite2-City.mmdb`, `GeoLite2-ASN.mmdb` (obligatorio), y `GeoLite2-Country.mmdb` (opcional).
   Fuente recomendada: <https://github.com/P3TERX/GeoLite.mmdb>.

> Los detalles avanzados del Agent (instalación, configuración, lanzamiento, compatibilidad) se mantienen en `docs/agent/*`.

## 🗄️ ClickHouse (Opcional)

SQLite es el motor de almacenamiento predeterminado de Neko Master y funciona bien para la mayoría de los usuarios.
Considere habilitar ClickHouse si necesita:

- Conjuntos de datos muy grandes (cientos de miles de entradas de dominio/IP)
- Consultas de agregación rápidas sobre rangos de tiempo largos (≥ 7 días)
- Separación de estadísticas históricas del almacenamiento de configuración/metadatos

> ClickHouse es completamente opcional. SQLite permanece como el almacén de configuración y metadatos independientemente de si ClickHouse está habilitado.

### Descripción general de la arquitectura

Cuando ClickHouse está habilitado, el sistema entra en **modo de escritura dual**:```
BatchBuffer.flush()
    │
    ├──→ SQLite (config / metadata, always written)
    └──→ ClickHouse (stats traffic data, dual-write)
           └── Buffer tables → SummingMergeTree async merge

> Los datos de ClickHouse se persisten en `./data/clickhouse`, separados del directorio de datos principal de la aplicación.

Si utilizas un **`docker-compose.yml` personalizado** (como el Escenario A/B anterior), añade el
bloque de servicio de ClickHouse manualmente:```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

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

Inicie y observe los registros de `[ClickHouse Writer]` para confirmar escrituras exitosas.

#### Fase 2: Cambiar la fuente de lectura```env
STATS_QUERY_SOURCE=auto        # Smart routing: recent data from CH, historical from SQLite
# or
STATS_QUERY_SOURCE=clickhouse  # Force all reads to ClickHouse

#### Fase 4 (opcional): modo solo CH

Una vez que ClickHouse esté funcionando de forma estable, detén las escrituras de estadísticas en SQLite:```env
CH_ONLY_MODE=1

Reinicia y todo vuelve al modo SQLite puro. Los datos históricos permanecen intactos.

---

## 🌐 Proxy Inverso y Túnel

Enfoque recomendado: mantener Web y WS bajo el mismo dominio, con enrutamiento por ruta:
`/` → `3000`, `/_cm_ws` → `3002`.

### Ejemplo Estándar de 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;
  }
}

### Ejemplo estándar de Cloudflare Tunnel

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

Para rutas gestionadas por el panel de Zero Trust (modo token), configure las mismas dos rutas y mantenga `/_cm_ws*` por encima de `/*`.

### Notas clave

1. No use `ws` (sin barra inicial) como ruta WS; puede coincidir en exceso y provocar `/_next/static/...` → `426 Upgrade Required`
2. La ruta WS debe estar por encima del catch-all `/*`
3. `NEXT_PUBLIC_WS_URL` es opcional por defecto; si se personaliza, reinicie el frontend/contenedor tras los cambios
4. Mapear solo `3000` sigue funcionando, pero recurre a HTTP polling (~5s), con menor capacidad de respuesta en tiempo real
5. Los fallos de `beacon.min.js` (script de analítica de Cloudflare) normalmente no están relacionados con el flujo de datos de la API/WS de la aplicación
6. No se requiere una regla adicional de reverse-proxy `/api` en la mayoría de configuraciones; el frontend usa `/api` del mismo origen y la aplicación gestiona el reenvío interno a `3001`

> Nota: `/_next/static/... 426 Upgrade Required` es común en configuraciones de **reverse proxy / túnel mal configurados**; es poco común en acceso local directo sin proxy.

### Soporte multiarquitectura

Las imágenes Docker soportan tanto `linux/amd64` como `linux/arm64`.

### Persistencia de datos

Los datos se almacenan en `/app/data` dentro del contenedor. Móntelo en el host para evitar la pérdida de datos:```yaml
volumes:
  - ./data:/app/data

## 🔐 Autenticación y seguridad

Neko Master admite autenticación de acceso para proteger los datos del panel.

### Línea base de seguridad en producción

1. Establezca un `COOKIE_SECRET` fijo (de lo contrario, las sesiones pueden invalidarse tras un reinicio).
2. No mantenga `FORCE_ACCESS_CONTROL_OFF=true` habilitado durante la operación normal.
3. Use `SHOWCASE_SITE_MODE=true` solo para entornos de demostración públicos (las operaciones de escritura están restringidas).

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

Luego reinicia:```bash
docker compose down
docker compose up -d

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

## 🛠️ Stack Tecnológico

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

## 🤝 Contribuir

¡Las contribuciones son bienvenidas!

- 🐛 [Reportar un error](https://github.com/foru17/neko-master/issues/new)
- 💡 [Solicitar una funcionalidad](https://github.com/foru17/neko-master/issues/new)
- 🔧 [Contribuir con código](https://github.com/foru17/neko-master/pulls)

Antes de abrir un PR, lee [CONTRIBUTING.md](https://github.com/foru17/neko-master/blob/main/CONTRIBUTING.md) (flujo de trabajo, comprobaciones, requisitos de i18n/modo oscuro).

**¿Desarrollas con una herramienta de codificación con IA?** (Claude Code, Copilot, Cursor, Codex, ...) Apúntala a [AGENTS.md](https://github.com/foru17/neko-master/blob/main/AGENTS.md) — convenciones, contratos clave y el mapa del proyecto — además de las guías de flujo de trabajo específicas por tarea en [`.claude/skills/`](https://github.com/foru17/neko-master/blob/main/.claude/skills). Claude Code detecta ambos automáticamente.

## 📄 Licencia

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

---

## ⭐ Historial de estrellas

[![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>Hecho con ❤️ por <a href="https://github.com/foru17">@foru17</a></sub><br>
  <sub>Si este proyecto te ayuda, considera darle una ⭐</sub>
</p>