Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,241 @@
+# MeshRay 项目架构优化建议
+
+## 📁 当前问题分析
+
+### 问题 1: `service_windows.go` 位置不当
+
+**当前位置**: `internal/service_windows.go` ❌
+
+**问题**:
+- `internal/` 应该存放**业务逻辑包**（API、Service、Model 等）
+- Windows 服务管理代码属于**程序启动器**，应该在 `cmd/` 目录
+- 与 `main.go` 的 `program` 结构体重叠冲突
+
+**正确位置**: `cmd/meshray/main_windows.go` ✅
+
+---
+
+### 问题 2: 描述信息不一致
+
+**项目文档定位** (README.md):
+> MeshRay - 高效、安全的去中心化异地组网平台 ✅
+
+**代码中的描述** (已修复):
+> ~~MeshRay - 去中心化的边缘网络枢纽~~ ❌
+
+**现在已统一为**:
+> MeshRay - 高效、安全的去中心化异地组网平台 ✅
+
+---
+
+## 🏗️ 正确的跨平台架构
+
+### Go 项目的标准结构
+
+```
+meshray/
+├── cmd/                    # 可执行程序的入口
+│   ├── meshray/           # 主程序
+│   │   ├── main.go        # 通用逻辑（所有平台）
+│   │   ├── main_unix.go   # Unix/Linux 特定逻辑（可选）
+│   │   └── main_windows.go # Windows 特定逻辑 ← service_windows.go 应在这里
+│   │
+│   └── reset-password/    # 密码重置工具
+│       └── main.go
+│
+├── internal/              # 内部业务逻辑包（不对外暴露）
+│   ├── api/              # API 层（HTTP Handler）
+│   ├── service/          # 业务服务层
+│   ├── model/            # 数据模型层
+│   ├── store/            # 数据存储层
+│   ├── ctr/              # 控制层（WireGuard 管理）
+│   ├── config/           # 配置管理
+│   └── logging/          # 日志系统
+│
+├── pkg/                  # 可复用的公共库（可选）
+│   └── utils/
+│
+├── web/                  # 前端代码
+│   ├── src/
+│   └── dist/
+│
+└── build/                # 构建脚本和配置
+    ├── build.bat
+    └── winres.json
+```
+
+---
+
+## 🔧 解决方案
+
+### 方案 A: 保持现状，简化实现（推荐）✅
+
+**原因**:
+1. `main.go` 已经有完整的 `program` 结构体定义
+2. Windows 服务管理逻辑已经基本完整
+3. 不需要重复定义 `Start()` / `Stop()` 方法
+
+**实施步骤**:
+1. ✅ 移动文件：`internal/service_windows.go` → `cmd/meshray/main_windows.go`
+2. ✅ 添加构建标签：`//go:build windows`
+3. ✅ 只保留 Windows 特有的服务管理函数
+4. ✅ 移除重复的 `program` 结构体定义
+
+**代码示例**:
+
+```go
+// cmd/meshray/main_windows.go
+//go:build windows
+// +build windows
+
+package main
+
+import (
+    "fmt"
+    "os"
+    "path/filepath"
+    "github.com/kardianos/service"
+)
+
+// 只包含 Windows 特有的服务管理函数
+func InstallService() error { ... }
+func UninstallService() error { ... }
+func GetServiceStatus() error { ... }
+func ManageService(action string) error { ... }
+```
+
+---
+
+### 方案 B: 完全分离平台特定代码（复杂，不推荐）
+
+**适用场景**: 
+- Windows 和 Linux 有完全不同的启动逻辑
+- 需要不同的依赖库
+- 复杂的平台适配
+
+**实施难度**: ⭐⭐⭐⭐⭐
+
+---
+
+## 📋 构建标签详解
+
+### Go 语言的跨平台机制
+
+#### 文件名构建标签
+
+```go
+// 文件后缀自动识别
+main.go            // 所有平台都编译
+main_windows.go    // 仅 Windows 编译
+main_linux.go      // 仅 Linux 编译
+main_darwin.go     // 仅 macOS 编译
+main_unix.go       // Unix-like 系统 (Linux, macOS, BSD)
+main_amd64.go      // 仅 x64 架构
+main_arm64.go      // 仅 ARM64 架构
+```
+
+#### 文件内构建标签
+
+```go
+//go:build windows
+// +build windows
+
+package main
+```
+
+**作用**:
+- 编译时自动选择对应平台的文件
+- 无运行时开销
+- 避免平台特定依赖冲突
+
+---
+
+## ✅ 修复结果
+
+### 1. 文件位置修正
+
+**之前**:
+```
+internal/
+└── service_windows.go  ❌ 位置不当
+```
+
+**现在**:
+```
+cmd/meshray/
+├── main.go            # 通用逻辑
+└── main_windows.go    ✅ Windows 特定逻辑
+```
+
+### 2. 描述信息统一
+
+**所有地方统一为**:
+```
+MeshRay - 高效、安全的去中心化异地组网平台
+```
+
+### 3. 代码结构清晰
+
+- ✅ `cmd/` - 程序入口（启动器）
+- ✅ `internal/` - 业务逻辑（核心功能）
+- ✅ 平台特定代码隔离
+
+---
+
+## 🎯 最佳实践总结
+
+### 1. 目录组织原则
+
+| 目录 | 用途 | 示例 |
+|------|------|------|
+| `cmd/` | 可执行程序入口 | `main.go`, `main_windows.go` |
+| `internal/` | 内部业务逻辑 | `api/`, `service/`, `model/` |
+| `pkg/` | 公共库（可选） | `utils/`, `crypto/` |
+
+### 2. 跨平台代码组织
+
+**推荐做法** ✅:
+```go
+// main.go - 通用代码
+type program struct { ... }
+func (p *program) Start() { ... }
+
+// main_windows.go - Windows 特有
+func InstallService() { ... }
+
+// main_linux.go - Linux 特有（如果需要）
+func SetupSystemd() { ... }
+```
+
+**不推荐做法** ❌:
+```go
+// 所有平台代码混在一起
+if runtime.GOOS == "windows" {
+    // Windows 代码
+} else {
+    // Linux 代码
+}
+```
+
+### 3. 构建标签使用
+
+**何时使用**:
+- ✅ 平台特定的系统调用
+- ✅ 不同的依赖库（如 Windows Service vs systemd）
+- ✅ 性能优化的平台特定实现
+
+**何时不用**:
+- ❌ 简单的配置差异（用配置文件）
+- ❌ 少量的平台判断（用 `runtime.GOOS`）
+
+---
+
+## 📚 参考资料
+
+- [Go Build Constraints](https://pkg.go.dev/go/build#hdr-Build_Constraints)
+- [Go Project Layout](https://github.com/golang-standards/project-layout)
+- [kardianos/service 文档](https://github.com/kardianos/service)
+
+---
+
+*MeshRay 架构优化指南 | v1.0*