为所有API接口添加授权验证，要求请求头中包含有效的API密钥才能访问。

主要变更：
- 新增授权中间件 (internal/middleware/auth.go)
  - 验证 X-API-Key 请求头
  - 密钥值为 xn001624.
  - 无效密钥返回 401 Unauthorized

- 更新路由配置 (cmd/server/main.go)
  - 使用路由组统一应用授权中间件
  - 保护所有文件和存储桶操作接口
  - Swagger 和 Web UI 保持公开访问

- 新增授权使用文档 (docs/AUTH_GUIDE.md)
  - 多语言使用示例 (cURL, JavaScript, Python)
  - 完整的错误说明和授权范围

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2026-01-05 20:22:04 +08:00

2.7 KiB

Raw Blame History

API 授权使用指南

概述

所有 API 接口现在都需要通过授权验证才能访问。每个请求都必须在请求头中包含有效的 API 密钥。

API 密钥

密钥值: xn001624
请求头名称: X-API-Key

使用方法

示例 1: 使用 cURL

# 上传文件
curl -X POST http://localhost:8080/files/upload \
  -H "X-API-Key: xn001624" \
  -F "file=@/path/to/your/file.txt" \
  -F "bucket=my-bucket" \
  -F "path=/uploads/"

# 列出存储桶
curl -X GET http://localhost:8080/buckets \
  -H "X-API-Key: xn001624"

# 下载文件
curl -X GET "http://localhost:8080/files/download?bucket=my-bucket&path=/uploads/file.txt" \
  -H "X-API-Key: xn001624" \
  -o downloaded_file.txt

示例 2: 使用 JavaScript (Fetch)

const response = await fetch('http://localhost:8080/buckets', {
  method: 'GET',
  headers: {
    'X-API-Key': 'xn001624',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

示例 3: 使用 Python (requests)

import requests

headers = {
    'X-API-Key': 'xn001624'
}

# 列出存储桶
response = requests.get(
    'http://localhost:8080/buckets',
    headers=headers
)

print(response.json())

示例 4: 使用 Postman

打开 Postman
在 Headers 选项卡中添加新的 key-value 对:
- Key: X-API-Key
- Value: xn001624
发送请求

错误响应

如果未提供 API 密钥或密钥无效，将返回以下错误：

状态码: 401 Unauthorized

响应体:

{
  "code": 401,
  "message": "未授权：请在请求头中提供有效的API密钥",
  "error": "Missing or invalid API key"
}

授权范围

以下所有 API 接口都需要授权：

文件操作

POST /files/upload - 上传文件
GET /files/download - 下载文件
GET /files/list - 列出文件
GET /files/preview - 获取文件预览URL
DELETE /files/delete - 删除文件

分片上传

POST /files/multipart/init - 初始化分片上传
PUT /files/multipart/part - 上传分片
POST /files/multipart/complete - 完成分片上传

存储桶操作

POST /buckets - 创建存储桶
GET /buckets - 列出存储桶
DELETE /buckets - 删除存储桶

无需授权的接口

以下接口不需要授权：

GET /swagger/* - Swagger 文档
GET /web/* - Web UI
GET / - 根路径重定向

安全建议

不要在客户端代码中硬编码 API 密钥
使用环境变量存储 API 密钥
定期更换 API 密钥
在生产环境中使用 HTTPS
实施速率限制以防止滥用

配置

如需修改 API 密钥，请编辑文件： internal/middleware/auth.go

修改 API_KEY_VALUE 常量的值即可。

2.7 KiB Raw Blame History Unescape Escape