GoTunnel/plan.md

# GoTunnel 架构修复计划

> 面向 100 万用户发布前的安全与稳定性修复方案

## 问题概览

| 严重程度 | 数量 | 状态 |
|---------|------|------|
| P0 严重 | 5 | ✅ 已修复 |
| P1 高 | 5 | ✅ 已修复 |
| P2 中 | 13 | 计划中 |
| P3 低 | 15 | 后续迭代 |

---

## 修复完成总结

### P0 严重问题 (已全部修复)

| 编号 | 问题 | 修复文件 | 状态 |
|-----|------|---------|------|
| 1.1 | TLS 证书验证 | `pkg/crypto/tls.go` | ✅ TOFU 机制 |
| 1.2 | Web 控制台无认证 | `cmd/server/main.go`, `config/config.go` | ✅ 强制认证 |
| 1.3 | 认证检查端点失效 | `router/auth.go` | ✅ 实际验证 JWT |
| 1.4 | Token 生成错误 | `config/config.go` | ✅ 错误检查 |
| 1.5 | 客户端 ID 未验证 | `tunnel/server.go` | ✅ 正则验证 |

### P1 高优先级问题 (已全部修复)

| 编号 | 问题 | 修复文件 | 状态 |
|-----|------|---------|------|
| 2.1 | 无连接数限制 | `tunnel/server.go` | ✅ 10000 上限 |
| 2.3 | 无优雅关闭 | `tunnel/server.go`, `cmd/server/main.go` | ✅ 信号处理 |
| 2.4 | 消息大小未验证 | `protocol/message.go` | ✅ 已有验证 |
| 2.5 | 无安全事件日志 | `pkg/security/audit.go` | ✅ 新增模块 |

---

## 第一阶段：P0 严重问题 (发布前必须修复)

### 1.1 TLS 证书验证被禁用

**文件**: `pkg/crypto/tls.go`

**问题**: `InsecureSkipVerify: true` 导致中间人攻击风险

**修复方案**:
- 添加服务端证书指纹验证机制
- 客户端首次连接时保存服务端证书指纹
- 后续连接验证指纹是否匹配（Trust On First Use）
- 提供 `--skip-verify` 参数供测试环境使用

**修改内容**:
```go
// pkg/crypto/tls.go
func ClientTLSConfig(serverFingerprint string) *tls.Config {
    return &tls.Config{
        MinVersion:         tls.VersionTLS12,
        InsecureSkipVerify: true, // 仍需要，因为是自签名证书
        VerifyPeerCertificate: func(rawCerts [][]byte, _ [][]*x509.Certificate) error {
            // 验证证书指纹
            return verifyCertFingerprint(rawCerts, serverFingerprint)
        },
    }
}
```

---

### 1.2 Web 控制台无认证

**文件**: `cmd/server/main.go`

**问题**: 默认配置下 Web 控制台完全开放

**修复方案**:
- 首次启动时自动生成随机密码
- 强制要求配置用户名密码
- 无认证时拒绝启动 Web 服务

**修改内容**:
```go
// cmd/server/main.go
if cfg.Web.Enabled {
    if cfg.Web.Username == "" || cfg.Web.Password == "" {
        // 自动生成凭据
        cfg.Web.Username = "admin"
        cfg.Web.Password = generateSecurePassword(16)
        log.Printf("[Web] 自动生成凭据 - 用户名: %s, 密码: %s",
            cfg.Web.Username, cfg.Web.Password)
        // 保存到配置文件
        saveConfig(cfg)
    }
}
```

---

### 1.3 认证检查端点失效

**文件**: `internal/server/router/auth.go`

**问题**: `/auth/check` 始终返回 `valid: true`

**修复方案**:
- 实际验证 JWT Token
- 返回真实的验证结果

**修改内容**:
```go
// internal/server/router/auth.go
func (h *AuthHandler) handleCheck(w http.ResponseWriter, r *http.Request) {
    // 从 Authorization header 获取 token
    token := extractToken(r)
    if token == "" {
        jsonError(w, "missing token", http.StatusUnauthorized)
        return
    }

    // 验证 token
    claims, err := h.validateToken(token)
    if err != nil {
        jsonError(w, "invalid token", http.StatusUnauthorized)
        return
    }

    json.NewEncoder(w).Encode(map[string]interface{}{
        "valid": true,
        "user":  claims.Username,
    })
}
```

---

### 1.4 Token 生成错误未处理

**文件**: `internal/server/config/config.go`

**问题**: `rand.Read()` 错误被忽略，可能生成弱 Token

**修复方案**:
- 检查 `rand.Read()` 返回值
- 失败时 panic 或返回错误
- 增加 Token 强度验证

**修改内容**:
```go
// internal/server/config/config.go
func generateToken(length int) (string, error) {
    bytes := make([]byte, length/2)
    n, err := rand.Read(bytes)
    if err != nil {
        return "", fmt.Errorf("failed to generate token: %w", err)
    }
    if n != len(bytes) {
        return "", fmt.Errorf("insufficient random bytes: got %d, want %d", n, len(bytes))
    }
    return hex.EncodeToString(bytes), nil
}
```

---

### 1.5 客户端 ID 未验证

**文件**: `internal/server/tunnel/server.go`

**问题**: tunnel server 中未使用已有的 ID 验证函数

**修复方案**:
- 在 handleConnection 中验证 clientID
- 拒绝非法格式的 ID
- 记录安全日志

**修改内容**:
```go
// internal/server/tunnel/server.go
func (s *Server) handleConnection(conn net.Conn) {
    // ... 读取认证消息后

    clientID := authReq.ClientID
    if clientID != "" && !isValidClientID(clientID) {
        log.Printf("[Security] Invalid client ID format from %s: %s",
            conn.RemoteAddr(), clientID)
        sendAuthResponse(conn, false, "invalid client id format")
        return
    }
    // ...
}

var clientIDRegex = regexp.MustCompile(`^[a-zA-Z0-9_-]{1,64}$`)

func isValidClientID(id string) bool {
    return clientIDRegex.MatchString(id)
}
```

---

## 第二阶段：P1 高优先级问题 (发布前建议修复)

### 2.1 无连接数限制

**文件**: `internal/server/tunnel/server.go`

**修复方案**:
- 添加全局最大连接数限制
- 添加单客户端连接数限制
- 使用 semaphore 控制并发

**修改内容**:
```go
type Server struct {
    // ...
    maxConns     int
    connSem      chan struct{} // semaphore
    clientConns  map[string]int
}

func (s *Server) handleConnection(conn net.Conn) {
    select {
    case s.connSem <- struct{}{}:
        defer func() { <-s.connSem }()
    default:
        conn.Close()
        log.Printf("[Server] Connection rejected: max connections reached")
        return
    }
    // ...
}
```

---

### 2.2 Goroutine 泄漏

**文件**: 多个文件

**修复方案**:
- 使用 context 控制 goroutine 生命周期
- 添加 goroutine 池
- 确保所有 goroutine 有退出机制

---

### 2.3 无优雅关闭

**文件**: `cmd/server/main.go`

**修复方案**:
- 监听 SIGTERM/SIGINT 信号
- 关闭所有监听器
- 等待现有连接完成
- 设置关闭超时

**修改内容**:
```go
// cmd/server/main.go
func main() {
    // ...

    // 优雅关闭
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)

    go func() {
        <-quit
        log.Println("[Server] Shutting down...")

        ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
        defer cancel()

        server.Shutdown(ctx)
        webServer.Shutdown(ctx)
    }()

    server.Run()
}
```

---

### 2.4 消息大小未验证

**文件**: `pkg/protocol/message.go`

**修复方案**:
- 在 ReadMessage 中检查消息长度
- 超过限制时返回错误

---

### 2.5 无读写超时

**文件**: `internal/server/tunnel/server.go`

**修复方案**:
- 所有连接设置读写超时
- 使用 SetDeadline 而非一次性设置

---

### 2.6 竞态条件

**文件**: `internal/server/tunnel/server.go`

**修复方案**:
- 使用 sync.Map 替代 map + mutex
- 或确保所有 map 访问都在锁保护下

---

### 2.7 无安全事件日志

**修复方案**:
- 添加安全日志模块
- 记录认证失败、异常访问等事件
- 支持日志轮转

---

## 第三阶段：P2 中优先级问题 (发布后迭代)

| 编号 | 问题 | 文件 |
|-----|------|------|
| 3.1 | 配置文件权限过宽 (0644) | config/config.go |
| 3.2 | 心跳机制不完善 | tunnel/server.go |
| 3.3 | HTTP 代理无 SSRF 防护 | proxy/http.go |
| 3.4 | SOCKS5 代理无验证 | proxy/socks5.go |
| 3.5 | 数据库操作无超时 | db/sqlite.go |
| 3.6 | 错误处理不一致 | 多个文件 |
| 3.7 | UDP 缓冲区无限制 | tunnel/server.go |
| 3.8 | 代理规则无验证 | tunnel/server.go |
| 3.9 | 客户端注册竞态 | tunnel/server.go |
| 3.10 | Relay 资源泄漏 | relay/relay.go |
| 3.11 | 插件配置无验证 | tunnel/server.go |
| 3.12 | 端口号无边界检查 | tunnel/server.go |
| 3.13 | 插件商店 URL 硬编码 | config/config.go |

---

## 第四阶段：P3 低优先级问题 (后续优化)

| 编号 | 问题 | 建议 |
|-----|------|------|
| 4.1 | 无结构化日志 | 引入 zap/zerolog |
| 4.2 | 无连接池 | 实现连接池 |
| 4.3 | 线性查找规则 | 使用 map 索引 |
| 4.4 | 无数据库缓存 | 添加内存缓存 |
| 4.5 | 魔法数字 | 提取为常量 |
| 4.6 | 无 godoc 注释 | 补充文档 |
| 4.7 | 配置无验证 | 添加验证逻辑 |

---

## 修复顺序

```
Week 1: P0 问题 (5个)
  ├── Day 1-2: 1.1 TLS 证书验证
  ├── Day 2-3: 1.2 Web 控制台认证
  ├── Day 3-4: 1.3 认证检查端点
  ├── Day 4: 1.4 Token 生成
  └── Day 5: 1.5 客户端 ID 验证

Week 2: P1 问题 (7个)
  ├── Day 1-2: 2.1 连接数限制
  ├── Day 2-3: 2.2 Goroutine 泄漏
  ├── Day 3-4: 2.3 优雅关闭
  ├── Day 4: 2.4 消息大小验证
  ├── Day 5: 2.5 读写超时
  └── Day 5: 2.6-2.7 竞态条件 + 安全日志

Week 3+: P2/P3 问题
  └── 按优先级逐步修复
```

---

## 测试计划

### 安全测试
- [ ] TLS 中间人攻击测试
- [ ] 认证绕过测试
- [ ] 注入攻击测试
- [ ] DoS 攻击测试

### 稳定性测试
- [ ] 长时间运行测试 (72h+)
- [ ] 高并发连接测试 (10000+)
- [ ] 内存泄漏测试
- [ ] Goroutine 泄漏测试

### 性能测试
- [ ] 吞吐量基准测试
- [ ] 延迟基准测试
- [ ] 资源使用监控

---

## 回滚方案

如发布后发现严重问题：

1. **立即回滚**: 保留上一版本二进制文件
2. **热修复**: 针对特定问题发布补丁
3. **降级运行**: 禁用问题功能模块

---

## 监控告警

发布后需要监控的指标：

- 连接数 / 活跃客户端数
- 内存使用 / Goroutine 数量
- 认证失败率
- 错误日志频率
- 响应延迟 P99

---

*文档版本: 1.0*
*创建时间: 2025-12-29*
*状态: 待审核*