> Recomendado em `.env` (mesmo diretório que `docker-compose.yml`):
> `COOKIE_SECRET=<string aleatória de pelo menos 32 bytes>` (gerar com `openssl rand -hex 32`)

> Este modo é totalmente compatível com atualizações e funciona imediatamente.
> Se o WS não estiver roteado, a aplicação recorre automaticamente ao polling HTTP.

#### Cenário B: WebSocket em tempo real (recomendado com proxy reverso)```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}

Abra <http://localhost:3000> para começar.

Se você usar o arquivo Compose integrado do repositório (padrão `3000/3001/3002`), execute o mesmo comando.

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

# Clone o repositório
git clone https://github.com/example/tool.git
cd tool

# Instale as dependências
pip install -r requirements.txt

python tool.py --target example.com

Abra <http://localhost:3000> para começar.

> O frontend usa `/api` de mesma origem por padrão, então a porta 3001 geralmente não é necessária externamente.
> Para WS em tempo real, seu proxy reverso/túnel precisa conseguir alcançar a porta `3002`. Caso contrário, o aplicativo recorre a polling HTTP de ~5s.

> Para `docker run`, altere as portas externas usando mapeamentos `-p` diretamente.
> Apenas se você usar acesso WS direto (sem proxy reverso) e a porta WS externa não for `3002`, passe também `-e WS_EXTERNAL_PORT=<external-ws-port>`.
>
> Modo de consulta MMDB local (opcional): monte `-v $(pwd)/geoip:/app/data/geoip:ro`,
> depois mude a fonte para Local em `Settings -> Preferences -> IP Lookup Source`.

### Opção 3: Script de Um Clique

Detecta automaticamente conflitos de porta e configura tudo:```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

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

> No modo source: o collector escuta em `3001/3002`, o web escuta em `3000` por padrão.
> Se você alterou `API_PORT` (não 3001), defina `API_URL` de acordo (por exemplo `API_URL=http://localhost:4001`) para que o rewrite de `/api` do web aponte para a API correta.
> `apps/collector/.env.local` tem precedência sobre `apps/collector/.env`.

## 🤖 Implantação do Agent

Use o modo Agent quando você quiser um serviço Neko Master centralizado e vários dispositivos remotos (OpenWrt, Linux, macOS) coletando dados do gateway local. O agent é executado próximo ao gateway, extrai os dados e reporta ao painel — o painel nunca se conecta diretamente ao gateway.

Tipos de gateway suportados: **Clash / Mihomo** (WebSocket em tempo real) e **Surge v5+** (polling HTTP).

### Instalação Rápida (comando gerado pela UI)

1. No dashboard, vá em `Settings → Backends`, adicione um backend `Agent`, selecione o tipo de gateway
2. Clique em **"View Agent Script"** e copie o comando de instalação de uma linha, depois execute-o no 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

> O script detecta automaticamente uma instalação existente — se o `neko-agent` já estiver presente, ele apenas adiciona a nova instância sem baixar novamente.
> Várias instâncias podem ser executadas no mesmo host (com `NEKO_INSTANCE_NAME` diferente), cada uma apontando para um gateway diferente.

### Documentação do Agent

- [Visão Geral](https://github.com/foru17/neko-master/blob/main/docs/agent/overview.en.md): arquitetura, comparação entre Direct e Agent, modelo de segurança
- [Início Rápido](https://github.com/foru17/neko-master/blob/main/docs/agent/quick-start.en.md): configuração ponta a ponta, da UI ao agent em execução
- [Guia de Instalação](https://github.com/foru17/neko-master/blob/main/docs/agent/install.en.md): métodos de instalação, inicialização automática com systemd / launchd
- [Configuração](https://github.com/foru17/neko-master/blob/main/docs/agent/config.en.md): referência completa de flags e variáveis de ambiente
- [Fluxo de Release](https://github.com/foru17/neko-master/blob/main/docs/agent/release.en.md): política de versionamento e compatibilidade
- [Solução de Problemas](https://github.com/foru17/neko-master/blob/main/docs/agent/troubleshooting.en.md): erros comuns e correções

## 📖 Primeiro Uso

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

### Conectar Clash / Mihomo

1. Abra <http://localhost:3000>
2. A caixa de diálogo **Gateway Configuration** aparecerá na primeira visita
3. Preencha as informações de conexão do seu gateway de rede (por exemplo, OpenClash):
   - **Name**: Nome personalizado (por exemplo, "Home Gateway")
   - **Type**: Selecione `Clash / Mihomo`
   - **Host**: Endereço do backend do gateway (por exemplo, `192.168.101.1`)
   - **Port**: Porta do backend do gateway (por exemplo, `9090`)
   - **Token**: Preencha se o Secret estiver configurado, caso contrário deixe vazio
4. Clique em "Add Backend" para salvar
5. O sistema começará automaticamente a coletar e analisar dados de tráfego

> 💡 **Obter Endereço do Gateway**: Vá ao painel de controle do seu gateway (por exemplo, OpenClash) → Ative "External Control" → Copie o endereço da API

### Conectar Surge

![Configuração da API HTTP do Surge](https://assets.kitploit.com/production/public/readmes/55481/9cc7414a5acad5b6c3f5fadccd072b50f0b552b305ff5003024a3d1304bb9ec4/bae0f4f4debf30de5fdf5331b6befad02135ba827c5812c1e4fdf33614c3aede-display-v1.webp)

O Neko Master suporta a conexão com gateways Surge para visualização completa da cadeia de regras e análise de tráfego.

#### 1. Ativar a API HTTP do Surge

Ative a API remota HTTP na sua configuração do Surge:```ini
[General]
http-api = 127.0.0.1:9091
http-api-tls = false
http-api-web-dashboard = true

Em seguida, reinicie:```bash
docker compose down
docker compose up -d

> Nota: se você usar acesso WS direto (sem proxy reverso) e a porta WS externa não for `3002`, defina `WS_EXTERNAL_PORT=<external-ws-port>`.

### Solução 3: Usar Script de Um Clique```bash
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

Use `openssl rand -hex 32` para gerar `COOKIE_SECRET`.

Recomendações adicionais:

1. Monte armazenamento persistente (por exemplo `./data:/app/data`) para evitar perda de dados e segredos.
2. Se usar acesso WS direto e a porta WS externa não for `3002`, defina `WS_EXTERNAL_PORT` de acordo.
3. Se a porta/endereço da API mudar na implantação de origem, atualize `API_URL` também.
4. Para consulta MMDB local, monte `./geoip:/app/data/geoip:ro` e altere a origem em `Settings -> Preferences -> IP Lookup Source`.
5. Os arquivos MMDB são grandes e não estão incluídos na imagem. Baixe-os e coloque-os em `./geoip` com nomes fixos:
   `GeoLite2-City.mmdb`, `GeoLite2-ASN.mmdb` (obrigatório) e `GeoLite2-Country.mmdb` (opcional).
   Fonte recomendada: <https://github.com/P3TERX/GeoLite.mmdb>.

> Detalhes avançados do Agent (instalação, configuração, release, compatibilidade) são mantidos em `docs/agent/*`.

## 🗄️ ClickHouse (Opcional)

SQLite é o mecanismo de armazenamento padrão do Neko Master e funciona bem para a maioria dos usuários.
Considere habilitar o ClickHouse se você precisar de:

- Conjuntos de dados muito grandes (centenas de milhares de entradas de domínio/IP)
- Consultas de agregação rápidas em longos intervalos de tempo (≥ 7 dias)
- Separação de estatísticas históricas do armazenamento de configuração/metadados

> O ClickHouse é totalmente opcional. O SQLite permanece como armazenamento de configuração e metadados independentemente de o ClickHouse estar habilitado.

### Visão Geral da Arquitetura

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

> Os dados do ClickHouse são persistidos em `./data/clickhouse`, separadamente do diretório de dados principal da aplicação.

Se você usar um **`docker-compose.yml` personalizado** (como o Cenário A/B acima), adicione o
bloco de serviço do 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 e observe os logs do `[ClickHouse Writer]` para confirmar gravações bem-sucedidas.

#### Fase 2: Alternar a fonte de leitura```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 somente CH

Depois que o ClickHouse estiver em execução estável, interrompa as gravações de estatísticas no SQLite:```env
CH_ONLY_MODE=1

Reinicie e tudo retorna ao modo SQLite puro. Os dados históricos permanecem intactos.

---

## 🌐 Proxy Reverso e Túnel

Abordagem recomendada: manter Web e WS sob o mesmo domínio, com roteamento por caminho:
`/` → `3000`, `/_cm_ws` → `3002`.

### Exemplo Padrão do 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;
  }
}

### Exemplo Padrão do 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 rotas gerenciadas pelo painel Zero Trust (modo token), configure as mesmas duas rotas e mantenha `/_cm_ws*` acima de `/*`.

### Notas Importantes

1. Não use `ws` (sem barra inicial) como caminho WS; ele pode fazer overmatch e causar `/_next/static/...` → `426 Upgrade Required`
2. A rota WS deve estar acima do catch-all `/*`
3. `NEXT_PUBLIC_WS_URL` é opcional por padrão; se personalizado, reinicie o frontend/container após as alterações
4. Mapear apenas `3000` ainda funciona, mas recorre a HTTP polling (~5s), com menor responsividade em tempo real
5. Falhas do `beacon.min.js` (script de analytics do Cloudflare) normalmente não estão relacionadas ao fluxo de dados da API/WS do app
6. Nenhuma regra extra de reverse-proxy `/api` é necessária na maioria das configurações; o frontend usa `/api` na mesma origem e o app lida com o encaminhamento interno para `3001`

> Nota: `/_next/static/... 426 Upgrade Required` é comum em configurações de **reverse proxy / tunnel mal configurados**; é incomum em acesso local direto sem proxy.

### Suporte Multi-Arquitetura

As imagens Docker suportam tanto `linux/amd64` quanto `linux/arm64`.

### Persistência de Dados

Os dados são armazenados em `/app/data` dentro do container. Monte-o no host para evitar perda de dados:```yaml
volumes:
  - ./data:/app/data

## 🔐 Autenticação e Segurança

O Neko Master suporta autenticação de acesso para proteger os dados do dashboard.

### Linha de Base de Segurança para Produção

1. Defina um `COOKIE_SECRET` fixo (caso contrário, as sessões podem ser invalidadas após a reinicialização).
2. Não mantenha `FORCE_ACCESS_CONTROL_OFF=true` ativado em operação normal.
3. Use `SHOWCASE_SITE_MODE=true` apenas para ambientes de demonstração públicos (as operações de escrita são restringidas).

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

Em seguida, reinicie:```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/)
- **Estilização**: [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
- **Banco de Dados**: [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/)

## 🤝 Contribuindo

Contribuições são bem-vindas!

- 🐛 [Reportar Bug](https://github.com/foru17/neko-master/issues/new)
- 💡 [Solicitar Funcionalidade](https://github.com/foru17/neko-master/issues/new)
- 🔧 [Contribuir com Código](https://github.com/foru17/neko-master/pulls)

Antes de abrir um PR, leia o [CONTRIBUTING.md](https://github.com/foru17/neko-master/blob/main/CONTRIBUTING.md) (fluxo de trabalho, verificações, requisitos de i18n/modo escuro).

**Desenvolvendo com uma ferramenta de codificação com IA?** (Claude Code, Copilot, Cursor, Codex, ...) Aponte-a para [AGENTS.md](https://github.com/foru17/neko-master/blob/main/AGENTS.md) — convenções, contratos principais e o mapa do projeto — além dos guias de fluxo de trabalho específicos por tarefa em [`.claude/skills/`](https://github.com/foru17/neko-master/blob/main/.claude/skills). O Claude Code captura ambos automaticamente.

## 📄 Licença

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

---

## ⭐ Histórico de Estrelas

[![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>Feito com ❤️ por <a href="https://github.com/foru17">@foru17</a></sub><br>
  <sub>Se este projeto te ajuda, considere dar uma ⭐</sub>
</p>