From bb0cc399508a005fbf4220420c6652c45b690e47 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=99=88=E6=AD=86?= <2685475410@qq.com>
Date: Tue, 29 Sep 2026 23:52:10 +0800
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(readme):=20=E5=90=8C?=
 =?UTF-8?q?=E6=AD=A5=E8=BF=91=E6=9C=9F=E6=94=B9=E5=8A=A8=E5=B9=B6=E4=BF=AE?=
 =?UTF-8?q?=E6=AD=A3=E8=BF=87=E6=97=B6=E5=86=85=E5=AE=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 补充 /healthz、protect_all 配置、错误响应规范（400/500/401）、缓存机制表
- 修正接口参数名与代码不符处：content 实为 item_id、multi-content 需 book_id、media 系列为 item_ids 等
- /vacuum 修正为 POST；技术栈删除已移除的 Gin，改为标准库 net/http
---
 README.md | 50 ++++++++++++++++++++++++++++++++------------------
 1 file changed, 32 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 27b5f9c..5f2f687 100644
--- a/README.md
+++ b/README.md
@@ -34,9 +34,11 @@ Go 语言实现的番茄小说非官方 API 服务，完整实现了签名算法
 
 - **签名算法** - Gorgon、8404、Argus、Ladon、Khronos
 - **设备密钥池** - 多设备轮换、自动补充
-- **SQLite 缓存** - 本地缓存、过期清理、数据库压缩；支持切换 PostgreSQL 与 Redis
+- **多级缓存** - 正文/详情/目录等 24 小时缓存，搜索/分类短缓存；存储后端可选 SQLite / PostgreSQL / Redis
 - **配置热更新** - 修改配置无需重启
-- **访问控制** - 支持 AccessKey 验证
+- **访问控制** - AccessKey 验证（常量时间比较防时序攻击），可扩展保护全部业务接口
+- **优雅退出** - 超时保护、信号驱动的平滑关闭
+- **错误规范** - 统一 JSON 错误响应，缺参 400 / 服务端错误 500
 
 ## 项目结构
 
@@ -134,36 +136,37 @@ go run ./cmd/fanqie
 | 接口 | 方法 | 说明 |
 | ------ | ------ | ------ |
 | `GET /` | GET | 服务首页 |
+| `GET /healthz` | GET | 存活探针（不校验密钥，供容器/反代使用） |
 | `GET /status` | GET | 服务状态（需 AccessKey） |
 | `GET /self-info` | GET | 自我信息（需 AccessKey） |
-| `GET /vacuum` | GET | 数据库压缩（需 AccessKey） |
+| `POST /vacuum` | POST | 数据库压缩（需 AccessKey） |
 
 ### 书籍相关
 
 | 接口 | 方法 | 说明 | 参数 |
 | ------ | ------ | ------ | ------ |
-| `/search` | GET | 搜索书籍 | `keyword`, `tab_type`, `offset` |
+| `/search` | GET | 搜索书籍 | `query`（或 `key`）, `tab_type`, `offset` |
 | `/detail` | GET | 书籍详情 | `book_id` |
 | `/info` | GET | 书籍详情（同 detail） | `book_id` |
 | `/catalog` | GET | 章节目录 | `book_id` |
 | `/directory/all_items` | GET | 章节目录（同 catalog） | `book_id` |
-| `/multi-detail` | GET | 批量书籍详情 | `book_ids`（逗号分隔） |
+| `/multi-detail` | GET | 批量书籍详情 | `book_id`（逗号分隔） |
 
 ### 内容相关
 
 | 接口 | 方法 | 说明 | 参数 |
 | ------ | ------ | ------ | ------ |
-| `/content` | GET | 章节内容 | `chapter_id`, `book_id` |
-| `/multi-content` | GET | 批量章节内容 | `chapter_ids`（逗号分隔） |
-| `/item-summary` | GET | 章节摘要 | `book_id`, `chapter_id` |
+| `/content` | GET | 章节内容 | `item_id` |
+| `/multi-content` | GET | 批量章节内容 | `book_id`, `item_ids`（逗号分隔） |
+| `/item-summary` | GET | 章节摘要 | `book_id`, `item_ids`（逗号分隔） |
 
 ### 评论相关
 
 | 接口 | 方法 | 说明 | 参数 |
 | ------ | ------ | ------ | ------ |
-| `/chapter_review` | GET | 章节评论 | `book_id`, `chapter_id` |
-| `/review` | GET | 书评列表 | `book_id`, `offset`, `limit` |
-| `/review_html` | GET | 评论 HTML | `book_id`, `chapter_id` |
+| `/chapter_review` | GET | 章节评论 | `book_id`, `item_id` |
+| `/review` | GET | 书评列表 | `book_id`, `item_id`, `para`, `comment_id`, `offset`, `limit` |
+| `/review_html` | GET | 评论 HTML | `book_id`, `item_id`, `para` |
 
 ### 分类相关
 
@@ -176,9 +179,9 @@ go run ./cmd/fanqie
 
 | 接口 | 方法 | 说明 | 参数 |
 | ------ | ------ | ------ | ------ |
-| `/audio` | GET | 音频内容 | `audio_id`, `tone_id` |
-| `/video` | GET | 视频内容 | `video_id` |
-| `/manga` | GET | 漫画内容 | `manga_id`, `chapter_id` |
+| `/audio` | GET | 音频内容 | `item_ids`, `tone_id`, `output` |
+| `/video` | GET | 视频内容 | `item_ids` |
+| `/manga` | GET | 漫画内容 | `item_ids`（或 `item_id`）, `show_html`, `output` |
 | `/manga/image/{itemID}/{index}` | GET | 漫画图片 | 路径参数 |
 
 ## 内容获取示例
@@ -235,6 +238,7 @@ server:
   host: "0.0.0.0"      # 监听地址
   port: "40180"         # 监听端口
   access_key: ""        # 访问密钥（可选）
+  protect_all: false    # 业务接口也要求访问密钥（公网部署建议开启）
 
 # 番茄小说配置
 fanqie:
@@ -324,6 +328,7 @@ cp .env.example .env
 | `server.host` | HTTP 服务监听地址 | `0.0.0.0` |
 | `server.port` | HTTP 服务监听端口 | `40180` |
 | `server.access_key` | 访问密钥，设为空则不验证 | - |
+| `server.protect_all` | 业务接口是否也要求访问密钥 | `false` |
 | `fanqie.algorithm` | 签名算法 `gorgon` / `8404` | `gorgon` |
 | `fanqie.signature` | 签名方法 `sign2` / `sign4` | `sign4` |
 | `fanqie.content.*` | 正文内容处理选项 | 见上文 |
@@ -377,15 +382,24 @@ cp .env.example .env
 
 ## 缓存机制
 
-- **SQLite 本地缓存** - 缓存书籍内容和章节数据
-- **自动清理** - 定期清理过期缓存
+- **接口缓存** - 命中直接返回，不打上游（Redis 启用时优先走 Redis）
+- **自动清理** - 定期清理过期缓存（Redis 由 TTL 自动过期）
 - **数据库压缩** - 支持 VACUUM 操作优化数据库
 
+| 接口 | 缓存时长 |
+| ------ | ------ |
+| `/content` | 24 小时 |
+| `/detail`、`/info`、`/catalog`、`/multi-detail`、`/item-summary` | 24 小时 |
+| `/search`、`/category-front`、`/category-landing` | 10 分钟 |
+| `/audio` 代理链接 | 2 小时（匹配 CDN 有效期） |
+
+失败响应不缓存；评论类接口为动态数据，不缓存。
+
 ## 技术栈
 
 - **Go 1.24** - 编程语言
-- **Gin** - HTTP 框架（间接依赖）
-- **SQLite3** - 本地数据库
+- **net/http** - 标准库 HTTP 服务（超时保护 + 优雅退出）
+- **SQLite3 / PostgreSQL / Redis** - 缓存与存储
 - **Viper** - 配置管理
 - **goquery** - HTML 解析