120 lines
3.2 KiB
Markdown
120 lines
3.2 KiB
Markdown
# 认证与 API 用户（JSON 手动维护）
|
||
|
||
本项目的 API v1 使用 **Bearer Token** 鉴权，且 **API 用户与网页用户完全隔离**。
|
||
|
||
## 1. 鉴权方式（每个请求都要带）
|
||
|
||
请求头：
|
||
|
||
```
|
||
Authorization: Bearer <TOKEN>
|
||
```
|
||
|
||
服务端会对 `<TOKEN>` 做 `SHA256`，与 `data/api_users.json` 中保存的 `token_sha256` 进行匹配。
|
||
|
||
## 2. API 用户配置文件
|
||
|
||
路径：
|
||
|
||
- `data/api_users.json`
|
||
|
||
格式（示例）：
|
||
|
||
```json
|
||
{
|
||
"users": {
|
||
"api_jojo": {
|
||
"token_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
|
||
"created_at": "2026-01-23",
|
||
"note": "for flutter app"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
- `users`：对象，key 是 API 用户名（建议全小写、只包含字母数字下划线/连字符）。
|
||
- `token_sha256`：必填，token 的 SHA256 十六进制字符串。
|
||
- `created_at` / `note`：可选，仅用于记录与审计。
|
||
|
||
注意：
|
||
|
||
- 当前实现为**启动时加载**该 JSON；如果你修改了 `data/api_users.json`，请**重启服务**使其生效。
|
||
|
||
## 3. 生成 token_sha256 的方法
|
||
|
||
### 3.1 用 Python 生成
|
||
|
||
```bash
|
||
python3 - <<'PY'
|
||
import hashlib
|
||
token = "YOUR_TOKEN"
|
||
print(hashlib.sha256(token.encode("utf-8")).hexdigest())
|
||
PY
|
||
```
|
||
|
||
把输出粘到 `token_sha256`。
|
||
|
||
### 3.2 token 建议
|
||
|
||
- 长度建议：>= 32 字符（越长越好）
|
||
- 生成建议：使用密码管理器或安全随机源生成
|
||
- 存储建议：客户端侧使用系统安全存储（Keychain/Keystore），不要写死在前端代码里
|
||
|
||
## 4. API 用户的独立落盘目录
|
||
|
||
每个 API 用户会创建独立工作区，默认根目录：
|
||
|
||
- `api/users/<api_username>/`
|
||
|
||
典型结构：
|
||
|
||
```
|
||
api/users/<api_username>/
|
||
project/
|
||
user_upload/ # API 上传文件只能落在这里（以及其子目录）
|
||
... # 智能体运行产生的项目文件也在 project 下
|
||
data/
|
||
conversations/ # 对话 JSON 落盘目录
|
||
memory.md
|
||
task_memory.md
|
||
...
|
||
logs/
|
||
```
|
||
|
||
对话文件示例路径：
|
||
|
||
- `api/users/api_jojo/data/conversations/conv_20260123_234245_036.json`
|
||
|
||
对话 JSON 结构（简化示例）：
|
||
|
||
```json
|
||
{
|
||
"id": "conv_20260123_234245_036",
|
||
"title": "新对话",
|
||
"created_at": "2026-01-23T23:42:45.036Z",
|
||
"updated_at": "...",
|
||
"messages": [
|
||
{ "role": "user", "content": "你好", "timestamp": "..." },
|
||
{ "role": "assistant", "content": "…", "reasoning_content": "", "timestamp": "..." },
|
||
{ "role": "tool", "name": "web_search", "content": "{...}", "timestamp": "..." }
|
||
],
|
||
"metadata": { "run_mode": "fast", "model_key": "kimi", "...": "..." }
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- API v1 **没有提供“读取历史对话”的 HTTP 接口**；如确实需要历史，请直接读落盘文件或后续再加只读接口。
|
||
|
||
## 5. 安全注意事项
|
||
|
||
- Bearer Token 等同密码：不要放到 Git、不要发到日志、不要在网页端暴露。
|
||
- 如果怀疑泄露：替换 token（更新 JSON），重启服务；旧 token 会立即失效。
|
||
- 生产环境建议：
|
||
- 通过反向代理限制来源 IP；
|
||
- 记录 API 调用审计日志（至少记录 user、endpoint、时间、返回码）；
|
||
- 加入速率限制（避免被刷）。
|
||
|