用户管理

用户管理

HeteroFlow V2 的用户管理系统提供完整的认证和授权功能，包括 JWT Token 认证、API Key 认证、基于角色的访问控制（RBAC），以及前端路由守卫。

JWT Token 认证机制

系统使用 JSON Web Token (JWT) 作为主要认证方式，采用 HS256（HMAC-SHA256）签名算法。

Token 结构

JWT Token 由三部分组成：Header.Payload.Signature

Payload 结构:

{
  "user_id": 1,
  "username": "admin",
  "role": "admin",
  "exp": 1716249600,
  "iat": 1716163200
}

Token 有效期

Token 有效期可通过环境变量配置：

# .env 文件
JWT_SECRET=your-secret-key-here
JWT_EXPIRE_HOURS=24
JWT_REFRESH_EXPIRE_DAYS=7

Token 签发

// 服务端签发 Token
token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
    "user_id":  user.ID,
    "username": user.Username,
    "role":     user.Role,
    "exp":      time.Now().Add(24 * time.Hour).Unix(),
    "iat":      time.Now().Unix(),
})
tokenString, _ := token.SignedString([]byte(jwtSecret))

API Key 认证

Agent 节点使用 API Key 进行认证，通过 X-API-Key HTTP Header 传递：

curl -X GET http://localhost:3333/api/v1/nodes 
  -H "X-API-Key: hf-ak-xxxxxxxxxxxxxxxx"

API Key 在 Agent 注册时自动生成，格式为 hf-ak- 前缀加上 32 位随机字符串。每个 Agent 节点拥有唯一的 API Key。

API Key 管理

RBAC 角色权限控制

系统采用基于角色的访问控制，定义两种角色：

Admin 角色（管理员）

管理员拥有全部 19 项权限：

User 角色（普通用户）

普通用户拥有 9 项权限：

前端路由守卫

前端使用三层路由守卫实现权限控制：

PublicRoute          ← 无需认证，公开访问
  └── /login         ← 登录页面
  └── /register      ← 注册页面
  └── /docs           ← 文档页面

PrivateRoute         ← 需要认证，登录后可访问
  └── /dashboard     ← 仪表盘
  └── /nodes         ← 节点管理
  └── /tasks         ← 任务管理
  └── /models        ← 模型管理

AdminRoute           ← 需要 admin 角色
  └── /users         ← 用户管理
  └── /plugins       ← 插件管理
  └── /settings      ← 系统设置
  └── /alerts/rules  ← 告警规则管理

守卫逻辑:

1. PublicRoute: 不检查 Token，直接放行

2. PrivateRoute: 检查 localStorage 中的 Token，无效则跳转登录页

3. AdminRoute: 检查 Token + 解析 role 字段，非 admin 跳转 403 页面

登录流程

用户输入用户名密码
       │
       ▼
┌──────────────┐     POST /api/v1/auth/login     ┌──────────────┐
│   前端表单    │ ─────────────────────────────→  │   后端 API   │
│              │                                  │              │
│              │     ← JWT Token                  │  验证密码    │
│              │ ←─────────────────────────────   │  签发 Token  │
└──────┬───────┘                                  └──────────────┘
       │
       ▼
  存储 Token 到 localStorage
  设置 axios 默认 Header: Authorization: Bearer <token>
       │
       ▼
  跳转到 /dashboard

Token 存储与刷新

存储

• Access Token: 存储在 localStorage 的 token 字段
• Refresh Token: 存储在 localStorage 的 refresh_token 字段
• Token 自动附加到所有 API 请求的 Authorization Header

自动刷新

前端 axios 拦截器实现 Token 自动刷新：

1. 发送请求时检查 Token 是否即将过期（剩余 < 5 分钟）

2. 如即将过期，先调用刷新接口获取新 Token

3. 用新 Token 替换旧 Token 并重新发送原请求

4. 如刷新失败（Refresh Token 也过期），跳转到登录页

CORS 配置

# config.yaml
server:
  cors:
    allowed_origins:
      - "http://localhost:5173"
      - "http://8.136.25.54:5173"
    allowed_methods:
      - GET
      - POST
      - PUT
      - DELETE
      - OPTIONS
    allowed_headers:
      - Authorization
      - Content-Type
      - X-API-Key
    max_age: 3600

DevBypassAuth 开发模式

开发环境下可通过配置跳过认证：

# config.yaml
auth:
  dev_bypass: true    # 开启开发模式认证跳过

或通过环境变量：

export DEV_BYPASS_AUTH=true

开启后所有 API 请求自动以 admin 身份执行，无需 Token。仅用于本地开发，生产环境务必关闭。

认证 API 接口

用户登录

curl -X POST http://localhost:3333/api/v1/auth/login 
  -H "Content-Type: application/json" 
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

响应:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin"
  }
}

用户注册

curl -X POST http://localhost:3333/api/v1/auth/register 
  -H "Content-Type: application/json" 
  -d '{
    "username": "newuser",
    "password": "securepass123",
    "email": "user@example.com"
  }'

刷新 Token

curl -X POST http://localhost:3333/api/v1/auth/refresh 
  -H "Content-Type: application/json" 
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }'

获取当前用户信息

curl -X GET http://localhost:3333/api/v1/auth/me 
  -H "Authorization: Bearer <token>"

修改密码

curl -X PUT http://localhost:3333/api/v1/auth/password 
  -H "Authorization: Bearer <token>" 
  -H "Content-Type: application/json" 
  -d '{
    "old_password": "admin123",
    "new_password": "newpass456"
  }'

环境变量配置