# 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 组网更简单！* ✨