foru17/neko-master Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

Neko Master

让你的网络流量一目了然。
实时监控 · 流量审计 · 多网关管理

中文 | English

[!IMPORTANT] 免责声明

本项目为 网络流量分析与可视化工具， 用于展示与统计本地网关的流量数据。

本项目 不提供任何网络接入服务、代理订阅或跨网络连接功能。 所有数据均来源于用户自有网络环境。

本项目遵循 MIT 协议开源，不对因使用本软件产生的任何后果承担责任。请在合规范围内使用。

</td>
<td align="center" width="50%">
  
</td>

</td>
<td align="center" width="50%">
  
</td>

🌐 在线演示

演示地址: [***]
访问密码: neko2026

演示站为只读展示模式，部分功能受限。

关于名称

Neko（ねこ）在日语中意为“猫”， 发音为 /ˈneɪkoʊ/（NEH-ko）。

如同猫一般安静而敏锐， Neko Master 专注于对网络流量进行轻量、精确的分析与可视化。

📋 目录

• 🚀 快速开始
• 🤖 Agent 部署
• 📖 首次使用
• 🔧 端口冲突解决
• 🐳 Docker 配置
• 🗄️ ClickHouse（可选）
• 🌐 反向代理与 Tunnel
• 🔐 认证与安全
• ❓ 常见问题
• 🏗️ 架构文档指引
• 🤝 反馈与 Issue
• 📁 项目结构
• 🛠️ 技术栈
• 📝 更新日志
• 📄 许可证

🚀 快速开始

方式一：Docker Compose（推荐）

仓库内置的 docker-compose.yml 默认映射 3000/3001/3002。
下方场景 A/B 是更精简的常见部署模板，可按需选择。

场景 A：最简部署（仅暴露 3000）

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

建议在 docker-compose.yml 同目录的 .env 中配置：
COOKIE_SECRET=<至少32字节随机字符串>（可用 openssl rand -hex 32 生成）

该模式完全兼容升级，页面可用。
未打通 WS 时会自动回退到 HTTP 轮询刷新。

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

yaml
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
      # 本地 MMDB（可选，文件需自行下载并放到 ./geoip）
      - ./geoip:/app/data/geoip:ro
    environment:
      - NODE_ENV=production
      - DB_PATH=/app/data/stats.db
      - COOKIE_SECRET=${COOKIE_SECRET}

启动服务：

bash
docker compose up -d

访问 http://localhost:3000

若你直接使用仓库内置 Compose 文件（默认暴露 3000/3001/3002），执行同一命令即可。

方式二：Docker 直接运行

bash
# 建议先生成固定 Cookie 密钥（用于会话持久）
export COOKIE_SECRET="$(openssl rand -hex 32)"

bash
# 最简（仅 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

# 实时 WS（配合反代）
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

默认前端 API 走同域 /api，通常不需要额外暴露 3001。
若希望 WebSocket 实时生效，需要让反代层可以访问 3002；未打通时会回退到 HTTP 轮询（约 5 秒级）。

访问 http://localhost:3000

docker run 修改外部端口时，直接改 -p 映射即可。
仅在“非反代直连 WS 且外部 WS 端口不是 3002”时，额外传入 -e WS_EXTERNAL_PORT=<外部WS端口>。

本地 MMDB 查询模式（可选）：额外挂载 -v $(pwd)/geoip:/app/data/geoip:ro， 并在面板「设置 -> 偏好设置 -> IP 查询来源」切换到本地。

方式三：一键脚本

自动检测端口冲突并配置，适合不熟悉 Docker 的用户：

bash
# 使用 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）是否被占用
• ✅ 提供可用的替代端口
• ✅ 创建配置文件并启动服务

方式四：源码运行

bash
# 1. 克隆仓库
git clone https://github.com/foru17/neko-master.git
cd neko-master

# 2. 安装依赖
pnpm install

# 3. 准备 collector 环境变量（源码模式读取 apps/collector/.env）
cp apps/collector/.env.example apps/collector/.env

# 4. 启动开发服务
pnpm dev

访问 http://localhost:3000

源码模式下：collector 默认监听 3001/3002，web 默认监听 3000。
如果你修改了 API_PORT（非 3001），请同步设置 API_URL（例如 API_URL=http://localhost:4001）供 web 的 /api 转发使用。
apps/collector/.env.local 的优先级高于 apps/collector/.env。

🤖 Agent 部署

当你希望中心化部署一个 Neko Master 服务，并在不同设备（OpenWrt、Linux、macOS）本地采集网关数据时，推荐使用 Agent 模式。Agent 运行在网关旁边，主动拉取数据并上报至面板，面板无需主动连接网关。

支持网关类型：***** / ***（WebSocket 实时）和 ***** v5+（HTTP 轮询）。

快速安装（UI 生成命令）

1. 在面板「设置 → 后端」中添加一个 Agent 类型后端，选择网关类型（*** 或 ***）
2. 点击「查看安装脚本」，复制一键安装命令，在目标主机上执行：

bash
# Clash / Mihomo 网关示例
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 网关示例
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

安装完成后，使用 nekoagent 管理实例：

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

脚本会自动检测已有安装，若已存在则只添加新实例而不重新下载二进制。 同一主机可同时运行多个实例（不同 NEKO_INSTANCE_NAME），对应不同网关。

Agent 文档

• 总览：架构说明、直连 vs Agent 对比、安全模型
• 快速开始：从 UI 到运行的完整步骤
• 安装指南：安装方式、systemd / launchd / OpenWrt 开机自启
• 参数配置：完整参数列表与示例
• 发布流程：版本命名与兼容性策略
• 常见问题：常见错误与解决方法

📖 首次使用

!首次使用

接入 *** / ***

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

💡 获取网关地址: 进入网关控制面板（如 Open***） → 打开「外部控制」→ 复制 API 地址

接入 ***

!*** HTTP API 配置

Neko Master 支持接入 *** 网关，实现完整的规则链可视化和流量分析。

1. 开启 *** HTTP API

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

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

或者通过 *** 的图形界面配置：

• HTTP 远程 API: 设置 → 常规 → HTTP 远程 API
• 端口: 默认 9091
• 认证: 建议设置密码增强安全性

2. 在 Neko Master 中添加 *** 后端

1. 打开 Neko Master 设置对话框
2. 点击「添加后端」
3. 填写连接信息：
   • 名称: 自定义名称（如 "*** Home"）
   • 类型: 选择 Surge
   • 地址: *** 运行的 IP 地址（如 192.168.1.1 或 127.0.0.1）
   • 端口: HTTP API 端口（默认 9091）
   • Token: HTTP API 密码（如果设置了的话）
4. 点击「测试连接」确认配置正确
5. 保存配置

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

🔧 端口冲突解决

如果看到错误提示端口已被占用，有以下几种解决方案：

方案 1：使用 .env 文件

创建 .env 文件（与 docker-compose.yml 同目录）：

env
WEB_EXTERNAL_PORT=8080    # 修改 Web UI 端口
API_EXTERNAL_PORT=8081    # 修改 API 端口
WS_EXTERNAL_PORT=8082     # 修改 WebSocket 外部端口（仅直连时需要）
COOKIE_SECRET=your-long-random-secret   # 强烈建议固定

然后重启：

bash
docker compose down
docker compose up -d

现在访问 http://localhost:8080

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

yaml
ports:
  - "8080:3000" # 外部 8080 → 内部 3000
  - "8082:3002" # 外部 8082 → 内部 3002（给反代/Tunnel 转发 WS）

说明：如果你不走反代、直接让浏览器连 ws://host:端口，且外部 WS 端口不是 3002，请同时设置 WS_EXTERNAL_PORT=<外部端口>。

方案 3：使用一键脚本

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

脚本会自动检测并提供可用的端口。

🐳 Docker 配置

端口说明

环境变量说明（部署）

高级调优变量（可选）

API / WS 地址解析优先级

1. API 客户端基址：runtime-config.API_URL → NEXT_PUBLIC_API_URL → 默认同域 /api
2. /api 的服务端转发目标：API_URL（默认 http://localhost:3001，在 Next.js rewrite 中生效）
3. WS URL：runtime-config.WS_URL → NEXT_PUBLIC_WS_URL → 自动候选（生产优先 /_cm_ws，失败再尝试直连端口）
4. WS 端口：runtime-config.WS_PORT（来自 WS_EXTERNAL_PORT）→ NEXT_PUBLIC_WS_PORT → 3002
5. 默认部署下无需手动配置 NEXT_PUBLIC_WS_URL；仅当你自定义 WS 路径/域名时再设置

线上环境建议（强烈）

env
NODE_ENV=production
DB_PATH=/app/data/stats.db
COOKIE_SECRET=<至少32字节随机字符串>
# 可选：默认切换到本地 MMDB 查询
# GEOIP_LOOKUP_PROVIDER=local
# 仅紧急恢复时临时开启，平时不要保留 true
# FORCE_ACCESS_CONTROL_OFF=false

可使用 openssl rand -hex 32 生成 COOKIE_SECRET。

补充建议：

1. 挂载持久化目录（如 ./data:/app/data），避免数据库与自动生成密钥丢失。
2. 如果外部直连 WS 且端口非 3002，务必同步设置 WS_EXTERNAL_PORT。
3. 若源码部署修改了 API 端口或地址，记得同步设置 API_URL。
4. 如需本地 MMDB 查询：挂载 ./geoip:/app/data/geoip:ro，并在面板「设置 -> 偏好设置 -> IP 查询来源」切换为本地。
5. MMDB 文件体积较大，项目镜像不内置数据库。请自行下载并放入 ./geoip，文件名固定为： GeoLite2-City.mmdb、GeoLite2-ASN.mmdb（必需），GeoLite2-Country.mmdb（可选）。 推荐来源：<[***]>。

进阶说明：Agent 模式的安装、参数、发布与兼容策略已迁移到 docs/agent/*，请以文档为准。

🗄️ ClickHouse（可选）

SQLite 是 Neko Master 的默认存储引擎，对大多数用户已完全够用。
如果你有以下需求，可以额外启用 ClickHouse：

• 数据量很大（域名 / IP 条目数十万以上）
• 需要快速的长时间范围（≥ 7 天）聚合查询
• 希望将历史统计数据与配置数据分层存储

ClickHouse 完全可选。SQLite 作为配置和元数据存储，无论是否启用 ClickHouse 都不会被移除。

架构说明

启用 ClickHouse 后，系统进入双写模式：

BatchBuffer.flush()
    │
    ├──→ SQLite（配置 / 元数据，始终写入）
    └──→ ClickHouse（统计流量数据，双写）
           └── Buffer 表 → SummingMergeTree 异步合并

读取来源由 STATS_QUERY_SOURCE 控制，默认仍为 sqlite。

启用 ClickHouse（Docker）

步骤一：启动 ClickHouse 容器

仓库内置的 docker-compose.yml 已包含 ClickHouse 服务，通过 profiles: [clickhouse] 隔离，默认不启动。 直接在仓库根目录执行：

bash
docker compose --profile clickhouse up -d

ClickHouse 数据持久化到 ./data/clickhouse，与主应用数据分目录存储。

如果你使用的是自定义 docker-compose.yml（如上方场景 A/B），需手动添加 ClickHouse 服务块：

yaml
services:
  neko-master:
    # ... 你的现有配置 ...
    environment:
      # 在现有 environment 中追加：
      - 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

步骤二：配置环境变量

在 .env 中添加（与 docker-compose.yml 同目录）：

env
# 开启 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

重启：

bash
docker compose --profile clickhouse up -d

ClickHouse 环境变量说明

健康回退机制：ClickHouse 连续写入失败超过 CH_UNHEALTHY_THRESHOLD 次后，系统自动标记为不健康，SQLite 写入恢复（即使开启了 CH_ONLY_MODE）。ClickHouse 恢复正常后自动重新标记为健康。

老用户迁移指引

从纯 SQLite 版本升级时，你的数据不会丢失。
SQLite 文件（./data/stats.db）完整保留，以下是推荐的渐进迁移路径：

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

env
CH_ENABLED=1
CH_WRITE_ENABLED=1
STATS_QUERY_SOURCE=sqlite   # 继续读 SQLite，CH 在后台积累数据

启动并观察 [ClickHouse Writer] 日志确认写入正常。

第二阶段：切换读取来源

env
STATS_QUERY_SOURCE=auto     # 自动选择：最近数据走 CH，历史走 SQLite
# 或
STATS_QUERY_SOURCE=clickhouse  # 强制读 CH

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

如需将 SQLite 历史统计数据搬入 ClickHouse：

bash
# 标准迁移（清空 CH 后重新导入，附带对账验证）
./scripts/ch-migrate-docker.sh

# 追加模式（保留 CH 现有数据，增量导入）
./scripts/ch-migrate-docker.sh --append

# 指定时间窗口
./scripts/ch-migrate-docker.sh --from 2026-02-01T00:00:00Z --to 2026-02-20T00:00:00Z

第四阶段（可选）：纯 ClickHouse 模式

当 ClickHouse 稳定运行后，可停止 SQLite 统计写入：

env
CH_ONLY_MODE=1

即使在 CH_ONLY_MODE=1 下，若 ClickHouse 不健康，系统会自动回退到 SQLite 写入，数据不会丢失。

回退到纯 SQLite

随时可以完全回退：

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

重启后恢复纯 SQLite 模式，历史数据完整保