Clash Master

优雅且现代化的 OpenClash 流量可视化分析工具
实时监控 · 多维度分析 · 多后端管理

简体中文 • English

• 🚀 快速开始
• 📖 首次使用
• 🔧 端口冲突解决
• 🐳 Docker 配置
• ❓ 常见问题
• 📁 项目结构
• 🛠️ 技术栈
• 📄 许可证

创建 docker-compose.yml：

services:
  clash-master:
    image: foru17/clash-master:latest
    container_name: clash-master
    restart: unless-stopped
    ports:
      - "3000:3000" # Web UI
      - "3001:3001" # API
      - "3002:3002" # WebSocket
    volumes:
      - ./data:/app/data
    environment:
      - NODE_ENV=production
      # 外部端口（可选，默认即为 3000/3001/3002）
      - WEB_EXTERNAL_PORT=3000
      - API_EXTERNAL_PORT=3001
      - WS_EXTERNAL_PORT=3002
      - DB_PATH=/app/data/stats.db

启动服务：

docker compose up -d

访问 http://localhost:3000

**最简（推荐，仅 Web 反代）：**

```bash
docker run -d \
  --name clash-master \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  --restart unless-stopped \
  foru17/clash-master:latest

可选（直连 API / WebSocket 时才需要）：

docker run -d \
  --name clash-master \
  -p 3000:3000 \
  -p 3001:3001 \
  -p 3002:3002 \
  -v $(pwd)/data:/app/data \
  --restart unless-stopped \
  foru17/clash-master:latest

默认前端走同域 /api，所以只需要暴露 3000。
只有当你需要直连 API / WS 或未配置 Nginx /api / /ws 反代时，才需要暴露 3001/3002。

访问 <http://localhost:3000>

> 如需自定义外部端口（docker run），请额外传入：
> `-e WEB_EXTERNAL_PORT=8080 -e API_EXTERNAL_PORT=8081 -e WS_EXTERNAL_PORT=8082`

### 方式三：一键脚本

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

```bash
# 使用 curl
curl -fsSL https://raw.githubusercontent.com/foru17/clash-master/main/setup.sh | bash

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

脚本会自动：

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

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

# 2. 安装依赖
pnpm install

# 3. 启动开发服务
pnpm dev

访问 http://localhost:3000

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

💡 获取 OpenClash 地址: 进入 OpenClash 插件 → 打开「外部控制」→ 复制地址

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

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

WEB_EXTERNAL_PORT=8080    # 修改 Web UI 端口
API_EXTERNAL_PORT=8081    # 修改 API 端口
WS_EXTERNAL_PORT=8082     # 修改 WebSocket 端口

然后重启：

docker compose down
docker compose up -d

现在访问 http://localhost:8080

ports:
  - "8080:3000" # 外部 8080 → 内部 3000
  - "8081:3001" # 外部 8081 → 内部 3001
  - "8082:3002" # 外部 8082 → 内部 3002

说明：前端会在运行时读取外部端口配置，无需再设置 NEXT_PUBLIC_WS_PORT。

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

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

只配置主站 Web 的 Nginx 反代即可：前端默认同域访问 /api，无需额外暴露或配置 3001/3002。 如需直连 API/WS，可设置 API_URL / WS_URL，或暴露对应端口。

Docker 镜像同时支持 linux/amd64 和 linux/arm64。

数据默认存储在容器内的 /app/data 目录，建议映射到宿主机：

volumes:
  - ./data:/app/data

# 拉取最新镜像并重新启动
docker compose pull
docker compose up -d

A: 参考上方端口冲突解决部分。最简单的方式是创建 .env 文件修改端口。

A: 确保三点：

1. .env 文件中的端口已修改
2. 重启了服务：docker compose restart
3. 访问时使用了新端口（如 http://localhost:8080）

A: 检查以下几点：

1. OpenClash 的「外部控制」是否已开启
2. OpenClash 地址是否正确（格式：IP:端口）
3. 如果配置了 Secret，Token 是否填写正确
4. 容器是否能访问到 OpenClash 所在网络

A:

# 查看所有日志
docker logs -f clash-master

# 只看最后 100 行
docker logs --tail 100 clash-master

A: 数据存储在映射的目录中（默认 ./data/stats.db）：

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

A:

1. 点击左侧边栏底部的「设置」
2. 切换到「数据库」标签页
3. 选择清理范围：1天前 / 7天前 / 30天前 / 全部

clash-master/
├── docker-compose.yml      # Docker Compose 配置
├── Dockerfile              # Docker 镜像构建
├── setup.sh                # 一键配置脚本
├── docker-start.sh         # Docker 容器启动脚本
├── start.sh                # 源码开发启动脚本
├── assets/                 # 预览图和图标
├── apps/
│   ├── collector/          # 数据收集服务（Node.js + WebSocket）
│   └── web/                # Next.js 前端应用
└── packages/
    └── shared/             # 共享类型定义和工具

• 前端: Next.js 16 + React 19 + TypeScript + Tailwind CSS
• UI 组件: shadcn/ui
• 数据收集: Node.js + Fastify + WebSocket + SQLite
• 可视化: Recharts + D3.js
• 国际化: next-intl（中/英）
• 部署: Docker + Docker Compose

MIT License © 2024 foru17

如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！