release: v1.4.0 — 标签系统、操作日志扩展与文档截图更新

- 每用户标签与彩色打标，图库 OR/AND 筛选与批量打标 - 操作日志记录登录、删除、设置与标签操作 - API 标签/打标接口；README 与文档站截图同步
2026-09-09 14:46:52 +08:00
1 parent f17d79b236
commit 737235acff
@@ -2,6 +2,8 @@

 PicHost 提供 REST 接口与 Twikoo 兼容端点。登录后打开顶栏 **API** 页：左侧为接口目录与 Token 管理，中间为参数说明与 cURL 示例，右侧可 **在线调试** 发送请求。

+![API 文档与在线调试](/screenshots/api.png)
+
 ## 鉴权

 所有 REST 接口使用请求头：
@@ -28,9 +30,12 @@ Auth-Token: YOUR_TOKEN
 ```bash
 curl -X POST "https://admin.example.com/api/images/upload" \
  -H "Auth-Token: YOUR_TOKEN" \
-  -F "image=@./demo.png"
+  -F "image=@./demo.png" \
+  -F 'tagIds=[1,2]'
 ```

+可选表单字段 `tagIds`：JSON 数组字符串（如 `[1,2]`）或重复字段，上传成功后自动打标。存储路径仍为 `images/年/月/id.webp`，**不会**因标签创建子目录。
+
 ### 2. 获取图片列表

 `GET /api/images`
@@ -42,6 +47,16 @@ curl "https://admin.example.com/api/images?limit=20&page=1" \
  -H "Auth-Token: YOUR_TOKEN"
 ```

+可选查询参数：
+
+| 参数 | 说明 |
+| ---- | ---- |
+| `tagIds` | 逗号分隔的标签 ID，默认 **OR**（含任一标签） |
+| `tagMode` | `and` 时多标签取交集 |
+| `untagged` | `1` 仅返回无标签图片 |
+
+响应 `items[]` 含 `tags` 数组（`id`、`name`、`color`）。
+
 ### 3. 搜索图片

 `GET /api/images/search`
@@ -77,6 +92,27 @@ curl -X POST "https://admin.example.com/api/images/batch-delete" \
  -d '{"keys":["images/2026/08/a.webp","images/2026/08/b.webp"]}'
 ```

+### 6. 标签管理
+
+| 方法 | 路径 | 说明 |
+| ---- | ---- | ---- |
+| `GET` | `/api/tags` | 当前用户标签列表（含 `imageCount`） |
+| `POST` | `/api/tags` | 创建 `{ "name": "工作", "color": "#22c55e" }` |
+| `PATCH` | `/api/tags/:id` | 改名称/颜色 |
+| `DELETE` | `/api/tags/:id` | 删除标签（不删图片） |
+| `POST` | `/api/tags/merge` | `{ "sourceIds": [2,3], "targetId": 1 }` |
+
+### 7. 图片打标
+
+| 方法 | 路径 | 说明 |
+| ---- | ---- | ---- |
+| `POST` | `/api/images/tags` | `{ "key": "images/…", "tagIds": [1,2] }` 追加 |
+| `PATCH` | `/api/images/tags` | 整体替换标签集合 |
+| `DELETE` | `/api/images/tags` | `key` + `tagId` 移除单个 |
+| `POST` | `/api/images/batch-tags` | `{ "keys": [], "tagIds": [], "action": "add" \| "remove" }` |
+
+`GET /api/stats` 支持与列表相同的 `tagIds` / `tagMode` / `untagged` 筛选，统计与当前筛选一致。
+
 ## 错误格式

 REST 接口返回 JSON，含 `code` 与 `message`（如 `UNAUTHORIZED`、`FORBIDDEN`、`INVALID_REQUEST`）。Twikoo 端点使用 EasyImage 兼容 JSON 格式。
@@ -4,6 +4,24 @@ PicHost 版本历史与重要变更说明。完整记录亦见仓库根目录 [C

 ---

+## [1.4.0] — 2026-09-09
+
+### 新增
+
+- **标签**：每用户彩色标签；设置页管理；上传/图库批量打标；图库 OR / AND 筛选
+- **操作日志**：登录、删除、设置、标签等操作；日期与用户筛选
+- **API**：标签与打标接口；上传 `tagIds`；列表/统计标签筛选
+
+### 文档
+
+- 截图与 README 同步 v1.4 界面
+
+## [1.3.0] — 2026-09-07
+
+### 新增
+
+- **站点备份 / 恢复 / 跨后端同步** 与任务中心；运维 CLI `backup-export`、`backup-restore`、`storage-sync`
+
 ## [1.2.8] — 2026-09-04

 ### 改进
@@ -1,4 +1,6 @@
-PicHost 支持通过环境变量（Docker / `.env`）与后台 **设置** 页配置。管理员在 **设置与偏好**（`/settings`）左侧切换 **基础设置**、**域名与路径**、**访问控制**、**操作日志**；多数项 **SQLite 优先**；部分项环境变量可覆盖或锁定后台编辑。
+PicHost 支持通过环境变量（Docker / `.env`）与后台 **设置** 页配置。管理员在 **设置与偏好**（`/settings`）左侧切换 **基础设置**、**域名与路径**、**访问控制**、**标签管理**、**操作日志**；多数项 **SQLite 优先**；部分项环境变量可覆盖或锁定后台编辑。
+
+![基础设置](/screenshots/settings.png)

 ## 优先级总览

@@ -37,7 +37,9 @@ docker compose up -d
   - **创建管理员**：填写用户名与密码，可选开放注册、双域名等。
   - **从备份恢复**：上传 `.phost.tar.gz` 整站备份包（覆盖当前数据；云存储密钥需恢复后重新填写）。
 3. （可选）配置网站域名、图片域名、防盗链等 — 详见 [环境变量](./configuration.md) 与 [双域名分离](./domain-separation.md)。
-4. 登录后可在首页上传图片；顶栏可进入 **图库**、**存储**（管理员）、**设置**、**API**。
+4. 登录后可在首页 **拖拽 / 点击 / Ctrl+V** 上传图片；上传结果区支持复制直链/Markdown/HTML/BBCode，并可 **批量打标签**。顶栏可进入 **图库**、**存储**（管理员）、**设置**、**API**。
+
+![上传](/screenshots/upload.png)

 | 创建管理员 | 从备份恢复 |
 | :--------: | :--------: |
@@ -12,15 +12,27 @@

 ## 截图预览

-**main** 分支暂无公网演示，以下为当前产品界面（v1.3.0+）。
+**main** 分支暂无公网演示，以下为当前产品界面（v1.4.0+）。

-| API | 图库（详情） |
+| 上传 | 批量打标 |
 | :-: | :-: |
-| ![API](/screenshots/api.png) | ![图库](/screenshots/gallery.png) |
+| ![上传](/screenshots/upload.png) | ![批量打标](/screenshots/tags-batch.png) |

-| 存储管理 | 设置与偏好 |
-| :------: | :--------: |
-| ![存储管理](/screenshots/storage.png) | ![设置与偏好](/screenshots/settings.png) |
+| 上传结果（含标签） | API |
+| :----------------: | :-: |
+| ![上传结果](/screenshots/upload-tags.jpg) | ![API](/screenshots/api.png) |
+
+| 图库（网格） | 图库（列表） |
+| :----------: | :----------: |
+| ![图库网格](/screenshots/gallery.png) | ![图库列表](/screenshots/gallery-list.png) |
+
+| 图片详情 | 标签管理 |
+| :------: | :------: |
+| ![图片详情](/screenshots/gallery-detail.png) | ![标签管理](/screenshots/tags.png) |
+
+| 存储管理 | 基础设置 |
+| :------: | :------: |
+| ![存储管理](/screenshots/storage.png) | ![基础设置](/screenshots/settings.png) |

 | 首次设置 | 从备份恢复 |
 | :------: | :--------: |
@@ -52,4 +52,4 @@ npm run docs:build    # 构建静态站点
 npm run docs:preview  # 预览构建结果
 ```

-文档源码在 `docs-site/`；截图源文件在 `docs/screenshots/`（含 `login.png`、`setup.png`、`setup-restore.png` 等），构建前会复制到 `docs-site/public/screenshots/`。在线文档：<https://o96u.github.io/PicHost/>
+文档源码在 `docs-site/`；截图源文件在 `docs/screenshots/`（含 `upload.png`、`gallery.png`、`tags.png`、`api.png`、`storage.png`、`settings.png`、`logs.png`、`setup.png` 等），构建前会复制到 `docs-site/public/screenshots/`。在线文档：<https://o96u.github.io/PicHost/>
@@ -18,6 +18,8 @@ PicHost 支持 **本地磁盘** 与 **S3 兼容对象存储**（Cloudflare R2、

 所有图片 **key** 以 `images/` 开头。上传 API **不再接受** `folder` 参数。

+**图片分类**使用每用户 **标签**（`tags` / `image_tags` 表），不改变磁盘路径。图库页按标签筛选；详见 [API 文档](./api.md#6-标签管理)。
+
 ## 添加存储后端

 1. 以管理员登录，打开 **存储** → **添加存储**。
@@ -56,7 +58,9 @@ PicHost 支持 **本地磁盘** 与 **S3 兼容对象存储**（Cloudflare R2、
 ## 用量与筛选

 - 存储页展示各后端用量（本地扫描目录，对象存储查询 API）
- 图库可按 **存储后端**、**上传来源** 筛选，支持网格/列表视图切换；点击图片打开详情弹窗（尺寸、存储路径、多格式链接复制）
+- 图库可按 **存储后端**、**上传来源**、**标签** 筛选，支持网格/列表视图切换；点击图片打开详情弹窗（尺寸、存储路径、标签、多格式链接复制）
+
+![图库网格](/screenshots/gallery.png) ![图库列表](/screenshots/gallery-list.png) ![图片详情](/screenshots/gallery-detail.png)

 ## 备份与迁移（v1.3.0+）

@@ -16,6 +16,7 @@ PicHost 使用基于角色的访问控制（RBAC）：**管理员（admin）**
 | 全局 API Token 管理 | ✓ | — |
 | 个人 API Token | ✓ | ✓ |
 | 图库统计概览（含注册用户数） | ✓ | 部分 |
+| 标签管理（设置 → 标签管理） | ✓ | — |
 | 操作日志（设置 → 操作日志） | ✓ | — |

 普通用户顶栏：**API**、**图库**；用户菜单：**修改密码**、**退出登录**。
@@ -39,6 +40,20 @@ PicHost 使用基于角色的访问控制（RBAC）：**管理员（admin）**
 - 验证配置错误无法登录时：`docker exec pichost slider` 重置为本地滑块
 - 登录失败有速率限制

+## 标签
+
+- 标签按 **用户隔离**：普通用户仅管理、筛选自己的标签与图片
+- 首页上传完成后可 **单张打标** 或 **批量打标签**；图库支持按标签筛选（多标签 OR / AND）与批量打标
+- 管理员在 **设置 → 标签管理** 新建、改色、合并、删除标签；标签仅用于分类，**不改变** `images/` 存储路径
+
+![批量打标](/screenshots/tags-batch.png) ![标签管理](/screenshots/tags.png)
+
+## 操作日志
+
+管理员在 **设置 → 操作日志** 查看上传、删除、登录、设置变更、标签操作等记录，支持按日期、用户、操作类型、来源筛选。
+
+![操作日志](/screenshots/logs.png)
+
 ## 上传偏好与自动删除

 - **上传偏好**：管理员在 **设置 → 基础设置** 配置客户端预压缩、自动复制链接等；普通用户可在首页上传卡片背面调整个人偏好