# MeshRay

> 去中心化 P2P 组网平台

> **💤 项目状态：个人练手的 Vibecoding 项目，目前已暂时搁置，后续有时间再继续完善。**

[![Version](https://img.shields.io/badge/version-2.3.x-blue.svg)](https://git.zkcoi.com/zkcoi/Meshray-Manager)
[![Status](https://img.shields.io/badge/status-paused-lightgrey.svg)](https://git.zkcoi.com/zkcoi/Meshray-Manager)
[![Go Version](https://img.shields.io/badge/go-1.21+-green.svg)](https://golang.org)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

---

## 🌟 核心特性

- ✅ **去中心化架构** — 无中心服务器，设备间直接 P2P 通信
- ✅ **智能穿透** — STUN + TURN 自动打洞，支持多种 NAT 类型
- ✅ **9 层降级传输** — 从 Direct-UDP 到 WS/WSS，链路不通自动切换
- ✅ **Mesh 中继** — 设备间中继转发，突破网络限制
- ✅ **安全加密** — WireGuard 官方库 + Ed25519 签名 + AES-256-GCM
- ✅ **DDNS 动态域名** — Cloudflare / 腾讯云 DNS 自动同步
- ✅ **Web 管理面板** — Go embed 内嵌静态资源，单文件部署
- ✅ **完整通知系统** — WebSocket 实时推送 + 持久化存储

---

## 🚀 快速开始

**Windows**:
```bash
start.bat
```

**Linux/Mac**:
```bash
chmod +x start.sh
./start.sh
```

**手动编译运行**:
```bash
go build -o meshray.exe ./cmd/meshray
./meshray.exe
```

访问：http://localhost:9531

> 前端已内嵌到 Go 二进制中，无需安装 Node.js 或单独编译前端。

---

## 📋 功能清单

### ✅ 已实现

| 功能模块 | 说明 |
|---------|------|
| 设备管理 | WG 设备增删改查、配置生成 |
| 组网管理 | 组网创建/加入/启停、MeshSeed 凭证 |
| 传输策略 | 9 层降级策略、自动/自定义/手动三种模式 |
| DDNS | Cloudflare + 腾讯云、IP 自动检测、TXT 记录 |
| 通知推送 | WebSocket 实时推送 + SQLite 持久化 |
| 备份恢复 | 创建/列表/恢复/删除/下载 |
| 系统设置 | 修改密码、重启核心、版本更新 |
| 仪表盘 | 网络状态、链路分布、系统信息 |

### ⏳ 待完善

| 功能模块 | 说明 |
|---------|------|
| 阿里云 DNS Provider | 依赖 libdns/aliyun 安装 |
| 备份恢复（完整实现） | 数据库导出 + 文件打包 |
| WebSocket 中间件 | 已有轮询，可增加实时推送 |

---

## 🛠️ 技术栈

### 后端
| 组件 | 技术 | 用途 |
|------|------|------|
| 语言 | Go 1.21+ | 主要编程语言 |
| Web 框架 | Gin | HTTP 服务器和路由 |
| ORM | GORM | 数据库操作 |
| 数据库 | SQLite (glebarez) | 嵌入式数据库 |
| 日志 | Zap | 结构化日志 |
| 配置 | Viper | 配置管理 |
| WireGuard | golang.zx2c4.com/wireguard | 用户态 WG 实现 |
| 认证 | bcrypt + golang-jwt | 密码加密 + JWT |
| NAT 穿透 | pion/turn, pion/webrtc | STUN/TURN/ICE |

### 前端
| 组件 | 技术 | 用途 |
|------|------|------|
| UI | 纯 JavaScript (ES6+) | 管理面板 |
| 静态资源 | Go embed | 内嵌到二进制 |

---

## 📖 文档

- 📗 [项目架构与详细介绍](docs/README.md)
- 📙 [完整功能开发总览](docs/README_开发完成总览.md)
- 📕 [功能验证与测试报告](docs/功能验证与测试报告.md)

---

## 🎯 使用场景

### 家庭组网
- 远程访问家中 NAS
- 搭建私有云服务
- 连接多个智能设备

### 企业办公
- 分支机构互联
- 远程办公接入
- 安全数据传输

### 开发测试
- 本地环境暴露公网
- 多设备联调测试
- Demo 演示环境

---

## 📊 项目结构

```
meshray/
├── cmd/                      # 可执行文件入口
├── core/                     # MeshRay-Core 建连层（9 层传输策略）
│   ├── connect/              # Direct-UDP / FakeTCP / TURN / STUN / ICE / WS
│   ├── transport/            # ConnManager + Relay 转发
│   └── plugins/wg/           # WireGuard 插件
├── internal/                 # 内部实现
│   ├── api/                  # REST API（Gin Handler + Middleware）
│   ├── ctr/                  # 调度中心（WG 设备管理）
│   ├── dnsprovider/          # DNS Provider 抽象层
│   ├── service/              # 业务逻辑层
│   └── store/sqlite/         # 数据库访问层
├── pkg/                      # 公共工具库
├── web/                      # 前端静态资源（Go embed 内嵌）
├── deploy/                   # Docker / Systemd 部署
├── docs/                     # 技术文档
└── config.yaml               # 运行配置
```

---

## 🔒 安全性

- ✅ **bcrypt 密码加密** — DefaultCost 强度
- ✅ **JWT 身份验证** — Token 过期机制
- ✅ **CORS 跨域控制** — 仅允许特定来源
- ✅ **SQL 参数化查询** — GORM 防注入
- ✅ **操作日志记录** — AuditLog 审计追踪

---

## 📈 性能指标

- **启动时间**: < 2 秒
- **API 响应**: < 100ms (本地)
- **数据库查询**: < 50ms
- **并发连接**: 支持 100+ 客户端
- **二进制体积**: 前端内嵌，单文件部署

---

## 🤝 开发

```bash
# 克隆项目
git clone https://git.zkcoi.com/zkcoi/Meshray-Manager.git
cd meshray

# 安装依赖
go mod download

# 运行
go run cmd/meshray/main.go
# 访问 http://localhost:9531
```

---

## 📄 许可证

MIT License

---

## 🙏 致谢

- [WireGuard](https://www.wireguard.com/) — 安全的 VPN 技术
- [Gin](https://gin-gonic.com/) — Go Web 框架
- [libdns](https://github.com/libdns/libdns) — DNS Provider 库
- [pion](https://github.com/pion) — WebRTC / TURN / STUN 实现