foru17/neko-master repository overview

Neko Master

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

English | 中文⁠

⁠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

⁠🚀 Quick Start

⁠Option 1: Docker Compose (Recommended)

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

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

Then run:

docker compose up -d

Open http://localhost:3000⁠ 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 COOKIE_SECRET="$COOKIE_SECRET" \
  --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 COOKIE_SECRET="$COOKIE_SECRET" \
  --restart unless-stopped \
  foru17/neko-master:latest

Open http://localhost:3000⁠ to get started.

⁠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 http://localhost:3000⁠ to configure.

⁠🤖 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)

1. In the dashboard, go to Settings → Backends, add an Agent backend, select gateway type
2. 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' \
        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

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)

⁠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

1. Open http://localhost:3000⁠
2. The Gateway Configuration dialog will appear on first visit
3. Fill in your network gateway (e.g., OpenClash) connection info:
   • Name: Custom name (e.g., "Home Gateway")
   • Type: Select Clash / Mihomo
   • Host: Gateway backend address (e.g., 192.168.101.1)
   • Port: Gateway backend port (e.g., 9090)
   • Token: Fill if Secret is configured, otherwise leave empty
4. Click "Add Backend" to save
5. The system will automatically start collecting and analyzing traffic data

⁠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

1. Open Neko Master settings dialog
2. Click "Add Backend"
3. Fill in the connection info:
   • Name: Custom name (e.g., "Surge Home")
   • Type: Select Surge
   • Host: IP address where Surge is running (e.g., 192.168.1.1 or 127.0.0.1)
   • Port: HTTP API port (default 9091)
   • Token: HTTP API password (if configured)
4. Click "Test Connection" to verify the configuration
5. Save the configuration

⁠🔧 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:

WEB_EXTERNAL_PORT=8080    # Change Web UI port
API_EXTERNAL_PORT=8081    # Change API port
WS_EXTERNAL_PORT=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 http://localhost:8080⁠

⁠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)

⁠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

⁠Environment Variables (Deployment)

⁠Advanced Tuning Variables (Optional)

⁠API / WS Resolution Priority

1. API client base: runtime-config.API_URL → NEXT_PUBLIC_API_URL → same-origin /api
2. /api server-side rewrite target: API_URL (default http://localhost:3001, applied in Next.js rewrites)
3. WS URL: runtime-config.WS_URL → NEXT_PUBLIC_WS_URL → auto candidates (when runtime-config.WS_PORT is set, direct port is preferred; otherwise /_cm_ws is tried first)
4. WS port: runtime-config.WS_PORT (from WS_EXTERNAL_PORT) → NEXT_PUBLIC_WS_PORT → 3002
5. In normal deployments, NEXT_PUBLIC_WS_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
# GEOIP_LOOKUP_PROVIDER=local
# Keep false in normal operation
# FORCE_ACCESS_CONTROL_OFF=false

Use openssl rand -hex 32 to generate COOKIE_SECRET.

Additional recommendations:

1. Mount persistent storage (for example ./data:/app/data) to avoid data and secret loss.
2. If using direct WS access and external WS port is not 3002, set WS_EXTERNAL_PORT accordingly.
3. If API port/address changes in source deployment, update API_URL as well.
4. For local MMDB lookup, mount ./geoip:/app/data/geoip:ro and switch source in Settings -> Preferences -> IP Lookup Source.
5. MMDB files are large and are not bundled in the image. Download and place them in ./geoip with fixed names: GeoLite2-City.mmdb, GeoLite2-ASN.mmdb (required), and GeoLite2-Country.mmdb (optional). Recommended source: https://github.com/P3TERX/GeoLite.mmdb⁠.

⁠🗄️ ClickHouse (Optional)

SQLite is Neko Master's default storage engine and works well for most users. Consider enabling ClickHouse if you need:

• Very large datasets (hundreds of thousands of domain/IP entries)
• Fast aggregation queries over long time ranges (≥ 7 days)
• Separation of historical stats from configuration/metadata storage

⁠Architecture Overview

When ClickHouse is enabled, the system enters dual-write mode:

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

Read source is controlled by STATS_QUERY_SOURCE (default: sqlite).

⁠Enabling ClickHouse (Docker)

⁠Step 1: Start the ClickHouse container

The repository's built-in docker-compose.yml already includes a ClickHouse service, gated by profiles: [clickhouse] so it does not start by default. From the repository root, run:

docker compose --profile clickhouse up -d

If you use a custom docker-compose.yml (such as Scenario A/B above), add the ClickHouse service block manually:

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

⁠Step 2: Configure environment variables

Add to your .env (same directory as docker-compose.yml):

# Enable ClickHouse connection
CH_ENABLED=1

# Enable dual-write
CH_WRITE_ENABLED=1

# Read source: sqlite (default) / auto (smart routing) / clickhouse (force)
STATS_QUERY_SOURCE=auto

# ClickHouse connection (defaults match docker-compose.yml, no change needed)
CH_HOST=clickhouse
CH_PORT=8123
CH_DATABASE=neko_master
CH_USER=neko
CH_PASSWORD=neko_master

Restart:

docker compose --profile clickhouse up -d

⁠ClickHouse Environment Variables