# MeshRay Service 层架构详解
**文档版本**: v1.0
**更新时间**: 2026-03-24
**适用范围**: `internal/service/` 模块
---
## 📊 Service 层在整体架构中的位置
```
┌─────────────────────────────────────────────┐
│ Web UI（Vue 3 + Element Plus） │
└────────────────┬────────────────────────────┘
│ REST API / WebSocket
┌────────────────▼────────────────────────────┐
│ API Handler（Gin 接入层） │
│ - network_handler.go │
│ - device_handler.go │
│ - user_handler.go │
│ - service_handler.go │
└────────────────┬────────────────────────────┘
│ 函数调用
┌────────────────▼────────────────────────────┐
│ Service Layer（业务逻辑层）⭐核心 │
│ - NetworkService ← 组网管理 │
│ - DeviceService ← 设备管理 │
│ - PolicyService ← 策略管理 │
│ - ExternalService ← 外部服务管理 │
│ - UserService ← 用户认证 │
│ - MonitorService ← 监控告警 │
│ - DDNSService ← DDNS 同步 │
│ - AuditService ← 审计日志 │
└──────┬──────────────────────────────────────┘
│
├──────────────────────────────────────┐
│ │
┌──────▼──────┐ ┌────────▼────────┐
│ Store Layer │ │ Ctr Layer │
│ (数据持久化) │ │ (实时控制) │
│ │ │ │
│ - networks │ │ - wgctrl │
│ - devices │ │ - core gRPC │
│ - policies │ │ - 实时调度 │
│ - users │ │ │
│ - services │ │ │
└─────────────┘ └─────────────────┘
```
**关键点**：
- ✅ **Service 层是业务逻辑的核心**
- ✅ **Ctr 层只是 Service 层调用的一个执行器**
- ✅ **很多 Service 功能完全不依赖 Ctr**（如用户登录、策略校验）
---
## 🎯 Service 层模块划分
### **完整的服务模块清单**
```
internal/service/
├── service.go # Service 层总入口和依赖注入
│ type ServiceProvider struct {
│ network *NetworkService
│ device *DeviceService
│ policy *PolicyService
│ external *ExternalService
│ user *UserService
│ monitor *MonitorService
│ ddns *DDNSService
│ audit *AuditService
│ }
│
├── network.go # 组网管理服务
│ ├── ListNetworks() []Network # 获取网络列表
│ ├── CreateNetwork() (*Network, error) # 创建网络
│ ├── DeleteNetwork() error # 删除网络
│ ├── UpdateNetwork() error # 更新网络配置
│ ├── GenerateMeshSeed() (*MeshSeed, error) # 生成 MeshSeed
│ ├── ParseMeshSeed() (*MeshSeed, error) # 解析 MeshSeed
│ └── JoinNetwork() error # 加入网络
│
├── device.go # 设备管理服务
│ ├── ListDevices() []Device # 设备列表
│ ├── AddDevice() (*Device, error) # 添加设备
│ ├── RemoveDevice() error # 删除设备
│ ├── RegenerateKey() error # 重新生成密钥
│ ├── GetDeviceConfig() (*WGConfig, error) # 获取 WG 配置
│ └── ImportDevice() error # 导入现有设备
│
├── policy.go # 策略管理服务
│ ├── ListPolicies() []Policy # 策略列表
│ ├── SetPolicy() error # 设置传输策略
│ ├── GetPolicy() (*Policy, error) # 获取策略
│ ├── ValidatePolicy() error # 验证策略合法性
│ ├── GetEffectivePolicy() (*Policy, error) # 获取生效策略
│ └── ResetPolicy() error # 重置策略
│
├── external_service.go # 外部服务管理服务
│ ├── ListServices() []ExternalService # 服务列表
│ ├── AddService() error # 添加服务
│ ├── UpdateService() error # 更新服务
│ ├── DeleteService() error # 删除服务
│ ├── TestConnectivity() error # 测试连通性
│ ├── GetServiceSchema() (string, error) # 获取 JSON Schema
│ └── ListByCategory() []ExternalService # 按分类筛选
│
├── user.go # 用户认证服务
│ ├── Login() (string, error) # 登录 → JWT Token
│ ├── Register() error # 注册
│ ├── ChangePassword() error # 修改密码
│ ├── VerifyToken() (*Claims, error) # 验证 JWT
│ ├── RefreshToken() (string, error) # 刷新 Token
│ └── GetUserByID() (*User, error) # 根据 ID 获取用户
│
├── monitor.go # 监控告警服务
│ ├── GetSystemStats() (*SystemStats, error) # 系统统计
│ ├── GetNetworkStatus() (*NetworkStatus, error) # 网络状态
│ ├── CheckAlertRules() ([]Alert, error) # 检查告警规则
│ ├── SendAlert() error # 发送告警
│ ├── ListAlertRules() []AlertRule # 告警规则列表
│ └── AddAlertRule() error # 添加告警规则
│
├── ddns.go # DDNS 服务
│ ├── SyncDDNS() error # 同步 DDNS 记录
│ ├── GetDDNSStatus() (*DDNSStatus, error) # 获取状态
│ ├── RefreshDDNS() error # 刷新记录
│ ├── TestDNSProvider() error # 测试 DNS 服务商
│ └── GetDDNSHistory() []DDNSRecord # 历史记录
│
└── audit.go # 审计日志服务
├── LogAction() error # 记录操作日志
├── ListAuditLogs() []AuditLog # 查询日志
├── ExportAuditLogs() ([]byte, error) # 导出日志
├── GetAuditStats() (*AuditStats, error) # 统计数据
└── CleanOldLogs() error # 清理旧日志
```
---
## 📋 每个 Service 的职责详解
### **1. NetworkService - 组网管理**
**职责**：
- ✅ 组网的创建、删除、更新
- ✅ MeshSeed 的生成和解析
- ✅ 网络配置的持久化
- ✅ 调用 Ctr 执行实际操作
**核心方法示例**：
```go
// CreateNetwork 创建网络
func (s *NetworkService) CreateNetwork(req CreateNetworkRequest) (*Network, error) {
// ① 业务规则校验
if req.Name == "" {
return nil, errors.New("组网名称不能为空")
}
// 检查名称是否重复
var existing Network
err := s.store.DB().Where("name = ?", req.Name).First(&existing).Error
if err == nil {
return nil, errors.New("组网名称已存在")
}
// ② 数据生成
networkID := snowflake.Generate()
secret := generateSecureSecret() // 32 字节随机
// ③ 保存到数据库
network := &model.Network{
ID: networkID,
Name: req.Name,
Secret: secret,
Subnet: req.Subnet,
STUNServers: []string{"stun.l.google.com:19302"},
CreatedAt: time.Now(),
}
err = s.store.DB().Create(network).Error
if err != nil {
return nil, err
}
// ④ 调用 ctr 执行（事务外，失败需回滚）
err = s.ctrClient.CreateNetwork(networkID, network.ToConfig())
if err != nil {
// 回滚：删除刚创建的 network
s.store.DB().Delete(network)
return nil, fmt.Errorf("调用 ctr 失败：%w", err)
}
return network, nil
}
// GenerateMeshSeed 生成组网凭证
func (s *NetworkService) GenerateMeshSeed(networkID uint64) (*MeshSeed, error) {
// ① 查询网络信息
var network model.Network
err := s.store.DB().First(&network, networkID).Error
if err != nil {
return nil, errors.New("网络不存在")
}
// ② 生成 SeedID（16 字节随机 Base64）
seedID := generateRandomBase64(16)
// ③ Ed25519 签名
signature := ed25519.Sign(privateKey, []byte(network.Secret))
// ④ AES-GCM 加密配置
ciphertext := aesGCM.Encrypt(network.ToJSON())
// ⑤ 构建 MeshSeed
meshSeed := &MeshSeed{
SeedID: seedID,
NetworkID: networkID,
Signature: signature,
Ciphertext: ciphertext,
IssuedAt: time.Now(),
ExpiresAt: time.Now().Add(365 * 24 * time.Hour),
}
// ⑥ 保存到数据库
s.store.DB().Create(&model.MeshSeed{
NetworkID: networkID,
Data: meshSeed.ToJSON(),
})
return meshSeed, nil
// ✅ 完全不需要调用 ctr！
}
```
---
### **2. DeviceService - 设备管理**
**职责**：
- ✅ WireGuard 密钥对生成
- ✅ 设备信息管理
- ✅ WG 配置文件生成
- ✅ 调用 Ctr 添加 Peer
**核心方法示例**：
```go
// AddDevice 添加设备
func (s *DeviceService) AddDevice(networkID uint64, name string) (*Device, error) {
// ① 查询网络
var network model.Network
err := s.store.DB().First(&network, networkID).Error
if err != nil {
return nil, errors.New("网络不存在")
}
// ② 生成 WG 密钥对
privateKey, publicKey, err := wgtypes.GenerateKey()
if err != nil {
return nil, err
}
// ③ 分配 IP（从子网中自动分配）
ip := allocateIP(network.Subnet)
// ④ 生成设备 ID
deviceID := snowflake.Generate()
// ⑤ 保存到数据库
device := &model.Device{
ID: deviceID,
NetworkID: networkID,
Name: name,
PublicKey: publicKey.String(),
PrivateKey: encryptPrivateKey(privateKey), // 加密存储
IP: ip,
AllowedIPs: []string{ip + "/32"},
}
err = s.store.DB().Create(device).Error
if err != nil {
return nil, err
}
// ⑥ 调用 ctr 添加 Peer（可选，如果立即上线）
if req.ImmediateConnect {
err = s.ctrClient.AddPeer(networkID, device.PublicKey, device.AllowedIPs)
if err != nil {
s.store.DB().Delete(device)
return nil, fmt.Errorf("调用 ctr 失败：%w", err)
}
}
return device, nil
}
// GetDeviceConfig 获取设备配置（生成 WG 配置文件）
func (s *DeviceService) GetDeviceConfig(deviceID uint64) (string, error) {
// ① 查询设备信息
var device model.Device
err := s.store.DB().Preload("Network").First(&device, deviceID).Error
if err != nil {
return "", errors.New("设备不存在")
}
// ② 解密私钥
privateKey := decryptPrivateKey(device.PrivateKey)
// ③ 生成 WG 配置
config := fmt.Sprintf(`[Interface]
PrivateKey = %s
Address = %s
ListenPort = 51820
[Peer]
PublicKey = %s
AllowedIPs = %s
Endpoint = %s:51820
`, privateKey, device.IP, device.Network.PublicKey, device.AllowedIPs, device.Network.Endpoint)
return config, nil
// ✅ 纯业务逻辑，不需要调用 ctr！
}
```
---
### **3. UserService - 用户认证（完全不依赖 Ctr）**
**职责**：
- ✅ 用户注册、登录
- ✅ JWT Token 生成和验证
- ✅ 密码加密存储
- ✅ 审计日志记录
**核心方法示例**：
```go
// Login 用户登录
func (s *UserService) Login(username, password string) (string, error) {
// ① 查询用户
var user model.User
err := s.store.DB().Where("username = ?", username).First(&user).Error
if err != nil {
return "", errors.New("用户名或密码错误")
}
// ② 验证密码（bcrypt）
err = bcrypt.CompareHashAndPassword([]byte(user.PasswordHash), []byte(password))
if err != nil {
return "", errors.New("用户名或密码错误")
}
// ③ 生成 JWT Token
claims := jwt.Claims{
UserID: user.ID,
Username: user.Username,
Role: user.Role,
}
token := jwt.GenerateToken(claims, jwtSecret, 24*time.Hour)
// ④ 记录登录日志
s.auditService.LogAction(user.ID, "login", "用户登录成功")
return token, nil
// ✅ 完全不需要调用 ctr！
}
// Register 用户注册
func (s *UserService) Register(username, password, email string) error {
// ① 检查用户名是否已存在
var existing model.User
err := s.store.DB().Where("username = ?", username).First(&existing).Error
if err == nil {
return errors.New("用户名已存在")
}
// ② 密码加密（bcrypt）
hash, err := bcrypt.GenerateFromPassword([]byte(password), 12)
if err != nil {
return err
}
// ③ 创建用户
user := &model.User{
Username: username,
Email: email,
PasswordHash: string(hash),
Role: "user",
}
err = s.store.DB().Create(user).Error
if err != nil {
return err
}
// ④ 记录注册日志
s.auditService.LogAction(user.ID, "register", "用户注册成功")
return nil
// ✅ 完全不需要调用 ctr！
}
```
---
### **4. PolicyService - 策略管理（部分依赖 Ctr）**
**职责**：
- ✅ 9 层传输策略配置
- ✅ 策略合法性校验
- ✅ 策略持久化
- ✅ 调用 Ctr 应用策略
**核心方法示例**：
```go
// SetPolicy 设置传输策略
func (s *PolicyService) SetPolicy(networkID uint64, policy PolicyConfig) error {
// ① 业务规则校验
if err := s.validatePolicy(policy); err != nil {
return fmt.Errorf("策略配置不合法：%w", err)
}
// ② 保存到数据库
policyModel := &model.Policy{
NetworkID: networkID,
Config: policy.ToJSON(),
UpdatedAt: time.Now(),
}
err := s.store.DB().Save(policyModel).Error
if err != nil {
return err
}
// ③ 调用 ctr 应用策略（可选，如果网络正在运行）
if network.IsActive {
err = s.ctrClient.UpdatePolicy(networkID, policy)
if err != nil {
return fmt.Errorf("应用策略失败：%w", err)
}
}
return nil
}
// validatePolicy 验证策略合法性（纯业务逻辑）
func (s *PolicyService) validatePolicy(policy PolicyConfig) error {
// 检查至少启用了一层
if !policy.AnyLayerEnabled() {
return errors.New("至少需要启用一层传输")
}
// 检查优先级顺序
if !policy.IsValidOrder() {
return errors.New("传输层优先级顺序不合法")
}
// 检查 STUN/TURN 服务器配置
if policy.EnableDirectUDP && len(policy.STUNServers) == 0 {
return errors.New("启用 Direct-UDP 需要配置 STUN 服务器")
}
if policy.EnableTURN && len(policy.TURNServers) == 0 {
return errors.New("启用 TURN 需要配置 TURN 服务器")
}
return nil
// ✅ 纯业务逻辑校验，不需要调用 ctr！
}
```
---
## 🔄 Service 层的通用模式
### **标准操作流程**
```go
func (s *XXXService) DoSomething(params Params) (Result, error) {
// ① 业务规则校验
if err := s.validate(params); err != nil {
return nil, err
}
// ② 数据生成/转换
data := generateData(params)
// ③ 保存到数据库
err := s.store.DB().Create(&data).Error
if err != nil {
return nil, err
}
// ④ 调用 ctr 执行（可选，放在事务外）
err = s.ctrClient.DoSomething(data.ID, data.Config)
if err != nil {
// 回滚：删除刚创建的数据
s.store.DB().Delete(&data)
return nil, fmt.Errorf("调用 ctr 失败：%w", err)
}
return data, nil
}
```
### **不调用 Ctr 的场景**
以下场景**完全不需要调用 Ctr**：
1. ✅ **用户认证**：Login/Register/VerifyToken
2. ✅ **数据查询**：ListXXX/GetXXX
3. ✅ **配置生成**：GenerateMeshSeed/GetDeviceConfig
4. ✅ **策略校验**：ValidatePolicy
5. ✅ **日志审计**：LogAction/ListAuditLogs
6. ✅ **统计分析**：GetAuditStats/GetSystemStats
---
## 📊 Service 与 Ctr 的职责对比
| 维度 | Service 层 | Ctr 层 |
|------|----------|--------|
| **定位** | 业务逻辑核心 | 实时控制执行器 |
| **职责** | 业务规则、数据生成、持久化 | 执行 WG/Core 操作 |
| **依赖数据库** | ✅ 是（直接操作） | ❌ 否（通过参数接收） |
| **依赖 Ctr** | ⚠️ 部分依赖 | ❌ 不依赖 Service |
| **主动性** | ✅ 主动发起调用 | ❌ 被动执行 |
| **可测试性** | ✅ 可 Mock Ctr | ✅ 可独立测试 |
| **示例方法** | CreateNetwork
Login
GenerateMeshSeed | CreateDevice
AddPeer
CreateEngine |
---
## ✅ 总结
### **Service 层的核心价值**
1. ✅ **业务逻辑的承载者**
- 处理所有业务规则
- 生成和转换数据
- 持久化到数据库
2. ✅ **Ctr 层的调用者**
- 决定何时调用 Ctr
- 传递必要的参数
- 处理 Ctr 的返回结果
3. ✅ **前后端的桥梁**
- 接收 API Handler 的请求
- 返回处理结果给 Handler
- 对外暴露完整的业务能力
### **设计原则**
- ✅ **Service 层是核心**：所有业务逻辑都在这里
- ✅ **Ctr 层是工具**：只在需要实时控制时调用
- ✅ **保持解耦**：Service 层可以独立于 Ctr 测试
- ✅ **事务一致性**：Ctr 失败时需要回滚数据库
---
*文档版本：v1.0*
*最后更新：2026-03-24*
*维护者：MeshRay Team*