從零搭建 Neko Master：網關流量視覺化面板完整教學

基於開源專案 foru17/neko-master（“Modern traffic analytics for edge gateways”）。本教學帶你從安裝 Docker 開始，一步步完成面板部署、接入 Clash / Mihomo 或 Surge 網關、讀懂每一張統計圖表，並覆蓋安全加固與多網關 Agent 模式。全程命令可直接複製，每一步都附有「做完你應該看到什麼」的驗證點。

目錄

1. 前言：為什麼你需要流量視覺化
2. 準備工作
3. Step 1：安裝與檢查 Docker
4. Step 2：啟動 Neko Master 面板
5. Step 3-A：接入 Clash / Mihomo 網關
6. Step 3-B：接入 Surge 網關
7. Step 4：讀懂面板的每個頁面
8. Step 5：安全三件事
9. 進階篇
10. 日常維運
11. 常見問題 FAQ
12. 結語與參考連結

前言：為什麼你需要流量視覺化

先問自己三個問題：

• 這個月跑掉的幾百 GB 流量，都去了哪些國家？
• 某個串流或下載域名，實際走的是哪個代理節點？
• 為什麼某個地區的上傳量遠大於下載量——是有設備在當中繼轉發，還是被盜用了？

如果答不上來，說明你的網關（Clash / Mihomo / Surge）對你來說還是個黑盒。Neko Master 就是用來把這個黑盒打開的工具。

Neko Master 是什麼

一句話：自託管的網關流量分析與視覺化面板。它從你的網關收集連線與流量數據，按地區、域名、IP、代理節點等維度統計並畫成圖表。

先吃一顆定心丸

官方明確聲明：Neko Master 只做流量分析與視覺化，不提供任何網路接入、代理訂閱或跨網連線功能；所有數據都來自你自己的網路環境。它不會「幫你翻出去」，只會「告訴你都翻了什麼」。

小知識：該專案早期名為 Clash Master，後更名為 Neko Master（“Like a cat, Neko Master observes network traffic quietly and precisely."）。

準備工作

檢查清單

架構一張圖看懂

┌─────────────────────┐        ┌──────────────────────┐        ┌──────────┐
│  你的網關            │        │  Neko Master 面板     │        │  瀏覽器   │
│  Clash / Mihomo     │───────▶│  收集 → 匯總 → SQLite │───────▶│  看圖表   │
│  或 Surge v5+       │  API   │  （Docker 容器）      │  Web   │          │
└─────────────────────┘        └──────────────────────┘        └──────────┘

進階的 Agent 模式則是在網關旁邊多放一個小代理人（Agent），由它就地拉數據再上報給中心面板，適合網關散落在路由器、小主機等多台設備的場景（見進階篇）。

端口速查表

Step 1：安裝與檢查 Docker

先檢查機器上有沒有 Docker：

docker -v

有版本號輸出（如 Docker version 27.x.x）就直接跳去 Step 2。沒有則安裝：

# Debian / Ubuntu 等 Linux 發行版的一鍵腳本（官方提供）
curl -fsSL https://get.docker.com | bash

⚠️ 一鍵腳本會以 root 權限安裝軟體，請確認你信任該來源。NAS 使用者（群暉 Container Manager、威聯通 Container Station）請直接在系統介面安裝 Docker 套件，跳過本步。

✅ 驗證點：docker -v 與 docker compose version 都有輸出。

Step 2：啟動 Neko Master 面板

2.1 建立目錄與金鑰

mkdir -p ~/neko-master && cd ~/neko-master

生成一組隨機金鑰（COOKIE_SECRET，用於登入工作階段（session）的 Cookie 簽名；不固定的話重啟容器後登入狀態可能失效）：

openssl rand -hex 32

把輸出的那串十六進位字串記下來，寫入同目錄的 .env 檔案：

# .env
COOKIE_SECRET=把剛才輸出的字串貼在這裡

2.2 建立 docker-compose.yml

在 ~/neko-master 目錄下建立 docker-compose.yml，內容如下（每一行都有註解）：

services:
  neko-master:
    image: foru17/neko-master:latest   # 官方映像（image，即打包好的軟體）
    container_name: neko-master        # 容器名稱，方便後續下指令
    restart: unless-stopped            # 開機自動啟動、異常自動重啟
    ports:
      - "3000:3000"                    # Web UI 端口
    volumes:
      - ./data:/app/data               # 數據持久化：統計庫與金鑰都存這裡
      # - ./geoip:/app/data/geoip:ro   # 可選：本地 GeoIP 庫（見進階篇）
    environment:
      - NODE_ENV=production
      - DB_PATH=/app/data/stats.db     # SQLite 資料庫檔案位置
      - COOKIE_SECRET=${COOKIE_SECRET} # 從 .env 讀取金鑰

2.3 啟動

docker compose up -d

✅ 驗證點：

1. docker ps 能看到 neko-master 且狀態為 Up；
2. 瀏覽器打開 http://你的伺服器IP:3000，會看到面板介面，首次存取會彈出「Gateway Configuration」網關設定對話框——先別關，下一步就是填它（也可以關掉，之後在 Settings → Backends 補）。

畫面打不開？先檢查防火牆是否放行 3000 端口，以及瀏覽器與伺服器是否在同一網路。

附：不想寫 yml？單命令版

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

Step 3-A：接入 Clash / Mihomo 網關

原理：面板透過網關的**外部控制 API（external-controller）**以 WebSocket 讀取即時連線與流量數據。

A1. 在網關側開啟外部控制

裸 mihomo / Clash 核心：在 config.yaml 中確認有以下兩行（沒有就加上）：

external-controller: 0.0.0.0:9090   # 控制 API 監聽地址與端口
secret: "你的secret"                # 存取密碼；面板與網關同機時可改用 127.0.0.1:9090 更穩妥

OpenClash（OpenWrt 外掛）：在外掛設定中開啟「外部控制（External Control）」，並記下它顯示的 API 地址與 secret。

⚠️ 0.0.0.0 表示區域網路內任何設備都能存取這個控制 API，務必設定 secret。

A2. 在面板側填寫

回到瀏覽器那個 Gateway Configuration 對話框（或 Settings → Backends → 新增）：

儲存。

✅ 驗證點：Overview 頁出現即時流量曲線，連線數隨你上網即時跳動。

Step 3-B：接入 Surge 網關

原理：Surge v5+ 提供 HTTP API，面板以約 2 秒一次的輪詢拉取數據（比 WebSocket 略有延遲，屬正常）。

B1. 在 Surge 側開啟 HTTP API

編輯 Surge 設定檔，在 [General] 段加入：

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

或用圖形介面：Settings → General → HTTP Remote API，預設端口 9091，建議設定密碼。

⚠️ 若面板與 Surge 不在同一台機器，需把 127.0.0.1 改成 Surge 所在機器的區域網路 IP（如 192.168.1.10:9091），否則面板連不進去。

B2. 在面板側填寫

✅ 驗證點：Overview 出現曲線（數據約每 2 秒更新一次）；Surge 使用者還可在 Rules 頁看到完整規則鏈命中情況。

Step 4：讀懂面板的每個頁面

每個頁面其實都在回答一個具體問題：

📷 截圖位：Regions 頁（按國家排列的流量卡片，含 ↓/↑/連線數三項指標）。

小白解讀技巧：正常瀏覽行為應該是「下載 ≫ 上傳」。若某地區或某域名出現上傳遠大於下載（例如下載 5 GB、上傳 28 GB），通常意味著該節點在被當作中轉/回源出口，值得點進 Domains 頁追查。

Step 5：安全三件事

面板掌握著你全部流量的統計資訊（去了哪、連了誰），安全設定不能省。

① 設定存取 Token

面板沒有預設帳號密碼，存取控制預設未開啟。進入左下角 Settings → Security 分頁，手動啟用並設定存取 Token。設好之後，任何人打開你的面板網址都必須先輸入 Token。

② 不要把 3000 端口裸奔公網

• 只在區域網路使用：無需額外操作，但 Token 仍建議設；
• 需要外網存取：用反向代理 + HTTPS，或走隧道（見進階篇），不要直接把 3000 映射到公網 IP。

③ 萬一忘記 Token

在容器環境變數加入 FORCE_ACCESS_CONTROL_OFF=true 重啟，進入緊急模式重置 Token；重置完記得把這個變數刪掉再重啟。

✅ 驗證點：無痕視窗打開面板網址，要求輸入 Token 才算過關。

進階篇

9.1 Agent 模式：一個面板管多台網關

適用場景：網關散落在 OpenWrt 路由器、Linux 小主機、macOS 等多台設備，或面板與網關之間網路不通（面板無法主動連網關）。Agent 運行在網關旁邊，就地拉數據再上報給中心面板。

步驟：

1. 面板進入 Settings → Backends，新增一個 Agent 類型後端，選擇網關類型；
2. 點選 “View Agent Script”，複製生成的一鍵安裝命令；
3. 到目標網關所在主機上執行。

Clash / Mihomo 網關範例：

curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/install.sh \
  | env NEKO_SERVER='http://你的面板: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://你的面板:3000' \
        NEKO_BACKEND_ID='2' \
        NEKO_BACKEND_TOKEN='ag_yyy' \
        NEKO_GATEWAY_TYPE='surge' \
        NEKO_GATEWAY_URL='http://127.0.0.1:9091' \
        sh

參數說明：

日常管理命令：

9.2 反向代理與 WebSocket

需要域名 + HTTPS 存取時，在 docker-compose.yml 的 ports 中追加 WebSocket 端口：

    ports:
      - "3000:3000"   # Web UI
      - "3002:3002"   # WebSocket（供 Nginx / 隧道轉發）

Nginx 參考設定（TLS 憑證部分自行補全）：

server {
    listen 443 ssl;
    server_name neko.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;      # 支援 WebSocket 升級
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

若代理後即時曲線不動（WebSocket 沒連上），用環境變數告訴前端正確的連線地址：

• NEXT_PUBLIC_WS_URL：覆蓋前端 WS 地址；
• NEXT_PUBLIC_API_URL：覆蓋前端 API 地址。

9.3 本地 GeoIP 庫（離線查歸屬地）

預設 GEOIP_LOOKUP_PROVIDER=online，會把 IP 發往線上查詢服務（預設端點 https://api.ipinfo.es/ipinfo）。介意隱私或查詢不穩的話改走本地庫：

1. 下載 MMDB 檔案（如 P3TERX/GeoLite.mmdb）放入 ./geoip 目錄；
2. 取消 compose 中這行的註解：- ./geoip:/app/data/geoip:ro；
3. 環境變數設 GEOIP_LOOKUP_PROVIDER=local，重啟容器。

9.4 ClickHouse：流量大戶才需要

預設 SQLite 足夠絕大多數家庭場景。當流量數據量極大、歷史查詢明顯變慢時，再考慮可選的 ClickHouse（24.8+）。官方建議分四階段遷移，不要一步到位：

預設連線參數：CH_HOST=clickhouse、CH_PORT=8123、CH_DATABASE=neko_master、CH_USER=neko、CH_PASSWORD=neko_master——生產環境務必改密碼。回滾很簡單：把所有 CH_* 設回 0、STATS_QUERY_SOURCE=sqlite 再重啟。

日常維運

常見問題 FAQ

Q1：面板連不上網關？ 逐一檢查：① 網關側 external-controller / http-api 是否真的開啟；② 面板跑在 Docker 裡時，Host 填 127.0.0.1 是無效的（那指向容器自己），請填網關主機的區域網路 IP；③ 端口與 secret/密碼是否抄錯；④ 兩機之間防火牆是否放行。

Q2：有連線數但曲線不動 / 沒流量？ ① 右上角時間範圍是否選錯；② 反向代理環境下 WebSocket 是否連上（見 9.2，必要時設 NEXT_PUBLIC_WS_URL）；③ Surge 後端為輪詢採集，約 2 秒延遲屬正常。

Q3：Regions 頁大量顯示未知地區？ GeoIP 查詢問題：線上源被牆或不穩時，按 9.3 切換本地 MMDB 庫。

Q4：這個面板安全嗎？會不會把我的流量傳出去？ 專案本身純統計視覺化，不提供代理或聯網服務；但請注意兩點：① 預設 GeoIP 線上查詢會把 IP 地址發往第三方查詢端點（可改本地庫）；② 面板數據等於你的上網清單，務必設 Token、不裸奔公網。

Q5：忘記存取 Token 怎麼辦？ 見 Step 5 第 ③ 條：FORCE_ACCESS_CONTROL_OFF=true 緊急重置，用完記得刪。

結語與參考連結

搭到這裡，你已經擁有了一個能回答「流量去哪了、誰在跑、走哪條節點」的自託管面板。日常記住三件事：備份 ./data、升級用 pull + up -d、Token 別忘設。

• 專案地址：https://github.com/foru17/neko-master
• Docker 映像：https://hub.docker.com/r/foru17/neko-master
• 官方聲明：本專案僅為流量分析與視覺化工具，不提供任何網路接入服務；所有數據來自使用者自有網路環境。

本文基於 2026-09-13 時點的官方 README 整理；映像版本 foru17/neko-master:latest。若你閱讀時專案已更新，請以倉庫最新說明文件為準。