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:
2026-05-24 10:56:40 +08:00
parent f4c1a10403
commit cbcda82515
7 changed files with 206 additions and 255 deletions
+16 -55
View File
@@ -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
}
}
```