97 lines
2.5 KiB
Markdown
97 lines
2.5 KiB
Markdown
# 鉴权与目录结构（API v1）
|
||
|
||
本项目的 API v1 使用 **Bearer Token** 鉴权，并且与网页端账号体系隔离。
|
||
|
||
---
|
||
|
||
## 1) 鉴权方式
|
||
|
||
所有需要鉴权的 API 请求都必须带 Header：
|
||
|
||
```
|
||
Authorization: Bearer <TOKEN>
|
||
```
|
||
|
||
- `<TOKEN>` 是你分配给 API 调用方的明文 token
|
||
- 服务端不会保存明文 token，只保存其 SHA256
|
||
|
||
---
|
||
|
||
## 2) API 用户与 token 的配置文件
|
||
|
||
文件：`data/api_users.json`
|
||
|
||
结构示例：
|
||
|
||
```json
|
||
{
|
||
"users": {
|
||
"api_demo": {
|
||
"token_sha256": "9d2f30ce92cee1301dbbdc990aed245a781c34717a1bf51a7a368b6f4ae28f50",
|
||
"created_at": "2026-01-23",
|
||
"note": "dev generated"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `users` 的 key 是 API 用户名（仅用于区分与落盘路径）
|
||
- 调用时只需要 token（用户名不会作为参数传入）
|
||
|
||
> 修改 `data/api_users.json` 后通常需要重启服务以生效（取决于当前是否支持热加载）。
|
||
|
||
---
|
||
|
||
## 3) 目录结构（多工作区）
|
||
|
||
API 用户根目录（默认）：`api/users/<api_user>/`
|
||
|
||
在该目录下包含：
|
||
|
||
### 3.1 用户级共享目录（prompts / personalization）
|
||
|
||
```
|
||
api/users/<api_user>/shared/
|
||
prompts/
|
||
<name>.txt
|
||
personalization/
|
||
personalization.json # 默认个性化（主文件）
|
||
<name>.json # 命名个性化
|
||
```
|
||
|
||
说明：
|
||
|
||
- `prompts` 与 `personalization` 是**用户级共享**：不同 workspace 共用同一份配置；
|
||
- `/api/v1/prompts` 与 `/api/v1/personalizations` 操作的就是这里的文件。
|
||
|
||
### 3.2 工作区目录（每个 workspace 独立）
|
||
|
||
```
|
||
api/users/<api_user>/workspaces/<workspace_id>/
|
||
project/ # 工具读写根目录（容器挂载目录）
|
||
user_upload/ # 上传目录（API 只允许在这里上传/下载）
|
||
data/ # 对话/备份等数据落盘（工作区独立）
|
||
conversations/
|
||
conv_*.json
|
||
backups/
|
||
prompts -> ../../shared/prompts # 软链（可能不存在）
|
||
personalization -> ../../shared/personalization # 软链（可能不存在）
|
||
logs/
|
||
```
|
||
|
||
说明：
|
||
|
||
- 每个 workspace 都会启动**独立容器**（隔离执行环境）；
|
||
- `project/` 与 `data/` 都是 workspace 级：对话文件不会跨 workspace 混用；
|
||
- `user_upload/` 也是 workspace 级：不同 workspace 互相不可见。
|
||
|
||
---
|
||
|
||
## 4) 并发规则
|
||
|
||
- 并发限制以 workspace 为粒度：同一 API 用户的同一 `workspace_id` 同时只允许一个任务运行。
|
||
- 不同 workspace 可以同时运行多个任务。
|
||
|