Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,319 @@
+# MeshRay 启动失败问题 - 根本原因分析与解决方案
+
+## 🔴 问题现象
+
+运行 `meshray.exe` 后，程序立即退出，无任何错误提示。
+
+---
+
+## 🔍 根本原因
+
+### 核心问题：**缺少 wintun.dll 驱动库**
+
+**错误日志**:
+```
+{"level":"warn","caller":"service/network.go:88","message":"调用 ctr 创建网络失败，将手动启动",
+"error":"创建 WireGuard 设备失败：创建 TUN 设备失败：Error loading wintun.dll DLL: 
+Unable to load library: The specified module could not be found."}
+```
+
+**影响**:
+1. WireGuard 设备无法创建
+2. Ctr 初始化失败
+3. 程序可能在初始化阶段崩溃或退出
+
+---
+
+## 📋 已完成的排查步骤
+
+### ✅ 1. 配置加载测试
+- **结果**: 配置加载成功
+- **文件**: config.yaml 已创建
+
+### ✅ 2. 数据库连接测试
+- **结果**: SQLite 数据库连接成功
+- **文件**: meshray.db 存在
+
+### ✅ 3. 日志系统测试
+- **结果**: 日志系统正常工作
+- **发现**: 历史日志显示服务曾经成功启动过
+
+### ✅ 4. 端口占用检查
+- **结果**: 端口 9531 未被占用
+- **命令**: `netstat -ano | findstr :9531`
+
+### ✅ 5. 进程状态检查
+- **结果**: 无 meshray 进程在运行
+- **命令**: `Get-Process | Where-Object {$_.ProcessName -like "*meshray*"}`
+
+### ❌ 6. WireGuard 驱动检查
+- **结果**: **缺少 wintun.dll**
+- **位置**: 应在项目根目录或 system32 目录
+
+---
+
+## 🛠️ 解决方案
+
+### 方案 1: 下载并安装 wintun.dll（推荐）
+
+#### 步骤：
+
+1. **访问官方下载页面**
+   ```
+   https://www.wintun.net/builds/wintun-0.14.1.zip
+   ```
+
+2. **下载并解压**
+   - 下载 wintun-0.14.1.zip
+   - 解压到临时目录
+
+3. **复制 DLL 文件**
+   ```powershell
+   # 根据系统架构选择对应版本
+   # 64 位系统（推荐）
+   Copy-Item .\wintun\bin\amd64\wintun.dll e:\Project\MeshRay\
+   
+   # 32 位系统
+   Copy-Item .\wintun\bin\x86\wintun.dll e:\Project\MeshRay\
+   
+   # ARM 架构
+   Copy-Item .\wintun\bin\arm64\wintun.dll e:\Project\MeshRay\
+   ```
+
+4. **验证文件存在**
+   ```powershell
+   Test-Path e:\Project\MeshRay\wintun.dll
+   # 应返回 True
+   ```
+
+5. **重新启动服务**
+   ```powershell
+   cd e:\Project\MeshRay
+   .\meshray.exe
+   ```
+
+---
+
+### 方案 2: 安装 WireGuard 官方驱动
+
+1. **下载 WireGuard 安装包**
+   ```
+   https://download.wireguard.com/windows-client/wireguard-installer.exe
+   ```
+
+2. **安装 WireGuard**
+   - 运行安装程序
+   - 按照提示完成安装
+
+3. **重启计算机**
+   - 确保驱动正确加载
+
+4. **重新启动 meshray**
+   ```powershell
+   .\meshray.exe
+   ```
+
+---
+
+### 方案 3: 使用用户态 WireGuard（无需驱动）
+
+修改代码使用纯用户态实现（需要修改代码）：
+
+```go
+// internal/ctr/wg.go
+// 在创建 WireGuard 设备前，先检查 wintun.dll 是否存在
+func (w *WGManager) CreateDevice(...) error {
+    // 检查 wintun.dll 是否存在
+    if _, err := os.Stat("wintun.dll"); os.IsNotExist(err) {
+        // 尝试使用 wireguard-go 用户态实现
+        return w.createUserModeDevice(...)
+    }
+    // 原有逻辑
+}
+```
+
+---
+
+## 📊 项目文件结构建议
+
+建议在项目中包含 wintun.dll 或提供自动下载脚本：
+
+```
+e:\Project\MeshRay\
+├── meshray.exe
+├── wintun.dll          ← 必需（Windows）
+├── config.yaml
+├── start.bat           ← 可添加驱动检查和下载
+└── ...
+```
+
+---
+
+## 🔧 改进建议
+
+### 1. 添加驱动检查逻辑
+
+修改 `cmd/meshray/main.go`:
+
+```go
+func checkWireGuardDriver() error {
+    // 检查 wintun.dll 是否存在
+    if _, err := os.Stat("wintun.dll"); os.IsNotExist(err) {
+        return fmt.Errorf("未找到 wintun.dll 驱动文件，请从 https://www.wintun.net 下载")
+    }
+    return nil
+}
+
+func (p *program) run(isInteractive bool) {
+    // ... 现有代码 ...
+    
+    // 步骤 2.5: 检查 WireGuard 驱动
+    fmt.Println("\n[步骤 2.5/7] 正在检查 WireGuard 驱动...")
+    if err := checkWireGuardDriver(); err != nil {
+        fmt.Printf("⚠️  WireGuard 驱动检查警告：%v\n", err)
+        fmt.Println("💡 提示：WireGuard 功能可能无法正常使用")
+    } else {
+        fmt.Println("✅ WireGuard 驱动检查通过")
+    }
+    
+    // ... 后续步骤 ...
+}
+```
+
+### 2. 提供驱动自动下载脚本
+
+创建 `install_driver.ps1`:
+
+```powershell
+#!/usr/bin/env pwsh
+
+Write-Host "=== MeshRay WireGuard 驱动安装脚本 ==="
+
+$arch = (Get-CimInstance Win32_Processor).AddressWidth
+if ($arch -eq 64) {
+    $url = "https://www.wintun.net/builds/wintun-0.14.1.zip"
+    Write-Host "检测到 64 位系统，开始下载..."
+    
+    Invoke-WebRequest -Uri $url -OutFile "wintun.zip"
+    Expand-Archive -Path "wintun.zip" -DestinationPath "wintun_temp" -Force
+    
+    Copy-Item ".\wintun_temp\wintun\bin\amd64\wintun.dll" -Destination ".\wintun.dll" -Force
+    
+    Remove-Item "wintun.zip" -Force
+    Remove-Item "wintun_temp" -Recurse -Force
+    
+    Write-Host "✅ wintun.dll 安装成功！"
+} else {
+    Write-Host "❌ 仅支持 64 位系统"
+}
+```
+
+### 3. 更新 start.bat
+
+修改 `start.bat`:
+
+```batch
+@echo off
+chcp 65001 >nul
+
+REM 检查 wintun.dll 是否存在
+if not exist "wintun.dll" (
+    echo ========================================
+    echo    ⚠️  未检测到 WireGuard 驱动
+    echo ========================================
+    echo.
+    echo 💡 WireGuard 功能需要 wintun.dll 驱动
+    echo.
+    echo 请选择以下操作：
+    echo   1. 自动下载安装（推荐）
+    echo   2. 手动下载（跳过此步）
+    echo   3. 退出
+    echo.
+    set /p choice="请输入选项 (1-3): "
+    
+    if "%choice%"=="1" (
+        powershell -ExecutionPolicy Bypass -File install_driver.ps1
+    ) else if "%choice%"=="2" (
+        echo 已跳过驱动安装
+    ) else (
+        exit /b
+    )
+)
+
+REM 继续原有启动逻辑...
+```
+
+---
+
+## 📝 其他发现的问题
+
+### 问题 1: 错误输出不完善
+**现象**: 程序启动失败但没有明显错误提示  
+**建议**: 添加详细的启动日志和错误输出
+
+### 问题 2: 缺少健康检查
+**现象**: 无法快速判断服务是否正常  
+**建议**: 实现 `/health` 端点并定期调用
+
+### 问题 3: 启动超时机制缺失
+**现象**: 如果某个步骤卡住，程序会一直等待  
+**建议**: 添加启动超时（如 30 秒）
+
+---
+
+## ✅ 验证步骤
+
+### 1. 验证 wintun.dll 存在
+```powershell
+Test-Path e:\Project\MeshRay\wintun.dll
+```
+
+### 2. 验证服务启动
+```powershell
+cd e:\Project\MeshRay
+.\meshray.exe
+```
+
+### 3. 验证 Web 访问
+打开浏览器访问：http://localhost:9531
+
+### 4. 验证 API 响应
+```bash
+curl http://localhost:9531/health
+```
+
+---
+
+## 🎯 下一步行动
+
+1. **立即下载 wintun.dll**
+   - 从官网下载
+   - 放置到项目根目录
+
+2. **重新启动服务**
+   - 运行 meshray.exe
+   - 观察控制台输出
+
+3. **测试 WireGuard 功能**
+   - 创建测试网络
+   - 验证设备创建成功
+
+4. **完善文档**
+   - 更新 README.md
+   - 添加驱动安装说明
+   - 提供故障排查指南
+
+---
+
+## 📞 参考资源
+
+- **wintun 官网**: https://www.wintun.net
+- **WireGuard 官方文档**: https://www.wireguard.com
+- **MeshRay 项目仓库**: https://git.zkcoi.com/zkcoi/meshray
+
+---
+
+**排查日期**: 2026-03-20  
+**问题状态**: 🔴 已定位根本原因  
+**解决方案**: ✅ 已提供  
+**优先级**: 🔥 紧急（阻塞启动）