docs: 适配单机场景,简化存储与认证方案
- 数据库:MySQL → SQLite,去掉连接池配置和 golang-migrate - 文件存储:OSS 对象存储 → 本地文件系统,统一 Gin 静态文件服务 - ID 生成:Sonyflake → 前缀+随机字符串 - 认证:Bearer Token → httpOnly Cookie,WebSocket 同步改为 Cookie 认证 - 质检重试:PromptBuilder 重试时注入 RejectReason 改进提示词 - 合并 multi-agent-pipeline.md 到 backend.md,消除文档重复 - 移除缓存管理 API(暴露内部实现细节)
This commit is contained in:
+16
-55
@@ -8,13 +8,16 @@
|
||||
|
||||
## 认证
|
||||
|
||||
除健康检查和注册登录外,所有接口需在请求头携带 Bearer Token:
|
||||
除健康检查和注册登录外,所有接口需通过 httpOnly Cookie 携带 JWT。登录/注册成功后,服务端通过 `Set-Cookie` 响应头写入 Token,后续请求自动携带。
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
Cookie 属性:
|
||||
- `Name`: `token`
|
||||
- `HttpOnly`: true
|
||||
- `SameSite`: Lax
|
||||
- `Path`: `/`
|
||||
- `MaxAge`: 由 `GEN2D_JWT_EXPIRE` 控制(默认 7200 秒)
|
||||
|
||||
Token 通过登录接口获取,过期时间由 `GEN2D_JWT_EXPIRE` 控制(默认 7200 秒)。Token 过期或无效时返回:
|
||||
Token 过期或无效时返回:
|
||||
|
||||
```json
|
||||
{ "code": 401, "message": "未登录或 Token 已过期", "data": null }
|
||||
@@ -77,7 +80,7 @@ Token 通过登录接口获取,过期时间由 `GEN2D_JWT_EXPIRE` 控制(默
|
||||
| `email` | string | 是 | 邮箱地址 |
|
||||
| `password` | string | 是 | 8-128 字符 |
|
||||
|
||||
响应:
|
||||
响应(Token 通过 `Set-Cookie` 响应头写入,不在 body 中返回):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -86,9 +89,7 @@ Token 通过登录接口获取,过期时间由 `GEN2D_JWT_EXPIRE` 控制(默
|
||||
"data": {
|
||||
"id": "user_a1B2c3D4",
|
||||
"username": "player1",
|
||||
"email": "player1@example.com",
|
||||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"expiresAt": "2026-05-24T12:00:00Z"
|
||||
"email": "player1@example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -121,7 +122,7 @@ Token 通过登录接口获取,过期时间由 `GEN2D_JWT_EXPIRE` 控制(默
|
||||
}
|
||||
```
|
||||
|
||||
响应:
|
||||
响应(Token 通过 `Set-Cookie` 响应头写入,不在 body 中返回):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -130,9 +131,7 @@ Token 通过登录接口获取,过期时间由 `GEN2D_JWT_EXPIRE` 控制(默
|
||||
"data": {
|
||||
"id": "user_a1B2c3D4",
|
||||
"username": "player1",
|
||||
"email": "player1@example.com",
|
||||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"expiresAt": "2026-05-24T12:00:00Z"
|
||||
"email": "player1@example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -173,7 +172,7 @@ Token 通过登录接口获取,过期时间由 `GEN2D_JWT_EXPIRE` 控制(默
|
||||
|
||||
## 工程管理
|
||||
|
||||
需认证。以下接口均需携带 Bearer Token,工程归属于当前登录用户。
|
||||
需认证。以下接口均需通过 Cookie 携带 Token,工程归属于当前登录用户。
|
||||
|
||||
| 状态 | 方法 | 路径 | 说明 |
|
||||
|------|------|------|------|
|
||||
@@ -260,7 +259,7 @@ Token 通过登录接口获取,过期时间由 `GEN2D_JWT_EXPIRE` 控制(默
|
||||
|
||||
### DELETE /api/v1/projects/:projectId
|
||||
|
||||
级联删除工程下的所有任务、素材及 OSS 文件。
|
||||
级联删除工程下的所有任务、素材及本地文件。
|
||||
|
||||
响应:
|
||||
|
||||
@@ -443,7 +442,7 @@ Token 通过登录接口获取,过期时间由 `GEN2D_JWT_EXPIRE` 控制(默
|
||||
"assets": [
|
||||
{
|
||||
"id": "asset_001",
|
||||
"url": "https://cdn.example.com/users/user_a1B2c3D4/projects/proj_abc123/tasks/task_xyz789/output/spritesheet.png",
|
||||
"url": "users/user_a1B2c3D4/projects/proj_abc123/tasks/task_xyz789/output/spritesheet.png",
|
||||
"format": "png",
|
||||
"width": 256,
|
||||
"height": 64,
|
||||
@@ -461,7 +460,7 @@ Token 通过登录接口获取,过期时间由 `GEN2D_JWT_EXPIRE` 控制(默
|
||||
|
||||
### WebSocket 消息格式
|
||||
|
||||
连接路径:`ws://host/api/v1/tasks/:taskId/ws?token=<jwt>`(通过 query 参数传递 Token)
|
||||
连接路径:`ws://host/api/v1/tasks/:taskId/ws`(通过 httpOnly Cookie 自动携带认证信息)
|
||||
|
||||
```typescript
|
||||
interface PipelineProgress {
|
||||
@@ -502,41 +501,3 @@ interface PipelineProgress {
|
||||
{"stage":"format_adapter","status":"completed","progress":100,"result":{"assets":[...]}}
|
||||
```
|
||||
|
||||
## 缓存管理
|
||||
|
||||
需认证。用于管理应用层去重缓存(详见 [数据存储 — 去重策略](database.md#去重策略)),主要用于调试和运维场景。
|
||||
|
||||
| 状态 | 方法 | 路径 | 说明 |
|
||||
|------|------|------|------|
|
||||
| [ ] | DELETE | `/api/v1/cache/:key` | 清除特定去重缓存条目 |
|
||||
| [ ] | POST | `/api/v1/cache/clear` | 批量清除所有去重缓存 |
|
||||
|
||||
### DELETE /api/v1/cache/:key
|
||||
|
||||
清除指定去重键的缓存条目。`:key` 为 `hash(prompt + assetType + params)` 生成的去重键,仅在需要手动解除去重锁定时使用。
|
||||
|
||||
响应:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/v1/cache/clear
|
||||
|
||||
清除所有去重缓存条目,不影响正在执行的任务。
|
||||
|
||||
响应:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"cleared": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user