admin/rust-imager

Fork 0

Files

lychang d64b85bc9a update code level

2026-07-21 03:33:35 +08:00

11 KiB

Raw Blame History

Imager API 文档

Base URL: http://<host>:<port>/api

相册

GET /api/albums

获取全量相册列表（从内存缓存）。

参数：无

响应：AlbumInfo[]

[
  {
    "id": "uuid",
    "title": "相册标题",
    "document": "文件夹名",
    "description": "描述",
    "cover_image_id": "uuid",
    "image_count": 100,
    "created_at": "2024-01-01T00:00:00",
    "tags": ["标签1", "标签2"],
    "persons": ["人物1"]
  }
]

GET /api/search

组合搜索（关键词/标签/人物过滤）。

参数（query）：

参数	类型	默认值	说明
q	string	-	标题关键词模糊匹配
tag	string	-	标签精确匹配
person	string	-	人物精确或模糊匹配
page	int	1	页码
limit	int	50	每页条数（最大 200）

响应：AlbumInfo[]

GET /api/album/random

从缓存随机返回一个相册。

参数：无

响应：AlbumInfo

GET /api/album/{id}

获取相册详情（含图片列表、标签、人物）。

参数（path）：

参数	类型	说明
id	uuid	相册 ID

响应：AlbumWithImages

{
  "album": {
    "id": "uuid",
    "title": "标题",
    "description": "描述",
    "cover_image_id": "uuid",
    "image_count": 100,
    "created_at": "...",
    "updated_at": "..."
  },
  "images": [
    {
      "id": "uuid",
      "album_id": "uuid",
      "filename": "1.jpg",
      "original_url": "...",
      "title": "图片标题",
      "description": null,
      "file_size": 123456,
      "width": 1920,
      "height": 1080,
      "mime_type": "image/jpeg",
      "created_at": "..."
    }
  ],
  "image_count": 100,
  "tags": ["标签1", "标签2"],
  "persons": ["人物1"]
}

POST /api/albums

创建新相册。

请求体：

{
  "title": "相册标题",
  "document": "文件夹名",
  "description": "描述（可选）"
}

响应（201 Created）：

{
  "id": "uuid"
}

图片

GET /api/image/{id}

获取图片原始二进制数据。

参数（path）：

参数	类型	说明
id	uuid	图片 ID

响应：二进制图片数据，Content-Type 按实际 mime 类型。带 ETag，Cache-Control: public, max-age=31536000。

GET /api/favorites

获取当前用户的收藏列表。

参数：无（用户固定为 default_user）

响应：FavoriteWithImage[]

GET /api/favorites/status/{id}

检查某图片的收藏状态。

参数（path）：

参数	类型	说明
id	uuid	图片 ID

POST /api/favorites

添加收藏。

请求体：

{
  "image_id": "uuid",
  "album_id": "uuid"
}

响应（201 Created）：

{
  "id": "uuid"
}

DELETE /api/favorites/{id}

按收藏 ID 取消收藏。

参数（path）：

参数	类型	说明
id	uuid	收藏 ID

DELETE /api/favorites/image/{id}

按图片 ID 取消收藏。

参数（path）：

参数	类型	说明
id	uuid	图片 ID

人物

GET /api/people

从内存缓存获取所有人名列表。

参数：无

响应：

{
  "total": 100,
  "persons": [
    {
      "id": 1,
      "name": "人物名",
      "display_name": "显示名",
      "total_albums": 10,
      "total_images": 50,
      "aliases": ["别名1", "别名2"]
    }
  ]
}

GET /api/people/search

从内存缓存搜索人名。

参数（query）：

参数	类型	说明
q	string	搜索关键词

响应：同上 PersonListResponse

GET /api/people/{name}

获取人物详情及关联相册。

参数（path）：

参数	类型	说明
name	string	人物名称

响应：PersonWithAlbums

{
  "album_count": 10,
  "person": {
    "id": 1,
    "name": "人物名",
    "display_name": "显示名",
    "total_albums": 10,
    "total_images": 50,
    "original_names": null,
    "created_at": "",
    "updated_at": ""
  },
  "albums": [/* AlbumInfo[] */]
}

GET /api/people/{id}/aliases

查询人物别名。

参数（path）：

参数	类型	说明
id	int	人物 ID

POST /api/people/delete/{name}

删除人物（从 imager.db + search.db 中清除），并重新解析受影响的相册。

参数（path）：

参数	类型	说明
name	string	人物名（URL 编码）

响应：

{
  "success": true,
  "person": "人物名",
  "albums_affected": 5,
  "persons_updated": 3,
  "tags_updated": 8,
  "synced": 5,
  "message": "人物 '人物名' 已删除，影响 5 个相册，重新解析完成..."
}

标签 / 元数据

GET /api/metadata/stats

从内存缓存计算元数据统计。

参数：无

响应：

{
  "total_persons": 100,
  "total_aliases": 50,
  "total_albums": 10000,
  "total_images": 50000,
  "total_tags": 2000
}

GET /api/tags/search

按标签搜索相册。

参数（query）：

参数	类型	说明
tag	string	必填，标签名

响应：AlbumInfo[]

GET /api/tags/popular

获取热门标签。

参数（query）：

参数	类型	默认值	说明
limit	int	50	返回数量

响应：

{
  "total": 50,
  "tags": [
    { "tag": "标签名", "count": 1000, "album_count": 1000 }
  ]
}

POST /api/tags/delete/{name}

删除标签（从 dict/album_tags/tags 表中清除），并重新解析受影响的相册。

参数（path）：

参数	类型	说明
name	string	标签名（URL 编码）

响应：

{
  "success": true,
  "tag": "标签名",
  "albums_affected": 5,
  "persons_updated": 3,
  "tags_updated": 8,
  "synced": 5,
  "message": "标签 '标签名' 已删除，影响 5 个相册，重新解析完成..."
}

参数	类型	默认值	说明
q	string	-	输入前缀
limit	int	10	返回数量

参数	类型	默认值	说明
q	string	-	输入名称
limit	int	10	返回数量

参数	类型	说明
context	string	必填，标签或人名
limit	int	默认 15

参数	类型	默认值	说明
limit	int	20（最大 50）	返回数量

管线

POST /api/pipeline/run

手动触发完整管线。

参数：无

响应：

{
  "success": true,
  "tags_cleaned": 0,
  "short_tags_removed": 0,
  "person_like_tags_removed": 0,
  "dirty_albums_detected": 0,
  "non_persons_deleted": 0,
  "stop_word_persons_removed": 0,
  "new_albums_found": 0,
  "persons_updated": 0,
  "tags_updated": 0,
  "persons_merged": 0,
  "aliases_moved": 0,
  "tags_removed_person": 0,
  "empty_albums_deleted": 0,
  "dup_albums_deleted": 0,
  "search_db_synced": 0,
  "message": "管线执行完毕：..."
}

POST /api/pipeline/reparse

重置所有相册为未处理状态，重新解析全部标签和人物并同步到 search.db。

参数：无

响应：

{
  "success": true,
  "albums_parsed": 100,
  "persons_updated": 80,
  "tags_updated": 200,
  "synced_to_search_db": 100,
  "message": "重新解析完成：..."
}

POST /api/pipeline/reparse-persons

重置所有相册，重新解析全部人物（清空 search.db 的人物关联后运行完整管线）。

参数：无

响应：

{
  "success": true,
  "albums_parsed": 100,
  "persons_updated": 80,
  "persons_merged": 5,
  "aliases_moved": 3,
  "non_persons_deleted": 2,
  "stop_word_persons_removed": 1,
  "synced_to_search_db": 100,
  "message": "人物重新解析完成：..."
}

POST /api/pipeline/reparse-tags

重置所有相册，重新解析全部标签（清空 search.db 的标签关联后运行完整管线）。

参数：无

响应：

{
  "success": true,
  "albums_parsed": 100,
  "tags_updated": 200,
  "short_tags_removed": 5,
  "synced_to_search_db": 100,
  "message": "标签重新解析完成：..."
}

词典

GET /api/dict/stats

查看标签词典状态。

参数：无

响应：

{
  "stats": "标签词典: ...",
  "categories": [
    { "name": "style", "label": "风格", "count": 50 }
  ],
  "total_tags": 2000,
  "total_stop_words": 20,
  "person_prefixes": ["prefix1"],
  "excluded_person_names": ["name1"],
  "included_person_names": ["name2"]
}

POST /api/dict/reload

从 search.db 的 dict 表热重载词典到内存。

参数：无

响应：

{
  "success": true,
  "message": "词典已从 search.db 重载: ..."
}

POST /api/dict/update

批量更新 dict 表条目，并自动重载内存词典。

请求体（数组）：

[
  {
    "word": "写真",
    "type": "tag",
    "category": "topic",
    "freq": null,
    "merged_to": null
  },
  {
    "word": "张三",
    "type": "person",
    "category": null,
    "freq": null,
    "merged_to": null
  }
]

type 可选值：tag、person、stop_word、person_prefix、excluded_person

响应：

{
  "success": true,
  "message": "更新 2 条字典条目，词典已从 search.db 重载: ...",
  "updated": 2
}

缓存

POST /api/cache/refresh

手动刷新所有内存缓存（AlbumsCache / TagCache / PersonCache）。

参数：无

响应：

{
  "success": true,
  "message": "缓存已刷新"
}

迁移

GET /api/migration/stats

查看当前数据库迁移状态。

参数：无

POST /api/migration/run

执行从旧数据库的数据迁移。

参数（query）：

参数	类型	说明
path	string	必填，旧数据库文件路径

队列

GET /api/queue/stats

获取任务队列状态。

参数：无

静态页面

方法	路径	说明
GET	`/`	首页（相册列表）
GET	`/album`	相册详情页（需 ?id=xxx 参数）
GET	`/assets/*`	静态资源文件

所有 API 响应均为 JSON 格式（仅 /api/image/{id} 返回二进制）。无认证鉴权。

11 KiB Raw Blame History Unescape Escape

Imager API 文档

相册

GET /api/albums

GET /api/search

GET /api/album/random

GET /api/album/{id}

POST /api/albums

图片

GET /api/image/{id}

收藏

GET /api/favorites

GET /api/favorites/status/{id}

POST /api/favorites

DELETE /api/favorites/{id}

DELETE /api/favorites/image/{id}

人物

GET /api/people

GET /api/people/search

GET /api/people/{name}

GET /api/people/{id}/aliases

POST /api/people/delete/{name}

标签 / 元数据

GET /api/metadata/stats

GET /api/tags/search

GET /api/tags/popular

POST /api/tags/delete/{name}

推荐

GET /api/recommend/tags

GET /api/recommend/persons

GET /api/recommend/related

GET /api/recommend/popular-persons

管线

POST /api/pipeline/run

POST /api/pipeline/reparse

POST /api/pipeline/reparse-persons

POST /api/pipeline/reparse-tags

词典

GET /api/dict/stats

POST /api/dict/reload

POST /api/dict/update

缓存

POST /api/cache/refresh

迁移

GET /api/migration/stats

POST /api/migration/run

队列

GET /api/queue/stats

静态页面

11 KiB

Raw Blame History