Neko Master 详细部署教程

项目概述

Neko Master 是一个现代化、优雅的网络流量可视化与分析仪表盘。它专注于本地网关环境的流量监控、审计和多网关支持，提供实时监控、趋势分析、域名分析、IP 分析和代理统计等功能。

重要声明：本项目是一个本地网关环境的流量分析与可视化工具，不提供任何网络访问服务、代理订阅或跨网络连接功能。所有数据均从用户自己的网络环境中采集。

核心特性：

  • 实时监控（WebSocket 毫秒级延迟）
  • 多维度趋势分析（30分钟 / 1小时 / 24小时）
  • 域名分析与 IP 分析（ASN、地理位置）
  • 代理节点流量统计
  • PWA 支持，可安装为桌面应用
  • 深色模式与中英文双语支持
  • 多后端支持，可同时监控多个 OpenClash 实例

技术栈：Next.js 16 + React 19 + TypeScript + Tailwind CSS + Node.js (Fastify) + SQLite + ClickHouse（可选）

部署前准备

系统要求

项目 要求
操作系统 Windows / macOS / Linux
Docker 20.10+（推荐部署方式）
Docker Compose v2.0+
内存 最低 512MB，推荐 1GB+
磁盘空间 最低 1GB（不含 ClickHouse 数据）
网络 需能访问你的网关设备（如 OpenClash）

支持的网关类型

  • Clash / Mihomo：通过 WebSocket 实时采集
  • Surge v5+：通过 HTTP 轮询采集

准备工作

  1. 确保 Docker 和 Docker Compose 已安装：

    1
    2
    docker --version
    docker compose version

  2. 确保你的网关设备已启用外部控制接口（如 OpenClash 的”外部控制”功能），并记录下 API 地址、端口和 Token（如有配置）。

方案一：Docker Compose 部署（推荐）

这是最简单、最稳定的部署方式。

场景 A：最小化部署（仅暴露 3000 端口）

适合大多数用户，无需反向代理即可使用全部核心功能。

步骤 1：创建项目目录

1
2
mkdir neko-master
cd neko-master

步骤 2：创建 docker-compose.yml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
services:
  neko-master:
    image: foru17/neko-master:latest
    container_name: neko-master
    restart: unless-stopped
    ports:
      - "3000:3000"  # Web UI
    volumes:
      - ./data:/app/data
      # 本地 MMDB（可选，需将文件下载到 ./geoip 目录）
      - ./geoip:/app/data/geoip:ro
    environment:
      - NODE_ENV=production
      - DB_PATH=/app/data/stats.db
      - COOKIE_SECRET=${COOKIE_SECRET}

步骤 3：创建 .env 文件

1
2
3
# 生成至少 32 字节的随机字符串
COOKIE_SECRET=$(openssl rand -hex 32)
echo "COOKIE_SECRET=$COOKIE_SECRET" > .env

步骤 4：启动服务

1
docker compose up -d

步骤 5：访问仪表盘

打开浏览器访问 http://localhost:3000。

此模式下，如果 WS 未路由，应用会自动回退到 HTTP 轮询模式（约 5 秒延迟）。

场景 B：实时 WebSocket 部署（推荐配合反向代理）

适合需要毫秒级实时推送的场景。

步骤 1：创建 docker-compose.yml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
services:
  neko-master:
    image: foru17/neko-master:latest
    container_name: neko-master
    restart: unless-stopped
    ports:
      - "3000:3000"  # Web UI
      - "3002:3002"  # WebSocket（用于 Nginx / Tunnel 转发）
    volumes:
      - ./data:/app/data
      - ./geoip:/app/data/geoip:ro
    environment:
      - NODE_ENV=production
      - DB_PATH=/app/data/stats.db
      - COOKIE_SECRET=${COOKIE_SECRET}

步骤 2：创建 .env 文件

1
2
COOKIE_SECRET=$(openssl rand -hex 32)
echo "COOKIE_SECRET=$COOKIE_SECRET" > .env

步骤 3：启动服务

1
docker compose up -d

步骤 4：访问

打开 http://localhost:3000。

方案二：Docker Run 部署

如果你不习惯使用 Compose，可以直接用 Docker 命令部署。

最小化部署（仅 3000）

1
2
3
4
5
6
7
8
9
10
# 生成固定的 cookie secret（用于会话持久化）
export COOKIE_SECRET="$(openssl rand -hex 32)"

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

实时 WebSocket 部署

1
2
3
4
5
6
7
8
9
10
export COOKIE_SECRET="$(openssl rand -hex 32)"

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

本地 MMDB 查询（可选）

1
2
3
4
5
6
7
8
docker run -d \
  --name neko-master \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/geoip:/app/data/geoip:ro \
  -e COOKIE_SECRET="$COOKIE_SECRET" \
  --restart unless-stopped \
  foru17/neko-master:latest

然后进入 Settings -> Preferences -> IP Lookup Source 切换为本地查询。

方案三：一键脚本部署

官方提供了一键部署脚本，会自动检测端口冲突并配置一切。

1
2
3
4
5
# 使用 curl
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

# 或使用 wget
wget -qO- https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh | bash

脚本会自动完成以下操作：

  • ✅ 下载 docker-compose.yml
  • ✅ 检查默认端口（3000/3001/3002）是否被占用
  • ✅ 建议可用的替代端口
  • ✅ 创建配置文件并启动服务

方案四：源码部署

适合需要修改源码或参与开发的用户。

步骤 1：克隆仓库

1
2
git clone https://github.com/foru17/neko-master.git
cd neko-master

步骤 2：安装依赖

1
pnpm install

如未安装 pnpm，先安装：

1
npm install -g pnpm

步骤 3：准备采集器环境变量

1
cp apps/collector/.env.example apps/collector/.env

步骤 4：启动开发服务

1
pnpm dev

步骤 5：访问

打开 http://localhost:3000 进行配置。

源码模式下：collector 默认监听 3001/3002，web 监听 3000。如果修改了 API_PORT，需要相应设置 API_URL。

首次使用配置

连接 Clash / Mihomo 网关

  1. 打开 http://localhost:3000
  2. 首次访问时会弹出网关配置对话框
  3. 填写你的网关连接信息：
    • 名称：自定义名称（如 “Home Gateway”）
    • 类型：选择 Clash / Mihomo
    • 主机：网关后端地址（如 192.168.101.1）
    • 端口：网关后端端口（如 9090）
    • Token：如果配置了 Secret 则填写，否则留空
  4. 点击 Add Backend 保存
  5. 系统会自动开始采集和分析流量数据

💡 获取网关地址：进入网关控制面板（如 OpenClash）→ 启用”外部控制” → 复制 API 地址

连接 Surge 网关

步骤 1：启用 Surge HTTP API

在 Surge 配置中启用 HTTP 远程 API：

1
2
3
4
[General]
http-api = 127.0.0.1:9091
http-api-tls = false
http-api-web-dashboard = true

或通过 Surge 图形界面配置：

  • HTTP Remote API：Settings → General → HTTP Remote API
  • 端口：默认 9091
  • 认证：建议设置密码以增强安全性

步骤 2：在 Neko Master 中添加 Surge 后端

  1. 打开 Neko Master 设置对话框
  2. 点击 Add Backend
  3. 填写连接信息：
    • 名称：自定义名称（如 “Surge Home”）
    • 类型：选择 Surge
    • 主机：Surge 运行的 IP 地址（如 192.168.1.1 或 127.0.0.1）
    • 端口：HTTP API 端口（默认 9091）
    • Token：HTTP API 密码（如已配置）
  4. 点击 Test Connection 验证配置
  5. 保存配置

💡 注意：Surge 使用 HTTP 轮询获取数据（相比 Clash 的 WebSocket 实时流），数据刷新延迟约 2 秒。

Agent 远程部署

当你需要一个中心化的 Neko Master 服务，同时从多个远程设备（OpenWrt、Linux、macOS）采集本地网关数据时，使用 Agent 模式。

工作原理

Agent 运行在网关附近，拉取数据并上报到面板——面板从不直接连接网关。

快速安装（UI 生成命令）

  1. 在仪表盘中进入 Settings → Backends，添加一个 Agent 后端，选择网关类型
  2. 点击 “View Agent Script” 复制一行安装命令，然后在目标主机上运行：

Clash / Mihomo 网关示例：

1
2
3
4
5
6
7
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 网关示例：

1
2
3
4
5
6
7
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

管理 Agent 实例

1
2
3
4
5
nekoagent list               # 列出所有实例
nekoagent status <instance>  # 查看运行状态
nekoagent logs <instance>    # 查看实时日志
nekoagent restart <instance> # 重启
nekoagent upgrade            # 全局升级（CLI + 二进制）

脚本会自动检测现有安装——如果 neko-agent 已存在，只添加新实例而不重新下载。同一主机可运行多个实例（不同 NEKO_INSTANCE_NAME）。

端口配置与冲突解决

端口说明

端口 用途 是否需要外部暴露 说明
3000 Web UI ✅ 必需 前端入口
3001 API 可选 前端默认使用同源 /api，通常无需公开暴露
3002 WebSocket 可选 实时推送端点，建议仅用于反向代理/隧道转发

解决端口冲突

方法 1：使用 .env 文件

在 docker-compose.yml 同目录创建 .env 文件：

1
2
3
4
WEB_EXTERNAL_PORT=8080    # 修改 Web UI 端口
API_EXTERNAL_PORT=8081    # 修改 API 端口
WS_EXTERNAL_PORT=8082     # 修改 WebSocket 外部端口（仅用于直接访问）
COOKIE_SECRET=your-long-random-secret   # 强烈建议保持固定

然后重启：

1
2
docker compose down
docker compose up -d

现在访问 http://localhost:8080。

方法 2：直接修改 docker-compose.yml

1
2
3
ports:
  - "8080:3000"  # 外部 8080 → 内部 3000
  - "8082:3002"  # 外部 8082 → 内部 3002

注意：如果使用直接 WS 访问（无反向代理）且外部 WS 端口不是 3002，需设置 WS_EXTERNAL_PORT=<外部WS端口>。

方法 3：使用一键脚本

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

环境变量参考

部署核心变量

变量 默认值 用途 何时设置
WEB_PORT 3000 Web 监听端口（容器内） 通常不变
API_PORT 3001 API 监听端口（容器内） 通常不变
COLLECTOR_WS_PORT 3002 WS 监听端口（容器内） 通常不变
DB_PATH /app/data/stats.db SQLite 数据路径 自定义数据路径
WEB_EXTERNAL_PORT 3000 外部 Web 端口映射 外部 Web 端口变化
WS_EXTERNAL_PORT 3002 外部 WS 端口映射 直接 WS 访问且端口变化
COOKIE_SECRET 自动生成 Cookie 签名密钥 生产环境强烈建议设置
GEOIP_LOOKUP_PROVIDER online IP 地理定位源（online / local） 默认使用本地 MMDB 查询

生产环境基线配置

1
2
3
4
5
6
7
NODE_ENV=production
DB_PATH=/app/data/stats.db
COOKIE_SECRET=<至少32字节随机字符串>
# 可选：默认使用本地 MMDB 查询
# GEOIP_LOOKUP_PROVIDER=local
# 正常运行时保持 false
# FORCE_ACCESS_CONTROL_OFF=false

使用 openssl rand -hex 32 生成 COOKIE_SECRET。

反向代理与隧道配置

推荐做法：将 Web 和 WS 保持在同一域名下，使用路径路由：/ → 3000，/_cm_ws → 3002。

Nginx 标准示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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;
  }
}

Cloudflare Tunnel 标准示例

~/.cloudflared/config.yml：

1
2
3
4
5
6
7
8
9
10
11
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

运行：

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

关键注意事项

  1. 不要使用 ws（无前导斜杠）作为 WS 路径，可能过度匹配导致 /_next/static/... 出现 426 Upgrade Required
  2. WS 路由必须在捕获所有 /\* 之上
  3. NEXT_PUBLIC_WS_URL 默认可选；如自定义，修改后需重启前端/容器
  4. 只映射 3000 仍可工作，但会回退到 HTTP 轮询（约 5 秒），实时性较差
  5. 大多数设置无需额外的 /api 反向代理规则，前端使用同源 /api，应用内部处理转发到 3001

ClickHouse 可选部署

SQLite 是 Neko Master 的默认存储引擎，适用于大多数用户。如果你需要处理非常大的数据集（数十万域名/IP 条目）或对长时间范围（≥ 7 天）进行快速聚合查询，可以考虑启用 ClickHouse。

步骤 1：启动 ClickHouse 容器

仓库内置的 docker-compose.yml 已包含 ClickHouse 服务，通过 profiles: [clickhouse] 控制，默认不启动：

1
docker compose --profile clickhouse up -d

步骤 2：配置环境变量

添加到 .env：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 启用 ClickHouse 连接
CH_ENABLED=1

# 启用双写
CH_WRITE_ENABLED=1

# 读取源：sqlite（默认）/ auto（智能路由）/ clickhouse（强制）
STATS_QUERY_SOURCE=auto

# ClickHouse 连接（默认值匹配 docker-compose.yml）
CH_HOST=clickhouse
CH_PORT=8123
CH_DATABASE=neko_master
CH_USER=neko
CH_PASSWORD=neko_master

步骤 3：重启服务

1
docker compose --profile clickhouse up -d

迁移路径（从 SQLite 升级）

阶段 1：双写（观察期，推荐起点）

1
2
3
CH_ENABLED=1
CH_WRITE_ENABLED=1
STATS_QUERY_SOURCE=sqlite

阶段 2：切换读取源

1
2
3
STATS_QUERY_SOURCE=auto
# 或
STATS_QUERY_SOURCE=clickhouse

阶段 3（可选）：迁移历史数据

1
./scripts/ch-migrate-docker.sh

阶段 4（可选）：CH-only 模式

1
CH_ONLY_MODE=1

即使设置 CH_ONLY_MODE=1，如果 ClickHouse 变得不健康，系统会自动回退到 SQLite 写入——不会丢失数据。

回退到纯 SQLite

1
2
3
4
CH_ENABLED=0
CH_WRITE_ENABLED=0
CH_ONLY_MODE=0
STATS_QUERY_SOURCE=sqlite

认证与安全

生产安全基线

  1. 设置固定的 COOKIE_SECRET（否则重启后会话可能失效）
  2. 正常运行中不要保持 FORCE_ACCESS_CONTROL_OFF=true
  3. 仅在公开演示环境使用 SHOWCASE_SITE_MODE=true

启用/禁用认证

  1. 打开仪表盘，点击左下角侧边栏的 “Settings”
  2. 进入 “Security” 标签页
  3. 启用/禁用访问控制并设置 Token

忘记 Token（紧急重置）

如果忘记 Token，临时设置 FORCE_ACCESS_CONTROL_OFF=true 进入紧急模式：

Docker Compose：

  1. 在 docker-compose.yml 中添加：

    1
    2
    environment:
      - FORCE_ACCESS_CONTROL_OFF=true

  2. 重启：

    1
    docker compose up -d

  3. 打开仪表盘，在 “Settings -> Security” 中重置 Token

  4. 立即移除此环境变量并重启

常见问题排查

问题 症状 解决方案
仅暴露 3000 能否正常使用 核心功能受限 可以。WS 未路由时自动回退 HTTP 轮询；完整实时体验需将 /_cm_ws 路由到 3002
端口冲突或修改后无法访问 连接失败 在 .env 中设置 WEB_EXTERNAL_PORT=8080 等，然后 docker compose down && docker compose up -d
重启后登录/会话消失 会话失效 设置固定 COOKIE_SECRET，并挂载 ./data:/app/data
本地 MMDB 查询需要哪些文件 地理定位失败 放置 GeoLite2-City.mmdb（必需）、GeoLite2-ASN.mmdb（必需）、GeoLite2-Country.mmdb（可选）到 ./geoip
无法连接 OpenClash / 网关 连接超时 检查网关侧是否启用外部控制、主机/端口是否正确、Token/Secret 是否正确、容器网络能否到达网关
如何备份和恢复数据 数据丢失 备份：cp -r ./data ./data-backup-$(date +%Y%m%d)；恢复：停止容器，复制备份，重启

数据持久化与更新

数据持久化

数据存储在容器内的 /app/data 目录。挂载到主机可防止数据丢失：

1
2
volumes:
  - ./data:/app/data

更新到最新版本

1
2
docker compose pull
docker compose up -d

总结

部署方案 适用场景 难度 推荐度
Docker Compose 场景 A 大多数用户，无需反向代理 ⭐ ⭐⭐⭐⭐⭐
Docker Compose 场景 B 需要实时 WebSocket ⭐⭐ ⭐⭐⭐⭐⭐
Docker Run 不习惯 Compose ⭐⭐ ⭐⭐⭐⭐
一键脚本 快速自动化部署 ⭐ ⭐⭐⭐⭐
源码部署 开发或定制需求 ⭐⭐⭐⭐ ⭐⭐
Agent 部署 多远程网关集中管理 ⭐⭐⭐ ⭐⭐⭐⭐

对于大多数用户，Docker Compose 场景 A 是最简单直接的选择：

1
2
3
4
# 创建目录和配置文件
mkdir neko-master && cd neko-master
# 创建 docker-compose.yml 和 .env
docker compose up -d

访问 http://localhost:3000，配置网关连接，即可开始监控网络流量。如需实时推送，使用场景 B 并配合反向代理路由 /_cm_ws 到 3002。