Neko Master

See your network traffic clearly.
Real-time monitoring · Traffic auditing · Multi-gateway support

English | 中文

[!IMPORTANT]

Disclaimer

This project is a traffic analysis and visualization tool

for local gateway environments.

It does not provide any network access service,

proxy subscription, or cross-network connectivity.

All data is collected from the user's own network environment.

This project is open-sourced under the MIT License. We assume no responsibility for any consequences resulting from the use of this software. Please use it in compliance with applicable laws and regulations.

About the Name

Neko (ねこ) means cat in Japanese. Pronounced /ˈneɪkoʊ/ (NEH-ko).

Like a cat, Neko Master observes network traffic quietly and precisely. It is a lightweight analytics dashboard designed for modern gateway environments.

📋 Table of Contents

• ✨ Features
• 🚀 Quick Start
• 🤖 Agent Deployment
• 📖 First Use
• 🔧 Port Conflict Resolution
• 🐳 Docker Configuration
• 🗄️ ClickHouse (Optional)
• 🌐 Reverse Proxy & Tunnel
• 🔐 Authentication & Security
• ❓ FAQ
• 🏗️ Architecture Guide
• 🤝 Feedback & Issues
• 📁 Project Structure
• 🛠️ Tech Stack
• 📄 License

✨ Features

| Feature | Description | | --------------------------- | ------------------------------------------------------------- | | 📊 Real-time Monitoring | WebSocket real-time collection with millisecond latency | | 📈 Trend Analysis | Multi-dimensional traffic trends: 30min / 1h / 24h | | 🌐 Domain Analysis | View traffic, associated IPs, and connection count per domain | | 🗺️ IP Analysis | ASN, geo-location, and associated domain display | | 🚀 Proxy Statistics | Traffic distribution and connection count per proxy node | | 📱 PWA Support | Install as desktop app for native experience | | 🌙 Dark Mode | Light / Dark / System theme support | | 🌍 i18n Support | English / Chinese seamless switching | | 🔄 Multi-Backend | Monitor multiple OpenClash backend instances simultaneously |

🚀 Quick Start

Option 1: Docker Compose (Recommended)

The repository's built-in docker-compose.yml maps 3000/3001/3002 by default.

Scenarios A/B below are minimal templates for common deployments.

Scenario A: Minimal deployment (only expose 3000)

services:
  neko-master:
    image: foru17/neko-master:latest
    container_name: neko-master
    restart: unless-stopped
    ports:
      - "3000:3000" # Web UI
    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
      - COOKIESECRET=${COOKIESECRET}

Recommended in .env (same directory as docker-compose.yml):

COOKIE_SECRET=<at least 32-byte random string> (generate with openssl rand -hex 32)

This mode is fully upgrade-compatible and works out of the box.

If WS is not routed, the app falls back to HTTP polling automatically.

Scenario B: Real-time WebSocket (recommended with reverse proxy)

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
      - COOKIESECRET=${COOKIESECRET}

Then run:

docker compose up -d

Open to get started.

If you use the repository's built-in Compose file (default 3000/3001/3002), run the same command.

Option 2: Docker Run

# Generate a fixed cookie secret first (for session persistence)
export COOKIE_SECRET="$(openssl rand -hex 32)"

# Minimal (only 3000)
docker run -d \
  --name neko-master \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  -e COOKIESECRET="$COOKIESECRET" \
  --restart unless-stopped \
  foru17/neko-master:latest
Real-time WS (with reverse proxy)
docker run -d \
  --name neko-master \
  -p 3000:3000 \
  -p 3002:3002 \
  -v $(pwd)/data:/app/data \
  -e COOKIESECRET="$COOKIESECRET" \
  --restart unless-stopped \
  foru17/neko-master:latest

Open to get started.

The frontend uses same-origin /api by default, so port 3001 is usually not required externally.

For real-time WS, your reverse proxy/tunnel must be able to reach port 3002. If not, the app falls back to ~5s HTTP polling.

For docker run, change external ports using -p mappings directly.

Only if you use direct WS access (no reverse proxy) and external WS port is not 3002, also pass -e WSEXTERNALPORT=<external-ws-port>.

Local MMDB lookup mode (optional): mount -v $(pwd)/geoip:/app/data/geoip:ro,

then switch source to Local in Settings -> Preferences -> IP Lookup Source.

Option 3: One-Click Script

Automatically detects port conflicts and configures everything:

# 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

The script will automatically:

• ✅ Download docker-compose.yml
• ✅ Check if default ports (3000/3001/3002) are in use
• ✅ Suggest available alternative ports
• ✅ Create configuration file and start the service

Option 4: Source Code

# 1. Clone the repository
git clone https://github.com/foru17/neko-master.git
cd neko-master
2. Install dependencies
pnpm install
3. Prepare collector env (source mode reads apps/collector/.env)
cp apps/collector/.env.example apps/collector/.env
4. Start development services
pnpm dev

Open to configure.

In source mode: collector listens on 3001/3002, web listens on 3000 by default.

If you changed APIPORT (not 3001), set APIURL accordingly (for example API_URL=http://localhost:4001) so web /api rewrite targets the correct API.

apps/collector/.env.local takes precedence over apps/collector/.env.

🤖 Agent Deployment

Use Agent mode when you want one centralized Neko Master service and multiple remote devices (OpenWrt, Linux, macOS) collecting local gateway data. The agent runs near the gateway, pulls data, and reports to the panel — the panel never connects to the gateway directly.

Supported gateway types: Clash / Mihomo (WebSocket real-time) and Surge v5+ (HTTP polling).

Quick Install (UI-generated command)

• In the dashboard, go to Settings → Backends, add an Agent backend, select gateway type
• Click "View Agent Script" and copy the one-line install command, then run it on the target host:

# 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' \
        NEKOBACKENDID='1' \
        NEKOBACKENDTOKEN='ag_xxx' \
        NEKOGATEWAYTYPE='clash' \
        NEKOGATEWAYURL='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' \
        NEKOBACKENDID='2' \
        NEKOBACKENDTOKEN='ag_yyy' \
        NEKOGATEWAYTYPE='surge' \
        NEKOGATEWAYURL='http://127.0.0.1:9091' \
        sh

After install, manage instances with nekoagent:

nekoagent list               # list all instances
nekoagent status <instance>  # check running state
nekoagent logs <instance>    # tail live logs
nekoagent restart <instance> # restart
nekoagent upgrade            # global upgrade (CLI + binary)

The script auto-detects an existing installation — if neko-agent is already present, it only adds the new instance without re-downloading.

Multiple instances can run on the same host (different NEKOINSTANCENAME), each pointing to a different gateway.

Agent Documentation

• Overview: architecture, Direct vs Agent comparison, security model
• Quick Start: end-to-end setup from UI to running agent
• Install Guide: install methods, systemd / launchd autostart
• Configuration: full flag and env variable reference
• Release Flow: versioning and compatibility policy
• Troubleshooting: common errors and fixes

📖 First Use

Connect Clash / Mihomo

• Open
• The Gateway Configuration dialog will appear on first visit
• Fill in your network gateway (e.g., OpenClash) connection info:

• Click "Add Backend" to save
• The system will automatically start collecting and analyzing traffic data

💡 Get Gateway Address: Go to your gateway control panel (e.g., OpenClash) → Enable "External Control" → Copy API address

Connect Surge

Neko Master supports connecting to Surge gateways for complete rule chain visualization and traffic analysis.

1. Enable Surge HTTP API

Enable HTTP remote API in your Surge configuration:

[General]
http-api = 127.0.0.1:9091
http-api-tls = false
http-api-web-dashboard = true

Or configure via Surge's graphical interface:

• HTTP Remote API: Settings → General → HTTP Remote API
• Port: Default 9091
• Authentication: Recommended to set a password for enhanced security

2. Add Surge Backend in Neko Master

• Open Neko Master settings dialog
• Click "Add Backend"
• Fill in the connection info:

• Click "Test Connection" to verify the configuration
• Save the configuration

💡 Note: Surge uses HTTP polling to fetch data (compared to Clash's WebSocket real-time stream), with a data refresh delay of approximately 2 seconds.

🔧 Port Conflict Resolution

If you see "port already in use" error, here are the solutions:

Solution 1: Use .env File

Create a .env file in the same directory as docker-compose.yml:

WEBEXTERNALPORT=8080    # Change Web UI port
APIEXTERNALPORT=8081    # Change API port
WSEXTERNALPORT=8082     # Change WebSocket external port (only for direct access)
COOKIE_SECRET=your-long-random-secret   # Strongly recommended to keep fixed

Then restart:

docker compose down
docker compose up -d

Now access

Solution 2: Directly Modify docker-compose.yml

ports:
  - "8080:3000" # External 8080 → Internal 3000
  - "8082:3002" # External 8082 → Internal 3002 (for proxy/tunnel WS forwarding)

Note: if you use direct WS access (no reverse proxy) and external WS port is not 3002, set WSEXTERNALPORT=<external-ws-port>.

Solution 3: Use One-Click Script

curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

The script will automatically detect and suggest available ports.

🐳 Docker Configuration

Ports

| Port | Purpose | External Required | Description | | :--: | :-------: | :---------------: | :---------------------------------------------------------------------------------------------------------- | | 3000 | Web UI | ✅ | Frontend entry point | | 3001 | API | Optional | Frontend uses same-origin /api by default; usually no public exposure needed (default Compose maps it) | | 3002 | WebSocket | Optional | Real-time push endpoint; recommended for reverse proxy/tunnel forwarding only (default Compose maps it) |

Environment Variables (Deployment)

| Variable | Default | Purpose | When to set | | :-- | :-- | :-- | :-- | | WEB_PORT | 3000 | Web listen port (inside container) | Usually unchanged | | API_PORT | 3001 | API listen port (inside container) | Usually unchanged | | COLLECTORWSPORT | 3002 | WS listen port (inside container) | Usually unchanged | | DB_PATH | /app/data/stats.db | SQLite data path | Custom data path | | WEBEXTERNALPORT | 3000 | External web port mapping in docker-compose.yml | External web port changed | | APIEXTERNALPORT | 3001 | External API port mapping in docker-compose.yml | Direct external API access needed | | WSEXTERNALPORT | 3002 | External WS port mapping in docker-compose.yml; also used for direct WS port inference | Direct WS access without proxy and external WS port changed | | NEXTPUBLICAPI_URL | empty | Override frontend API base URL (e.g. https://api.example.com) | API is not same-origin /api | | NEXTPUBLICWSURL | empty | Override frontend WS URL (absolute URL or /customws) | Custom WS path/domain | | NEXTPUBLICWSPORT | 3002 | WS direct-connection fallback port (build-time only — setting this at Docker runtime has no effect; use WSEXTERNAL_PORT instead) | Only for custom source builds | | API_URL | http://localhost:3001 | Next.js /api rewrite target (mainly source/custom builds) | API listen address changed | | COOKIE_SECRET | auto-generated | Cookie signing secret; if not fixed, sessions can be invalidated after restart when data dir is not persisted | Strongly recommended in production | | GEOIPLOOKUPPROVIDER | online | IP geolocation source (online / local) | Default to local MMDB lookup | | GEOIPONLINEAPI_URL | https://api.ipinfo.es/ipinfo | Online IP geolocation API endpoint (must be compatible with ipinfo.my response schema) | Set only when you deploy a compatible endpoint | | FORCEACCESSCONTROL_OFF | false | Force disable access control (emergency recovery) | Temporary use only when token is lost | | SHOWCASESITEMODE | false | Read-only showcase mode (blocks sensitive write operations) | Public demo sites only |

Advanced Tuning Variables (Optional)

| Variable | Default | Description | | :-- | :-- | :-- | | FLUSHINTERVALMS | 30000 | Buffer flush interval for collector writes | | FLUSHMAXBUFFER_SIZE | 5000 | Max buffer entries before early flush | | REALTIMEMAXMINUTES | 180 | Realtime in-memory window size (minutes) | | REALTIMERANGEENDTOLERANCEMS | 120000 | End-time tolerance for range queries | | SURGEPOLICYSYNCINTERVALMS | 600000 | Surge policy sync interval | | DBRANGEQUERYCACHETTL_MS | 8000 | Range-query cache TTL | | DBHISTORICALQUERYCACHETTL_MS | 300000 | Historical-query cache TTL | | DBRANGEQUERYCACHEMAX_ENTRIES | 1024 | Max range-query cache entries | | DBRANGEQUERYCACHEDISABLED | empty | Set 1 to disable range-query cache | | DEBUG_SURGE | false | Enable Surge collector debug logs (true) |

API / WS Resolution Priority

• API client base: runtime-config.APIURL → NEXTPUBLICAPIURL → same-origin /api
• /api server-side rewrite target: API_URL (default http://localhost:3001, applied in Next.js rewrites)
• WS URL: runtime-config.WSURL → NEXTPUBLICWSURL → auto candidates (when runtime-config.WSPORT is set, direct port is preferred; otherwise /cm_ws is tried first)
• WS port: runtime-config.WSPORT (from WSEXTERNALPORT) → NEXTPUBLICWSPORT → 3002
• In normal deployments, NEXTPUBLICWS_URL is usually unnecessary unless you use a custom WS path/domain

Production Environment Baseline (Recommended)

NODE_ENV=production
DB_PATH=/app/data/stats.db
COOKIE_SECRET=<at least 32-byte random string>
Optional: default to local MMDB lookup
GEOIPLOOKUPPROVIDER=local
Keep false in normal operation
FORCEACCESSCONTROL_OFF=false

Use openssl rand -hex 32 to generate COOKIE_SECRET.

Additional recommendations:

• Mount persistent storage (for example ./data:/app/data) to avoid data and secret loss.
• If using direct WS access and external WS port is not 3002, set WSEXTERNALPORT accordingly.
• If API port/address changes in source deployment, update API_URL as well.
• For local MMDB lookup, mount ./geoip:/app/data/geoip:ro and switch source in Settings -> Preferences -> IP Lookup Source.
• MMDB files are large and are not bundled in the image. Download and place them in ./geoip with fixed names:

BatchBuffer.flush()
    │
    ├──→ SQLite (config / metadata, always written)
    └──→ ClickHouse (stats traffic data, dual-write)
           └── Buffer tables → SummingMergeTree async merge

docker compose --profile clickhouse up -d

services:
  neko-master:
    # ... your existing config ...
    environment:
      # append to existing environment section:
      - CHENABLED=${CHENABLED:-0}
      - CHHOST=${CHHOST:-clickhouse}
      - CHPORT=${CHPORT:-8123}
      - CHDATABASE=${CHDATABASE:-neko_master}
      - CHUSER=${CHUSER:-neko}
      - CHPASSWORD=${CHPASSWORD:-neko_master}
      - CHWRITEENABLED=${CHWRITEENABLED:-0}
      - STATSQUERYSOURCE=${STATSQUERYSOURCE:-sqlite}
    networks:
      - neko-master-network
clickhouse:     image: clickhouse/clickhouse-server:24.8     container_name: neko-master-clickhouse     restart: unless-stopped     profiles: ["clickhouse"]     ports:       - "${CHEXTERNALHTTP_PORT:-8123}:8123"       - "${CHEXTERNALNATIVE_PORT:-9000}:9000"     volumes:       - ./data/clickhouse:/var/lib/clickhouse     environment:       - CLICKHOUSEDB=${CHDATABASE:-neko_master}       - CLICKHOUSEUSER=${CHUSER:-neko}       - CLICKHOUSEPASSWORD=${CHPASSWORD:-neko_master}       - CLICKHOUSEDEFAULTACCESS_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

# Enable ClickHouse connection
CH_ENABLED=1
Enable dual-write
CHWRITEENABLED=1
Read source: sqlite (default) / auto (smart routing) / clickhouse (force)
STATSQUERYSOURCE=auto
ClickHouse connection (defaults match docker-compose.yml, no change needed)
CH_HOST=clickhouse
CH_PORT=8123
CHDATABASE=nekomaster
CH_USER=neko
CHPASSWORD=nekomaster

docker compose --profile clickhouse up -d

CH_ENABLED=1
CHWRITEENABLED=1
STATSQUERYSOURCE=sqlite   # Keep reading from SQLite while CH accumulates data

STATSQUERYSOURCE=auto        # Smart routing: recent data from CH, historical from SQLite
or
STATSQUERYSOURCE=clickhouse  # Force all reads to ClickHouse

# Standard migration (truncate CH then re-import, with consistency check)
./scripts/ch-migrate-docker.sh
Append mode (keep existing CH data, incremental import)
./scripts/ch-migrate-docker.sh --append
Specific time window
./scripts/ch-migrate-docker.sh --from 2026-02-01T00:00:00Z --to 2026-02-20T00:00:00Z

CHONLYMODE=1

CH_ENABLED=0
CHWRITEENABLED=0
CHONLYMODE=0
STATSQUERYSOURCE=sqlite

server {
  listen 443 ssl http2;
  server_name neko.example.com;
location / {     proxy_pass http://<neko-master-host>:3000;     proxyhttpversion 1.1;     proxysetheader Host $host;     proxysetheader X-Real-IP $remote_addr;     proxysetheader X-Forwarded-For $proxyaddxforwardedfor;     proxysetheader X-Forwarded-Proto $scheme;   }
location ^~ /cmws {     proxy_pass http://<neko-master-host>:3002;     proxyhttpversion 1.1;     proxysetheader Upgrade $http_upgrade;     proxysetheader Connection "upgrade";     proxysetheader Host $host;     proxysetheader X-Forwarded-For $proxyaddxforwardedfor;     proxysetheader X-Forwarded-Proto $scheme;     proxyreadtimeout 86400;     proxysendtimeout 86400;     proxy_buffering off;   } }

# Not required by default (already /cmws)
NEXTPUBLICWSURL=/customws

tunnel: <your-tunnel-name-or-id>
credentials-file: /path/to/<credentials>.json
ingress:   - hostname: neko.example.com     path: /cmws*     service: http://localhost:3002   - hostname: neko.example.com     path: /*     service: http://localhost:3000   - service: http_status:404

cloudflared tunnel --config ~/.cloudflared/config.yml run <your-tunnel-name-or-id>

volumes:
  - ./data:/app/data

# Pull the latest image and restart
docker compose pull
docker compose up -d

COOKIE_SECRET=<at least 32-byte random string>
FORCEACCESSCONTROL_OFF=false
SHOWCASESITEMODE=false

environment:
     - FORCEACCESSCONTROL_OFF=true

docker compose up -d

docker stop neko-master
   docker rm neko-master

docker run -d \
     --name neko-master \
     -p 3000:3000 \
     -v $(pwd)/data:/app/data \
     -e FORCEACCESSCONTROL_OFF=true \
     foru17/neko-master:latest

WEBEXTERNALPORT=8080
APIEXTERNALPORT=8081
WSEXTERNALPORT=8082

docker compose down
docker compose up -d

cp -r ./data ./data-backup-$(date +%Y%m%d)

docker compose down
cp -r ./data-backup-YYYYMMDD/. ./data/
docker compose up -d

neko-master/
├── docker-compose.yml      # Docker Compose config
├── Dockerfile              # Docker image build
├── setup.sh                # One-click setup script
├── docker-start.sh         # Docker container startup script
├── start.sh                # Source code dev startup script
├── docs/                   # Documentation (see docs/README.md)
│   ├── README.md           # Documentation index (English default)
│   ├── README.zh.md        # Documentation index (Chinese)
│   ├── README.en.md        # Documentation index (English mirror)
│   ├── architecture.md     # System architecture (Chinese)
│   ├── architecture.en.md  # System architecture (English)
│   ├── release-checklist.md
│   ├── agent/              # Agent docs (bilingual)
│   │   ├── overview.md / overview.en.md
│   │   ├── quick-start.md / quick-start.en.md
│   │   ├── install.md / install.en.md
│   │   ├── config.md / config.en.md
│   │   ├── release.md / release.en.md
│   │   └── troubleshooting.md / troubleshooting.en.md
│   ├── research/           # Research reports
│   └── dev/                # Internal development docs
├── assets/                 # Screenshots and icons
├── apps/
│   ├── collector/          # Data collection service (Node.js + WebSocket)
│   ├── agent/              # Agent daemon (Go)
│   └── web/                # Next.js frontend app
└── packages/
    └── shared/             # Shared types and utilities