file-system/docs/LOGIN_GUIDE.md

# Web 登录功能说明

## 功能概述

Web UI 现已添加密钥登录功能，用户必须先登录才能访问文件管理系统。

## 使用流程

### 1. 访问登录页面

打开浏览器访问：
```
http://localhost:8080/web/login.html
```

### 2. 输入 API 密钥

在登录页面输入 API 密钥：
```
xn001624.
```

### 3. 登录成功

登录成功后，系统会：
- 将密钥保存到浏览器的 localStorage
- 自动跳转到主页面 `/web/`
- 所有后续 API 请求都会自动携带密钥

### 4. 退出登录

点击右上角的"退出"按钮可以：
- 清除本地存储的密钥
- 跳转回登录页面

## 技术实现

### 后端 (遵循 CQRS 模式)

1. **登录查询** (`internal/api/handlers/auth_handlers.go`)
   ```go
   type LoginQuery struct {
       APIKey string `json:"api_key" binding:"required"`
   }
   ```

2. **登录处理器**
   ```go
   type LoginHandler struct {
       apiKey string
   }

   func (h *LoginHandler) Handle(ctx context.Context, query LoginQuery) (LoginResult, error)
   ```

3. **认证端点** (`internal/api/endpoints/auth_endpoints.go`)
   ```go
   func (e *AuthEndpoint) Login(c *gin.Context)
   ```

4. **路由配置** (`cmd/server/main.go`)
   - `/auth/login` - 公开接口，无需授权
   - 所有其他 API 接口都需要 `X-API-Key` 请求头

### 前端

1. **登录页面** (`web/login.html`)
   - 美观的渐变背景登录界面
   - 密钥输入框（密码类型）
   - 表单验证和错误提示
   - 登录后自动跳转

2. **主页面** (`web/index.html`)
   - 检查 localStorage 中的 token
   - 未登录显示提示信息
   - 已登录正常显示文件管理界面
   - 所有 API 请求自动携带 `X-API-Key` 头
   - 401 错误自动跳转回登录页

## 安全特性

1. **前端存储**: 使用 localStorage 存储密钥（适合单用户场景）
2. **自动过期**: 当 API 返回 401 时自动清除密钥并跳转登录
3. **密钥保护**: 密钥输入框使用 password 类型，屏幕上不可见
4. **退出功能**: 支持主动退出登录

## 接口说明

### POST /auth/login

**请求体**:
```json
{
  "api_key": "xn001624."
}
```

**成功响应** (200):
```json
{
  "success": true,
  "message": "登录成功",
  "token": "xn001624."
}
```

**失败响应** (200):
```json
{
  "success": false,
  "message": "API密钥无效"
}
```

## 使用示例

### 使用 cURL 测试登录接口

```bash
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"api_key": "xn001624."}'
```

### 前端 API 调用示例

登录后，所有 API 请求会自动携带密钥：

```javascript
// 登录
const res = await axios.post('/auth/login', {
    api_key: 'xn001624.'
});

// 保存 token
localStorage.setItem('rustfs_token', res.data.token);

// 后续请求自动携带密钥
const api = axios.create({
    baseURL: window.location.origin,
    headers: {
        'X-API-Key': localStorage.getItem('rustfs_token')
    }
});

// 调用 API
const buckets = await api.get('/buckets');
```

## 文件结构

```
internal/
├── api/
│   ├── endpoints/
│   │   └── auth_endpoints.go        # 认证端点
│   └── handlers/
│       └── auth_handlers.go         # 登录处理器
└── middleware/
    └── auth.go                      # API 授权中间件

web/
├── login.html                       # 登录页面
└── index.html                       # 主页面（含登录检查）
```

## 更新日志

### v1.2
- ✨ 添加 Web 登录功能
- ✨ 创建登录页面 UI
- ✨ 实现 CQRS 模式的登录验证
- 🔒 所有 Web 操作需要先登录
- 📝 添加登录文档