foru17/neko-masterPublic

Neko Master

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

English | 中文

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.

• ✨ 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

The repository's built-in docker-compose.yml maps 3000/3001/3002 by default. Scenarios A/B below are minimal templates for common deployments.

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}

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.

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.

# 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.

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 WS_EXTERNAL_PORT=<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.

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

# 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.

In source mode: collector listens on 3001/3002, web listens on 3000 by default. If you changed API_PORT (not 3001), set API_URL 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.

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

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)

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 NEKO_INSTANCE_NAME), each pointing to a different gateway.

• 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

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

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

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

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

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

💡 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.

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

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

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 WS_EXTERNAL_PORT=<external-ws-port>.

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

The script will automatically detect and suggest available ports.

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

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.

Advanced Agent details (install, config, release, compatibility) are maintained under docs/agent/*.

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

ClickHouse is entirely optional. SQLite remains as the configuration and metadata store regardless of whether ClickHouse is enabled.

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

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

ClickHouse data is persisted to ./data/clickhouse, separate from the main app data directory.

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

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

Health & Fallback: After CH_UNHEALTHY_THRESHOLD consecutive write failures, the system automatically marks ClickHouse as unhealthy and resumes SQLite writes—even when CH_ONLY_MODE=1. Once ClickHouse recovers, it is re-marked healthy and logged.

Upgrading from a SQLite-only version? Your data is safe. The SQLite file (./data/stats.db) is fully preserved. Here is the recommended gradual migration path:

CH_ENABLED=1
CH_WRITE_ENABLED=1
STATS_QUERY_SOURCE=sqlite   # Keep reading from SQLite while CH accumulates data

Start and watch [ClickHouse Writer] logs to confirm successful writes.

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

To move historical SQLite stats into 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

Once ClickHouse is running stably, stop SQLite stats writes:

CH_ONLY_MODE=1

Even with CH_ONLY_MODE=1, if ClickHouse becomes unhealthy the system automatically falls back to SQLite writes—no data loss.

You can always roll back completely:

CH_ENABLED=0
CH_WRITE_ENABLED=0
CH_ONLY_MODE=0
STATS_QUERY_SOURCE=sqlite

Restart and everything returns to pure SQLite mode. Historical data remains intact.

Recommended approach: keep Web and WS under the same domain, with path routing: / → 3000, /_cm_ws → 3002.

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;
  }
}

Optional env override:

# Not required by default (already /_cm_ws)
# NEXT_PUBLIC_WS_URL=/custom_ws

~/.cloudflared/config.yml:

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

Run:

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

For Zero Trust dashboard-managed routes (token mode), configure the same two routes and keep /_cm_ws* above /*.

1. Do not use ws (without leading slash) as WS path; it can overmatch and cause /_next/static/... → 426 Upgrade Required
2. WS route must be above catch-all /*
3. NEXT_PUBLIC_WS_URL is optional by default; if customized, restart frontend/container after changes
4. Mapping only 3000 still works, but falls back to HTTP polling (~5s), with less real-time responsiveness
5. beacon.min.js failures (Cloudflare analytics script) are typically unrelated to app API/WS data flow
6. No extra /api reverse-proxy rule is required in most setups; frontend uses same-origin /api and app handles internal forwarding to 3001

Note: /_next/static/... 426 Upgrade Required is common in misconfigured reverse proxy / tunnel setups; it is uncommon in direct local access without a proxy.

Docker images support both linux/amd64 and linux/arm64.

Data is stored in /app/data inside the container. Mount it to host to prevent data loss:

volumes:
  - ./data:/app/data

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

Neko Master supports access authentication to protect dashboard data.

1. Set a fixed COOKIE_SECRET (otherwise sessions may be invalidated after restart).
2. Do not keep FORCE_ACCESS_CONTROL_OFF=true enabled in normal operation.
3. Use SHOWCASE_SITE_MODE=true only for public demo environments (write operations are restricted).

Example:

COOKIE_SECRET=<at least 32-byte random string>
# FORCE_ACCESS_CONTROL_OFF=false
# SHOWCASE_SITE_MODE=false

1. Open dashboard and click "Settings" in the lower-left sidebar.
2. Go to the "Security" tab.
3. Enable/disable access control and set your token.

If you forgot the token, temporarily set FORCE_ACCESS_CONTROL_OFF=true to enter emergency mode.

1. Add to docker-compose.yml:

   environment:
     - FORCE_ACCESS_CONTROL_OFF=true

2. Restart:

   docker compose up -d

3. Open dashboard and reset token in "Settings -> Security".

4. Remove this env var immediately after reset, then restart again.

1. Stop and remove container:

   docker stop neko-master
   docker rm neko-master

2. Re-run with emergency flag:

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

3. Reset token, then remove this flag and restart normally.

A: Yes. Core features still work. If WS is not routed, the app automatically falls back to HTTP polling. For full realtime experience, route /_cm_ws to 3002.

A: Create/update .env (same directory as docker-compose.yml):

WEB_EXTERNAL_PORT=8080
API_EXTERNAL_PORT=8081
WS_EXTERNAL_PORT=8082

Then restart:

docker compose down
docker compose up -d

A: Usually because COOKIE_SECRET is not fixed or data directory is not persisted.

1. Set a fixed COOKIE_SECRET
2. Mount ./data:/app/data

A: Create ./geoip in your project directory (same level as docker-compose.yml is recommended), then place:

1. GeoLite2-City.mmdb (required)
2. GeoLite2-ASN.mmdb (required)
3. GeoLite2-Country.mmdb (optional)

Recommended source: https://github.com/P3TERX/GeoLite.mmdb. Inside the container, the fixed lookup path is /app/data/geoip, so keep: ./geoip:/app/data/geoip:ro. To update later, just replace files in host ./geoip.

A: Check:

1. External control is enabled on gateway side
2. Host/port is correct
3. Token/Secret is correct (if configured)
4. Container network can reach gateway

A: Backup first:

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

Restore:

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

If you want to quickly understand the system design depth, read in this order:

1. System Architecture Diagram: end-to-end layering and module responsibilities → docs/architecture.en.md
2. Data Flow: Clash / Surge collection pipelines and aggregation
3. Data Model & Storage: SQLite schema, ClickHouse Buffer tables, retention policy
4. Realtime Channel Design: RealtimeStore merge strategy and WS push
5. ClickHouse Module: dual-write architecture, health fallback, read routing

Full documentation index: docs/README.md

This documentation covers the core design of collection, aggregation, caching, realtime push, and multi-backend management.

This project uses GitHub Issue Templates (Bug / Feature / Support).

Please include at least:

1. Deployment method (Compose / Docker Run / Source)
2. Version info (image tag or commit)
3. Key env vars (masked, e.g. COOKIE_SECRET=***)
4. Reproduction steps and expected vs actual behavior
5. Key logs (docker logs, browser console, network errors)

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

• Frontend: Next.js 16 + React 19 + TypeScript
• Styling: Tailwind CSS + shadcn/ui
• Charts: Recharts
• i18n: next-intl
• Backend: Node.js + Fastify + WebSocket
• Database: SQLite (better-sqlite3) + ClickHouse (optional)
• Build: pnpm + Turborepo

Contributions are welcome!

• 🐛 Submit Bug
• 💡 Request Feature
• 🔧 Contribute Code

Before opening a PR, read CONTRIBUTING.md (workflow, checks, i18n/dark-mode requirements).

Developing with an AI coding tool? (Claude Code, Copilot, Cursor, Codex, ...) Point it at AGENTS.md — conventions, key contracts, and the project map — plus the task-specific workflow guides in .claude/skills/. Claude Code picks both up automatically.

MIT © foru17

_{Made with ❤️ by @foru17
If this project helps you, please consider giving it a ⭐}