404 lines
7.8 KiB
Markdown
404 lines
7.8 KiB
Markdown
# 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 组网更简单！* ✨
|