Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,403 @@
+# MeshRay 运行指南
+
+**更新时间**: 2026-03-24  
+**状态**: ✅ **可以正常运行**
+
+---
+
+## 🚀 **快速启动**
+
+### **方式一：使用 go run（推荐）**
+
+```bash
+# 在项目根目录执行
+cd e:\Project\MeshRay
+go run ./cmd/meshray
+```
+
+**优点**:
+- ✅ 不会被 Windows SmartScreen 拦截
+- ✅ 开发调试方便
+- ✅ 可以看到实时日志输出
+
+**访问地址**: http://localhost:9531
+
+---
+
+### **方式二：运行编译后的 exe**
+
+```bash
+# 直接运行
+.\meshray.exe
+```
+
+**如果遇到"应用程序控制策略已阻止此文件"**：
+
+#### **解决方案 1：右键解锁**
+1. 右键点击 `meshray.exe`
+2. 选择"属性"
+3. 在底部勾选"解除锁定"
+4. 点击"确定"
+5. 再次运行
+
+#### **解决方案 2：使用数字证书签名**
+需要购买代码签名证书对 exe 进行签名（适合生产环境）
+
+#### **解决方案 3：临时禁用 SmartScreen**
+不推荐，会降低系统安全性
+
+---
+
+## ✅ **验证运行状态**
+
+### **成功启动的标志**
+
+```
+MeshRay v2.0.0 - Starting...
+✅ 配置加载成功
+✅ 日志系统初始化成功
+正在连接数据库...
+✅ 数据库初始化成功
+正在初始化管理员账户...
+✅ 管理员账户已存在（用户名：admin）
+正在初始化管理策...
+✅ 默认策略初始化成功
+🚀 正在启动 MeshRay...
+🌐 MeshRay 启动成功！
+📍 访问地址：http://localhost:9531
+💡 提示：请在浏览器中打开上述地址访问管理面板
+```
+
+---
+
+### **检查服务是否正常**
+
+#### **1. 访问登录页面**
+```
+http://localhost:9531
+```
+应该看到登录界面
+
+#### **2. 健康检查接口**
+```bash
+curl http://localhost:9531/health
+```
+
+**预期响应**:
+```json
+{
+  "status": "ok"
+}
+```
+
+#### **3. 测试 API**
+```bash
+# 获取统计数据（需要先登录）
+curl http://localhost:9531/api/v1/dashboard/stats
+```
+
+---
+
+## 🔧 **常见问题解决**
+
+### **问题 1：端口被占用**
+
+**错误信息**:
+```
+bind: address already in use
+```
+
+**解决方案**:
+
+1. **查找占用端口的进程**:
+```powershell
+netstat -ano | findstr :9531
+```
+
+2. **杀死占用端口的进程**:
+```powershell
+taskkill /F /PID <进程 ID>
+```
+
+3. **或者修改配置端口**:
+编辑 `configs/config.yaml`:
+```yaml
+server:
+  port: 9532  # 改为其他端口
+```
+
+---
+
+### **问题 2：数据库锁定**
+
+**错误信息**:
+```
+database is locked
+```
+
+**解决方案**:
+
+1. **停止应用**
+
+2. **删除数据库锁文件**:
+```powershell
+rm data\*.db-shm
+rm data\*.db-wal
+```
+
+3. **重新启动应用**
+
+---
+
+### **问题 3：前端资源找不到**
+
+**错误信息**:
+```
+open web/dist/index.html: The system cannot find the path specified.
+```
+
+**解决方案**:
+
+1. **重新编译前端**:
+```bash
+cd web
+npm run build
+```
+
+2. **确保 dist 目录存在**:
+```bash
+ls web/dist
+```
+
+3. **重新编译后端**:
+```bash
+go build -o meshray.exe ./cmd/meshray
+```
+
+---
+
+### **问题 4：托盘图标错误**
+
+**错误信息**:
+```
+ERROR systray: Unable to set icon
+```
+
+**说明**: 
+- ⚠️ 这是 Windows 11 的已知问题
+- ✅ **不影响功能使用**
+- ✅ 可以安全忽略
+
+**解决方案**（可选）:
+如果不想看到这个错误，可以在 `internal/tray/tray.go` 中注释掉设置图标的代码。
+
+---
+
+## 📊 **运行日志示例**
+
+### **正常启动日志**
+
+```
+2026-03-24T10:30:00.000+0800    INFO    api/server.go:150      MeshRay v2.0.0 - Starting...
+2026-03-24T10:30:00.001+0800    INFO    config/config.go:45    ✅ 配置加载成功
+2026-03-24T10:30:00.002+0800    INFO    logging/zap.go:30      ✅ 日志系统初始化成功
+2026-03-24T10:30:00.003+0800    INFO    store/sqlite.go:78     正在连接数据库...
+2026-03-24T10:30:00.010+0800    INFO    store/sqlite.go:85     ✅ 数据库初始化成功
+2026-03-24T10:30:00.011+0800    INFO    service/user.go:50     正在初始化管理员账户...
+2026-03-24T10:30:00.015+0800    INFO    service/user.go:65     ✅ 管理员账户已存在（用户名：admin）
+2026-03-24T10:30:00.016+0800    INFO    service/policy.go:40   正在初始化管理策...
+2026-03-24T10:30:00.020+0800    INFO    service/policy.go:55   ✅ 默认策略初始化成功
+2026-03-24T10:30:00.021+0800    INFO    api/server.go:200      🚀 正在启动 MeshRay...
+2026-03-24T10:30:00.025+0800    INFO    api/server.go:210      🌐 MeshRay 启动成功！
+2026-03-24T10:30:00.026+0800    INFO    api/server.go:211      📍 访问地址：http://localhost:9531
+2026-03-24T10:30:00.027+0800    INFO    api/server.go:212      💡 提示：请在浏览器中打开上述地址访问管理面板
+```
+
+---
+
+## 🎯 **首次使用**
+
+### **1. 登录系统**
+
+**默认管理员账户**:
+- 用户名：`admin`
+- 密码：`admin123`
+
+**访问**: http://localhost:9531
+
+---
+
+### **2. 创建第一个组网**
+
+1. 登录后进入 Dashboard
+2. 点击左侧菜单"组网管理"
+3. 点击"创建组网"按钮
+4. 填写组网信息：
+   - 名称：例如"我的第一个网络"
+   - 描述：可选
+   - 策略：选择默认策略
+5. 点击"提交"
+
+---
+
+### **3. 添加设备**
+
+1. 进入刚创建的组网详情
+2. 点击"添加设备"
+3. 填写设备信息：
+   - 名称：例如"我的电脑"
+   - IP 地址：自动分配或手动指定
+4. 点击"提交"
+5. 下载设备配置文件（.conf 文件）
+
+---
+
+### **4. 配置 WireGuard**
+
+**Windows 客户端**:
+
+1. 下载并安装 WireGuard: https://www.wireguard.com/install/
+2. 打开 WireGuard 客户端
+3. 点击"导入隧道"
+4. 选择刚才下载的 `.conf` 文件
+5. 点击"激活"按钮
+
+**Linux 客户端**:
+
+```bash
+# 复制配置文件
+sudo cp your-network.conf /etc/wireguard/
+
+# 启动 WireGuard
+sudo wg-quick up your-network
+
+# 查看状态
+sudo wg show
+```
+
+---
+
+## 📈 **性能监控**
+
+### **查看系统状态**
+
+访问 Dashboard 可以看到：
+- ✅ 组网数量统计
+- ✅ 设备在线状态
+- ✅ CPU/内存/磁盘使用率
+- ✅ 网络流量监控
+- ✅ 最近日志
+
+---
+
+### **查看日志**
+
+**方法 1**: 通过 Web 界面
+- 访问 `/settings/logs`
+
+**方法 2**: 查看日志文件
+```bash
+# 日志文件位置
+logs\meshray.log
+```
+
+**方法 3**: 实时日志输出
+```bash
+# go run 模式下会自动输出到终端
+```
+
+---
+
+## 🔐 **安全建议**
+
+### **1. 修改默认密码**
+
+首次登录后立即修改：
+1. 点击右上角用户头像
+2. 选择"个人信息"
+3. 修改密码
+4. 保存
+
+---
+
+### **2. 配置 HTTPS（生产环境）**
+
+编辑 `configs/config.yaml`:
+```yaml
+server:
+  https:
+    enabled: true
+    cert_file: /path/to/cert.pem
+    key_file: /path/to/key.pem
+```
+
+---
+
+### **3. 配置防火墙**
+
+**Windows**:
+```powershell
+# 允许 9531 端口
+New-NetFirewallRule -DisplayName "MeshRay" -Direction Inbound -LocalPort 9531 -Protocol TCP -Action Allow
+```
+
+**Linux**:
+```bash
+sudo ufw allow 9531/tcp
+```
+
+---
+
+## 🛠️ **开发模式**
+
+### **前后端同时开发**
+
+**终端 1 - 后端**:
+```bash
+cd e:\Project\MeshRay
+go run ./cmd/meshray
+```
+
+**终端 2 - 前端**:
+```bash
+cd e:\Project\MeshRay\web
+npm run dev
+```
+
+**访问**:
+- 后端 API: http://localhost:9531
+- 前端开发服务器：http://localhost:5173
+
+**前端会自动代理到后端**:
+- `vite.config.js` 中已配置代理
+- 所有 `/api/*` 请求会转发到后端
+
+---
+
+## 📝 **总结**
+
+### **推荐运行方式**
+
+| 场景 | 方式 | 命令 |
+|------|------|------|
+| **开发调试** | go run | `go run ./cmd/meshray` |
+| **生产部署** | 编译 exe | `go build -o meshray.exe` |
+| **快速测试** | go run | `go run ./cmd/meshray` |
+
+---
+
+### **关键信息**
+
+- ✅ **默认端口**: 9531
+- ✅ **默认账户**: admin / admin123
+- ✅ **数据库位置**: `data/meshray.db`
+- ✅ **日志位置**: `logs/meshray.log`
+- ✅ **配置文件**: `configs/config.yaml`
+
+---
+
+**运行状态**: ✅ **可以正常访问**  
+**访问地址**: http://localhost:9531  
+**下一步**: 在浏览器中打开上述地址开始使用！🚀
+
+*MeshRay - 让 P2P 组网更简单！* ✨