后端架构

概述

后端服务是 EchoCenter 的核心，负责处理 HTTP 请求、WebSocket 通信、业务逻辑和数据持久化。

项目结构

backend/
├── cmd/
│   └── server/
│       └── main.go          # 入口点
├── internal/
│   ├── api/                 # API 层
│   │   ├── handler/        # 处理器
│   │   ├── middleware/     # 中间件
│   │   ├── router/         # 路由
│   │   └── websocket/      # WebSocket
│   ├── auth/               # 认证
│   ├── butler/             # Butler 服务
│   ├── config/             # 配置
│   ├── models/             # 数据模型
│   └── repository/         # 数据存储
├── pkg/                    # 公共包
│   └── errors/            # 错误处理
└── scripts/               # 启动脚本

核心组件

1. HTTP API 服务

• 路由 - RESTful API 路由
• 处理器 - 请求处理逻辑
• 中间件 - 认证、日志、错误处理
• 响应 - 统一响应格式

2. WebSocket 服务

• Hub - 连接管理，消息持久化后再投递
• 消息处理器 - 持久化同步执行，LLM 处理异步执行
• 代理注册 - 代理连接管理
• 路由规则 - target_id 定向投递、CHAT* 回声控制、Butler-Agent 监控按权限定向发送

3. 认证服务

• JWT - 令牌生成和验证
• 中间件 - 路由保护
• 用户管理 - 用户 CRUD

4. Butler 服务

• 消息处理 - 接收和处理消息
• 命令执行 - 执行用户命令
• 授权请求 - 发送授权请求
• 响应处理 - 处理代理响应

5. 数据存储

• 数据库层 - 支持项目的可配置持久化，并可通过 DB_DRIVER=postgres 启用 PostgreSQL。
• 数据库迁移 - 内置迁移系统，使用 migrations 表追踪已执行的变更，确保 Schema 更新的原子性和可靠性。
• Repository - 数据访问层拆分为 users/messages/chat/butler auth/bootstrap 等模块，边界更清晰。
• 凭据存储拆分 - 人类凭据与机器凭据拆分至 human_credentials / machine_credentials，安全边界更清晰。

架构图

:::demo

graph TD
    A[HTTP 客户端] --> B[Gin Router]
    B --> C[Middleware]
    C --> D[Handler]
    D --> E[Service]
    E --> F[Repository]
    F --> G[Database]
    
    H[WebSocket 客户端] --> I[WebSocket Hub]
    I --> J[Message Handler]
    J --> K[Butler Service]
    K --> L[Agent]

:::

数据模型

User

type User struct {
    ID       uint   `json:"id"`
    Username string `json:"username"`
    Password string `json:"-"`
    Role     string `json:"role"`
}

Message

type Message struct {
    ID         uint   `json:"id"`
    SenderID   uint   `json:"sender_id"`
    SenderName string `json:"sender_name"`
    SenderRole string `json:"sender_role"`
    TargetID   uint   `json:"target_id"`
    Payload    string `json:"payload"`
    Timestamp  string `json:"timestamp"`
}

Agent

type Agent struct {
    ID       uint   `json:"id"`
    Username string `json:"username"`
    Role     string `json:"role"`
    Status   string `json:"status"`
}

API 路由

认证

• POST /api/auth/login - 登录
• POST /api/auth/register - 注册

用户

• GET /api/users - 获取用户列表
• GET /api/users/:id - 获取用户详情
• POST /api/users/agents - 注册代理
• DELETE /api/users/agents/:id - 删除代理

消息

• GET /api/messages - 获取消息列表
• POST /api/messages - 发送消息

中间件

认证中间件

func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        // 验证 token
    }
}

日志中间件

func LoggerMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 记录请求日志
    }
}

错误处理

统一错误格式

{
  "error": "用户友好的错误信息"
}

错误处理安全性

• 信息隐藏 - 在内部错误（500）发生时，系统会向客户端隐藏数据库等敏感细节，统一返回 "Internal server error"。
• 详细日志 - 真实的错误原因会记录在服务器日志中，便于调试。
• 类型映射 - 业务错误会自动映射到对应的 HTTP 状态码。

性能优化

数据库优化

• 连接池 - 针对 WAL 模式进行了优化，允许在保持数据一致性的同时进行多个并发读操作。
• 原子迁移 - 所有数据库结构变更都在事务中执行，确保一致性。
• 索引优化 - 对关键列（时间戳、ID）建立索引以实现快速检索。

缓存

• Redis（未来）
• 内存缓存

并发处理

• Goroutine
• Channel

安全性

输入验证

• 结构体验证
• 类型验证

SQL 注入防护

• 参数化查询
• ORM 使用

XSS 防护

• HTML 转义
• 输入验证

凭据与流式安全

• /api/users/agents 不返回明文 api_token（仅返回 token_hint 元数据）。
• Butler-Agent 监控事件通过 WebSocket 定向给有权限接收者（管理员），不做全量广播。
• CHAT / CHAT_STREAM / CHAT_STREAM_END 对系统角色（AGENT、BUTLER）禁用发送者回声，避免自循环。

部署

构建

go build -o bin/server ./cmd/server

运行

./bin/server

Docker

FROM golang:1.21-alpine
WORKDIR /app
COPY . .
RUN go build -o server ./cmd/server
CMD ["./server"]