1. 项目定位与用途
Neko Master 是一款专为本地网关环境设计的现代化网络流量可视化分析仪表板。它通过轻量级代理实时收集网络流量数据，以清晰、直观的图表和报表形式展示流量趋势、域名访问、IP 地理分布等信息，帮助用户全面掌握网络使用情况，适用于网络监控、审计与故障排查场景。项目明确声明不提供网络访问服务或代理订阅，所有数据均来自用户自有网络环境。
项目档案应用项目
Neko Master 网络流量可视化仪表板 - 本地网关实时监控与分析工具 Docker部署指南
Neko Master 是一款专为本地网关设计的现代化网络流量可视化分析工具，提供 WebSocket 实时监控、多维度趋势分析、域名/IP 深度洞察。支持 Docker 一键部署，适用于家庭和企业网络监控、流量审计与异常排查。本页包含安装配置、使用教程及技术架构说明。
AI 总结
Neko Master 是一款专为本地网关环境设计的现代化网络流量可视化分析仪表板，通过轻量级代理实时收集数据，提供毫秒级 WebSocket 监控、多维度趋势分析与域名/IP 深度洞察，支持 Docker 一键部署。
中文项目介绍
Neko Master 是一个现代且优雅的网络流量可视化与分析仪表板，专为本地网关环境设计。它通过部署轻量级代理（neko-agent）实时收集流量数据，以清晰直观的图表展示流量趋势、域名访问、IP 地理分布等信息，帮助用户全面掌握网络使用情况。
该项目解决的核心问题是：在本地网关环境中，用户难以直观查看和分析网络流量。传统工具往往实时性不足、分析维度单一或界面陈旧。Neko Master 提供毫秒级延迟的 WebSocket 实时监控、多时间维度趋势分析（30分钟/1小时/24小时）、域名与 IP 的深度关联分析（包括 ASN 和地理位置），以及美观的现代化界面，使用户能够快速洞察流量异常、识别高频访问域名、了解 IP 地理分布，从而提升网络管理效率。
主要适用场景包括：家庭或企业网关的实时流量监控与分析；多节点网络环境下的集中式流量审计；网络异常排查与流量趋势观察；域名解析与 IP 关联关系分析。需要注意的是，Neko Master 仅分析用户自有网络环境的数据，不提供任何代理订阅或跨网络访问服务。
技术特征方面，项目采用 monorepo 架构，使用 pnpm 和 turbo 管理多个工作区（agent、collector、web）。前端基于 Next.js，数据收集端使用 TypeScript，代理端使用 Go。支持 WebSocket 实时推送、多维度分析、Docker 一键部署，并提供中英文界面。数据存储默认使用 SQLite，可选集成 ClickHouse。安全配置需设置 COOKIE_SECRET，IP 地理查询支持在线接口或本地 MMDB。
详细信息与使用说明
2. 解决的问题
传统网络流量分析工具往往存在实时性不足、分析维度单一或界面陈旧等问题。Neko Master 针对本地网关环境，提供毫秒级延迟的 WebSocket 实时监控、多时间维度趋势分析（30分钟/1小时/24小时）、域名与 IP 的深度关联分析（包括 ASN 和地理位置），以及美观的现代化界面，使用户能够快速洞察流量异常、识别高频访问域名、了解 IP 地理分布，从而提升网络管理效率。
3. 适用场景
该工具适用于：家庭或小型企业网关的日常流量监控；多节点网络环境下的集中式流量审计与报表生成；网络异常或性能问题时的流量趋势分析与根因定位；安全审计中域名解析与 IP 关联关系的核查。需要注意的是，Neko Master 仅分析用户自有网络环境的数据，不提供任何代理或跨网络访问服务，使用时应遵守当地法律法规。
4. 安装方式
Docker 部署：复制 .env.example 为 .env，根据实际情况修改 WEB_EXTERNAL_PORT、API_EXTERNAL_PORT、WS_EXTERNAL_PORT 等端口配置（默认 3000/3001/3002），然后执行 `docker compose up -d` 启动服务。Agent 部署：在网关设备上下载并运行 neko-agent 二进制文件，参考 docs/agent/install.en.md 进行安装。反向代理配置（可选）：若需通过域名访问，需在 Nginx 等代理 /api 和 /ws 路径至对应服务端口。
5. 使用方式
访问 Web UI：浏览器打开 `http://服务器IP:WEB_EXTERNAL_PORT`（默认 http://localhost:3000）。实时监控：仪表板首页通过 WebSocket 自动推送实时流量数据，展示当前连接数、吞吐量等关键指标。趋势分析：在趋势页面选择 30分钟/1小时/24小时 时间范围查看流量变化。域名/IP 分析：分别进入域名和 IP 页面，查看详细访问记录、关联 IP/域名、ASN 和地理位置信息。Agent 管理：在设置页面添加和管理多个网关 Agent，支持 Clash 和 Surge 两种网关类型。
6. 补充说明与实现特点
项目采用 monorepo 结构，前端基于 Next.js 构建，后端 collector 使用 TypeScript，agent 使用 Go 语言。数据存储默认使用 SQLite（DB_PATH 可配置），可选集成 ClickHouse 以支持更大规模数据。安全方面需配置 COOKIE_SECRET。IP 地理查询支持在线接口或本地 MMDB 文件。项目遵循 MIT 许可证，明确声明不承担使用后果责任，要求用户遵守当地法律法规。详细架构请参考 docs/architecture.en.md。
思维导图
当前仓库信息不足，或结构不够稳定，暂时没有生成可靠的思维导图。
常见问题
Neko Master 是否需要代理订阅或跨网络访问？
不需要。Neko Master 仅分析用户自有本地网关环境的流量数据，不提供任何网络访问服务、代理订阅或跨网络连通性功能。所有数据均来自用户自己的网络环境，项目明确声明不承担使用后果责任。
如何部署 Neko Master？
推荐使用 Docker 部署：复制 .env.example 为 .env，修改端口配置（如 WEB_EXTERNAL_PORT=3000），然后执行 `docker compose up -d`。同时需要在网关设备上部署 neko-agent 并配置连接参数，参考 docs/agent/install.en.md 和 config.en.md。
Agent 配置参数有哪些？
必填参数包括：--server-url（面板地址）、--backend-id（后端ID）、--backend-token（后端令牌）、--gateway-type（clash/surge）、--gateway-url（网关API地址）。可选参数如 --gateway-token、--report-interval、--heartbeat-interval 等，详细说明见 docs/agent/config.en.md。
支持哪些网关类型？
目前支持 Clash 和 Surge 两种网关类型。Agent 通过网关的 API 获取流量数据，需要根据网关类型提供相应的认证令牌：Clash 使用 Authorization 头部，Surge 使用 x-key 头部。
数据存储在哪里？如何扩展？
默认使用 SQLite 数据库，路径为 /app/data/stats.db（可通过 DB_PATH 配置）。如需处理更大数据量，可集成 ClickHouse，详细配置参考文档中关于 ClickHouse 的章节。IP 地理查询支持在线接口（默认）或本地 MMDB 文件两种模式。