✨ feat(manga,device): 漫画免签名兜底与 phone 注册身份选项

- /manga 设备池签名路线全部失败时自动降级 wkbrowser 免签名路线（materials/skeleton 三段策略收集原图直链，无需设备/签名/解密），响应附 source: wkbrowser
- 新增配置 fanqie.device_identity（默认 pad 保持现状；phone 对齐书源真机注册 payload：host_bit 64 + 补 hardware/device_device/fingerprint 字段）
- README 与 openapi.yaml 同步文档，新增 manga_fallback 解析测试

.deploy.env.example

@@ -0,0 +1,44 @@
+# ============================================================
+# 部署配置模板（deploy.sh 使用）
+#
+# 使用方法（在服务器上）：
+#   cp .deploy.env.example .deploy.env && vi .deploy.env
+#
+# 说明：
+#   - .deploy.env 不入库（.gitignore 已忽略），只写要覆盖的项
+#   - 路径类默认值由 APP_NAME 派生（如 /opt/${APP_NAME}/bin），改 APP_NAME 即全部跟随
+#   - 应用环境变量固定读取 ${SRC_DIR}/.env（模板见 .env.example，敏感密码放那里）
+# ============================================================
+
+# ---------- 应用信息 ----------
+# APP_NAME="fanqie"
+# APP_DESC="番茄小说api接口"
+
+# ---------- 运行用户 ----------
+# 留空 = 执行 deploy.sh 的当前用户
+RUN_USER=""
+
+# ---------- 路径 ----------
+# 代码目录，同时也是服务的工作目录（config/config.yaml、.env、cache.db 都在这里）
+SRC_DIR="/root/code/novel/fanqie-go"
+
+# 以下路径默认由 APP_NAME 派生，一般无需修改：
+# BIN_DIR="/opt/fanqie/bin"                          # 默认 /opt/${APP_NAME}/bin
+# SERVICE_FILE="/etc/systemd/system/fanqie.service"  # 默认 /etc/systemd/system/${APP_NAME}.service
+# NGINX_CONF="/etc/nginx/conf.d/fanqie.conf"         # 默认 /etc/nginx/conf.d/${APP_NAME}.conf
+
+# ---------- 网络 ----------
+# APP_PORT="40180"
+DOMAIN="fq.20010117.xyz"
+
+# ---------- 证书 ----------
+# acme.sh 申请证书的邮箱，用于账户注册与过期提醒
+CERT_EMAIL="you@example.com"
+# 证书安装目录（acme.sh --install-cert 目标，nginx 配置从此处读取）
+# CERT_DIR="/etc/nginx/ssl"
+
+# ---------- 编译 ----------
+# BUILD_TARGET="./cmd/fanqie"
+
+# ---------- 其他 ----------
+# KEEP_VERSIONS=5

.env.example

@@ -0,0 +1,18 @@
+# 敏感配置模板：复制为 .env 并填入真实值（.env 已被 gitignore，不会提交）
+# 环境变量优先于 config.yaml 中的对应配置
+
+# 进程时区（IANA 名称），日志时间戳与 /status 页所有时间均按此显示
+TZ=Asia/Shanghai
+
+# 服务访问密钥（/status、/self-info 等端点的鉴权）
+# FQ_SERVER_ACCESS_KEY=your-access-key
+
+# PostgreSQL 连接（覆盖 cache.postgres.*）
+FQ_PG_HOST=127.0.0.1
+FQ_PG_USER=postgres
+FQ_PG_PASSWORD=
+FQ_PG_DATABASE=fanqie
+
+# Redis 连接（覆盖 cache.redis.*）
+FQ_REDIS_HOST=127.0.0.1
+FQ_REDIS_PASSWORD=

.gitignore

@@ -12,7 +12,7 @@ pkg/
 *.out
 
 # Output of the go coverage tool
-*.html
+cover.html
 _coverage/
 
 # Go workspace file
@@ -28,6 +28,7 @@ go.work
 # Environment variables
 .env
 .env.local
+.deploy.env
 .env.*.local
 
 # OS
@@ -43,4 +44,17 @@ __pycache__
 
 # Build output
 /dist/
-/build/
+/build/
+
+cache.db
+video_cache/
+
+# Build output
+fanqie-*
+/fanqie
+
+# 环境变量（含真实密码，勿提交）
+.env
+.finesse/
+fanqie.log
+.codegraph/

Makefile

@@ -0,0 +1,20 @@
+BINARY      := fanqie
+VERSION     ?= $(shell date +%Y%m%d-%H%M%S)
+BUILD_TIME  := $(shell date -u '+%Y-%m-%dT%H:%M:%SZ')
+BUILD_TARGET := ./cmd/fanqie
+
+LDFLAGS := -s -w -X main.Version=$(VERSION) -X main.BuildTime=$(BUILD_TIME)
+
+.PHONY: build build-linux test clean
+
+build:
+	CGO_ENABLED=0 go build -ldflags="$(LDFLAGS)" -o $(BINARY)-$(VERSION) $(BUILD_TARGET)
+
+build-linux:
+	CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="$(LDFLAGS)" -o $(BINARY)-$(VERSION)-linux $(BUILD_TARGET)
+
+test:
+	go vet ./... && go test ./...
+
+clean:
+	rm -f $(BINARY)-*

README.md

@@ -30,13 +30,21 @@ Go 语言实现的番茄小说非官方 API 服务，完整实现了签名算法
 - 分类首页数据
 - 分类详情页（支持筛选、排序、分页）
 
+### 榜单与个人数据
+
+- 🏆 榜单（推荐 / 完结 / 热搜 / 黑马 / 爆更）
+- 📚 我的书架（按分组浏览，需 sessionid）
+- 🕐 阅读历史（含阅读进度，需 sessionid）
+
 ### 技术特性
 
 - **签名算法** - Gorgon、8404、Argus、Ladon、Khronos
 - **设备密钥池** - 多设备轮换、自动补充
-- **SQLite 缓存** - 本地缓存、过期清理、数据库压缩
+- **多级缓存** - 正文/详情/目录等 24 小时缓存，搜索/分类短缓存；存储后端可选 SQLite / PostgreSQL / Redis
 - **配置热更新** - 修改配置无需重启
-- **访问控制** - 支持 AccessKey 验证
+- **访问控制** - AccessKey 验证（常量时间比较防时序攻击），可扩展保护全部业务接口
+- **优雅退出** - 超时保护、信号驱动的平滑关闭
+- **错误规范** - 统一 JSON 错误响应，缺参 400 / 服务端错误 500
 
 ## 项目结构
 
@@ -109,7 +117,7 @@ fanqie-go/
 
 ### 环境要求
 
-- Go 1.24+
+- Go 1.25+
 - SQLite3
 
 ### 安装运行
@@ -127,56 +135,73 @@ go run ./cmd/fanqie
 
 ## API 接口文档
 
+机器可读的完整接口定义见 [openapi.yaml](openapi.yaml)(OpenAPI 3.1,可直接导入 Swagger UI / Apifox / Postman)。
+
 ### 基础接口
 
 | 接口 | 方法 | 说明 |
 | ------ | ------ | ------ |
 | `GET /` | GET | 服务首页 |
+| `GET /healthz` | GET | 存活探针（不校验密钥，供容器/反代使用） |
 | `GET /status` | GET | 服务状态（需 AccessKey） |
-| `GET /self-info` | GET | 自我信息（需 AccessKey） |
-| `GET /vacuum` | GET | 数据库压缩（需 AccessKey） |
 
 ### 书籍相关
 
 | 接口 | 方法 | 说明 | 参数 |
 | ------ | ------ | ------ | ------ |
-| `/search` | GET | 搜索书籍 | `keyword`, `tab_type`, `offset` |
+| `/search` | GET | 搜索书籍 | `query`（或 `key`）, `tab_type`, `offset`（结果在顶层 `data`，已按 `tab_type` 过滤展平） |
 | `/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`, `sort`, `offset`, `count` |
+| `/review_html` | GET | 评论 HTML | `book_id`, `item_id`, `para`, `sort`, `page`, `page_size` |
 
 ### 分类相关
 
 | 接口 | 方法 | 说明 | 参数 |
 | ------ | ------ | ------ | ------ |
 | `/category-front` | GET | 分类首页 | - |
-| `/category-landing` | GET | 分类详情 | `category_id`, `word_number`, `book_status`, `sort_by`, `offset` |
+| `/category-landing` | GET | 分类详情 | `category_id`, `word_number`, `book_status`, `sort_by`, `offset`, `selected_items`（新版分类标签自带筛选项，透传上游） |
+
+### 榜单与个人数据
+
+| 接口 | 方法 | 说明 | 参数 |
+| ------ | ------ | ------ | ------ |
+| `/rank` | GET | 榜单（免签名接口） | `side_type`（`10` 推荐 / `11` 完结 / `12` 热搜 / `13` 黑马 / `15` 爆更，默认推荐）, `page`（默认 1，每页 20 本） |
+| `/bookshelf` | GET | 我的书架（需登录） | `sessionid`（必填，见下方「获取 sessionid」）, `group`（可选，按分组过滤；响应含每本书的 `group_name`） |
+| `/read-history` | GET | 阅读历史（需登录） | `sessionid`（必填）, `offset`（默认 0，每页 20 条；响应每项的 `history` 字段保留上游原始记录，含阅读进度） |
+
+#### 获取 sessionid
+
+番茄网页版登录由字节风控（滑块验证）保护，无法通过 API 直接登录（书源实现同样依赖浏览器人工登录）。获取方式：
+
+1. 浏览器打开 [fanqienovel.com](https://fanqienovel.com/) 并登录（手机验证码或密码）
+2. F12 → Application → Cookies → 复制 `sessionid` 的值（有效期较长，可长期使用）
+3. 直接传入 `/bookshelf?sessionid=...` 或 `/read-history?sessionid=...` 使用（书架为空多半是 sessionid 无效或已过期）
 
 ### 媒体相关
 
 | 接口 | 方法 | 说明 | 参数 |
 | ------ | ------ | ------ | ------ |
-| `/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 | 漫画图片 | 路径参数 |
 
 ## 内容获取示例
@@ -202,16 +227,18 @@ GET http://localhost:40180/catalog?book_id=xxx
 ### 获取章节内容
 
 ```bash
-GET http://localhost:40180/content?book_id=xxx&chapter_id=xxx
+GET http://localhost:40180/content?item_id=xxx
 ```
 
 支持以下 URL 参数覆盖默认配置：
 
 | 参数 | 说明 | 可选值 |
 | ------ | ------ | ------ |
-| `text_mode` | 文本模式 | `plain`（纯文本）, `html`（HTML） |
-| `img_mode` | 图片模式 | `remove`（移除）, `keep`（保留） |
-| `review_mode` | 评论模式 | `remove`（移除）, `keep`（保留） |
+| `text_mode` | 文本模式 | `plain`（纯文本）, `html`（HTML）, 或 `1`/`0` |
+| `img_mode`（或 `image_mode`） | 图片模式 | `remove`（移除）, `keep`（保留）, 或 `0`/`1` |
+| `review_mode`（或 `review`） | 评论模式 | `keep`（启用段评）, `remove`（禁用）, 或 `1`/`0` |
+
+纯文本输出（`text_mode=plain` 或配置 `remove_html_tags: true`）时不注入段评标记——`<comment>` 为 XML 标签，纯文本无法承载；需要段评时配置 `remove_html_tags: false`。
 
 ### 批量获取
 
@@ -233,6 +260,13 @@ server:
   host: "0.0.0.0"      # 监听地址
   port: "40180"         # 监听端口
   access_key: ""        # 访问密钥（可选）
+  protect_all: false    # 业务接口也要求访问密钥（公网部署建议开启）
+
+  # 请求日志：记录 时间/IP/方法/路径/状态/耗时（query 中的 key 自动脱敏），
+  # 4xx/5xx 额外保留错误响应摘要（前 4KB）；不记录响应体。/status 页可查看最近 20 条
+  request_log:
+    enabled: false      # 是否启用
+    retention_days: 7   # 保留天数，自动清理
 
 # 番茄小说配置
 fanqie:
@@ -244,6 +278,11 @@ fanqie:
   # - "sign4": X-Gorgon + X-Ladon + X-Argus + X-Khronos
   signature: "sign4"
 
+  # 注册设备身份:
+  # - "pad": 平板身份（默认，历史行为）
+  # - "phone": 手机身份（对齐书源真机注册 payload，可对照测试注册率/存活率）
+  device_identity: "pad"
+
   # 内容处理
   content:
     remove_images: false        # 移除图片
@@ -258,15 +297,30 @@ fanqie:
   # 漫画处理
   manga:
     # 输出模式:
-    # - "proxy": 代理模式
-    # - "url": 直接返回图片 URL
+    # - "proxy": 代理模式（图片已解密，推荐；"url" 返回的原始链接 404 且内容加密不可用）
     # - "data_uri": Base64 编码
-    output_mode: "url"
+    # - "url": 直接返回图片 URL（不可用）
+    output_mode: "proxy"
 
 # 缓存配置
 cache:
   enabled: true              # 启用缓存
-  sqlite_path: "./cache.db" # SQLite 路径
+  backend: sqlite            # 存储后端: sqlite | postgres
+  sqlite_path: "./cache.db" # SQLite 路径（backend 为 sqlite 时使用）
+  # PostgreSQL连接配置（backend 为 postgres 时使用）
+  postgres:
+    host: "127.0.0.1"      # 主机
+    port: 5432             # 端口
+    user: "postgres"       # 用户名
+    password: ""           # 密码
+    database: "fanqie"     # 数据库名
+    sslmode: "disable"     # SSL 模式: disable | prefer | require
+  redis:                     # Redis 热缓存层（启用后与 SQL 双写：Redis 短 TTL + SQL 持久层 30 天）
+    enabled: false
+    host: "127.0.0.1"      # 主机
+    port: 6379             # 端口
+    password: ""           # 密码
+    db: 0                  # 数据库编号
   cleanup_enabled: true     # 启用自动清理
   cleanup_seconds: 86400    # 清理间隔（秒）
 
@@ -278,6 +332,28 @@ device_key_pool:
   max_size: 30            # 最大设备数
 ```
 
+### 敏感配置（.env）
+
+密码等敏感值不建议写进 `config.yaml`（会进 git 历史）。复制 `.env.example` 为 `.env` 填入真实值即可，`.env` 已被 gitignore：
+
+```bash
+cp .env.example .env
+```
+
+支持的环境变量（优先于 `config.yaml` 对应项）：
+
+| 环境变量 | 覆盖配置 | 说明 |
+| -------- | -------- | ---- |
+| `FQ_SERVER_ACCESS_KEY` | `server.access_key` | 服务访问密钥 |
+| `FQ_PG_HOST` | `cache.postgres.host` | PostgreSQL 主机 |
+| `FQ_PG_USER` | `cache.postgres.user` | PostgreSQL 用户名 |
+| `FQ_PG_PASSWORD` | `cache.postgres.password` | PostgreSQL 密码 |
+| `FQ_PG_DATABASE` | `cache.postgres.database` | PostgreSQL 数据库名 |
+| `FQ_REDIS_HOST` | `cache.redis.host` | Redis 主机 |
+| `FQ_REDIS_PASSWORD` | `cache.redis.password` | Redis 密码 |
+
+已有环境变量优先于 `.env` 文件中的值。
+
 ### 配置说明表
 
 | 配置项 | 说明 | 默认值 |
@@ -285,12 +361,26 @@ device_key_pool:
 | `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.device_identity` | 注册设备身份 `phone` / `pad` | `pad` |
 | `fanqie.content.*` | 正文内容处理选项 | 见上文 |
-| `fanqie.manga.output_mode` | 漫画输出模式 | `url` |
-| `cache.enabled` | 是否启用 SQLite 缓存 | `true` |
+| `fanqie.manga.output_mode` | 漫画输出模式 | `proxy` |
+| `cache.enabled` | 是否启用正文内容缓存 | `true` |
+| `cache.backend` | SQL 存储后端 `sqlite` / `postgres` | `sqlite` |
 | `cache.sqlite_path` | SQLite 数据库路径 | `./cache.db` |
+| `cache.postgres.host` | PostgreSQL 主机 | `127.0.0.1` |
+| `cache.postgres.port` | PostgreSQL 端口 | `5432` |
+| `cache.postgres.user` | PostgreSQL 用户名 | `postgres` |
+| `cache.postgres.password` | PostgreSQL 密码 | 空 |
+| `cache.postgres.database` | PostgreSQL 数据库名 | `fanqie` |
+| `cache.postgres.sslmode` | SSL 模式 | `disable` |
+| `cache.redis.enabled` | 启用 Redis 缓存（正文与音频代理缓存走 Redis） | `false` |
+| `cache.redis.host` | Redis 主机 | `127.0.0.1` |
+| `cache.redis.port` | Redis 端口 | `6379` |
+| `cache.redis.password` | Redis 密码 | 空 |
+| `cache.redis.db` | Redis 数据库编号 | `0` |
 | `device_key_pool.enabled` | 是否启用设备密钥池 | `true` |
 | `device_key_pool.initial_size` | 初始设备数量 | `20` |
 | `device_key_pool.min_size` | 最小设备数量 | `10` |
@@ -326,15 +416,58 @@ device_key_pool:
 
 ## 缓存机制
 
-- **SQLite 本地缓存** - 缓存书籍内容和章节数据
-- **自动清理** - 定期清理过期缓存
+Redis 启用时为**双层架构**：Redis 热层（TTL=业务缓存时长）+ SQL 持久层（不可变内容固定保留 30 天）。
+
+- **读**：Redis → 未命中查 SQL（命中自动回填 Redis）→ 回源上游
+- **写**：Redis + SQL 双写；搜索/分类等动态短缓存只走 Redis 不落库
+- **防击穿**：singleflight 合并并发未命中请求，同一 key 只有一个请求打上游
+- **自动清理** - 定期按行内过期时间清理 SQL 过期缓存（Redis 由 TTL 自动过期）
 - **数据库压缩** - 支持 VACUUM 操作优化数据库
 
+| 接口 | 缓存时长 |
+| ------ | ------ |
+| `/content`、`/multi-content` | 24 小时（SQL 层 30 天） |
+| `/detail`、`/info`、`/catalog`、`/multi-detail`、`/item-summary` | 24 小时（SQL 层 30 天） |
+| `/search`、`/category-front`、`/category-landing` | 10 分钟（仅 Redis） |
+| `/audio` 代理链接 | 2 小时（匹配 CDN 有效期） |
+
+失败响应不缓存；评论类接口为动态数据，不缓存。
+
+## 部署
+
+### Linux 服务器（deploy.sh 一键部署）
+
+```bash
+# 首次：编译 + 部署 + 写入 systemd/nginx 配置
+./deploy.sh v1.0.0 --init
+
+# 日常：拉取代码 + 编译 + 部署 + 重启
+./deploy.sh v1.0.0
+
+# 版本管理
+./deploy.sh --list                # 列出已部署版本
+./deploy.sh --rollback v1.0.0     # 回滚到指定版本
+
+# 服务运维
+sudo systemctl status fanqie
+sudo journalctl -u fanqie -f
+```
+
+部署结构：二进制存于 `/opt/fanqie/bin/`，`fanqie-current` 软链接指向当前版本（保留最近 5 个），systemd 守护 + Nginx 反代，部署后自动做 `/healthz` 健康检查。
+
+首次 `--init` 时若服务器装有 certbot，会自动申请 HTTPS 证书并配置 80→443 跳转（邮箱默认 `admin@域名`，可用 `.deploy.env` 的 `CERT_EMAIL` 覆盖）；续期由 `certbot.timer` 自动完成，续期后经 deploy-hook 重载 Nginx。
+
+### 本地交叉编译
+
+```bash
+make build-linux VERSION=v1.0.0   # 产物 fanqie-v1.0.0-linux，scp 到服务器即可运行
+```
+
 ## 技术栈
 
-- **Go 1.24** - 编程语言
-- **Gin** - HTTP 框架（间接依赖）
-- **SQLite3** - 本地数据库
+- **Go 1.25** - 编程语言
+- **net/http** - 标准库 HTTP 服务（超时保护 + 优雅退出）
+- **SQLite3 / PostgreSQL / Redis** - 缓存与存储
 - **Viper** - 配置管理
 - **goquery** - HTML 解析
 

bookSource.json

@@ -0,0 +1,63 @@
+[
+  {
+    "bookSourceName": "🔅番茄聚合",
+    "bookSourceGroup": "📖番茄小说",
+    "bookSourceType": 0,
+    "bookSourceUrl": "https://fq.20010117.xyz",
+    "bookSourceComment": "番茄聚合书源（fanqie-go 后端）\n\n基础使用教程：\n1、搜索：\n    1) 基础搜索：直接搜，默认搜索当前模式内容\n    2) 快捷搜索：使用特殊关键词(x,t,m,d)搜索\n         x:书名  如(x:十日终焉)  搜小说（可省略）\n         t:书名  如(t:十日终焉)  搜听书\n         m:书名  如(m:十日终焉)  搜漫画\n         d:书名  如(d:十日终焉)  搜短剧\n         冒号支持中文英文，也可在书源设置中切换默认搜索模式\n2、发现页：\n    顶部筛选选择 类型/频道/字数/更新/排序 后，点击分类宫格浏览，下拉翻页\n3、段评：\n    阅读正文时点击段尾气泡即可查看段落评论，样式可在段评设置中调整\n4、听书/漫画/短剧：\n    听书自动用播放器播放；漫画走服务端解密代理；短剧打开章节自动唤起播放\n\n更换服务器地址：只需修改源URL(bookSourceUrl)，全部规则使用相对地址自动跟随",
+    "bookSourceEnabled": true,
+    "enabledExplore": true,
+    "enabledCookieJar": true,
+    "customOrder": 0,
+    "weight": 0,
+    "respondTime": 180000,
+    "lastUpdateTime": 1791607295124,
+    "bookUrlPattern": "https?:\\/\\/(?:[a-zA-Z0-9-]+\\.)?[a-zA-Z0-9-]+(?::\\d+)?\\/detail\\?book_id=\\d+.*",
+    "jsLib": "// 当前书源版本号\nlet localVersion = '26.10.10';\n\n// 初始配置\nconst defaultConfig = {\n    发现页类型: \"小说\",\n    频道: \"男频\",\n    搜索模式: \"小说\"\n};\n\n// 获取源变量\nfunction getVariable(k) {\n    if (k == undefined) k = \"\";\n    const { source } = this;\n    let parsed = {};\n    try {\n        parsed = JSON.parse(source.getVariable());\n    } catch {}\n    if (k == \"\") {\n        return parsed;\n    }\n    let value = parsed[k];\n    if (value == undefined) {\n        value = defaultConfig[k];\n    }\n    return value != undefined ? value : \"\";\n}\n\n// 设置源变量\nfunction setVariable(k, v, t) {\n    if (t == undefined) t = true;\n    const { source, java } = this;\n    const vs = this.getVariable();\n    vs[k] = v;\n    source.setVariable(JSON.stringify(vs, null, 4));\n    if (k != '搜索关键词' && t) {\n        java.toast(`\\n设置 ${k} 为 ${v}`)\n    }\n}\n\n// 还原\nfunction deleteVariable() {\n    const { source, java } = this;\n    source.setVariable('');\n    java.longToast('\\n所有设置已还原到初始化导入状态');\n}\n\n// 从 URL 提取内容类型标记(n小说/t听书/m漫画/d短剧)。\n// 注意：jsLib 函数作用域看不到规则变量 baseUrl，必须由调用方显式传入\nfunction fqTab(url, def) {\n    if (def == undefined) def = 'n';\n    let m = String(url).match(/fqtab=([ntmd])/);\n    return m ? m[1] : def;\n}\n\n// 判断当前环境\nfunction checkEnv() {\n    const {\n        java,\n        source\n    } = this;\n\n    try {\n        java.qread();\n        return \"轻阅读\";\n    } catch (e) {}\n\n    try {\n        if (typeof java.reLoginView == 'function') {\n            return \"改版\";\n        }\n        new Packages.io.legato.kazusa.utils.TimeoutCancellationException('');\n        return \"改版\";\n    } catch (e) {}\n    try {\n        java.deviceID();\n        return \"苹果\";\n    } catch (e) {}\n\n    if (typeof source.loginUi == 'function') {\n        return \"安卓\";\n    }\n\n    return \"改版\";\n}\n\n// 备用设置方案（登录页按钮）\nfunction ste(v) {\n    const { java } = this;\n    let moreSettings = this.getVariable(\"更多设置\") || {};\n    let paraSettings = this.getVariable(\"段评设置\") || {};\n    if (v == \"段评\") {\n        if (paraSettings[\"段评开关\"] != \"false\") {\n            paraSettings[\"段评开关\"] = \"false\";\n            java.longToast(\"\\n❌段评已关闭\");\n        } else {\n            paraSettings[\"段评开关\"] = \"true\";\n            java.longToast(\"\\n✅段评已开启\");\n        }\n    }\n    if (v == \"小说\" || v == \"听书\" || v == \"漫画\" || v == \"短剧\") {\n        moreSettings[\"搜索模式\"] = v;\n        java.longToast(`\\n已设置搜索模式为 ${v}`);\n    }\n    if (v == \"图片\") {\n        if (moreSettings[\"显示图片\"] != \"false\") {\n            moreSettings[\"显示图片\"] = \"false\";\n            java.longToast(\"\\n❌已关闭图片显示\");\n        } else {\n            moreSettings[\"显示图片\"] = \"true\";\n            java.longToast(\"\\n✅已开启图片显示\");\n        }\n    }\n    if (v == \"简介\") {\n        if (moreSettings[\"完整简介\"] != \"false\") {\n            moreSettings[\"完整简介\"] = \"false\";\n            java.longToast(\"\\n❌已关闭完整简介\");\n        } else {\n            moreSettings[\"完整简介\"] = \"true\";\n            java.longToast(\"\\n✅已开启完整简介\");\n        }\n    }\n    this.setVariable(\"更多设置\", moreSettings, false);\n    this.setVariable(\"段评设置\", paraSettings, false);\n}\n\n// 按钮切换时改变源变量并刷新发现\nfunction show(m, t) {\n    const { java, source } = this;\n    let data = {};\n    try {\n        data = JSON.parse(source.getVariable())\n    } catch {}\n    data[t] = m;\n    if (t == \"发现页类型\") {\n        data[\"频道\"] = '男频';\n    }\n    source.setVariable(JSON.stringify(data, null, 2));\n    java.refreshExplore();\n}\n\nfunction createFilter(title, chars, defaultVal, paramKey, size, viewName) {\n    if (viewName == undefined) viewName = \"'请选择类型'\";\n    return {\n        title: title,\n        type: \"select\",\n        chars: chars,\n        default: defaultVal,\n        \"viewName\": viewName,\n        action: `show(infoMap['${title}'],'${paramKey}')`,\n        style: {\n            layout_flexGrow: 1,\n            layout_flexBasisPercent: size\n        }\n    };\n}\n\nfunction createText(title, action, defaultValue, size, viewName) {\n    return {\n      title: title,\n      type: 'text',\n      default: defaultValue || '',\n      action: action,\n      viewName: viewName || title,\n      style: {\n        layout_flexGrow: 1,\n        layout_flexBasisPercent: size\n      }\n    };\n}\n\nfunction createButton(title, action, size) {\n    return {\n      title: title,\n      type: 'butLine truncated
+    "loginUi": "[\n    {\n        \"name\": \"⚙️ 书源设置\",\n        \"type\": \"button\",\n        \"action\": \"getHtmlSettings()\",\n        \"style\": { \"layout_flexGrow\": 1, \"layout_flexBasisPercent\": 0.4 }\n    }, {\n        \"name\": \"🗨 段评设置\",\n        \"type\": \"button\",\n        \"action\": \"getSvgSettings()\",\n        \"style\": { \"layout_flexGrow\": 1, \"layout_flexBasisPercent\": 0.4 }\n    }, {\n        \"name\": \"===下方为备用设置方案===\",\n        \"type\": \"button\",\n        \"action\": \"\",\n        \"style\": { \"layout_flexGrow\": 1, \"layout_flexBasisPercent\": 1 }\n    }, {\n        \"name\": \"📖搜索小说\",\n        \"type\": \"button\",\n        \"action\": \"ste('小说')\",\n        \"style\": { \"layout_flexGrow\": 1, \"layout_flexBasisPercent\": 0.4 }\n    }, {\n        \"name\": \"🎧搜索听书\",\n        \"type\": \"button\",\n        \"action\": \"ste('听书')\",\n        \"style\": { \"layout_flexGrow\": 1, \"layout_flexBasisPercent\": 0.4 }\n    }, {\n        \"name\": \"🎥搜索短剧\",\n        \"type\": \"button\",\n        \"action\": \"ste('短剧')\",\n        \"style\": { \"layout_flexGrow\": 1, \"layout_flexBasisPercent\": 0.4 }\n    }, {\n        \"name\": \"🎨搜索漫画\",\n        \"type\": \"button\",\n        \"action\": \"ste('漫画')\",\n        \"style\": { \"layout_flexGrow\": 1, \"layout_flexBasisPercent\": 0.4 }\n    }, {\n        \"name\": \"段评开关\",\n        \"type\": \"button\",\n        \"action\": \"ste('段评')\",\n        \"style\": { \"layout_flexGrow\": 1, \"layout_flexBasisPercent\": 0.25 }\n    }, {\n        \"name\": \"图片开关\",\n        \"type\": \"button\",\n        \"action\": \"ste('图片')\",\n        \"style\": { \"layout_flexGrow\": 1, \"layout_flexBasisPercent\": 0.25 }\n    }, {\n        \"name\": \"简介开关\",\n        \"type\": \"button\",\n        \"action\": \"ste('简介')\",\n        \"style\": { \"layout_flexGrow\": 1, \"layout_flexBasisPercent\": 0.25 }\n    }, {\n        \"name\": \"⛔‼️ 清空还原设置\",\n        \"type\": \"button\",\n        \"action\": \"deleteVariable()\",\n        \"style\": { \"layout_flexGrow\": 1, \"layout_flexBasisPercent\": 1 }\n    }\n]",
+    "searchUrl": "<js>\nlet moreSettings = getVariable('更多设置');\nlet tab = moreSettings && moreSettings['搜索模式'] || '小说';\nvar k = String(key);\nlet m = k.match(/^[xtmdXTMD][:：]\\s*/);\nif (m) {\n    tab = { x: '小说', t: '听书', m: '漫画', d: '短剧' }[m[0][0].toLowerCase()];\n    k = k.slice(m[0].length);\n}\nlet tabType = { 小说: 3, 听书: 2, 漫画: 8, 短剧: 11 }[tab] || 3;\n`/search?query=${encodeURIComponent(k)}&offset=${(page - 1) * 10}&tab_type=${tabType}`;\n</js>",
+    "exploreUrl": "<js>\nvar base = String(source.getKey()).replace(/\\/$/, '');\nvar tab = getVariable('发现页类型') || '小说';\nvar channel = getVariable('频道') || '男频';\nvar wordNumMap = { '不限': '0', '30万字以内': '4', '100万字以内': '1', '30万-100万': '5', '100万-300万': '2', '300万字以上': '3', '100万字以上': '9' };\nvar updateMap = { '不限': '2', '完结': '0', '连载中': '1', '今日更新': '3' };\nvar sortMap = { '综合': '0', '热门': '24', '最新': '76', '评分': '12' };\nvar wordNum = getVariable('字数') || '不限';\nvar update = getVariable('更新') || '不限';\nvar sort = getVariable('排序') || '综合';\nvar q = `&word_number=${wordNumMap[wordNum] || '0'}&book_status=${updateMap[update] || '2'}&sort_by=${sortMap[sort] || '0'}`;\nvar tabCode = { 小说: 'n', 听书: 't', 漫画: 'm', 短剧: 'd' }[tab] || 'n';\n\nvar list = [];\nlist.push(createFilter('类型', ['小说', '听书', '短剧', '漫画'], tab, '发现页类型', 0.4));\nlist.push(createFilter('频道', ['男频', '女频'], channel, '频道', 0.4));\nlist.push(createText('搜索关键词', \"setVariable('搜索关键词',(infoMap['搜索关键词'] || (infoMap.get && infoMap.get('搜索关键词'))))\", getVariable('搜索关键词') || '', 0.5, \"'搜索书名或作者'\"));\nlist.push(createButton('🔍搜索', 'exploreSearch()', 0.3));\nlist.push({ title: '⚙️书源设置', type: 'button', action: 'getHtmlSettings()', style: { layout_flexGrow: 1, layout_flexBasisPercent: 0.25 } });\nlist.push({ title: '🗨段评设置', type: 'button', action: 'getSvgSettings()', style: { layout_flexGrow: 1, layout_flexBasisPercent: 0.25 } });\nlist.push(createFilter('字数', Object.keys(wordNumMap), wordNum, '字数', 0.4));\nlist.push(createFilter('更新', Object.keys(updateMap), update, '更新', 0.4));\nlist.push(createFilter('排序', Object.keys(sortMap), sort, '排序', 0.1));\n\nif (tab == '短剧') {\n    list.push({ title: '短剧暂无分类，请使用上方搜索 🔍', url: '', style: { layout_flexGrow: 1, layout_flexBasisPercent: 1 } });\n} else {\n    var ctab = tab == '小说' ? (channel == '女频' ? 0 : 1) : (tab == '听书' ? 3 : 5);\n    try {\n        var res = JSON.parse(java.ajax(base + '/category-front?tab=' + ctab));\n        var cells = ((res.data || {}).category_tab_data || {}).cell_data || [];\n        cells.forEach(function (cell) {\n            (cell.atom_data || []).forEach(function (a) {\n                var c = a.category_data;\n                if (c && c.category_id != null) {\n                    list.push({\n                        title: c.name,\n                        url: base + '/category-landing?category_id=' + c.category_id + '&offset={{(page-1)*20}}' + q + '&fqtab=' + tabCode,\n                        style: { layout_flexGrow: 1, layout_flexBasisPercent: 0.25 }\n                    });\n                }\n            });\n        });\n    } catch (e) {\n        java.toast('发现页分类获取失败');\n    }\n}\nJSON.stringify(list);\n</js>",
+    "ruleSearch": {
+      "bookList": "<js>\nvar d = JSON.parse(result);\nvar isVideo = /tab_type=11/.test(baseUrl);\nvar arr = [];\n(d.data || []).forEach(function (b) {\n    var list = isVideo ? (b.video_data || []) : (b.book_data || []);\n    list.forEach(function (x) {\n        if (isVideo) {\n            arr.push({\n                book_id: x.series_id,\n                book_name: x.title,\n                author: '',\n                abstract: x.rec_text || '',\n                thumb_url: x.horiz_cover || x.cover,\n                category: '短剧',\n                creation_status: '1',\n                score: x.score,\n                word_number: String(x.episode_cnt || '')\n            });\n        } else {\n            arr.push(x);\n        }\n    });\n});\narr;\n</js>",
+      "name": "$.book_name",
+      "author": "$.author",
+      "kind": "{{$.creation_status=='0'?'完结':'连载'}},{{$.category}},{{$.score}}分",
+      "wordCount": "$.word_number##^0+$",
+      "intro": "$.abstract",
+      "coverUrl": "$.thumb_url",
+      "bookUrl": "<js>\nvar t = /tab_type=11/.test(baseUrl) ? 'd' : /tab_type=2/.test(baseUrl) ? 't' : /tab_type=8/.test(baseUrl) ? 'm' : 'n';\n`/detail?book_id=${result.book_id}&fqtab=${t}`;\n</js>",
+      "checkKeyWord": "斗罗大陆"
+    },
+    "ruleExplore": {
+      "bookList": "$.data.book_info[*]",
+      "name": "$.book_name",
+      "author": "$.author",
+      "kind": "{{$.category}},{{$.score}}分",
+      "wordCount": "$.word_number##^0+$",
+      "intro": "$.abstract",
+      "coverUrl": "$.thumb_url",
+      "bookUrl": "<js>\nvar m = String(baseUrl).match(/fqtab=([ntmd])/);\n`/detail?book_id=${result.book_id}&fqtab=${m ? m[1] : 'n'}`;\n</js>"
+    },
+    "ruleBookInfo": {
+      "init": "$.data",
+      "name": "$.book_name",
+      "author": "$.author",
+      "kind": "{{$.creation_status=='0'?'完结':'连载'}},{{$.category}}",
+      "wordCount": "$.word_number##^0+$",
+      "lastChapter": "$.last_chapter_title",
+      "coverUrl": "$.thumb_url",
+      "intro": "<js>\nconst { book_id, last_chapter_title, last_chapter_update_time, word_number, score, abstract, read_count, category } = result;\nlet m0 = String(baseUrl).match(/fqtab=([ntmd])/);\nconst tab = { n: '小说', t: '听书', m: '漫画', d: '短剧' }[(m0 ? m0[1] : 'n')];\nlet moreSettings = getVariable('更多设置');\nconst lightDivider = \"❇️───────❇️───────❇️\";\nconst heavyDivider = \"&lrm;\\n&lrm;\";\nconst isValid = (v) => String(v).length > 1;\nlet ctitle = book.durChapterTitle || '未开始';\nconst two = (n) => ('0' + n).slice(-2);\nconst fmtTime = (t) => {\n    let n = parseInt(t);\n    if (!n || n <= 0) return '';\n    let d = new Date(n * 1000);\n    return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;\n};\nconst formatAbstract = (text) => String(text).split(\"\\n\").map(line => `    ${line}`).join(\"\\n\");\nconst buildBasicInfo = (items) => {\n    let info = \"\";\n    for (let [value, prefix, icon] of items) {\n        if (isValid(value)) info += `    ${icon} ${prefix} ${value}\\n`;\n    }\n    return info;\n};\nlet info = `    🏷 数据来源：番茄小说(fanqie-go)\\n    🔄 当前模式：${tab}\\n    📖 阅读至：${ctitle}\\n`;\nconst fullBasicInfo = buildBasicInfo([\n    [category, \"书籍分类：\", \"🌈\"],\n    [last_chapter_title, \"最新章节：\", \"📚\"],\n    [fmtTime(last_chapter_update_time), \"更新时间：\", \"⏳\"],\n    [word_number, \"书籍字数：\", \"📝\"],\n    [score, \"书籍评分：\", \"⭐\"],\n    [read_count, \"今阅读人数：\", \"📃\"]\n]);\nif (fullBasicInfo) info += `${lightDivider}\\n${fullBasicInfo}`;\nif (isValid(abstract)) info += `${heavyDivider}\\n    📖 书籍简介：\\n${formatAbstract(abstract)}\\n`;\ninfo += `${lightDivider}\\n${heavyDivider}\\n    数据更新于 ${new Date().toLocaleString()}\\n`;\nconst abstractMode = moreSettings && moreSettings['完整简介'] || 'true';\nif (abstractMode == \"false\") {\n    const simplifiedBasicInfo = buildBasicInfo([\n        [last_chapter_title, \"最新章节：\", \"📚\"],\n        [fmtTime(last_chapter_update_time), \"更新时间：\", \"⏳\"],\n        [word_number, \"书籍字数：\", \"📝\"],\n        [score, \"书籍评分：\", \"⭐\"]\n    ]);\n    info = `\\n&lrm;${isValid(abstract) ? `📖 书籍简介：\\n${formatAbstract(abstract)}\\n${heavyDivider}` : ''}🏷 数据来源：番茄小说\\n${simplifiedBasicInfo}`;\n} else {\n    info = info.split(\"\\n\").map(line => line.replace(/^ {4}/, \"\")).join(\"\\n\");\n}\ninfo;\n</js>",
+      "tocUrl": "<js>\nvar m = String(baseUrl).match(/fqtab=([ntmd])/);\n`/catalog?book_id=${result.book_id}&fqtab=${m ? m[1] : 'n'}`;\n</js>",
+      "canReName": "1"
+    },
+    "ruleToc": {
+      "chapterList": "<js>\n// 类型随书切换（照光遇 typeMap：安卓用 default，苹果端用其类型体系）\nconst typeMap = {\n    \"小说\": { \"苹果\": 0, \"default\": 8 },\n    \"听书\": { \"苹果\": 1, \"default\": 32 },\n    \"漫画\": { \"苹果\": 2, \"default\": 64 },\n    \"短剧\": { \"苹果\": 3, \"default\": 8 }\n};\nconst device_type = checkEnv();\nvar tabName = { n: '小说', t: '听书', m: '漫画', d: '短剧' }[fqTab(baseUrl, 'n')];\nvar currentType = typeMap[tabName] || typeMap[\"小说\"];\nif (device_type == '苹果') {\n    book.type = currentType[device_type];\n} else {\n    book.type = currentType.default;\n}\ntry {\n    book.imageStyle = checkEnv() == '改版' ? 'FULL' : 'TEXT';\n} catch (e) {}\nresult;\n</js>$.data.item_data_list[*]",
+      "chapterName": "$.title",
+      "chapterUrl": "<js>\nvar t = fqTab(baseUrl, 'n');\nvar id = result.item_id;\nvar u = {\n    n: `/content?item_id=${id}&text_mode=html&review=keep&image_mode=keep&fqtab=n`,\n    t: `/audio?item_ids=${id}&fqtab=t`,\n    m: `/manga?item_ids=${id}&output=proxy&fqtab=m`,\n    d: `/video?item_ids=${id}&fqtab=d`\n}[t];\nu;\n</js>"
+    },
+    "ruleContent": {
+      "content": "<js>\nvar t = fqTab(baseUrl, 'n');\nlet moreSettings = getVariable('更多设置');\nlet dpSettings = getVariable('段评设置');\nlet islyc = checkEnv();\n\nif (t == 't') {\n    // 听书：直接返回音频地址\n    JSON.parse(result).data[0].main_url;\n} else if (t == 'm') {\n    // 漫画：拼装图片\n    var d = JSON.parse(result);\n    var org = String(baseUrl).match(/^https?:\\/\\/[^\\/]+/)[0];\n    var imgs = (d.data || {}).images || [];\n    var out = [];\n    for (var i = 0; i < imgs.length; i++) {\n        out.push('<img src=\"' + org + imgs[i].data + '\">');\n    }\n    out.join('\\n');\n} else if (t == 'd') {\n    // 短剧：选最高清晰度，当前章节自动唤起播放\n    var d = JSON.parse(result).data || {};\n    var vl = d.video_list || {};\n    var list = [];\n    for (var k in vl) { list.push(vl[k]); }\n    list.sort(function (a, b) { return (b.vheight || 0) - (a.vheight || 0); });\n    var org = String(baseUrl).match(/^https?:\\/\\/[^\\/]+/)[0];\n    var url = list.length ? String(list[0].main_url) : '';\n    if (url && url.indexOf('http') != 0) { url = org + url; }\n    if (url && book.durChapterIndex == chapter.index) {\n        java.startBrowser(url, chapter.title);\n    }\n    '▶️ 本集已唤起播放（菜单-刷新可重新打开）：\\n' + url;\n} else {\n    // 小说：正文 + 段评气泡\n    var d = JSON.parse(result);\n    var content = String((d.data || {}).content || '');\n    let show_img = moreSettings && moreSettings['显示图片'] || 'true';\n    if (show_img == 'false') {\n        content = removeAllImgTags(content);\n    }\n    let para = dpSettings && dpSettings['段评开关'] || 'true';\n    if (para == 'true' && content.indexOf('<comment') != -1) {\n        content = islyc == '苹果' ? paraForiOS(content, '番茄') : paraForAndroid(content, '番茄');\n    }\n    content;\n}\n</js>",
+      "title": "$.data.title"
+    }
+  }
+]

cmd/fanqie/main.go

@@ -14,15 +14,25 @@ import (
 	"os/signal"
 	"syscall"
 	"time"
+
+	// 嵌入 tzdata，容器内无系统时区库时 TZ 仍可用
+	_ "time/tzdata"
 )
 
+// Version / BuildTime 由编译时 -ldflags "-X main.Version=... -X main.BuildTime=..." 注入
 var (
+	Version   = "dev"
+	BuildTime = "unknown"
+
 	logger        = common.NewLogger("main", "INFO", "")
 	configWatcher *config.ConfigWatcher
 )
 
 func main() {
-	logger.Info("番茄小说API服务 - v2.0.0")
+	// 时区生效须先于一切时间显示（.env 中的 TZ）
+	config.ApplyTimezone()
+
+	logger.Info(fmt.Sprintf("番茄小说API服务 版本=%s 编译时间=%s", Version, BuildTime))
 
 	// 加载配置文件
 	initConfig()
@@ -33,10 +43,17 @@ func main() {
 		os.Exit(1)
 	}
 	defer fqapi.CloseCache() // 程序退出时关闭数据库
-	
+
+	// 初始化 Redis 缓存（可选）
+	if err := fqapi.InitRedis(); err != nil {
+		logger.Error("Redis 初始化失败: " + err.Error())
+		os.Exit(1)
+	}
+	defer fqapi.CloseRedis()
+
 	// 加载统计数据
 	handlers.LoadStatistics()
-	
+
 	// 启动统计数据定期保存
 	handlers.StartStatisticsSaver()
 	defer handlers.StopStatisticsSaver() // 程序退出时保存统计数据
@@ -45,6 +62,12 @@ func main() {
 	fqapi.StartCacheCleanup()
 	defer fqapi.StopCacheCleanup() // 程序退出时停止清理任务
 
+	// 启动请求日志（server.request_log.enabled 开启时生效）
+	if err := fqapi.InitRequestLog(); err != nil {
+		logger.Warning("请求日志初始化失败: " + err.Error())
+	}
+	defer fqapi.CloseRequestLog() // 程序退出时落盘剩余日志
+
 	// 初始化算法切换器
 	initAlgorithm()
 
@@ -53,6 +76,7 @@ func main() {
 		logger.Error("设备密钥池初始化失败: " + err.Error())
 		os.Exit(1)
 	}
+	defer fqapi.FlushDevicePool() // 程序退出时落盘设备使用记录
 
 	// 设置路由
 	setupRoutes()
@@ -92,9 +116,9 @@ func initAlgorithm() {
 	if config.GetAppConfig() != nil {
 		algos.GlobalAlgorithmSwitcher.SwitchAlgorithm(config.GetAppConfig().Fanqie.Algorithm)
 		logger.Info(fmt.Sprintf("当前算法: %s", config.GetAppConfig().Fanqie.Algorithm))
-		
+
 		algos.GlobalSignatureSwitcher.SwitchSignature(config.GetAppConfig().Fanqie.Signature)
-		
+
 		// 根据签名方法显示详细信息
 		var signatureDetails string
 		if config.GetAppConfig().Fanqie.Signature == "sign4" {
@@ -114,7 +138,7 @@ func initDeviceKeyPool() error {
 	pool := fqapi.GetDeviceKeyPool()
 	if err := pool.Initialize(); err != nil {
 		return fmt.Errorf("初始化设备密钥池失败: %w", err)
-}
+	}
 
 	// 显示池状态
 	stats := pool.GetStats()
@@ -128,32 +152,39 @@ func initDeviceKeyPool() error {
 func setupRoutes() {
 	http.HandleFunc("/", handlers.HandleMain)
 	http.HandleFunc("/status", handlers.RequireAccessKey(handlers.HandleStatus))
-	http.HandleFunc("/self-info", handlers.RequireAccessKey(handlers.HandleSelfInfo))
-	http.HandleFunc("/vacuum", handlers.RequireAccessKey(handlers.HandleVacuum))
 
-	// API端点
-	http.HandleFunc("/search", handlers.HandleSearch)
-	http.HandleFunc("/detail", handlers.HandleDetail)
-	http.HandleFunc("/info", handlers.HandleDetail)
-	http.HandleFunc("/catalog", handlers.HandleCatalog)
-	http.HandleFunc("/directory/all_items", handlers.HandleCatalog)
-	http.HandleFunc("/multi-detail", handlers.HandleMultiDetail)
-	http.HandleFunc("/multi-content", handlers.HandleMultiContent)
-	http.HandleFunc("/content", handlers.HandleContent)
-	http.HandleFunc("/item-summary", handlers.HandleItemSummary)
-	http.HandleFunc("/category-front", handlers.HandleCategoryFront)
-	http.HandleFunc("/category-landing", handlers.HandleCategoryLanding)
-	http.HandleFunc("/audio", handlers.HandleAudio)
-	http.HandleFunc("/audio/proxy/", handlers.HandleAudioProxy)
-	http.HandleFunc("/video", handlers.HandleVideo)
-	http.HandleFunc("/manga", handlers.HandleManga)
-	http.HandleFunc("/manga/image/", handlers.HandleMangaImageProxy)
-	
+	http.HandleFunc("/healthz", handlers.HandleHealth)
+
+	// API端点：请求日志 + 限流 + protect_all 鉴权链（代理路由不鉴权，URL 由服务端生成不含 key）
+	wrap := func(h http.HandlerFunc) http.HandlerFunc {
+		return handlers.LogRequestMiddleware(handlers.RateLimit(handlers.OptionalAccessKey(h)))
+	}
+	http.HandleFunc("/search", wrap(handlers.HandleSearch))
+	http.HandleFunc("/detail", wrap(handlers.HandleDetail))
+	http.HandleFunc("/info", wrap(handlers.HandleDetail))
+	http.HandleFunc("/catalog", wrap(handlers.HandleCatalog))
+	http.HandleFunc("/directory/all_items", wrap(handlers.HandleCatalog))
+	http.HandleFunc("/multi-detail", wrap(handlers.HandleMultiDetail))
+	http.HandleFunc("/rank", wrap(handlers.HandleRank))
+	http.HandleFunc("/bookshelf", wrap(handlers.HandleBookshelf))
+	http.HandleFunc("/read-history", wrap(handlers.HandleReadHistory))
+	http.HandleFunc("/multi-content", wrap(handlers.HandleMultiContent))
+	http.HandleFunc("/content", wrap(handlers.HandleContent))
+	http.HandleFunc("/item-summary", wrap(handlers.HandleItemSummary))
+	http.HandleFunc("/category-front", wrap(handlers.HandleCategoryFront))
+	http.HandleFunc("/category-landing", wrap(handlers.HandleCategoryLanding))
+	http.HandleFunc("/audio", wrap(handlers.HandleAudio))
+	http.HandleFunc("/audio/proxy/", wrap(handlers.HandleAudioProxy))
+	http.HandleFunc("/video", wrap(handlers.HandleVideo))
+	http.HandleFunc("/video/proxy/", wrap(handlers.HandleVideoProxy))
+	http.HandleFunc("/manga", wrap(handlers.HandleManga))
+	http.HandleFunc("/manga/image/", wrap(handlers.HandleMangaImageProxy))
+
 	// 评论相关端点
-	http.HandleFunc("/chapter_review", handlers.HandleChapterReview)
-	http.HandleFunc("/review", handlers.HandleReview)
-	http.HandleFunc("/review_html", handlers.HandleReviewHTML)
-	
+	http.HandleFunc("/chapter_review", wrap(handlers.HandleChapterReview))
+	http.HandleFunc("/review", wrap(handlers.HandleReview))
+	http.HandleFunc("/review_html", wrap(handlers.HandleReviewHTML))
+
 	// 表情图片静态文件服务
 	http.Handle("/emoji/", http.StripPrefix("/emoji/", http.FileServer(http.Dir("emoji"))))
 }
@@ -162,7 +193,7 @@ func setupRoutes() {
 func startServer() {
 	host := "0.0.0.0"
 	port := "40180"
-	
+
 	if config.GetAppConfig() != nil {
 		if config.GetAppConfig().Server.Host != "" {
 			host = config.GetAppConfig().Server.Host
@@ -171,10 +202,11 @@ func startServer() {
 			port = config.GetAppConfig().Server.Port
 		}
 	}
-	
+
 	addr := host + ":" + port
 	server := &http.Server{
-		Addr: addr,
+		Addr:    addr,
+		Handler: handlers.Gzip(http.DefaultServeMux),
 		// 超时保护：防止慢客户端长期占用连接
 		ReadHeaderTimeout: 10 * time.Second,
 		ReadTimeout:       60 * time.Second,

config/config.yaml

@@ -2,9 +2,16 @@
 
 # 服务器配置
 server:
-  port: "40180"        # 监听端口
-  host: "0.0.0.0"     # 监听地址
-  access_key: ""       # 访问密钥，为空则不启用验证（用于 /status 和 /self-info）
+  port: "40180" # 监听端口
+  host: "0.0.0.0" # 监听地址
+  access_key: "" # 访问密钥，为空则不启用验证（用于 /status）
+  rate_limit_qps: 0 # 每 IP 每秒请求上限（令牌桶，突发 10），0=不限制
+
+  # 请求日志（只记元数据与错误摘要，不存响应体；在 /status 页"最近请求"展示）
+  # 注意：日志时间显示与"近 7 天请求"统计依赖 .env 中的 TZ 时区
+  request_log:
+    enabled: true
+    retention_days: 7 # 日志保留天数，自动清理
 
 # 番茄小说配置
 fanqie:
@@ -12,57 +19,93 @@ fanqie:
   # gorgon: Gorgon算法
   # 8404: 备用算法
   algorithm: "gorgon"
-  
+
   # 签名方法: "sign2" 或 "sign4"
   # sign2: 仅Gorgon签名
   # sign4: X-Gorgon + X-Ladon + X-Argus 完整签名
   signature: "sign4"
-  
+
   # 内容处理配置
   content:
     # 是否移除图片（默认false，保留图片）
     remove_images: false
-    
+
     # 是否移除图片描述（默认false，保留描述）
     remove_image_desc: true
-    
+
     # 是否移除空行（默认true，移除空行）
     remove_blank_lines: true
-    
+
     # 是否移除HTML标签（默认false，保留HTML）
     remove_html_tags: true
-    
+
     # 是否移除章节名（默认false，保留章节名）
     remove_chapter_title: true
-    
+
     # 是否添加段落缩进（默认true，添加两个全角空格）
-    add_paragraph_indent: false
-    
+    add_paragraph_indent: true
+
     # 段落间使用双换行（true=\n\n, false=\n）
-    double_newline: false
-    
+    double_newline: true
+
     # 是否启用段评功能（默认true，启用段评）
     enable_review: true
-  
+
+  # 视频处理配置
+  video:
+    # 输出模式：proxy / url
+    # proxy: 返回本地解密代理URL /video/proxy/{key}（已解密，可直接播放，推荐）
+    # url: 返回原始CDN链接（内容为 CENC 加密，需自行解密）
+    output_mode: "proxy"
+
+    # 默认清晰度：max（最高档）/ 360p/480p/540p/720p / 档位 key（video_1..N）
+    # 留空返回全部清晰度；/video 接口的 quality 参数优先于此配置
+    quality: "max"
+
+    # 解密后视频的磁盘缓存（同一视频重复播放直接读本地文件，无需重新下载解密）
+    cache_enabled: true
+    cache_path: "./video_cache"
+
   # 漫画处理配置
   manga:
     # 输出模式：proxy / data_uri / url
-    # proxy: 返回本地代理URL /manga/image/{itemID}/{index}
+    # proxy: 返回本地代理URL /manga/image/{itemID}/{index}（图片已解密，推荐）
     # data_uri: 返回 data:image/jpeg;base64,/9j/4AAQ...
-    # url: 返回原始图片URL数组
-    output_mode: "url"
+    # url: 返回原始图片URL数组（不可用：链接404且内容加密）
+    output_mode: "proxy"
 
 # 缓存配置
 cache:
   # 是否启用正文内容缓存
   enabled: true
-  
-  # SQLite数据库文件路径
+
+  # 存储后端：sqlite | postgres
+  backend: postgres
+
+  # SQLite数据库文件路径（backend 为 sqlite 时使用）
   sqlite_path: "./cache.db"
-  
+
+  # PostgreSQL连接配置（backend 为 postgres 时使用）
+  # 敏感值（密码等）建议放 .env，见 .env.example；环境变量优先于此处配置
+  postgres:
+    host: "127.0.0.1"
+    port: 5432
+    user: "postgres"
+    password: ""
+    database: "fanqie"
+    sslmode: "disable" # disable | prefer | require
+
+  # Redis缓存（启用后正文缓存与音频代理缓存走 Redis，统计数据与设备池仍在 SQL 库）
+  redis:
+    enabled: true
+    host: "127.0.0.1"
+    port: 6379
+    password: ""
+    db: 1
+
   # 是否启用正文内容缓存自动清理
   cleanup_enabled: true
-  
+
   # 正文内容缓存清理时间（秒），0表示不自动清理
   cleanup_seconds: 86400
 
@@ -70,13 +113,12 @@ cache:
 device_key_pool:
   # 是否启用设备密钥池
   enabled: true
-  
+
   # 初始化设备数量
   initial_size: 20
-  
+
   # 最小设备数量（低于此数量自动补充）
   min_size: 10
-  
+
   # 最大设备数量
   max_size: 30
-

deploy.sh

@@ -0,0 +1,674 @@
+#!/bin/bash
+# ============================================================
+# Go 应用一键部署脚本
+#
+# 用法：
+#   ./deploy.sh                       # 编译 + 部署（自动版本号）
+#   ./deploy.sh v1.2.0                # 编译 + 部署（指定版本）
+#   ./deploy.sh v1.2.0 --init         # 首次初始化（写 systemd/nginx 配置）
+#   ./deploy.sh v1.2.0 --no-pull      # 跳过 git pull
+#   ./deploy.sh v1.2.0 --no-autostart # 部署后不开机自启
+#   ./deploy.sh v1.2.0 --no-restart   # 只部署，不重启服务
+#   ./deploy.sh --stop                # 停止服务
+#   ./deploy.sh --start               # 启动服务
+#   ./deploy.sh --clean               # 清除所有部署内容（服务/nginx/证书），重新 --init 前用
+#   ./deploy.sh --build-only          # 只编译，不部署
+#   ./deploy.sh --rollback            # 交互式回滚到指定版本
+#   ./deploy.sh --rollback v1.0.0     # 直接回滚到指定版本
+#   ./deploy.sh --list                # 列出所有已部署版本
+#   ./deploy.sh --sync-nginx          # 更新线上 nginx 配置（备份+校验+失败回滚）
+#   ./deploy.sh --help                # 显示帮助
+# ============================================================
+
+set -euo pipefail
+
+# ==================== 加载本地配置 ====================
+# .deploy.env（不入库）覆盖下方默认值；模板见 .deploy.env.example
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "${SCRIPT_DIR}/.deploy.env" ]; then
+  # shellcheck disable=SC1091
+  source "${SCRIPT_DIR}/.deploy.env"
+fi
+
+# ==================== 配置区（默认值，可被 .deploy.env 覆盖） ====================
+APP_NAME="${APP_NAME:-fanqie}"             # 应用名（用于服务名、目录名）
+APP_DESC="${APP_DESC:-番茄小说api接口}"     # 服务描述
+RUN_USER="${RUN_USER:-$(whoami)}"          # 运行用户（默认当前用户）
+SRC_DIR="${SRC_DIR:-/root/code/novel/fanqie-go}"  # 代码目录
+BIN_DIR="${BIN_DIR:-/opt/${APP_NAME}/bin}"         # 二进制存放目录
+SERVICE_FILE="${SERVICE_FILE:-/etc/systemd/system/${APP_NAME}.service}"
+NGINX_CONF="${NGINX_CONF:-/etc/nginx/conf.d/${APP_NAME}.conf}"
+APP_PORT="${APP_PORT:-40180}"              # 程序监听端口
+DOMAIN="${DOMAIN:-fq.20010117.xyz}"        # 域名
+CERT_EMAIL="${CERT_EMAIL:-admin@${DOMAIN}}"  # 证书申请邮箱（过期提醒）
+CERT_DIR="${CERT_DIR:-/etc/nginx/ssl}"       # 证书目录（acme.sh --install-cert 安装位置）
+BUILD_TARGET="${BUILD_TARGET:-./cmd/fanqie}"  # go build 的包路径
+ENV_FILE="${ENV_FILE:-${SRC_DIR}/.env}"    # 应用环境变量（.env.example 为模板）
+KEEP_VERSIONS="${KEEP_VERSIONS:-5}"        # 保留最近几个版本
+AUTO_START="${AUTO_START:-true}"           # 服务是否开机自启（--no-autostart 覆盖）
+
+# ==================== 颜色与日志 ====================
+C_GREEN='\033[1;32m'; C_YELLOW='\033[1;33m'; C_RED='\033[1;31m'; C_BLUE='\033[1;34m'; C_RESET='\033[0m'
+log()  { echo -e "${C_GREEN}[$(date '+%H:%M:%S')]${C_RESET} $*"; }
+warn() { echo -e "${C_YELLOW}[警告]${C_RESET} $*"; }
+err()  { echo -e "${C_RED}[错误]${C_RESET} $*" >&2; }
+info() { echo -e "${C_BLUE}[信息]${C_RESET} $*"; }
+
+# 非 root 时自动加 sudo
+SUDO=""
+if [ "$(id -u)" -ne 0 ]; then
+  SUDO="sudo"
+fi
+
+# ==================== 参数解析 ====================
+VERSION=""
+INIT=false
+NO_PULL=false
+BUILD_ONLY=false
+ROLLBACK=false
+ROLLBACK_VERSION=""
+LIST=false
+FORCE=false
+SYNC_NGINX=false
+AUTO_START="${AUTO_START:-true}"
+NO_RESTART=false
+STOP=false
+START=false
+CLEAN=false
+
+print_help() {
+  cat <<EOF
+用法: $0 [选项] [版本号]
+
+选项:
+  --init                首次初始化，写入 systemd 和 nginx 配置
+  --no-pull             跳过 git pull
+  --no-autostart        服务不设置开机自启（默认自启）
+  --no-restart          只部署不重启服务（自启设置仍会应用）
+  --stop                停止服务后退出
+  --start               启动服务后退出
+  --clean               清除本脚本部署的全部内容（服务/nginx/二进制/证书，含 certbot 残留；
+                        保留 SRC_DIR 下的 .env/配置/数据库），之后重新 --init 即可
+  --build-only          只编译，不部署、不重启服务
+  --force, -f           允许覆盖已存在的同名版本（默认报错退出）
+  --rollback [版本]     回滚到指定版本（不带版本号则交互式选择）
+  --list                列出所有已部署的版本
+  --sync-nginx          只更新 nginx 配置（备份旧配置，校验失败自动回滚）
+  --help, -h            显示此帮助
+
+示例:
+  $0                          # 编译 + 部署（自动版本号）
+  $0 v1.2.0                   # 编译 + 部署（指定版本）
+  $0 v1.2.0 --init            # 首次初始化部署
+  $0 --build-only             # 只编译
+  $0 --rollback               # 交互式回滚
+  $0 --rollback v1.0.0        # 回滚到 v1.0.0
+  $0 --list                   # 查看所有版本
+EOF
+}
+
+i=0
+ARGS=("$@")
+while [ $i -lt ${#ARGS[@]} ]; do
+  arg="${ARGS[$i]}"
+  case "$arg" in
+    --init)        INIT=true ;;
+    --no-pull)     NO_PULL=true ;;
+    --no-autostart) AUTO_START=false ;;
+    --no-restart)  NO_RESTART=true ;;
+    --stop)        STOP=true ;;
+    --start)       START=true ;;
+    --clean)       CLEAN=true ;;
+    --build-only)  BUILD_ONLY=true ;;
+    --rollback)
+      ROLLBACK=true
+      # 看下一个参数是不是版本号
+      if [ $((i+1)) -lt ${#ARGS[@]} ] && [[ "${ARGS[$((i+1))]}" != --* ]]; then
+        ROLLBACK_VERSION="${ARGS[$((i+1))]}"
+        i=$((i+1))
+      fi
+      ;;
+    --list)        LIST=true ;;
+    --sync-nginx)  SYNC_NGINX=true ;;
+    --force|-f)    FORCE=true ;;
+    --help|-h)     print_help; exit 0 ;;
+    v*)            VERSION="$arg" ;;
+    *)             err "未知参数: $arg"; print_help; exit 1 ;;
+  esac
+  i=$((i+1))
+done
+
+VERSION="${VERSION:-v$(date +%Y%m%d-%H%M%S)}"
+BUILD_TIME=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
+
+# ==================== 辅助函数 ====================
+
+# 原子切换软链接
+switch_symlink() {
+  local target="$1"
+  $SUDO ln -sfn "$target" "${BIN_DIR}/${APP_NAME}-current.tmp"
+  $SUDO mv -Tf "${BIN_DIR}/${APP_NAME}-current.tmp" "${BIN_DIR}/${APP_NAME}-current"
+}
+
+# 列出所有版本
+list_versions() {
+  if [ ! -d "${BIN_DIR}" ]; then
+    warn "二进制目录不存在: ${BIN_DIR}"
+    return 0
+  fi
+  local current
+  current=$(readlink -f "${BIN_DIR}/${APP_NAME}-current" 2>/dev/null | xargs -r basename || echo "")
+  info "已部署版本（${BIN_DIR}）："
+  echo ""
+  local i=1
+  for f in $(ls -1t ${BIN_DIR}/${APP_NAME}-v* 2>/dev/null); do
+    local name
+    name=$(basename "$f")
+    if [ "$name" = "$current" ]; then
+      echo -e "  ${C_GREEN}* ${name}  (当前版本)${C_RESET}"
+    else
+      echo "    ${name}"
+    fi
+    i=$((i+1))
+  done
+  if [ $i -eq 1 ]; then
+    warn "没有找到任何版本"
+  fi
+}
+
+# 清理旧版本
+cleanup_old_versions() {
+  log "清理旧版本（保留最近 ${KEEP_VERSIONS} 个）..."
+  local current
+  current=$(readlink -f "${BIN_DIR}/${APP_NAME}-current" 2>/dev/null | xargs -r basename || echo "")
+  local count=0
+  # 按时间倒序列出，保留前 N 个，且不删当前版本
+  for f in $(ls -1t ${BIN_DIR}/${APP_NAME}-v* 2>/dev/null); do
+    local name
+    name=$(basename "$f")
+    count=$((count+1))
+    if [ $count -gt ${KEEP_VERSIONS} ] && [ "$name" != "$current" ]; then
+      $SUDO rm -f "$f"
+      log "  已删除: $name"
+    fi
+  done
+}
+
+# 定位 acme.sh：PATH → 当前用户目录 → root 目录（sudo 后 HOME 可能被重置）
+find_acme_sh() {
+  local acme
+  acme="$(command -v acme.sh 2>/dev/null || true)"
+  for c in "${HOME}/.acme.sh/acme.sh" "/root/.acme.sh/acme.sh"; do
+    if [ -z "$acme" ] && [ -x "$c" ]; then acme="$c"; fi
+  done
+  echo "$acme"
+}
+
+# 删除已存在的路径并逐项记录（文件/目录/glob 展开结果均可，不存在则跳过）
+rm_logged() {
+  local p
+  for p in "$@"; do
+    if [ -e "$p" ] || [ -L "$p" ]; then
+      $SUDO rm -rf "$p"
+      log "  已删除: $p"
+    fi
+  done
+}
+
+# 应用开机自启设置（AUTO_START 由 --no-autostart / .deploy.env 决定）
+apply_autostart() {
+  if [ "$AUTO_START" = true ]; then
+    $SUDO systemctl enable "${APP_NAME}" >/dev/null 2>&1 || true
+  else
+    $SUDO systemctl disable "${APP_NAME}" >/dev/null 2>&1 || true
+    info "开机自启已禁用（--no-autostart）"
+  fi
+}
+
+# 重启服务 + 验证
+restart_and_verify() {
+  # 注意：不要用 "list-unit-files | grep -q"——grep -q 提前退出会让 systemctl 收到
+  # SIGPIPE，在 pipefail 下整条管道判假（unit 多的机器必踩），误报"服务不存在"
+  if ! systemctl cat "${APP_NAME}" >/dev/null 2>&1; then
+    warn "服务 ${APP_NAME}.service 不存在，请先执行 $0 --init"
+    return 0
+  fi
+
+  apply_autostart
+
+  if [ "$NO_RESTART" = true ]; then
+    info "跳过服务重启（--no-restart），需要时执行: sudo systemctl restart ${APP_NAME}"
+    return 0
+  fi
+
+  log "重启 ${APP_NAME} 服务..."
+  $SUDO systemctl restart "${APP_NAME}"
+
+  if command -v nginx >/dev/null 2>&1; then
+    $SUDO systemctl reload nginx 2>/dev/null || $SUDO nginx -s reload 2>/dev/null || true
+  fi
+
+  # 健康自检：确认服务真正响应，而非仅进程存活
+  # 应用启动时初始化设备池（逐个注册设备）较慢，轮询等待就绪，最多 60s
+  if command -v curl >/dev/null 2>&1; then
+    healthy=false
+    for _ in $(seq 1 30); do
+      if curl -fsS --max-time 2 "http://127.0.0.1:${APP_PORT}/healthz" >/dev/null 2>&1; then
+        healthy=true
+        break
+      fi
+      sleep 2
+    done
+    if [ "$healthy" = true ]; then
+      log "健康检查通过: /healthz"
+    else
+      err "健康检查失败: http://127.0.0.1:${APP_PORT}/healthz"
+      warn "服务可能启动异常，如需回滚执行: $0 --rollback"
+      $SUDO journalctl -u "${APP_NAME}" -n 30 --no-pager || true
+      exit 1
+    fi
+  fi
+
+  echo ""
+  log "服务状态:"
+  $SUDO systemctl status "${APP_NAME}" --no-pager -l | head -n 15 || true
+  echo ""
+  log "最近日志:"
+  $SUDO journalctl -u "${APP_NAME}" -n 15 --no-pager || true
+}
+
+
+# 写入 nginx 配置（--init 与 --sync-nginx 共用的唯一模板来源）
+# 模板自带完整 443/证书配置（证书存在时启用），不依赖签发工具注入——
+# 这样 --sync-nginx 覆盖配置时不会丢失 HTTPS 段（注入式配置会被覆盖回 80-only）
+write_nginx_conf() {
+  # 反代 location（80 无证书时与 443 共用）
+  local proxy_locations
+  proxy_locations=$(cat <<LOC_EOF
+
+    # 视频解密代理：关闭缓冲，分片（Range/206）直通，避免 nginx 对大文件二次落盘
+    location /video/proxy/ {
+        proxy_pass http://127.0.0.1:${APP_PORT};
+        proxy_http_version 1.1;
+        proxy_set_header Host \$host;
+        proxy_set_header X-Real-IP \$remote_addr;
+        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto \$scheme;
+        proxy_buffering off;
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
+    }
+
+    location / {
+        proxy_pass http://127.0.0.1:${APP_PORT};
+        proxy_http_version 1.1;
+        proxy_set_header Host \$host;
+        proxy_set_header X-Real-IP \$remote_addr;
+        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto \$scheme;
+        proxy_set_header Upgrade \$http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
+    }
+LOC_EOF
+)
+
+  local ssl_block=""
+  if [ -f "${CERT_DIR}/${DOMAIN}/fullchain.pem" ]; then
+    log "检测到 ${DOMAIN} 证书，配置启用 443"
+    ssl_block=$(cat <<SSL_EOF
+
+server {
+    listen 443 ssl http2;
+    server_name ${DOMAIN};
+
+    ssl_certificate     ${CERT_DIR}/${DOMAIN}/fullchain.pem;
+    ssl_certificate_key ${CERT_DIR}/${DOMAIN}/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    access_log /var/log/nginx/${APP_NAME}.access.log;
+    error_log  /var/log/nginx/${APP_NAME}.error.log;
+${proxy_locations}
+}
+SSL_EOF
+)
+  else
+    warn "未找到 ${CERT_DIR}/${DOMAIN}/ 证书，本次仅写 80 配置（不跳转 HTTPS）；证书签发后重跑: $0 --sync-nginx"
+  fi
+
+  # 80 端口：有证书时仅 ACME 验证 + 301 跳转；无证书时直接反代
+  local root_location
+  if [ -n "${ssl_block}" ]; then
+    root_location='    location / {
+        return 301 https://$host$request_uri;
+    }'
+  else
+    root_location="${proxy_locations}"
+  fi
+
+  $SUDO tee "${NGINX_CONF}" >/dev/null <<NGINX_EOF
+server {
+    listen 80;
+    server_name ${DOMAIN};
+
+    access_log /var/log/nginx/${APP_NAME}.access.log;
+    error_log  /var/log/nginx/${APP_NAME}.error.log;
+
+    # ACME http-01 验证（acme.sh webroot 模式依赖）
+    location /.well-known/acme-challenge/ {
+        root /var/www/html;
+    }
+
+${root_location}
+}${ssl_block}
+NGINX_EOF
+
+  # 写入后立即校验并重载：ACME 验证必须打到最新配置，
+  # 否则签发时线上仍是内存里的旧配置（80→301→443→反代→404），验证必败
+  if $SUDO nginx -t 2>/dev/null; then
+    $SUDO systemctl reload nginx 2>/dev/null || $SUDO nginx -s reload 2>/dev/null || true
+  fi
+}
+
+# 更新已部署服务器的 nginx 配置：备份 → 重写 → 校验 → 失败回滚
+sync_nginx_conf() {
+  local backup=""
+  if [ -f "${NGINX_CONF}" ]; then
+    backup="${NGINX_CONF}.bak.$(date +%Y%m%d%H%M%S)"
+    $SUDO cp "${NGINX_CONF}" "${backup}"
+    log "已备份原配置: ${backup}"
+  else
+    warn "nginx 配置不存在，将写入全新配置: ${NGINX_CONF}"
+  fi
+
+  write_nginx_conf
+  log "已写入新配置: ${NGINX_CONF}"
+
+  if $SUDO nginx -t; then
+    $SUDO systemctl reload nginx 2>/dev/null || $SUDO nginx -s reload 2>/dev/null || true
+    log "nginx 配置已更新并重载"
+  else
+    err "nginx -t 校验失败"
+    if [ -n "${backup}" ] && [ -f "${backup}" ]; then
+      $SUDO cp "${backup}" "${NGINX_CONF}"
+      if $SUDO nginx -t >/dev/null 2>&1; then
+        $SUDO systemctl reload nginx 2>/dev/null || $SUDO nginx -s reload 2>/dev/null || true
+        warn "已回滚到备份配置: ${backup}"
+      fi
+    fi
+    exit 1
+  fi
+}
+
+# ==================== --list ====================
+if [ "$LIST" = true ]; then
+  list_versions
+  exit 0
+fi
+
+# ==================== --sync-nginx ====================
+# 只更新 nginx 配置（给已部署服务器同步模板变更用），不动二进制与服务
+if [ "$SYNC_NGINX" = true ]; then
+  command -v nginx >/dev/null 2>&1 || { err "未找到 nginx"; exit 1; }
+  sync_nginx_conf
+  exit 0
+fi
+
+# ==================== --stop / --start ====================
+if [ "$STOP" = true ] || [ "$START" = true ]; then
+  systemctl cat "${APP_NAME}" >/dev/null 2>&1 || { err "服务 ${APP_NAME}.service 不存在，请先执行 $0 --init"; exit 1; }
+  if [ "$STOP" = true ]; then
+    $SUDO systemctl stop "${APP_NAME}"
+    log "✅ 已停止 ${APP_NAME}（开机自启设置不变）"
+  else
+    $SUDO systemctl start "${APP_NAME}"
+    sleep 1
+    $SUDO systemctl status "${APP_NAME}" --no-pager -l | head -n 15 || true
+  fi
+  exit 0
+fi
+
+# ==================== --clean ====================
+# 清除本脚本部署的全部内容，便于重新 --init 初次部署
+if [ "$CLEAN" = true ]; then
+  warn "将删除以下内容："
+  echo "  - systemd 服务: ${SERVICE_FILE}"
+  echo "  - nginx 配置:   ${NGINX_CONF}（含 --sync-nginx 的 .bak.* 备份）"
+  echo "  - 二进制目录:   ${BIN_DIR}"
+  echo "  - 证书:         ${CERT_DIR}/${DOMAIN}、acme.sh 中该域名的全部数据、certbot 残留"
+  echo "  （保留 ${SRC_DIR} 下的 .env / 配置 / 数据库；acme.sh 本体保留供重新部署使用）"
+  read -rp "确认清理？输入 yes 继续: " REPLY
+  [ "$REPLY" = "yes" ] || { info "已取消"; exit 0; }
+
+  echo ""
+  log "开始清理，实际删除项："
+
+  # 服务
+  if systemctl cat "${APP_NAME}" >/dev/null 2>&1; then
+    $SUDO systemctl disable --now "${APP_NAME}" || true
+    $SUDO rm -f "${SERVICE_FILE}"
+    $SUDO systemctl daemon-reload
+    log "  已删除: ${SERVICE_FILE}（服务已停止并取消自启）"
+  fi
+
+  # nginx 配置（含 --sync-nginx 产生的 .bak.* 备份）
+  if [ -f "${NGINX_CONF}" ] || ls "${NGINX_CONF}".bak.* >/dev/null 2>&1; then
+    rm_logged "${NGINX_CONF}" "${NGINX_CONF}".bak.*
+    if $SUDO nginx -t 2>/dev/null; then
+      $SUDO systemctl reload nginx 2>/dev/null || $SUDO nginx -s reload 2>/dev/null || true
+      log "  nginx 已重载"
+    fi
+  fi
+
+  # 二进制与版本目录
+  rm_logged "${BIN_DIR}"
+
+  # 证书：移除 acme.sh 管理（--remove 不吊销，LE 证书自然过期），删安装目录
+  # 及 acme.sh 域名数据（含验证失败残留的 domain key，否则重签会要求 --force）
+  ACME_SH="$(find_acme_sh)"
+  if [ -n "$ACME_SH" ]; then
+    $SUDO "$ACME_SH" --remove -d "${DOMAIN}" >/dev/null 2>&1 || true
+  fi
+  rm_logged "${CERT_DIR}/${DOMAIN}" \
+            "${HOME}/.acme.sh/${DOMAIN}_ecc" "${HOME}/.acme.sh/${DOMAIN}" \
+            "/root/.acme.sh/${DOMAIN}_ecc" "/root/.acme.sh/${DOMAIN}"
+
+  # certbot 残留（历史部署用 certbot 时遗留）
+  if command -v certbot &>/dev/null; then
+    if systemctl is-enabled certbot.timer >/dev/null 2>&1; then
+      $SUDO systemctl disable --now certbot.timer
+      log "  已停用: certbot.timer"
+    fi
+    if [ -d "/etc/letsencrypt/live/${DOMAIN}" ]; then
+      $SUDO certbot delete --cert-name "${DOMAIN}" --non-interactive >/dev/null 2>&1 || true
+    fi
+  fi
+  rm_logged "/etc/letsencrypt/live/${DOMAIN}" "/etc/letsencrypt/archive/${DOMAIN}" \
+            "/etc/letsencrypt/renewal/${DOMAIN}.conf" \
+            "/etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh"
+
+  echo ""
+  log "✅ 清理完成。重新部署: $0 --init"
+  exit 0
+fi
+
+# ==================== --rollback ====================
+if [ "$ROLLBACK" = true ]; then
+  if [ ! -d "${BIN_DIR}" ]; then
+    err "二进制目录不存在: ${BIN_DIR}"
+    exit 1
+  fi
+
+  # 没指定版本，交互式选择
+  if [ -z "$ROLLBACK_VERSION" ]; then
+    list_versions
+    echo ""
+    read -rp "输入要回滚到的版本号（如 ${APP_NAME}-v1.0.0，直接回车取消）: " TARGET
+    [ -z "$TARGET" ] && { info "已取消"; exit 0; }
+    ROLLBACK_VERSION="$TARGET"
+  fi
+
+  # 补全前缀
+  if [[ "$ROLLBACK_VERSION" != ${APP_NAME}-* ]]; then
+    ROLLBACK_VERSION="${APP_NAME}-${ROLLBACK_VERSION}"
+  fi
+
+  TARGET_PATH="${BIN_DIR}/${ROLLBACK_VERSION}"
+  if [ ! -f "$TARGET_PATH" ]; then
+    err "版本不存在: $TARGET_PATH"
+    exit 1
+  fi
+
+  log "回滚到: ${ROLLBACK_VERSION}"
+  switch_symlink "${ROLLBACK_VERSION}"
+  restart_and_verify
+  echo ""
+  log "✅ 已回滚到 ${ROLLBACK_VERSION}"
+  exit 0
+fi
+
+# ==================== 1. 前置检查 ====================
+log "检查环境..."
+command -v go >/dev/null 2>&1 || { err "未找到 go，请先安装 Go"; exit 1; }
+command -v nginx >/dev/null 2>&1 || warn "未检测到 nginx"
+
+cd "$SRC_DIR" || { err "代码目录不存在: $SRC_DIR"; exit 1; }
+
+# ==================== 2. 拉取代码 ====================
+if [ "$NO_PULL" = false ] && [ -d .git ]; then
+  log "拉取最新代码..."
+  git pull --ff-only || warn "git pull 失败，继续使用当前代码"
+else
+  log "跳过 git pull"
+fi
+
+# ==================== 3. 编译 ====================
+log "编译 ${APP_NAME} (版本: ${VERSION})..."
+CGO_ENABLED=0 go build \
+  -ldflags="-s -w -X main.Version=${VERSION} -X main.BuildTime=${BUILD_TIME}" \
+  -o "${APP_NAME}-${VERSION}" \
+  "${BUILD_TARGET}"
+
+[ -f "${APP_NAME}-${VERSION}" ] || { err "编译产物不存在"; exit 1; }
+log "编译完成: ${APP_NAME}-${VERSION}"
+
+# ==================== --build-only ====================
+if [ "$BUILD_ONLY" = true ]; then
+  echo ""
+  log "✅ 仅编译模式，产物：$(pwd)/${APP_NAME}-${VERSION}"
+  echo "   如需部署，请执行: $0 ${VERSION} --no-pull"
+  exit 0
+fi
+
+# ==================== 4. 部署二进制 ====================
+log "部署到 ${BIN_DIR}..."
+$SUDO mkdir -p "${BIN_DIR}"
+# 同名版本默认拒绝覆盖，防止 --rollback 回滚到被覆盖的旧文件
+if [ -e "${BIN_DIR}/${APP_NAME}-${VERSION}" ]; then
+  if [ "$FORCE" = true ]; then
+    warn "版本 ${VERSION} 已存在，--force 覆盖"
+  else
+    err "版本 ${VERSION} 已存在于 ${BIN_DIR}，换版本号或加 --force 覆盖"; exit 1
+  fi
+fi
+$SUDO mv "${APP_NAME}-${VERSION}" "${BIN_DIR}/"
+$SUDO chmod +x "${BIN_DIR}/${APP_NAME}-${VERSION}"
+
+switch_symlink "${APP_NAME}-${VERSION}"
+log "软链接已切换到: ${APP_NAME}-${VERSION}"
+
+cleanup_old_versions
+
+# ==================== 5. 首次初始化 ====================
+if [ "$INIT" = true ]; then
+  log "初始化 systemd 服务: ${SERVICE_FILE}"
+  $SUDO tee "${SERVICE_FILE}" >/dev/null <<EOF
+[Unit]
+Description=${APP_DESC}
+After=network.target
+
+[Service]
+Type=simple
+User=${RUN_USER}
+Group=${RUN_USER}
+WorkingDirectory=${SRC_DIR}
+ExecStart=${BIN_DIR}/${APP_NAME}-current
+EnvironmentFile=-${ENV_FILE}
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+NoNewPrivileges=true
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+  log "初始化 Nginx 配置: ${NGINX_CONF}"
+  write_nginx_conf
+
+
+  # ---- 首次初始化自动申请 HTTPS 证书（一次性；续期由 acme.sh cron 自动处理）----
+  if [ -f "${CERT_DIR}/${DOMAIN}/fullchain.pem" ]; then
+    log "证书已存在，跳过申请"
+  else
+    ACME_SH="$(find_acme_sh)"
+    if [ -z "$ACME_SH" ]; then
+      err "未找到 acme.sh，请先安装: curl https://get.acme.sh | sh -s email=${CERT_EMAIL}"
+      exit 1
+    fi
+    log "未检测到证书，使用 acme.sh 申请: ${DOMAIN}"
+    $SUDO mkdir -p /var/www/html "${CERT_DIR}/${DOMAIN}"
+    # --force：上次验证失败会残留 domain key，重试时 acme.sh 拒绝覆盖要求 --force
+    if $SUDO "$ACME_SH" --issue -d "${DOMAIN}" -w /var/www/html --server letsencrypt --keylength ec-256 -m "${CERT_EMAIL}" --force \
+       && $SUDO "$ACME_SH" --install-cert -d "${DOMAIN}" --ecc \
+            --fullchain-file "${CERT_DIR}/${DOMAIN}/fullchain.pem" \
+            --key-file "${CERT_DIR}/${DOMAIN}/privkey.pem" \
+            --reloadcmd "systemctl reload nginx"; then
+      log "证书申请成功，写入 443 配置..."
+      write_nginx_conf
+    else
+      warn "证书申请失败，请检查域名解析与 80 端口；成功后重跑: $0 --sync-nginx"
+    fi
+  fi
+
+  if command -v getenforce >/dev/null 2>&1 && [ "$(getenforce)" != "Disabled" ]; then
+    log "检测到 SELinux，放行 Nginx 网络连接..."
+    $SUDO setsebool -P httpd_can_network_connect 1 || warn "setsebool 失败"
+  fi
+
+  if command -v firewall-cmd >/dev/null 2>&1 && systemctl is-active --quiet firewalld; then
+    log "放行防火墙 80/443..."
+    $SUDO firewall-cmd --permanent --add-service=http >/dev/null
+    $SUDO firewall-cmd --permanent --add-service=https >/dev/null
+    $SUDO firewall-cmd --reload >/dev/null
+  fi
+
+  log "重载 systemd..."
+  $SUDO systemctl daemon-reload
+fi
+
+# ==================== 6. 校验 Nginx ====================
+if [ -f "${NGINX_CONF}" ]; then
+  log "校验 Nginx 配置..."
+  $SUDO nginx -t || { err "Nginx 配置有误"; exit 1; }
+fi
+
+# ==================== 7. 重启服务 + 验证 ====================
+restart_and_verify
+
+echo ""
+log "✅ 部署完成！"
+echo "   版本:   ${VERSION}"
+echo "   二进制: ${BIN_DIR}/${APP_NAME}-current"
+echo "   端口:   ${APP_PORT}"
+echo "   域名:   http://${DOMAIN}"
+echo ""
+echo "常用命令:"
+echo "  查看状态: sudo systemctl status ${APP_NAME}"
+echo "  查看日志: sudo journalctl -u ${APP_NAME} -f"
+echo "  重启服务: sudo systemctl restart ${APP_NAME}"
+echo "  列出版本: $0 --list"
+echo "  回滚版本: $0 --rollback"

go.mod

@@ -1,19 +1,27 @@
 module fanqie
 
-go 1.24.0
+go 1.25.0
 
 require (
 	github.com/PuerkitoBio/goquery v1.8.1
 	github.com/fsnotify/fsnotify v1.7.0
 	github.com/google/uuid v1.4.0
+	github.com/jackc/pgx/v5 v5.11.0
 	github.com/mattn/go-sqlite3 v1.14.18
+	github.com/redis/go-redis/v9 v9.22.0
 	github.com/spf13/viper v1.18.2
+	golang.org/x/sync v0.17.0
+	golang.org/x/time v0.5.0
 )
 
 require (
 	github.com/andybalholm/cascadia v1.3.1 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/magiconair/properties v1.8.7 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
@@ -23,9 +31,8 @@ require (
 	github.com/spf13/afero v1.11.0 // indirect
 	github.com/spf13/cast v1.6.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
-	github.com/stretchr/testify v1.11.1 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
-	go.uber.org/atomic v1.9.0 // indirect
+	go.uber.org/atomic v1.11.0 // indirect
 	go.uber.org/multierr v1.9.0 // indirect
 	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
 	golang.org/x/net v0.46.0 // indirect

go.sum

@@ -2,6 +2,12 @@ github.com/PuerkitoBio/goquery v1.8.1 h1:uQxhNlArOIdbrH1tr0UXwdVFgDcZDrZVdcpygAc
 github.com/PuerkitoBio/goquery v1.8.1/go.mod h1:Q8ICL1kNUJ2sXGoAhPGUdYDJvgQgHzJsnnd3H7Ho5jQ=
 github.com/andybalholm/cascadia v1.3.1 h1:nhxRkql1kdYCc8Snf7D5/D3spOX+dBgjA6u8x004T2c=
 github.com/andybalholm/cascadia v1.3.1/go.mod h1:R4bJ1UQfqADjvDa4P6HZHLh/3OxWWEqc0Sk8XGwHqvA=
+github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
+github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
+github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
+github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
@@ -16,6 +22,16 @@ github.com/google/uuid v1.4.0 h1:MtMxsa51/r9yyhkyLsVeVt0B+BGQZzpQiTQ4eHZ8bc4=
 github.com/google/uuid v1.4.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
 github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.11.0 h1:IzBBtyK9AHqf98cctWFifYSci2hgQR/cd56wB4p+ogg=
+github.com/jackc/pgx/v5 v5.11.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
+github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
@@ -31,6 +47,8 @@ github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/redis/go-redis/v9 v9.22.0 h1:laDvpYXTJtZLloinw1fA5Kqd6HAEH2XKxOkG/PDq2F0=
+github.com/redis/go-redis/v9 v9.22.0/go.mod h1:y2g0Wj8rQvuK0ELM+oxSudcLtC09JScs98I/X9gRWY4=
 github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/sagikazarmark/locafero v0.4.0 h1:HApY1R9zGo4DBgr7dqsTH/JJxLTTsOt7u6keLGt6kNQ=
@@ -49,13 +67,16 @@ github.com/spf13/viper v1.18.2 h1:LUXCnvUvSM6FXAsj6nnfc8Q2tp1dIgUfY9Kc8GsSOiQ=
 github.com/spf13/viper v1.18.2/go.mod h1:EKmWIqdnk5lOcmR72yw6hS+8OPYcwD0jteitLMVB+yk=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
-go.uber.org/atomic v1.9.0 h1:ECmE8Bn/WFTYwEW/bpKD3M8VtR/zQVbavAoalC1PYyE=
-go.uber.org/atomic v1.9.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc=
+github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
+github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
+go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
+go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
 go.uber.org/multierr v1.9.0 h1:7fIwc/ZtS0q++VgcfqFDxSBZVv/Xo49/SYnDFupUwlI=
 go.uber.org/multierr v1.9.0/go.mod h1:X2jQV1h+kxSjClGpnseKVIxpmcjrj7MNnI0bnlfKTVQ=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
@@ -72,6 +93,8 @@ golang.org/x/net v0.46.0 h1:giFlY12I07fugqwPuWJi68oOnpfqFnJIJzaIIm2JVV4=
 golang.org/x/net v0.46.0/go.mod h1:Q9BGdFy1y4nkUwiLvT5qtyhAnEHgnQ/zd8PfU6nc210=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
+golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -91,14 +114,17 @@ golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
 golang.org/x/text v0.30.0 h1:yznKA/E9zq54KzlzBEAWn1NXSQ8DIp/NYMy88xJjl4k=
 golang.org/x/text v0.30.0/go.mod h1:yDdHFIX9t+tORqspjENWgzaCVXgk0yYnYuSZ8UzzBVM=
+golang.org/x/time v0.5.0 h1:o7cqy6amK/52YcAKIPlM3a+Fpj35zvRj2TP+e1xFSfk=
+golang.org/x/time v0.5.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA=
 gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/algos/golden_test.go

@@ -0,0 +1,79 @@
+//go:debug randseednop=0
+
+package algos
+
+import (
+	"encoding/hex"
+	"math/rand"
+	"testing"
+)
+
+// 固定输入 + 固定时间戳的 golden 测试：签名算法被改坏时在此最先失败。
+// 基准值取自当前实现；有意修改算法后用相同输入重新生成并更新期望值。
+// 8404 内嵌随机数且走全局 math/rand，Go 1.25 起 rand.Seed 默认是 no-op，
+// 故用 //go:debug randseednop=0 恢复其钉死随机序列的旧语义。
+// x-argus 的 protobuf 编码按 map 迭代顺序输出（protobuf.go:385），天然
+// 不确定，无法全量 golden，只测其内部的确定性哈希层。
+
+const (
+	goldenParams = "aid=1967&app_name=fanqie_novel&device_id=1234567890123456&version_name=5.9.5"
+	goldenStub   = "d41d8cd98f00b204e9800998ecf8427e"
+	goldenCookie = "install_id=728944090949322; device_id=1234567890123456"
+	goldenSecDev = "1234567890123456"
+	goldenAID    = 1967
+	goldenLcID   = 1611921764
+)
+
+// var：Sign2 需要 *int64，不能对常量取址
+var goldenTS = int64(1700000000)
+
+func goldenArgs() (string, string, string, string, int, int, string, int, int, *int64) {
+	return goldenParams, goldenStub, goldenSecDev, goldenCookie,
+		goldenAID, goldenLcID, "v04.06.01-ml-android", 135004672, 0, &goldenTS
+}
+
+func assertGolden(t *testing.T, name string, got map[string]string, want map[string]string) {
+	t.Helper()
+	for k, v := range want {
+		if got[k] != v {
+			t.Errorf("%s %s = %q, want %q", name, k, got[k], v)
+		}
+	}
+}
+
+func TestGorgonSign2Golden(t *testing.T) {
+	GlobalAlgorithmSwitcher.SwitchAlgorithm("gorgon")
+	assertGolden(t, "gorgon", Sign2(goldenArgs()), map[string]string{
+		"x-gorgon":        "0404b0d30000bbd9e75fe1edb046d324b7853694a6177ca72d0a",
+		"x-khronos":       "1700000000",
+		"x-ss-req-ticket": "1700000000000",
+	})
+}
+
+func TestAlgo8404Sign2Golden(t *testing.T) {
+	rand.Seed(1)
+	GlobalAlgorithmSwitcher.SwitchAlgorithm("8404")
+	defer GlobalAlgorithmSwitcher.SwitchAlgorithm("gorgon")
+	assertGolden(t, "8404", Sign2(goldenArgs()), map[string]string{
+		"X-Gorgon":        "8404210f00008eec413318e9f810571e96fca6fb4a0f497e78e5",
+		"X-Khronos":       "1700000000",
+		"X-SS-REQ-Ticket": "1700000000000",
+	})
+}
+
+func TestLadonGolden(t *testing.T) {
+	// 固定 randomBytes，绕开 crypto/rand
+	got := LadonEncrypt(goldenTS, goldenLcID, goldenAID, []byte{0xde, 0xad, 0xbe, 0xef})
+	if want := "3q2+7/6PK4T/ZqM1zu2AIWFdXW2D9gdHrXRfOb02lxi6GnYm"; got != want {
+		t.Errorf("ladon = %q, want %q", got, want)
+	}
+}
+
+func TestArgusHashGolden(t *testing.T) {
+	if got := hex.EncodeToString(GetBodyHash(goldenStub)); got != "9c840df1aec0" {
+		t.Errorf("bodyHash = %s, want 9c840df1aec0", got)
+	}
+	if got := hex.EncodeToString(GetQueryHash(goldenParams)); got != "58bc068af10b" {
+		t.Errorf("queryHash = %s, want 58bc068af10b", got)
+	}
+}

internal/algos/signer.go

@@ -74,6 +74,7 @@ func Sign4(
 	// 添加 Ladon 和 Argus 签名
 	ladon := &Ladon{}
 	result["x-ladon"] = ladon.Encrypt(timestamp, licenseID, aid)
+	result["x-helios"] = result["x-ladon"] // X-Helios 与 X-Ladon 同值（对齐书源实现）
 
 	argus := &Argus{}
 	result["x-argus"] = argus.GetSign(

internal/config/config.go

@@ -3,8 +3,10 @@ package config
 import (
 	"fmt"
 	"log"
+	"os"
 	"sync"
 	"sync/atomic"
+	"time"
 
 	"github.com/spf13/viper"
 )
@@ -19,17 +21,29 @@ type Config struct {
 
 // ServerConfig 服务器配置
 type ServerConfig struct {
-	Port      string `mapstructure:"port"`
-	Host      string `mapstructure:"host"`
-	AccessKey string `mapstructure:"access_key"`
+	Port         string           `mapstructure:"port"`
+	Host         string           `mapstructure:"host"`
+	AccessKey    string           `mapstructure:"access_key"`
+	ProtectAll   bool             `mapstructure:"protect_all"`   // 业务接口也要求访问密钥（公网部署建议开启）
+	RateLimitQPS float64          `mapstructure:"rate_limit_qps"` // 每 IP 每秒请求上限，0=不限制
+	RequestLog   RequestLogConfig `mapstructure:"request_log"`    // 请求日志（只记元数据与错误摘要）
+}
+
+// RequestLogConfig 请求日志配置
+type RequestLogConfig struct {
+	Enabled       bool `mapstructure:"enabled"`        // 是否记录业务接口请求元数据
+	RetentionDays int  `mapstructure:"retention_days"` // 日志保留天数，<=0 视为 7
 }
 
 // FanqieConfig 番茄小说配置
 type FanqieConfig struct {
 	Algorithm string        `mapstructure:"algorithm"`
 	Signature string        `mapstructure:"signature"` // 签名方法: sign2 / sign4
+	// 注册设备身份: pad（默认，历史行为）/ phone（对齐手机 App 书源注册 payload）
+	DeviceIdentity string   `mapstructure:"device_identity"`
 	Content   ContentConfig `mapstructure:"content"`
 	Manga     MangaConfig   `mapstructure:"manga"`
+	Video     VideoConfig   `mapstructure:"video"`
 }
 
 // ContentConfig 内容处理配置
@@ -49,12 +63,42 @@ type MangaConfig struct {
 	OutputMode string `mapstructure:"output_mode"` // 输出模式: data_uri / base64 / url
 }
 
+// VideoConfig 视频处理配置
+type VideoConfig struct {
+	OutputMode   string `mapstructure:"output_mode"`  // 输出模式: url（原始CDN链接，内容加密）/ proxy（本地解密代理，可直接播放）
+	Quality      string `mapstructure:"quality"`      // 默认清晰度: max（最高档）/ 360p/480p/... 或档位 key（video_1..N），留空返回全部
+	CacheEnabled bool   `mapstructure:"cache_enabled"` // 解密后视频的磁盘缓存
+	CachePath    string `mapstructure:"cache_path"`    // 缓存目录
+}
+
 // CacheConfig 缓存配置
 type CacheConfig struct {
-	Enabled        bool   `mapstructure:"enabled"`
-	SQLitePath     string `mapstructure:"sqlite_path"`
-	CleanupEnabled bool   `mapstructure:"cleanup_enabled"` // 是否启用缓存清理
-	CleanupSeconds int    `mapstructure:"cleanup_seconds"` // 缓存清理时间（秒）
+	Enabled        bool           `mapstructure:"enabled"`
+	Backend        string         `mapstructure:"backend"` // 存储后端: sqlite | postgres
+	SQLitePath     string         `mapstructure:"sqlite_path"`
+	Postgres       PostgresConfig `mapstructure:"postgres"`
+	Redis          RedisConfig    `mapstructure:"redis"`
+	CleanupEnabled bool           `mapstructure:"cleanup_enabled"` // 是否启用缓存清理
+	CleanupSeconds int            `mapstructure:"cleanup_seconds"` // 缓存清理时间（秒）
+}
+
+// PostgresConfig PostgreSQL 连接配置
+type PostgresConfig struct {
+	Host     string `mapstructure:"host"`
+	Port     int    `mapstructure:"port"`
+	User     string `mapstructure:"user"`
+	Password string `mapstructure:"password"`
+	Database string `mapstructure:"database"`
+	SSLMode  string `mapstructure:"sslmode"` // disable | prefer | require
+}
+
+// RedisConfig Redis 缓存配置（启用后正文缓存与音频代理缓存走 Redis，统计数据与设备池仍在 SQL 库）
+type RedisConfig struct {
+	Enabled  bool   `mapstructure:"enabled"`
+	Host     string `mapstructure:"host"`
+	Port     int    `mapstructure:"port"`
+	Password string `mapstructure:"password"`
+	DB       int    `mapstructure:"db"`
 }
 
 // DeviceKeyPoolConfig 设备密钥池配置
@@ -90,6 +134,22 @@ func NewConfigManager() *ConfigManager {
 	}
 }
 
+// ApplyTimezone 按 TZ 环境变量/.env 设置进程时区。
+// 必须在任何时间显示之前调用（time.Local 首次使用后不再重读 TZ）。
+// 环境变量已设 TZ 时以环境变量为准（.env 不覆盖已有环境变量）。
+func ApplyTimezone() {
+	loadDotenv("./.env")
+	tz := os.Getenv("TZ")
+	if tz == "" {
+		return
+	}
+	if _, err := time.LoadLocation(tz); err != nil {
+		log.Printf("[config/WARN] 无效时区 TZ=%s，沿用系统时区: %v", tz, err)
+		return // 不写入 TZ：无效值会让 time.Local 落到 UTC
+	}
+	os.Setenv("TZ", tz)
+}
+
 // LoadConfig 加载配置文件
 func LoadConfig(configPath string) error {
 	// 初始化管理器
@@ -98,6 +158,9 @@ func LoadConfig(configPath string) error {
 		manager.configPath = configPath
 	}
 
+	// 加载 .env（若存在），敏感配置可由环境变量覆盖
+	loadDotenv("./.env")
+
 	viper.SetConfigFile(configPath)
 	viper.SetConfigType("yaml")
 
@@ -112,6 +175,7 @@ func LoadConfig(configPath string) error {
 	if err := viper.Unmarshal(newConfig); err != nil {
 		return fmt.Errorf("解析配置文件失败: %w", err)
 	}
+	applyEnvOverrides(newConfig)
 
 	// 更新配置
 	appConfig.Store(newConfig)
@@ -124,10 +188,13 @@ func setDefaults() {
 	// 服务器配置
 	viper.SetDefault("server.port", "40180")
 	viper.SetDefault("server.host", "0.0.0.0")
+	viper.SetDefault("server.request_log.enabled", false)
+	viper.SetDefault("server.request_log.retention_days", 7)
 
 	// 番茄小说配置
 	viper.SetDefault("fanqie.algorithm", "gorgon")
 	viper.SetDefault("fanqie.signature", "sign2")
+	viper.SetDefault("fanqie.device_identity", "pad")
 	
 	// 内容处理配置
 	viper.SetDefault("fanqie.content.remove_images", false)
@@ -142,12 +209,34 @@ func setDefaults() {
 	// 漫画处理配置
 	viper.SetDefault("fanqie.manga.output_mode", "url")
 
+	// 视频处理配置
+	viper.SetDefault("fanqie.video.output_mode", "proxy")
+	viper.SetDefault("fanqie.video.quality", "max")
+	viper.SetDefault("fanqie.video.cache_enabled", true)
+	viper.SetDefault("fanqie.video.cache_path", "./video_cache")
+
 	// 缓存配置
 	viper.SetDefault("cache.enabled", true)
+	viper.SetDefault("cache.backend", "sqlite")
 	viper.SetDefault("cache.sqlite_path", "./cache.db")
 	viper.SetDefault("cache.cleanup_enabled", false)
 	viper.SetDefault("cache.cleanup_seconds", 86400)
 
+	// PostgreSQL 配置
+	viper.SetDefault("cache.postgres.host", "127.0.0.1")
+	viper.SetDefault("cache.postgres.port", 5432)
+	viper.SetDefault("cache.postgres.user", "postgres")
+	viper.SetDefault("cache.postgres.password", "")
+	viper.SetDefault("cache.postgres.database", "fanqie")
+	viper.SetDefault("cache.postgres.sslmode", "disable")
+
+	// Redis 配置
+	viper.SetDefault("cache.redis.enabled", false)
+	viper.SetDefault("cache.redis.host", "127.0.0.1")
+	viper.SetDefault("cache.redis.port", 6379)
+	viper.SetDefault("cache.redis.password", "")
+	viper.SetDefault("cache.redis.db", 0)
+
 	// 设备密钥池配置
 	viper.SetDefault("device_key_pool.enabled", true)
 	viper.SetDefault("device_key_pool.initial_size", 3)
@@ -188,6 +277,7 @@ func ReloadConfig() error {
 	if err := viper.Unmarshal(newConfig); err != nil {
 		return fmt.Errorf("重新解析配置文件失败: %w", err)
 	}
+	applyEnvOverrides(newConfig)
 
 	// 更新配置
 	manager.mu.Lock()

internal/config/dotenv.go

@@ -0,0 +1,49 @@
+package config
+
+import (
+	"os"
+	"strings"
+)
+
+// loadDotenv 加载 .env 文件到环境变量（文件不存在则跳过；不覆盖已有环境变量）
+func loadDotenv(path string) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return
+	}
+	for _, line := range strings.Split(string(data), "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		k, v, ok := strings.Cut(line, "=")
+		if !ok {
+			continue
+		}
+		k = strings.TrimSpace(k)
+		v = strings.Trim(strings.TrimSpace(v), `"'`)
+		if os.Getenv(k) == "" {
+			os.Setenv(k, v)
+		}
+	}
+}
+
+// applyEnvOverrides 用环境变量覆盖敏感配置（配合 .env 使用，真实密码不进 config.yaml）
+func applyEnvOverrides(c *Config) {
+	for _, o := range []struct {
+		env string
+		dst *string
+	}{
+		{"FQ_SERVER_ACCESS_KEY", &c.Server.AccessKey},
+		{"FQ_PG_HOST", &c.Cache.Postgres.Host},
+		{"FQ_PG_USER", &c.Cache.Postgres.User},
+		{"FQ_PG_PASSWORD", &c.Cache.Postgres.Password},
+		{"FQ_PG_DATABASE", &c.Cache.Postgres.Database},
+		{"FQ_REDIS_HOST", &c.Cache.Redis.Host},
+		{"FQ_REDIS_PASSWORD", &c.Cache.Redis.Password},
+	} {
+		if v := os.Getenv(o.env); v != "" {
+			*o.dst = v
+		}
+	}
+}

internal/config/video_config_test.go

@@ -0,0 +1,46 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/spf13/viper"
+)
+
+// video 段配置读取：显式值生效、缺省回落 viper 默认值
+func TestVideoConfig(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	os.WriteFile(path, []byte(`
+fanqie:
+  video:
+    output_mode: "proxy"
+    quality: "720p"
+`), 0644)
+
+	v := viper.New()
+	v.SetConfigFile(path)
+	if err := v.ReadInConfig(); err != nil {
+		t.Fatal(err)
+	}
+	var c Config
+	if err := v.Unmarshal(&c); err != nil {
+		t.Fatal(err)
+	}
+	if c.Fanqie.Video.OutputMode != "proxy" || c.Fanqie.Video.Quality != "720p" {
+		t.Fatalf("显式配置未生效: %+v", c.Fanqie.Video)
+	}
+
+	// 缺省回落
+	v2 := viper.New()
+	v2.SetDefault("fanqie.video.output_mode", "url")
+	v2.SetDefault("fanqie.video.quality", "")
+	var c2 Config
+	if err := v2.Unmarshal(&c2); err != nil {
+		t.Fatal(err)
+	}
+	if c2.Fanqie.Video.OutputMode != "url" || c2.Fanqie.Video.Quality != "" {
+		t.Fatalf("默认值不符: %+v", c2.Fanqie.Video)
+	}
+}

internal/fqapi/audio.go

@@ -1,7 +1,6 @@
 package fqapi
 
 import (
-	"encoding/json"
 	"fanqie/internal/common"
 	"fmt"
 )
@@ -118,8 +117,7 @@ func HandleAudio(itemIDs interface{}, toneID interface{}, output interface{}) (s
 			}
 		}
 
-		resultBytes, _ := json.Marshal(respJSON)
-		return string(resultBytes), nil
+		return marshalNoEscape(UnwrapJSONStrings(respJSON)), nil
 	}
 
 	// 返回错误信息
@@ -132,4 +130,3 @@ func HandleAudio(itemIDs interface{}, toneID interface{}, output interface{}) (s
 	audioLogger.Error(fmt.Sprintf("获取音频失败: code=%v, msg=%s", respCode, errMsg))
 	return BuildErrorResponse(errMsg), nil
 }
-

internal/fqapi/audio_proxy.go

@@ -4,15 +4,16 @@ import (
 	"database/sql"
 	"encoding/json"
 	"fmt"
+	"io"
 	"time"
 )
 
 // AudioCacheItem 音频缓存项
 type AudioCacheItem struct {
 	OriginalURL string            `json:"original_url"` // 原始CDN URL
-	DeviceID    string           `json:"device_id"`    // 关联的设备ID
+	DeviceID    string            `json:"device_id"`    // 关联的设备ID
 	Headers     map[string]string `json:"headers"`      // 请求头信息
-	CachedAt    time.Time        `json:"cached_at"`    // 缓存时间
+	CachedAt    time.Time         `json:"cached_at"`    // 缓存时间
 }
 
 // GenerateAudioProxyURL 生成音频代理URL
@@ -20,18 +21,28 @@ func GenerateAudioProxyURL(originalURL, deviceID string, headers map[string]stri
 	// 生成缓存key
 	key := generateRandomKey(16)
 
+	// Redis 模式：TTL 自动过期
+	if redisCache != nil {
+		saveAudioProxyEntry(key, &audioProxyEntry{
+			OriginalURL: originalURL,
+			DeviceID:    deviceID,
+			Headers:     headers,
+		})
+		return fmt.Sprintf("/audio/proxy/%s", key)
+	}
+
 	// 将headers序列化为JSON字符串
 	headersJSON, _ := json.Marshal(headers)
 
 	// 存储到数据库
 	if cacheDB != nil {
-		cacheMutex.Lock()
-		defer cacheMutex.Unlock()
 
-		_, err := cacheDB.Exec(`
-			INSERT INTO audio_cache (key, original_url, device_id, headers, created_at)
-			VALUES (?, ?, ?, ?, ?)
-		`, key, originalURL, deviceID, string(headersJSON), time.Now().Unix())
+		_, err := cacheDB.Exec(q(`
+			INSERT INTO audio_cache (key, original_url, device_id, headers, created_at, updated_at)
+			VALUES (?, ?, ?, ?, ?, ?)
+			ON CONFLICT(key) DO UPDATE SET original_url = excluded.original_url,
+				device_id = excluded.device_id, headers = excluded.headers, updated_at = excluded.updated_at
+		`), key, originalURL, deviceID, string(headersJSON), time.Now().Unix(), time.Now().Unix())
 		if err != nil {
 			audioLogger.Error("保存音频缓存失败: " + err.Error())
 		}
@@ -41,66 +52,81 @@ func GenerateAudioProxyURL(originalURL, deviceID string, headers map[string]stri
 	return fmt.Sprintf("/audio/proxy/%s", key)
 }
 
-// HandleAudioProxy 处理音频代理请求
-func HandleAudioProxy(key string) ([]byte, string, error) {
+// loadMediaProxyEntry 读取媒体代理映射（audio/video 共用；Redis 优先，回退 SQL）
+type mediaProxyEntry struct {
+	OriginalURL string
+	DeviceID    string
+	Headers     map[string]string
+}
+
+func loadMediaProxyEntry(key string) (*mediaProxyEntry, error) {
+	if redisCache != nil {
+		entry, err := loadAudioProxyEntry(key)
+		if err != nil {
+			return nil, err
+		}
+		return &mediaProxyEntry{OriginalURL: entry.OriginalURL, DeviceID: entry.DeviceID, Headers: entry.Headers}, nil
+	}
 	if cacheDB == nil {
-		return nil, "", fmt.Errorf("数据库未初始化")
+		return nil, fmt.Errorf("数据库未初始化")
 	}
 
-	// 从数据库获取音频信息
 	var originalURL, deviceID, headersJSON string
 	var createdAt int64
-
-	cacheMutex.Lock()
-	err := cacheDB.QueryRow(`
+	err := cacheDB.QueryRow(q(`
 		SELECT original_url, device_id, headers, created_at
 		FROM audio_cache WHERE key = ?
-	`, key).Scan(&originalURL, &deviceID, &headersJSON, &createdAt)
-	cacheMutex.Unlock()
+	`), key).Scan(&originalURL, &deviceID, &headersJSON, &createdAt)
 
 	if err == sql.ErrNoRows {
-		return nil, "", fmt.Errorf("音频信息不存在，请先调用 /audio 接口")
+		return nil, fmt.Errorf("媒体信息不存在，请先调用 /audio 或 /video 接口")
 	}
 	if err != nil {
-		return nil, "", fmt.Errorf("查询音频缓存失败: %w", err)
+		return nil, fmt.Errorf("查询媒体缓存失败: %w", err)
+	}
+	// 过期清理（2小时，匹配CDN链接有效期）
+	if time.Now().Unix()-createdAt > 7200 {
+		cacheDB.Exec(q("DELETE FROM audio_cache WHERE key = ?"), key)
+		return nil, fmt.Errorf("媒体信息已过期，请重新调用接口")
 	}
 
-	// 检查缓存是否过期（2小时，匹配CDN链接有效期）
-	if time.Now().Unix()-createdAt > 7200 { // 2小时 = 7200秒
-		// 清理过期缓存
-		cacheMutex.Lock()
-		cacheDB.Exec("DELETE FROM audio_cache WHERE key = ?", key)
-		cacheMutex.Unlock()
-		return nil, "", fmt.Errorf("音频信息已过期，请重新调用 /audio 接口")
-	}
-
-	// 解析headers
 	var headers map[string]string
 	json.Unmarshal([]byte(headersJSON), &headers)
 	if headers == nil {
 		headers = make(map[string]string)
 	}
+	return &mediaProxyEntry{OriginalURL: originalURL, DeviceID: deviceID, Headers: headers}, nil
+}
 
-	// 下载音频内容，使用关联的设备信息
-	data, contentType, err := downloadMediaWithRetry(originalURL, deviceID, headers, 3)
+// HandleAudioProxy 处理音频代理请求（流式返回，调用方负责 Close）
+func HandleAudioProxy(key string) (io.ReadCloser, string, error) {
+	entry, err := loadMediaProxyEntry(key)
+	if err != nil {
+		return nil, "", err
+	}
+
+	// 下载音频内容（流式），使用关联的设备信息
+	body, contentType, err := downloadMediaWithRetry(entry.OriginalURL, entry.DeviceID, entry.Headers, 3)
 	if err != nil {
 		return nil, "", fmt.Errorf("下载音频失败: %w", err)
 	}
 
-	return data, contentType, nil
+	return body, contentType, nil
 }
 
 // CleanExpiredAudioCache 清理过期的音频缓存
 func CleanExpiredAudioCache() {
+	// Redis 模式下由 TTL 自动过期，无需清理
+	if redisCache != nil {
+		return
+	}
+
 	if cacheDB == nil {
 		return
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	// 删除2小时前的缓存
-	result, err := cacheDB.Exec("DELETE FROM audio_cache WHERE created_at < ?", time.Now().Unix()-7200)
+	result, err := cacheDB.Exec(q("DELETE FROM audio_cache WHERE created_at < ?"), time.Now().Unix()-7200)
 	if err != nil {
 		audioLogger.Error("清理过期音频缓存失败: " + err.Error())
 		return

internal/fqapi/cache_manager.go

@@ -1,127 +1,323 @@
 package fqapi
 
 import (
+	"context"
 	"database/sql"
 	"encoding/json"
 	"fanqie/internal/common"
 	"fanqie/internal/config"
 	"fmt"
-	"sync"
+	"net/url"
+	"strconv"
+	"strings"
+	"sync/atomic"
 	"time"
 
+	_ "github.com/jackc/pgx/v5/stdlib"
 	_ "github.com/mattn/go-sqlite3"
+	"github.com/redis/go-redis/v9"
+	"golang.org/x/sync/singleflight"
 )
 
+const (
+	// sqlCacheTTLSeconds SQL 持久层保留时长：不可变内容（正文/详情/目录）与业务 TTL 解耦，
+	// Redis 过期或重启后由 SQL 回填，避免重新打上游
+	sqlCacheTTLSeconds = 30 * 86400
+)
+
+// volatileCachePrefixes 动态短缓存（值会变）只走 Redis/短 TTL，不进 SQL 长期层
+var volatileCachePrefixes = []string{"search_", "category_", "rank_"}
+
+// isVolatileCacheKey 判断是否为动态短缓存 key
+func isVolatileCacheKey(key string) bool {
+	for _, p := range volatileCachePrefixes {
+		if strings.HasPrefix(key, p) {
+			return true
+		}
+	}
+	return false
+}
+
+// cacheSF 合并并发 miss 的回源请求，防止缓存击穿
+var cacheSF singleflight.Group
+
 var (
 	cacheDB             *sql.DB
-	cacheMutex          sync.Mutex
+	dbDriver            string // "sqlite3" | "pgx"
+	redisCache          *redis.Client
 	cacheLogger         = common.NewLogger("cache_manager", "INFO", "")
-	contentRequestCount int  // content接口访问计数
-	countMutex          sync.Mutex
+	contentRequestCount atomic.Int64 // content接口访问计数
 	cacheCleanupTicker  *time.Ticker // 缓存清理定时器
 )
 
+// q 按数据库方言转换占位符（PostgreSQL 使用 $n 形式）
+func q(query string) string {
+	if dbDriver != "pgx" {
+		return query
+	}
+	var b strings.Builder
+	n := 0
+	for i := 0; i < len(query); i++ {
+		if query[i] == '?' {
+			n++
+			b.WriteString("$" + strconv.Itoa(n))
+		} else {
+			b.WriteByte(query[i])
+		}
+	}
+	return b.String()
+}
+
+// InitRedis 初始化 Redis 缓存（启用后正文缓存与音频代理缓存走 Redis）
+func InitRedis() error {
+	cfg := config.GetAppConfig()
+	if cfg == nil || !cfg.Cache.Redis.Enabled {
+		return nil
+	}
+
+	redisCache = redis.NewClient(&redis.Options{
+		Addr:     fmt.Sprintf("%s:%d", cfg.Cache.Redis.Host, cfg.Cache.Redis.Port),
+		Password: cfg.Cache.Redis.Password,
+		DB:       cfg.Cache.Redis.DB,
+		// 缓存场景失败不重试：miss 直接降级 SQL，重试只会放大网络慢时的请求延迟
+		MaxRetries:      0,
+		ReadTimeout:     3 * time.Second,
+		WriteTimeout:    3 * time.Second,
+		MinRetryBackoff: 0,
+	})
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if err := redisCache.Ping(ctx).Err(); err != nil {
+		redisCache = nil
+		return fmt.Errorf("连接 Redis 失败: %w", err)
+	}
+
+	cacheLogger.Info(fmt.Sprintf("Redis 缓存已启用: %s:%d db=%d", cfg.Cache.Redis.Host, cfg.Cache.Redis.Port, cfg.Cache.Redis.DB))
+	return nil
+}
+
+// CloseRedis 关闭 Redis 连接
+func CloseRedis() {
+	if redisCache != nil {
+		redisCache.Close()
+	}
+}
+
 // CacheData 缓存数据结构
 type CacheData struct {
 	Data string  `json:"data"`
 	Expi float64 `json:"expi"`
 }
 
-// InitDB 初始化数据库
+// InitDB 初始化数据库（按 cache.backend 选择 sqlite 或 postgres）
 func InitDB() error {
 	if cacheDB != nil {
 		return nil // 已初始化
 	}
 
-	// 使用配置的路径
-	dbPath := "./cache.db"
-	cfg := config.GetConfig()
-	if cfg != nil && cfg.Cache.SQLitePath != "" {
-		dbPath = cfg.Cache.SQLitePath
+	cfg := config.GetAppConfig()
+	backend := "sqlite"
+	dsn := "./cache.db"
+	if cfg != nil {
+		if cfg.Cache.Backend != "" {
+			backend = cfg.Cache.Backend
+		}
+		if backend == "postgres" {
+			pg := cfg.Cache.Postgres
+			if pg.Host == "" || pg.Database == "" {
+				return fmt.Errorf("cache.backend 为 postgres 但未配置 host/database")
+			}
+			// 用 net/url 构造连接串，密码中的特殊字符会被自动转义
+			u := &url.URL{
+				Scheme:   "postgres",
+				User:     url.UserPassword(pg.User, pg.Password),
+				Host:     fmt.Sprintf("%s:%d", pg.Host, pg.Port),
+				Path:     pg.Database,
+				RawQuery: "sslmode=" + pg.SSLMode,
+			}
+			dsn = u.String()
+		} else if cfg.Cache.SQLitePath != "" {
+			dsn = cfg.Cache.SQLitePath
+		}
+	}
+
+	switch backend {
+	case "postgres":
+		dbDriver = "pgx"
+	default:
+		dbDriver = "sqlite3"
+		// ponytail: 单文件场景，WAL + 忙等待即可，无需更多调优
+		dsn = dsn + "?_journal_mode=WAL&_busy_timeout=5000"
 	}
 
 	var err error
-	cacheDB, err = sql.Open("sqlite3", dbPath)
+	cacheDB, err = sql.Open(dbDriver, dsn)
 	if err != nil {
 		cacheLogger.Error("打开数据库失败: " + err.Error())
 		return err
 	}
-
-	// 创建缓存表（添加created_at字段用于清理）
-	_, err = cacheDB.Exec(`CREATE TABLE IF NOT EXISTS cache (
-		key TEXT PRIMARY KEY, 
-		value TEXT,
-		created_at INTEGER DEFAULT (strftime('%s', 'now'))
-	)`)
-	if err != nil {
-		cacheLogger.Error("创建缓存表失败: " + err.Error())
+	if err := cacheDB.Ping(); err != nil {
+		cacheLogger.Error("连接数据库失败: " + err.Error())
 		return err
 	}
+	cacheLogger.Info(fmt.Sprintf("数据库已连接: %s (driver=%s)", backend, dbDriver))
 
-
-	// 创建statistics表（保存请求统计，始终使用）
-	_, err = cacheDB.Exec(`CREATE TABLE IF NOT EXISTS statistics (
-		id INTEGER PRIMARY KEY CHECK (id = 1),
-		total_requests INTEGER DEFAULT 0,
-		search_requests INTEGER DEFAULT 0,
-		detail_requests INTEGER DEFAULT 0,
-		catalog_requests INTEGER DEFAULT 0,
-		content_requests INTEGER DEFAULT 0,
-		manga_requests INTEGER DEFAULT 0,
-		audio_requests INTEGER DEFAULT 0,
-		video_requests INTEGER DEFAULT 0,
-		category_requests INTEGER DEFAULT 0,
-		updated_at INTEGER DEFAULT (strftime('%s', 'now'))
-	)`)
-	if err != nil {
-		cacheLogger.Error("创建statistics表失败: " + err.Error())
+	if err := createTables(); err != nil {
 		return err
 	}
+	return nil
+}
+
+// createTables 创建数据表（两套 DDL 各自兼容对应方言）
+func createTables() error {
+	// 通用部分：statistics 初始化、索引、audio_cache 建表在两方言间一致或按 q() 转换
+	tables := []struct{ name, sqliteDDL, pgDDL string }{
+		{"cache",
+			`CREATE TABLE IF NOT EXISTS cache (
+			key TEXT PRIMARY KEY,
+			value TEXT,
+			expi INTEGER DEFAULT 0,
+			created_at INTEGER DEFAULT (strftime('%s', 'now')),
+			updated_at INTEGER DEFAULT (strftime('%s', 'now'))
+		)`,
+			`CREATE TABLE IF NOT EXISTS cache (
+			key TEXT PRIMARY KEY,
+			value TEXT,
+			expi BIGINT DEFAULT 0,
+			created_at BIGINT DEFAULT extract(epoch FROM now())::bigint,
+			updated_at BIGINT DEFAULT extract(epoch FROM now())::bigint
+		)`},
+		{"statistics",
+			`CREATE TABLE IF NOT EXISTS statistics (
+			id INTEGER PRIMARY KEY CHECK (id = 1),
+			total_requests INTEGER DEFAULT 0,
+			search_requests INTEGER DEFAULT 0,
+			detail_requests INTEGER DEFAULT 0,
+			catalog_requests INTEGER DEFAULT 0,
+			content_requests INTEGER DEFAULT 0,
+			manga_requests INTEGER DEFAULT 0,
+			audio_requests INTEGER DEFAULT 0,
+			video_requests INTEGER DEFAULT 0,
+			category_requests INTEGER DEFAULT 0,
+			created_at INTEGER DEFAULT (strftime('%s', 'now')),
+			updated_at INTEGER DEFAULT (strftime('%s', 'now'))
+		)`,
+			`CREATE TABLE IF NOT EXISTS statistics (
+			id INTEGER PRIMARY KEY CHECK (id = 1),
+			total_requests INTEGER DEFAULT 0,
+			search_requests INTEGER DEFAULT 0,
+			detail_requests INTEGER DEFAULT 0,
+			catalog_requests INTEGER DEFAULT 0,
+			content_requests INTEGER DEFAULT 0,
+			manga_requests INTEGER DEFAULT 0,
+			audio_requests INTEGER DEFAULT 0,
+			video_requests INTEGER DEFAULT 0,
+			category_requests INTEGER DEFAULT 0,
+			created_at BIGINT DEFAULT extract(epoch FROM now())::bigint,
+			updated_at BIGINT DEFAULT extract(epoch FROM now())::bigint
+		)`},
+		{"device_pool",
+			`CREATE TABLE IF NOT EXISTS device_pool (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			device_header TEXT NOT NULL UNIQUE,
+			key TEXT NOT NULL,
+			key_ver INTEGER NOT NULL,
+			is_valid INTEGER DEFAULT 1,
+			created_at INTEGER NOT NULL,
+			last_used_at INTEGER NOT NULL,
+			updated_at INTEGER DEFAULT (strftime('%s', 'now'))
+		)`,
+			`CREATE TABLE IF NOT EXISTS device_pool (
+			id BIGSERIAL PRIMARY KEY,
+			device_header TEXT NOT NULL UNIQUE,
+			key TEXT NOT NULL,
+			key_ver INTEGER NOT NULL,
+			is_valid INTEGER DEFAULT 1,
+			created_at INTEGER NOT NULL,
+			last_used_at INTEGER NOT NULL,
+			updated_at BIGINT DEFAULT extract(epoch FROM now())::bigint
+		)`},
+		{"audio_cache",
+			`CREATE TABLE IF NOT EXISTS audio_cache (
+			key TEXT PRIMARY KEY,
+			original_url TEXT NOT NULL,
+			device_id TEXT NOT NULL,
+			headers TEXT,
+			created_at INTEGER DEFAULT (strftime('%s', 'now')),
+			updated_at INTEGER DEFAULT (strftime('%s', 'now'))
+		)`,
+			`CREATE TABLE IF NOT EXISTS audio_cache (
+			key TEXT PRIMARY KEY,
+			original_url TEXT NOT NULL,
+			device_id TEXT NOT NULL,
+			headers TEXT,
+			created_at BIGINT DEFAULT extract(epoch FROM now())::bigint,
+			updated_at BIGINT DEFAULT extract(epoch FROM now())::bigint
+		)`},
+	}
+
+	for _, t := range tables {
+		ddl := t.sqliteDDL
+		if dbDriver == "pgx" {
+			ddl = t.pgDDL
+		}
+		if _, err := cacheDB.Exec(ddl); err != nil {
+			cacheLogger.Error("创建" + t.name + "表失败: " + err.Error())
+			return err
+		}
+	}
 
 	// 初始化statistics表（如果不存在记录）
-	_, err = cacheDB.Exec(`INSERT OR IGNORE INTO statistics (id) VALUES (1)`)
-	if err != nil {
+	if _, err := cacheDB.Exec(`INSERT INTO statistics (id) VALUES (1) ON CONFLICT (id) DO NOTHING`); err != nil {
 		cacheLogger.Error("初始化statistics表失败: " + err.Error())
 	}
 
 	// 创建索引以提高清理效率
-	_, err = cacheDB.Exec(`CREATE INDEX IF NOT EXISTS idx_created_at ON cache(created_at)`)
-	if err != nil {
+	if _, err := cacheDB.Exec(`CREATE INDEX IF NOT EXISTS idx_created_at ON cache(created_at)`); err != nil {
 		cacheLogger.Error("创建索引失败: " + err.Error())
 	}
-
-	// 创建device_pool表（设备密钥池）
-	_, err = cacheDB.Exec(`CREATE TABLE IF NOT EXISTS device_pool (
-		id INTEGER PRIMARY KEY AUTOINCREMENT,
-		device_header TEXT NOT NULL,
-		key TEXT NOT NULL,
-		key_ver INTEGER NOT NULL,
-		is_valid INTEGER DEFAULT 1,
-		created_at INTEGER NOT NULL,
-		last_used_at INTEGER NOT NULL
-	)`)
-	if err != nil {
-		cacheLogger.Error("创建device_pool表失败: " + err.Error())
-		return err
-	}
-
-	// 创建device_pool索引
-	_, err = cacheDB.Exec(`CREATE INDEX IF NOT EXISTS idx_device_pool_valid ON device_pool(is_valid)`)
-	if err != nil {
+	if _, err := cacheDB.Exec(`CREATE INDEX IF NOT EXISTS idx_device_pool_valid ON device_pool(is_valid)`); err != nil {
 		cacheLogger.Warning("创建device_pool索引失败: " + err.Error())
 	}
+	// 旧库补唯一约束：表已存在时 DDL 的 UNIQUE 不会生效，用唯一索引补齐；
+	// 若存量数据已有重复 device_header 则创建失败，仅告警提示人工清理
+	if _, err := cacheDB.Exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_device_pool_header ON device_pool(device_header)`); err != nil {
+		cacheLogger.Warning("补建device_header唯一索引失败（可能存在重复设备，清理后重启即可）: " + err.Error())
+	}
 
-	// 创建audio_cache表（音频代理缓存）
-	_, err = cacheDB.Exec(`CREATE TABLE IF NOT EXISTS audio_cache (
-		key TEXT PRIMARY KEY,
-		original_url TEXT NOT NULL,
-		device_id TEXT NOT NULL,
-		headers TEXT,
-		created_at INTEGER DEFAULT (strftime('%s', 'now'))
-	)`)
-	if err != nil {
-		cacheLogger.Error("创建audio_cache表失败: " + err.Error())
-		return err
+	// 旧表补 created_at/updated_at 列（新表 DDL 自带，此处仅老库生效）
+	for _, m := range []struct{ table, col, ddl string }{
+		{"cache", "updated_at", "INTEGER DEFAULT 0"}, // SQLite ALTER 不允许非常量默认值，先补 0 再回填
+		{"cache", "expi", "INTEGER DEFAULT 0"},
+		{"statistics", "created_at", "INTEGER DEFAULT 0"},
+		{"device_pool", "updated_at", "INTEGER DEFAULT 0"},
+		{"device_pool", "key_ts", "INTEGER DEFAULT 0"},
+		{"audio_cache", "updated_at", "INTEGER DEFAULT 0"},
+	} {
+		if dbDriver == "pgx" {
+			m.ddl = "BIGINT DEFAULT 0"
+		}
+		alter := "ALTER TABLE " + m.table + " ADD COLUMN "
+		if dbDriver == "pgx" {
+			alter += "IF NOT EXISTS "
+		}
+		if _, err := cacheDB.Exec(alter + m.col + " " + m.ddl); err != nil {
+			cacheLogger.Debug("补列跳过（已存在）: " + m.table + "." + m.col)
+		}
+	}
+
+	// 旧行回填（幂等：仅 0 值行受影响）
+	for _, backfill := range []string{
+		`UPDATE cache SET updated_at = created_at WHERE updated_at = 0`,
+		`UPDATE cache SET expi = created_at + 86400 WHERE expi = 0`,
+		`UPDATE statistics SET created_at = updated_at WHERE created_at = 0`,
+		`UPDATE device_pool SET updated_at = last_used_at WHERE updated_at = 0`,
+		`UPDATE audio_cache SET updated_at = created_at WHERE updated_at = 0`,
+	} {
+		if _, err := cacheDB.Exec(backfill); err != nil {
+			cacheLogger.Warning("时间列回填失败: " + err.Error())
+		}
 	}
 
 	return nil
@@ -129,28 +325,61 @@ func InitDB() error {
 
 // isCacheEnabled 检查正文内容缓存是否启用
 func isCacheEnabled() bool {
-	cfg := config.GetConfig()
+	cfg := config.GetAppConfig()
 	if cfg == nil {
 		return false
 	}
 	return cfg.Cache.Enabled
 }
 
-// GetCache 获取正文内容缓存
+// withCache 只读接口的缓存包装：命中直接返回，miss 回源后写入（仅缓存成功响应）。
+// singleflight 合并并发 miss，同一 key 只有一个请求打上游
+// ponytail: 空参等防御分支若漏到此处，其错误 JSON 也会被缓存到 TTL 到期——handler 层 validateParams 已拦截
+func withCache(key string, ttl int, fetch func() (string, error)) (string, error) {
+	if c := GetCache(key); c != "" {
+		// 旧缓存可能存有未解包的 JSON 字符串字段，出口幂等解包
+		// （对新写入的已解包数据无影响）
+		return reencodeUnwrapped(c), nil
+	}
+	v, err, _ := cacheSF.Do(key, func() (interface{}, error) {
+		// 双重检查：等锁期间可能已被并发请求填充
+		if c := GetCache(key); c != "" {
+			return c, nil
+		}
+		result, err := fetch()
+		if err == nil {
+			UpdateCache(key, result, ttl)
+		}
+		return result, err
+	})
+	if err != nil {
+		return "", err
+	}
+	return v.(string), nil
+}
+
+// GetCache 获取缓存：Redis 热层 → SQL 持久层（命中回填 Redis）→ 未命中
 func GetCache(key string) string {
 	if !isCacheEnabled() {
 		return ""
 	}
-	
+
+	if redisCache != nil {
+		if v := redisGetCache(key); v != "" {
+			return v
+		}
+		if isVolatileCacheKey(key) {
+			return "" // 搜索/分类等动态数据不落库，Redis 未命中即回源
+		}
+	}
+
 	if cacheDB == nil {
 		return ""
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	var value string
-	err := cacheDB.QueryRow("SELECT value FROM cache WHERE key = ?", key).Scan(&value)
+	var expi int64
+	err := cacheDB.QueryRow(q("SELECT value, expi FROM cache WHERE key = ?"), key).Scan(&value, &expi)
 	if err != nil {
 		if err != sql.ErrNoRows {
 			cacheLogger.Error("查询缓存失败: " + err.Error())
@@ -158,39 +387,52 @@ func GetCache(key string) string {
 		return ""
 	}
 
+	// 检查是否过期（expi 为 0 的旧行由启动回填兜底，此处防御）
+	if time.Now().Unix() >= expi {
+		cacheLogger.Debug("缓存已过期(SQL): " + key)
+		return ""
+	}
+
 	var cacheData CacheData
-	err = json.Unmarshal([]byte(value), &cacheData)
-	if err != nil {
+	if err := json.Unmarshal([]byte(value), &cacheData); err != nil {
 		cacheLogger.Error("解析缓存数据失败: " + err.Error())
 		return ""
 	}
 
-	cacheLogger.Debug("缓存命中: " + key)
+	cacheLogger.Debug("缓存命中(SQL): " + key)
 
-	// 检查是否过期
-	if time.Now().Unix() < int64(cacheData.Expi) {
-		cacheLogger.Debug("缓存有效！")
-		return cacheData.Data
+	// SQL 命中而 Redis 未命中（过期/重启）：异步回填热层，剩余时长为 TTL，
+	// 回填（尤其大 value）不阻塞本次请求
+	if redisCache != nil {
+		remain := int(expi - time.Now().Unix())
+		if remain < 60 {
+			remain = 60
+		}
+		go redisUpdateCache(key, cacheData.Data, remain)
 	}
-
-	cacheLogger.Debug("缓存已过期！")
-	return ""
+	return cacheData.Data
 }
 
-// UpdateCache 更新缓存
-// UpdateCache 更新或插入正文内容缓存
+// UpdateCache 写入缓存：Redis 热层（TTL=业务过期时间）+ SQL 持久层双写。
+// 不可变内容在 SQL 固定保留 30 天，动态短缓存（search/category）只走 Redis。
+// Redis 写失败只降级不阻断：持久层照常落库，热层下次请求回填
 func UpdateCache(key string, value string, expi int) error {
 	if !isCacheEnabled() {
 		return nil
 	}
-	
+
+	if redisCache != nil {
+		if err := redisUpdateCache(key, value, expi); err != nil {
+			cacheLogger.Warning(fmt.Sprintf("Redis 写入失败（降级为仅 SQL 落库）: %v", err))
+		} else if isVolatileCacheKey(key) {
+			return nil // 动态短缓存不落库（Redis 成功即止）
+		}
+	}
+
 	if cacheDB == nil {
 		return nil
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	cacheData := CacheData{
 		Data: value,
 		Expi: float64(time.Now().Unix() + int64(expi)),
@@ -201,18 +443,17 @@ func UpdateCache(key string, value string, expi int) error {
 		return err
 	}
 
-	// 检查是否存在
-	var exists bool
-	err = cacheDB.QueryRow("SELECT 1 FROM cache WHERE key = ?", key).Scan(&exists)
-
-	if err == sql.ErrNoRows {
-		// 不存在，插入
-		_, err = cacheDB.Exec("INSERT INTO cache (key, value) VALUES (?, ?)", key, string(jsonData))
-	} else {
-		// 存在，更新
-		_, err = cacheDB.Exec("UPDATE cache SET value = ? WHERE key = ?", string(jsonData), key)
+	// SQL 保留时长：不可变内容固定 30 天（Redis 未启用时沿用业务 TTL，保持纯 SQL 模式原行为）
+	sqlTTL := int64(sqlCacheTTLSeconds)
+	if redisCache == nil || isVolatileCacheKey(key) {
+		sqlTTL = int64(expi)
 	}
 
+	// UPSERT：ON CONFLICT 语法 SQLite 3.24+ 与 PostgreSQL 通用
+	now := time.Now().Unix()
+	_, err = cacheDB.Exec(q(`INSERT INTO cache (key, value, expi, created_at, updated_at) VALUES (?, ?, ?, ?, ?)
+		ON CONFLICT(key) DO UPDATE SET value = excluded.value, expi = excluded.expi, updated_at = excluded.updated_at`),
+		key, string(jsonData), now+sqlTTL, now, now)
 	if err != nil {
 		cacheLogger.Error("更新缓存失败: " + err.Error())
 		return err
@@ -222,7 +463,6 @@ func UpdateCache(key string, value string, expi int) error {
 	return nil
 }
 
-
 // CloseCache 关闭缓存数据库
 func CloseCache() {
 	if cacheDB != nil {
@@ -230,25 +470,23 @@ func CloseCache() {
 	}
 }
 
-
-
-
 // CleanupAllCache 立即清理所有正文缓存
 func CleanupAllCache() error {
 	if cacheDB == nil {
 		return fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	// 删除所有缓存数据
 	_, err := cacheDB.Exec("DELETE FROM cache")
 	if err != nil {
 		return err
 	}
 
-	// 智能压缩：仅在空闲空间超过阈值时执行
+	// 智能压缩：仅在空闲空间超过阈值时执行（仅 SQLite，PG 由 autovacuum 自行管理）
+	if dbDriver == "pgx" {
+		return nil
+	}
+
 	var freelistCount int64
 	err = cacheDB.QueryRow("PRAGMA freelist_count").Scan(&freelistCount)
 	if err == nil && freelistCount > 0 {
@@ -258,7 +496,7 @@ func CleanupAllCache() error {
 			freeBytes := freelistCount * pageSize
 			// 阈值：空闲空间超过 5MB 时才执行压缩
 			const vacuumThreshold = 5 * 1024 * 1024 // 5MB
-			
+
 			if freeBytes >= vacuumThreshold {
 				cacheLogger.Info(fmt.Sprintf("空闲空间 %.2f MB，开始执行压缩...", float64(freeBytes)/(1024*1024)))
 				_, err = cacheDB.Exec("VACUUM")
@@ -278,7 +516,7 @@ func CleanupAllCache() error {
 
 // CleanupExpiredCache 清理过期的正文缓存
 func CleanupExpiredCache() error {
-	cfg := config.GetConfig()
+	cfg := config.GetAppConfig()
 	if cfg == nil {
 		return fmt.Errorf("配置未加载")
 	}
@@ -297,14 +535,8 @@ func CleanupExpiredCache() error {
 		return fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
-	// 计算过期时间点（当前时间 - cleanup_seconds）
-	expiredTime := time.Now().Unix() - int64(cfg.Cache.CleanupSeconds)
-
-	// 删除过期的缓存（created_at < expiredTime）
-	result, err := cacheDB.Exec("DELETE FROM cache WHERE created_at < ?", expiredTime)
+	// 删除已过期的缓存（按行内过期时间 expi，而非创建时间）
+	result, err := cacheDB.Exec(q("DELETE FROM cache WHERE expi < ?"), time.Now().Unix())
 	if err != nil {
 		cacheLogger.Error("清理过期缓存失败: " + err.Error())
 		return err
@@ -315,15 +547,18 @@ func CleanupExpiredCache() error {
 	if err != nil {
 		cacheLogger.Warning("获取删除行数失败: " + err.Error())
 	} else if rowsAffected > 0 {
-		cacheLogger.Info(fmt.Sprintf("已清理 %d 条过期缓存（创建时间早于 %d 秒前）", rowsAffected, cfg.Cache.CleanupSeconds))
+		cacheLogger.Info(fmt.Sprintf("已清理 %d 条过期缓存（SQL 持久层）", rowsAffected))
 	}
 
+	// 顺带清理磁盘视频缓存（7 天未访问的解密文件）
+	CleanupVideoCache()
+
 	return nil
 }
 
 // StartCacheCleanup 启动缓存自动清理任务
 func StartCacheCleanup() {
-	cfg := config.GetConfig()
+	cfg := config.GetAppConfig()
 	if cfg == nil || !cfg.Cache.CleanupEnabled || cfg.Cache.CleanupSeconds <= 0 {
 		cacheLogger.Info("缓存自动清理未启用或配置无效，跳过启动")
 		return
@@ -365,46 +600,13 @@ func StopCacheCleanup() {
 }
 
 // IncrementContentRequestCount 增加content接口访问计数
-func IncrementContentRequestCount() int {
-	countMutex.Lock()
-	defer countMutex.Unlock()
-	contentRequestCount++
-	return contentRequestCount
-}
+func IncrementContentRequestCount() int { return int(contentRequestCount.Add(1)) }
 
 // ResetContentRequestCount 重置访问计数
-func ResetContentRequestCount() {
-	countMutex.Lock()
-	defer countMutex.Unlock()
-	contentRequestCount = 0
-}
+func ResetContentRequestCount() { contentRequestCount.Store(0) }
 
 // GetContentRequestCount 获取当前访问计数
-func GetContentRequestCount() int {
-	countMutex.Lock()
-	defer countMutex.Unlock()
-	return contentRequestCount
-}
-
-// VacuumDatabase 压缩数据库，释放磁盘空间
-func VacuumDatabase() error {
-	if cacheDB == nil {
-		return fmt.Errorf("数据库未初始化")
-	}
-
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
-	cacheLogger.Info("开始执行数据库压缩...")
-	_, err := cacheDB.Exec("VACUUM")
-	if err != nil {
-		cacheLogger.Error("数据库压缩失败: " + err.Error())
-		return err
-	}
-
-	cacheLogger.Info("数据库压缩完成，磁盘空间已释放")
-	return nil
-}
+func GetContentRequestCount() int { return int(contentRequestCount.Load()) }
 
 // GetDatabaseStats 获取数据库统计信息
 func GetDatabaseStats() (map[string]interface{}, error) {
@@ -412,9 +614,6 @@ func GetDatabaseStats() (map[string]interface{}, error) {
 		return nil, fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	stats := make(map[string]interface{})
 
 	// 获取cache表记录数
@@ -426,13 +625,27 @@ func GetDatabaseStats() (map[string]interface{}, error) {
 	}
 	stats["cache_count"] = cacheCount
 
-	// 获取数据库页面统计
+	// PostgreSQL：用库大小填充，无 freelist 概念
+	if dbDriver == "pgx" {
+		var totalSize int64
+		if err := cacheDB.QueryRow("SELECT pg_database_size(current_database())").Scan(&totalSize); err == nil {
+			stats["page_count"] = int64(0)
+			stats["page_size"] = int64(0)
+			stats["freelist_count"] = int64(0)
+			stats["total_size_bytes"] = totalSize
+			stats["free_size_bytes"] = int64(0)
+			stats["used_size_bytes"] = totalSize
+		}
+		return stats, nil
+	}
+
+	// SQLite：获取数据库页面统计
 	var pageCount, pageSize, freelistCount int64
 	err = cacheDB.QueryRow("PRAGMA page_count").Scan(&pageCount)
 	if err == nil {
 		stats["page_count"] = pageCount
 	}
-	
+
 	err = cacheDB.QueryRow("PRAGMA page_size").Scan(&pageSize)
 	if err == nil {
 		stats["page_size"] = pageSize
@@ -455,11 +668,8 @@ func SaveStatistics(stats map[string]int64) error {
 		return fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
-	_, err := cacheDB.Exec(`
-		UPDATE statistics 
+	_, err := cacheDB.Exec(q(`
+		UPDATE statistics
 		SET total_requests = ?,
 			search_requests = ?,
 			detail_requests = ?,
@@ -469,11 +679,12 @@ func SaveStatistics(stats map[string]int64) error {
 			audio_requests = ?,
 			video_requests = ?,
 			category_requests = ?,
-			updated_at = strftime('%s', 'now')
+			updated_at = ?
 		WHERE id = 1
-	`, stats["total"], stats["search"], stats["detail"], stats["catalog"],
-		stats["content"], stats["manga"], stats["audio"], stats["video"], stats["category"])
-	
+	`), stats["total"], stats["search"], stats["detail"], stats["catalog"],
+		stats["content"], stats["manga"], stats["audio"], stats["video"], stats["category"],
+		time.Now().Unix())
+
 	if err != nil {
 		cacheLogger.Error("保存统计数据失败: " + err.Error())
 		return err
@@ -488,17 +699,14 @@ func LoadStatistics() (map[string]int64, error) {
 		return nil, fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	var total, search, detail, catalog, content, manga, audio, video, category int64
-	
+
 	err := cacheDB.QueryRow(`
 		SELECT total_requests, search_requests, detail_requests, catalog_requests,
 			   content_requests, manga_requests, audio_requests, video_requests, category_requests
 		FROM statistics WHERE id = 1
 	`).Scan(&total, &search, &detail, &catalog, &content, &manga, &audio, &video, &category)
-	
+
 	if err == sql.ErrNoRows {
 		// 没有数据，返回空统计
 		return map[string]int64{
@@ -506,7 +714,7 @@ func LoadStatistics() (map[string]int64, error) {
 			"content": 0, "manga": 0, "audio": 0, "video": 0, "category": 0,
 		}, nil
 	}
-	
+
 	if err != nil {
 		cacheLogger.Error("加载统计数据失败: " + err.Error())
 		return nil, err
@@ -525,4 +733,4 @@ func LoadStatistics() (map[string]int64, error) {
 	}
 
 	return stats, nil
-}
+}

internal/fqapi/cache_manager_test.go

@@ -0,0 +1,104 @@
+package fqapi
+
+import (
+	"database/sql"
+	"fanqie/internal/config"
+	"fmt"
+	"sync"
+	"testing"
+
+	_ "github.com/mattn/go-sqlite3"
+)
+
+// TestConcurrentCacheAccess 验证删除全局串行锁后并发读写缓存不死锁、不 panic、数据正确（配合 -race）
+func TestConcurrentCacheAccess(t *testing.T) {
+	if err := config.LoadConfig("../../config/config.yaml"); err != nil {
+		t.Skipf("无法加载配置: %v", err)
+	}
+
+	db, err := sql.Open("sqlite3", t.TempDir()+"/test.db?_journal_mode=WAL&_busy_timeout=5000")
+	if err != nil {
+		t.Fatal(err)
+	}
+	oldDB, oldDriver := cacheDB, dbDriver
+	cacheDB, dbDriver = db, "sqlite3"
+	defer func() {
+		cacheDB, dbDriver = oldDB, oldDriver
+		db.Close()
+	}()
+
+	if _, err := db.Exec(`CREATE TABLE IF NOT EXISTS cache (
+		key TEXT PRIMARY KEY,
+		value TEXT,
+		expi INTEGER DEFAULT 0,
+		created_at INTEGER DEFAULT (strftime('%s', 'now')),
+		updated_at INTEGER DEFAULT (strftime('%s', 'now'))
+	)`); err != nil {
+		t.Fatal(err)
+	}
+
+	var wg sync.WaitGroup
+	for i := 0; i < 8; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			for j := 0; j < 30; j++ {
+				key := fmt.Sprintf("k-%d-%d", i, j)
+				if err := UpdateCache(key, "value-"+key, 60); err != nil {
+					t.Errorf("UpdateCache(%s): %v", key, err)
+					return
+				}
+				if got := GetCache(key); got != "value-"+key {
+					t.Errorf("GetCache(%s) = %q, want %q", key, got, "value-"+key)
+					return
+				}
+			}
+		}(i)
+	}
+	wg.Wait()
+}
+
+// TestWithCache 验证缓存命中不回源、失败响应不缓存
+func TestWithCache(t *testing.T) {
+	if err := config.LoadConfig("../../config/config.yaml"); err != nil {
+		t.Skipf("无法加载配置: %v", err)
+	}
+	db, err := sql.Open("sqlite3", t.TempDir()+"/test.db?_journal_mode=WAL&_busy_timeout=5000")
+	if err != nil {
+		t.Fatal(err)
+	}
+	oldDB, oldDriver := cacheDB, dbDriver
+	cacheDB, dbDriver = db, "sqlite3"
+	defer func() {
+		cacheDB, dbDriver = oldDB, oldDriver
+		db.Close()
+	}()
+	if _, err := db.Exec(`CREATE TABLE IF NOT EXISTS cache (
+		key TEXT PRIMARY KEY, value TEXT,
+		expi INTEGER DEFAULT 0,
+		created_at INTEGER DEFAULT (strftime('%s', 'now')),
+		updated_at INTEGER DEFAULT (strftime('%s', 'now'))
+	)`); err != nil {
+		t.Fatal(err)
+	}
+
+	calls := 0
+	fetch := func() (string, error) { calls++; return "result", nil }
+	if got, _ := withCache("wc_hit", 60, fetch); got != "result" {
+		t.Fatalf("首次应返回回源结果, got %q", got)
+	}
+	if got, _ := withCache("wc_hit", 60, fetch); got != "result" {
+		t.Fatalf("命中应返回缓存结果, got %q", got)
+	}
+	if calls != 1 {
+		t.Fatalf("命中缓存不应回源, fetch 调用 %d 次", calls)
+	}
+
+	errCalls := 0
+	errFetch := func() (string, error) { errCalls++; return "", fmt.Errorf("boom") }
+	withCache("wc_miss", 60, errFetch)
+	withCache("wc_miss", 60, errFetch)
+	if errCalls != 2 {
+		t.Fatalf("失败响应不应被缓存, fetch 调用 %d 次", errCalls)
+	}
+}

internal/fqapi/catalog.go

@@ -10,8 +10,14 @@ import (
 
 var catalogLogger = common.NewLogger("catalog", "INFO", "")
 
-// HandleGetCatalog 处理获取书籍目录
+// HandleGetCatalog 处理获取书籍目录,目录数据基本不变,缓存 24 小时
 func HandleGetCatalog(bookID string) (string, error) {
+	return withCache("catalog_"+bookID, 86400, func() (string, error) {
+		return fetchCatalog(bookID)
+	})
+}
+
+func fetchCatalog(bookID string) (string, error) {
 	if bookID == "" {
 		return BuildErrorResponse("需要参数 book_id"), nil
 	}
@@ -46,8 +52,8 @@ func HandleGetCatalog(bookID string) (string, error) {
 			delete(data, "catalog_data")
 		}
 
-		// 重新序列化
-		resultBytes, err := json.Marshal(respJSON)
+		// 重新序列化（解包 JSON 字符串字段）
+		resultBytes, err := json.Marshal(UnwrapJSONStrings(respJSON))
 		if err != nil {
 			return BuildErrorResponse("序列化失败"), err
 		}
@@ -124,8 +130,7 @@ func offShelfCatalog(bookID string) (string, error) {
 		},
 	}
 
-	resultBytes, _ := json.Marshal(response)
-	return string(resultBytes), nil
+	return marshalNoEscape(UnwrapJSONStrings(response)), nil
 }
 
 // itemMultiDetail 批量获取章节详情
@@ -204,4 +209,3 @@ func itemMultiDetail(itemList []string) ([]map[string]interface{}, error) {
 
 	return nil, fmt.Errorf("请求失败")
 }
-

internal/fqapi/category_front.go

@@ -7,14 +7,23 @@ import (
 
 var categoryFrontLogger = common.NewLogger("category_front", "INFO", "")
 
-// HandleCategoryFront 处理获取分类列表
+// HandleCategoryFront 处理获取分类列表,分类列表短缓存 10 分钟
 func HandleCategoryFront(tab interface{}) (string, error) {
+	return withCache(fmt.Sprintf("category_front_%v", tab), 600, func() (string, error) {
+		return fetchCategoryFront(tab)
+	})
+}
+
+func fetchCategoryFront(tab interface{}) (string, error) {
 	tabInt := ParseIntParam(tab, 0)
 
+	// 新版分类接口参数（category_new_page_715=1 + new_category_type，
+	// 旧参数 new_category_tab 已失效——对齐 2026-10 可用的书源实现）
 	reqURL := BuildURL(
 		"https://reading.snssdk.com/reading/bookapi/new_category/front/v/",
-		fmt.Sprintf("new_category_tab=%d", tabInt),
-		fmt.Sprintf("update_version_code=%s", "58932"),
+		"category_new_page_715=1",
+		fmt.Sprintf("new_category_type=%d", tabInt),
+		"update_version_code=" + ClientVersionCode,
 		"distinct_style=1",
 	)
 
@@ -36,9 +45,8 @@ func HandleCategoryFront(tab interface{}) (string, error) {
 	}
 
 	if code, ok := respJSON["code"].(float64); ok && code == 0 {
-		return resp.Text, nil
+		return reencodeUnwrapped(resp.Text), nil
 	}
 
 	return BuildErrorResponse("获取失败"), nil
 }
-

internal/fqapi/category_landing.go

@@ -7,27 +7,55 @@ import (
 
 var categoryLandingLogger = common.NewLogger("category_landing", "INFO", "")
 
-// HandleCategoryLanding 处理获取分类详情
-func HandleCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy interface{}) (string, error) {
+// HandleCategoryLanding 处理获取分类详情,分类详情短缓存 10 分钟
+// selectedItems：新版分类标签自带的筛选项（selected_items，透传上游）
+func HandleCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy, selectedItems interface{}) (string, error) {
+	return withCache(fmt.Sprintf("category_landing_%v_%v_%v_%v_%v_%v", categoryID, offset, wordNumber, bookStatus, sortBy, selectedItems), 600, func() (string, error) {
+		return fetchCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy, selectedItems)
+	})
+}
+
+func fetchCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy, selectedItems interface{}) (string, error) {
 	// 参数转换
 	categoryIDInt := ParseIntParam(categoryID, 0)
 	offsetInt := ParseIntParam(offset, 0)
 	wordNumberInt := ParseIntParam(wordNumber, 0)
 	bookStatusInt := ParseIntParam(bookStatus, 0)
 	sortByInt := ParseIntParam(sortBy, 0)
+	selectedItemsStr := ParseStringParam(selectedItems, "")
 
-	if categoryIDInt == 0 {
+	if categoryIDInt == 0 && selectedItemsStr == "" {
 		return BuildErrorResponseWithCode(100144, "参数错误"), nil
 	}
 
+	params := []string{
+		fmt.Sprintf("limit=%d", 20),
+		fmt.Sprintf("offset=%d", offsetInt),
+	}
+	if categoryIDInt != 0 {
+		params = append(params, fmt.Sprintf("category_id=%d", categoryIDInt))
+	}
+	if wordNumberInt != 0 {
+		params = append(params, fmt.Sprintf("word_number=%d", wordNumberInt))
+	}
+	if bookStatusInt != 0 {
+		params = append(params, fmt.Sprintf("book_status=%d", bookStatusInt))
+	}
+	if sortByInt != 0 {
+		params = append(params, fmt.Sprintf("sort_by=%d", sortByInt))
+	}
+	// 新版分类标签：selected_items 由 front 页标签自带，需与其 from_front_page 配对透传
+	if selectedItemsStr != "" {
+		params = append(params,
+			"selected_items="+selectedItemsStr,
+			"selected_item_from_front_page="+selectedItemsStr,
+			"source=front_category",
+		)
+	}
+
 	reqURL := BuildURL(
 		"https://reading.snssdk.com/reading/bookapi/new_category/landing/v/",
-		fmt.Sprintf("category_id=%d", categoryIDInt),
-		fmt.Sprintf("limit=%d", 20),
-		fmt.Sprintf("offset=%d", offsetInt),
-		fmt.Sprintf("word_number=%d", wordNumberInt),
-		fmt.Sprintf("book_status=%d", bookStatusInt),
-		fmt.Sprintf("sort_by=%d", sortByInt),
+		params...,
 	)
 
 	resp, err := GorgonRequest(reqURL, map[string]interface{}{
@@ -48,9 +76,8 @@ func HandleCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy in
 	}
 
 	if code, ok := respJSON["code"].(float64); ok && code == 0 {
-		return resp.Text, nil
+		return reencodeUnwrapped(resp.Text), nil
 	}
 
 	return BuildErrorResponse("获取失败"), nil
 }
-

internal/fqapi/content.go

@@ -5,12 +5,14 @@ import (
 	"encoding/json"
 	"fanqie/internal/common"
 	"fmt"
-	"sort"
 	"strings"
+
+	"golang.org/x/sync/singleflight"
 )
 
 var (
 	contentLogger = common.NewLogger("content", "INFO", "")
+	contentSF     singleflight.Group // 合并同一章节的并发回源请求，防缓存击穿
 )
 
 // ContentFetcher 内容获取器
@@ -22,23 +24,31 @@ func HandleGetContent(itemID string, textMode, imageMode interface{}) (string, e
 		return `{"code": -1, "msg": "需要参数 item_id"}`, nil
 	}
 
-	// 参数转换
-	textModeBool := parseBoolParam(textMode)
-	imageModeBool := parseBoolParamDefault(imageMode, true)
+	// 参数转换（URL 参数优先，未传时回退配置）
+	textModeBool := parseBoolParamDefault(textMode, getContentConfig().RemoveHTMLTags)
+	imageModeBool := parseBoolParamDefault(imageMode, !getContentConfig().RemoveImages)
 
-	// contentLogger.Info(fmt.Sprintf("获取内容 item_id=%s text_mode=%v image_mode=%v", itemID, textModeBool, imageModeBool))
-
-	// 检查缓存
 	cache := GetCache("content_" + itemID)
-	if cache != "" {
-		return processCachedContent(cache, textModeBool, imageModeBool)
+	if cache == "" {
+		// 同一章节并发请求只打一次上游，其余等待共享结果
+		v, err, _ := contentSF.Do("content_"+itemID, func() (interface{}, error) {
+			// 双重检查：等锁期间可能已被并发请求填充
+			if c := GetCache("content_" + itemID); c != "" {
+				return c, nil
+			}
+			return fetchContentFromAPI(itemID)
+		})
+		if err != nil {
+			return "", err
+		}
+		cache = v.(string)
 	}
 
-	// 缓存未命中，从API获取
-	return fetchContentFromAPI(itemID, textModeBool, imageModeBool)
+	// 出口按各自参数解析（缓存/回源共用同一路径）
+	return processCachedContent(cache, textModeBool, imageModeBool)
 }
 
-// processCachedContent 处理缓存内容
+// processCachedContent 处理缓存内容（content 为解密后的原始正文）
 func processCachedContent(cache string, textMode, imageMode bool) (string, error) {
 	var d map[string]interface{}
 	json.Unmarshal([]byte(cache), &d)
@@ -50,23 +60,23 @@ func processCachedContent(cache string, textMode, imageMode bool) (string, error
 		}
 	}
 
-	return buildJSONResponse(d), nil
+	return buildJSONResponse(UnwrapJSONStrings(d)), nil
 }
 
-// fetchContentFromAPI 从API获取内容（带设备切换重试）
-func fetchContentFromAPI(itemID string, textMode, imageMode bool) (string, error) {
-	return fetchContentWithRetry(itemID, textMode, imageMode, 0)
+// fetchContentFromAPI 从API获取内容（带设备切换重试），返回缓存格式 JSON
+func fetchContentFromAPI(itemID string) (string, error) {
+	return fetchContentWithRetry(itemID, 0)
 }
 
 // fetchContentWithRetry 从API获取内容，支持设备切换重试
-func fetchContentWithRetry(itemID string, textMode, imageMode bool, retryCount int) (string, error) {
+func fetchContentWithRetry(itemID string, retryCount int) (string, error) {
 	// 防止无限递归
 	const maxRetries = 5
 	if retryCount >= maxRetries {
 		contentLogger.Warning(fmt.Sprintf("已重试 %d 次，尝试备用接口", maxRetries))
-		return tryBackupAPI(itemID, textMode, imageMode)
+		return tryBackupAPI(itemID)
 	}
-	
+
 	// 从设备密钥池获取设备
 	pool := GetDeviceKeyPool()
 	item, err := pool.GetNext()
@@ -74,11 +84,12 @@ func fetchContentWithRetry(itemID string, textMode, imageMode bool, retryCount i
 		contentLogger.Error("从设备池获取设备失败: " + err.Error())
 		return `{"code": -1, "msg": "设备池暂无可用设备"}`, err
 	}
-	
+
 	header := item.DeviceHeader
 	currentKeyInfo := &KeyInfo{
 		Key: item.Key,
 		Ver: item.KeyVer,
+		Ts:  item.KeyTs,
 	}
 	contentLogger.Debug(fmt.Sprintf("使用池中设备 ID=%d (重试次数: %d)", item.ID, retryCount))
 
@@ -90,16 +101,13 @@ func fetchContentWithRetry(itemID string, textMode, imageMode bool, retryCount i
 		"app_name=novelapp",
 		"channel=0",
 		"device_platform=android",
-		"version_code=66.9",
+		"version_code=" + ClientVersionCode,
 		"item_id=" + itemID,
 		"os_version=0",
+		fmt.Sprintf("key_register_ts=%d", currentKeyInfo.Ts), // 降低上游密钥不匹配概率
 		headerWithoutVersion,
 	}
-
-	allParams := strings.Join(params, "&")
-	paramList := strings.Split(allParams, "&")
-	sort.Strings(paramList)
-	sortedParams := strings.Join(paramList, "&")
+	sortedParams := buildSortedQuery(params...)
 
 	url := "https://reading.snssdk.com/reading/reader/full/v/?" + sortedParams
 
@@ -114,7 +122,7 @@ func fetchContentWithRetry(itemID string, textMode, imageMode bool, retryCount i
 		contentLogger.Warning(fmt.Sprintf("主接口请求出错，标记设备无效并切换设备: %v", err))
 		pool.MarkInvalid(header)
 		pool.RemoveInvalid()
-		return fetchContentWithRetry(itemID, textMode, imageMode, retryCount+1)
+		return fetchContentWithRetry(itemID, retryCount+1)
 	}
 
 	var body map[string]interface{}
@@ -126,7 +134,7 @@ func fetchContentWithRetry(itemID string, textMode, imageMode bool, retryCount i
 			contentLogger.Warning("响应data字段无效，切换设备重试")
 			pool.MarkInvalid(header)
 			pool.RemoveInvalid()
-			return fetchContentWithRetry(itemID, textMode, imageMode, retryCount+1)
+			return fetchContentWithRetry(itemID, retryCount+1)
 		}
 
 		contentEncoded, ok := data["content"].(string)
@@ -135,76 +143,101 @@ func fetchContentWithRetry(itemID string, textMode, imageMode bool, retryCount i
 			contentLogger.Warning(fmt.Sprintf("内容返回 Invalid，标记设备无效并切换设备 (重试: %d)", retryCount))
 			pool.MarkInvalid(header)
 			pool.RemoveInvalid()
-			return fetchContentWithRetry(itemID, textMode, imageMode, retryCount+1)
+			return fetchContentWithRetry(itemID, retryCount+1)
 		}
 
 		// 检查密钥版本
 		keyVersion, _ := data["key_version"].(float64)
-		if currentKeyInfo != nil && int(keyVersion) != currentKeyInfo.Ver {
+		if int(keyVersion) != currentKeyInfo.Ver {
 			contentLogger.Warning("密钥版本不匹配，重新获取密钥")
-			
+
 			// 更新池中的密钥
 			newKeyInfo, err := GetKey(header)
 			if err == nil {
-				UpdateKeyInPool(header, newKeyInfo.Key, newKeyInfo.Ver)
+				UpdateKeyInPool(header, newKeyInfo)
 				currentKeyInfo = newKeyInfo
 			} else {
 				// 获取密钥失败，切换设备
 				contentLogger.Warning("获取密钥失败，切换设备重试")
 				pool.MarkInvalid(header)
 				pool.RemoveInvalid()
-				return fetchContentWithRetry(itemID, textMode, imageMode, retryCount+1)
+				return fetchContentWithRetry(itemID, retryCount+1)
 			}
 		}
 
-		// 解密内容
-		contentBytes, _ := base64.StdEncoding.DecodeString(contentEncoded)
-		if len(contentBytes) < 16 {
-			contentLogger.Warning("内容长度不足，切换设备重试")
-			pool.MarkInvalid(header)
-			pool.RemoveInvalid()
-			return fetchContentWithRetry(itemID, textMode, imageMode, retryCount+1)
-		}
-
-		iv := contentBytes[0:16]
-		encryptedData := contentBytes[16:]
-
-		keyBytes, _ := base64.StdEncoding.DecodeString(currentKeyInfo.Key)
-		decrypted, err := De(encryptedData, keyBytes, iv)
+		contentStr, err := decodeContentBody(data, currentKeyInfo)
 		if err != nil {
 			contentLogger.Warning(fmt.Sprintf("解密失败，切换设备重试: %v", err))
 			pool.MarkInvalid(header)
 			pool.RemoveInvalid()
-			return fetchContentWithRetry(itemID, textMode, imageMode, retryCount+1)
+			return fetchContentWithRetry(itemID, retryCount+1)
 		}
 
-		// 处理内容
-		contentStr := string(decrypted)
-		contentStr = strings.Replace(contentStr, `<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>`, "", -1)
+		contentStr = strings.ReplaceAll(contentStr, `<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?>`, "")
 		contentStr = strings.TrimSpace(contentStr)
 
 		data["content"] = contentStr
 
-		// 更新缓存
-		cacheData := buildCacheData(data)
-		saveCacheJSON("content_"+itemID, cacheData, 86400*2)
-
-		// 解析内容
-		parser := NewContentParser()
-		data["content"] = parser.Parse(contentStr, textMode, imageMode)
-
-		return buildJSONResponse(body), nil
+		// 写缓存并返回缓存格式（按参数的解析统一放在出口 processCachedContent）
+		cacheStr := marshalNoEscape(buildCacheData(UnwrapJSONStrings(data)))
+		UpdateCache("content_"+itemID, cacheStr, 86400)
+		return cacheStr, nil
 	}
 
 	// 响应code不为0，切换设备重试
 	contentLogger.Warning(fmt.Sprintf("响应code异常: %.0f，切换设备重试", body["code"]))
 	pool.MarkInvalid(header)
 	pool.RemoveInvalid()
-	return fetchContentWithRetry(itemID, textMode, imageMode, retryCount+1)
+	return fetchContentWithRetry(itemID, retryCount+1)
 }
 
-// tryBackupAPI 尝试备用API（所有设备都失败后的最后手段）
-func tryBackupAPI(itemID string, textMode, imageMode bool) (string, error) {
+// decodeContentBody 按上游 crypt_status 解出正文：
+//   - 0：base64 密文，设备密钥 AES-CBC 解密（compress_status!=0 时解压）
+//   - 1：明文（可能压缩）
+//   - 2：密钥已失效，刷新密钥后由调用方重试
+func decodeContentBody(data map[string]interface{}, keyInfo *KeyInfo) (string, error) {
+	contentEncoded, _ := data["content"].(string)
+	cryptStatus, _ := data["crypt_status"].(float64)
+	compressStatus, _ := data["compress_status"].(float64)
+
+	switch int(cryptStatus) {
+	case 1:
+		if compressStatus != 0 {
+			return string(gunzipMaybe([]byte(contentEncoded))), nil
+		}
+		return contentEncoded, nil
+
+	case 2:
+		return "", fmt.Errorf("密钥已失效（crypt_status=2），需刷新密钥重试")
+
+	default:
+		// 500003 场景（设备无需解密）仍下发密文时按明文兜底
+		if keyInfo == nil || keyInfo.Key == "" {
+			return contentEncoded, nil
+		}
+
+		contentBytes, err := base64.StdEncoding.DecodeString(contentEncoded)
+		if err != nil || len(contentBytes) < 16 {
+			return "", fmt.Errorf("内容密文长度异常")
+		}
+
+		iv := contentBytes[0:16]
+		encryptedData := contentBytes[16:]
+
+		keyBytes, _ := base64.StdEncoding.DecodeString(keyInfo.Key)
+		decrypted, err := De(encryptedData, keyBytes, iv)
+		if err != nil {
+			return "", err
+		}
+		if compressStatus != 0 {
+			decrypted = gunzipMaybe(decrypted)
+		}
+		return string(decrypted), nil
+	}
+}
+
+// tryBackupAPI 尝试备用API（所有设备都失败后的最后手段），返回缓存格式 JSON
+func tryBackupAPI(itemID string) (string, error) {
 	contentLogger.Warning("尝试备用接口1（所有设备均失败）")
 
 	// 从设备池获取任意一个有效设备用于备用接口
@@ -217,8 +250,8 @@ func tryBackupAPI(itemID string, textMode, imageMode bool) (string, error) {
 	header := item.DeviceHeader
 
 	// 备用接口1：使用DH加密
-	backupAPI := fmt.Sprintf("https://novel.snssdk.com/api/novel/book/reader/content/v1?support_image=1&item_id=%s&aid=1319&app_name=novelapp&channel=0&device_platform=android&os_version=2&version_code=58932&%s",
-		itemID, header)
+	backupAPI := fmt.Sprintf("https://novel.snssdk.com/api/novel/book/reader/content/v1?support_image=1&item_id=%s&aid=1319&app_name=novelapp&channel=0&device_platform=android&os_version=2&version_code=%s&%s",
+		itemID, ClientVersionCode, header)
 
 	cm := NewCM()
 	resp, err := GorgonRequest(backupAPI, map[string]interface{}{
@@ -259,21 +292,16 @@ func tryBackupAPI(itemID string, textMode, imageMode bool) (string, error) {
 			contentLogger.Error("解密失败: " + err.Error())
 			return `{"code": -1, "msg": "解密失败"}`, err
 		}
+		decryptedContent = string(gunzipMaybe([]byte(decryptedContent)))
 
-		data["content"] = decryptedContent
+		data["content"] = strings.TrimSpace(decryptedContent)
 
-		// 更新缓存
-		bodyJSONStr := buildJSONResponse(body)
-		UpdateCache("content_"+itemID, bodyJSONStr, 86400)
-
-		// 解析内容
-		parser := NewContentParser()
-		data["content"] = parser.Parse(decryptedContent, textMode, imageMode)
-
-		return buildJSONResponse(body), nil
+		// 写缓存并返回缓存格式
+		cacheStr := marshalNoEscape(buildCacheData(UnwrapJSONStrings(data)))
+		UpdateCache("content_"+itemID, cacheStr, 86400)
+		return cacheStr, nil
 	}
 
 	contentLogger.Warning("备用接口1获取正文出错！")
 	return `{"code": -1, "msg": "获取失败"}`, fmt.Errorf("所有接口都失败")
 }
-

internal/fqapi/content_parser.go

@@ -9,11 +9,24 @@ import (
 	"github.com/PuerkitoBio/goquery"
 )
 
+// imgSrcRe 匹配 img 标签的 src 属性
+var imgSrcRe = regexp.MustCompile(`(?i)(<img[^>]*\ssrc=")([^"]*)(")`)
+
+// permanentizeImgSrc 将正文插图链接替换为永久 CDN 链接（原链接带临时参数会过期）
+func permanentizeImgSrc(html string) string {
+	return imgSrcRe.ReplaceAllStringFunc(html, func(m string) string {
+		parts := imgSrcRe.FindStringSubmatch(m)
+		if len(parts) < 3 || parts[2] == "" {
+			return m
+		}
+		return parts[1] + NormalizeNovelImageURL(parts[2]) + parts[3]
+	})
+}
+
 var (
 	parserLogger = common.NewLogger("content_parser", "INFO", "")
 )
 
-
 // ContentParser 内容解析器
 type ContentParser struct {
 	cfg config.ContentConfig
@@ -41,15 +54,15 @@ func (p *ContentParser) Parse(content string, textMode bool, imageMode bool) str
 		content = p.removeImageDesc(content)
 	}
 
-	// 4. 根据参数或配置移除图片
-	// URL参数 image_mode=0 或配置 remove_images=true 时移除图片
-	if !imageMode || p.cfg.RemoveImages {
+	// 4. 根据参数移除图片
+	// imageMode=false 时移除（URL 参数与配置 remove_images 已在调用方合成：URL 优先）
+	if !imageMode {
 		content = p.removeImages(content)
 	}
 
-	// 5. 根据参数或配置处理内容模式
-	// URL参数 text_mode=1 或配置 remove_html_tags=true 时使用文本模式
-	if textMode || p.cfg.RemoveHTMLTags {
+	// 5. 根据参数处理内容模式
+	// textMode=true 时提取纯文本（URL 参数与配置 remove_html_tags 已在调用方合成：URL 优先）
+	if textMode {
 		return p.extractText(content)
 	}
 
@@ -119,6 +132,8 @@ func (p *ContentParser) extractText(content string) string {
 				divHTML = decodeHTMLEntities(divHTML)
 				// 标准化img属性
 				divHTML = normalizeImgAttributes(divHTML)
+				// 插图链接永久化
+				divHTML = permanentizeImgSrc(divHTML)
 				finalResult = append(finalResult, divHTML)
 			}
 			return
@@ -143,13 +158,13 @@ func (p *ContentParser) extractText(content string) string {
 
 	// 拼接结果
 	var result string
-	
+
 	// 根据配置决定段落间的换行符
 	separator := "\n"
 	if p.cfg.DoubleNewline {
 		separator = "\n\n"
 	}
-	
+
 	if p.cfg.AddParagraphIndent && len(finalResult) > 0 {
 		// 添加段落缩进（两个全角空格）
 		result = "\u3000\u3000" + strings.Join(finalResult, separator+"\u3000\u3000")
@@ -170,10 +185,13 @@ func (p *ContentParser) extractText(content string) string {
 func (p *ContentParser) processHTMLMode(content string) string {
 	// 标准化img属性
 	content = normalizeImgAttributes(content)
-	
+
 	// 解码HTML实体
 	content = decodeHTMLEntities(content)
-	
+
+	// 插图链接永久化（原链接带临时参数会过期）
+	content = permanentizeImgSrc(content)
+
 	// 根据配置决定是否移除空行
 	if p.cfg.RemoveBlankLines {
 		// 对HTML内容移除空的<p>标签
@@ -184,4 +202,3 @@ func (p *ContentParser) processHTMLMode(content string) string {
 
 	return content
 }
-

internal/fqapi/content_utils.go

@@ -1,12 +1,85 @@
 package fqapi
 
 import (
+	"bytes"
+	"compress/gzip"
+	"compress/zlib"
 	"encoding/json"
 	"fanqie/internal/config"
-	"sort"
+	"io"
+	"net/url"
+	"regexp"
 	"strings"
 )
 
+// 客户端版本统一（与 2026-10 可用的书源实现一致；旧值 58932/5.8.9.32 混用易触发风控）
+const (
+	ClientVersionCode = "72732"
+	ClientVersionName = "7.2.7.32"
+)
+
+// PermanentNovelImgHost 番茄小说图片的永久 CDN 域名（原始链接带临时参数会过期失效）
+const PermanentNovelImgHost = "https://p6-novel.byteimg.com"
+
+// novelPicMd5Re 匹配图片路径中的 32 位十六进制资源 ID
+var novelPicMd5Re = regexp.MustCompile(`^/novel-pic/([a-f0-9]{32})`)
+
+// NormalizeNovelImageURL 将临时图片链接永久化：
+//   - /novel-pic/{md5} → p6-novel.byteimg.com/origin/novel-pic/{md5}（正文插图原图）
+//   - 含 ~tplv 的模板图（封面缩放）→ p6-novel.byteimg.com 保留原路径
+func NormalizeNovelImageURL(raw string) string {
+	u := strings.TrimSpace(strings.ReplaceAll(raw, "&", "&"))
+	if u == "" {
+		return ""
+	}
+	if strings.HasPrefix(u, "//") {
+		u = "https:" + u
+	}
+	idx := strings.Index(u, "/novel-pic/")
+	if idx < 0 {
+		return u
+	}
+	path := u[idx:]
+	if m := novelPicMd5Re.FindStringSubmatch(path); m != nil && !strings.Contains(path, "~tplv") {
+		return PermanentNovelImgHost + "/origin/novel-pic/" + m[1]
+	}
+	return PermanentNovelImgHost + path
+}
+
+// gunzipMaybe 自适应解压上游正文（gzip 与 zlib 帧都可能出现），非压缩数据原样返回
+func gunzipMaybe(data []byte) []byte {
+	if r, err := gzip.NewReader(bytes.NewReader(data)); err == nil {
+		if out, err2 := io.ReadAll(r); err2 == nil {
+			r.Close()
+			return out
+		}
+	}
+	if r, err := zlib.NewReader(bytes.NewReader(data)); err == nil {
+		if out, err2 := io.ReadAll(r); err2 == nil {
+			r.Close()
+			return out
+		}
+	}
+	return data
+}
+
+// buildSortedQuery 将若干 "k=v" 段合并为 form 编码的查询串（按键排序）。
+// 设备机型等值含空格时必须编码，否则实际请求的 URL 与签名输入不一致，
+// registerkey 等接口会注册失败（书源 2026-10-10 修复的同类问题）
+func buildSortedQuery(parts ...string) string {
+	vals := url.Values{}
+	for _, part := range parts {
+		for _, seg := range strings.Split(part, "&") {
+			if seg == "" {
+				continue
+			}
+			k, v, _ := strings.Cut(seg, "=")
+			vals.Add(k, v)
+		}
+	}
+	return vals.Encode()
+}
+
 // getContentConfig 获取内容配置（带默认值）
 func getContentConfig() config.ContentConfig {
 	if config.GetAppConfig() != nil {
@@ -57,20 +130,25 @@ func removeBlankLines(content string) string {
 	for strings.Contains(content, "\n\n\n") {
 		content = strings.ReplaceAll(content, "\n\n\n", "\n\n")
 	}
-	
+
 	// 移除首尾的空白
 	content = strings.TrimSpace(content)
-	
+
 	return content
 }
 
 // ============ 参数解析工具函数 ============
 
-// parseBoolParam 解析布尔参数
-func parseBoolParam(param interface{}) bool {
+// ParseBoolParam 解析布尔参数，支持 1/0、true/false 及语义别名
+// text_mode: plain(纯文本)=true / html=false
+// image_mode、review: keep(保留/启用)=true / remove(移除/禁用)=false
+func ParseBoolParam(param interface{}) bool {
 	switch v := param.(type) {
 	case string:
-		return v == "true" || v == "1" || strings.ToLower(v) == "true"
+		switch strings.ToLower(v) {
+		case "1", "true", "plain", "keep":
+			return true
+		}
 	case bool:
 		return v
 	}
@@ -82,7 +160,7 @@ func parseBoolParamDefault(param interface{}, defaultVal bool) bool {
 	if param == nil || param == "" {
 		return defaultVal
 	}
-	return parseBoolParam(param)
+	return ParseBoolParam(param)
 }
 
 // ============ JSON 处理工具函数 ============
@@ -100,6 +178,78 @@ func buildJSONResponse(data interface{}) string {
 	return escapeJSON(string(resultBytes))
 }
 
+// marshalNoEscape 序列化 JSON 时不做 HTML 转义。
+// json.Marshal 默认把 URL 中的 & < > 转义为 & 等,直接从响应文本复制
+// URL 到浏览器会因字面转义序列打不开;含播放/下载链接的响应用本函数
+func marshalNoEscape(v interface{}) string {
+	var buf bytes.Buffer
+	enc := json.NewEncoder(&buf)
+	enc.SetEscapeHTML(false)
+	if err := enc.Encode(v); err != nil {
+		return "{}"
+	}
+	return strings.TrimSuffix(buf.String(), "\n")
+}
+
+// UnwrapJSONStrings 递归解包字符串形式的 JSON 值。上游常把对象/数组
+// 双重编码为字符串(如 category_schema: "[{\"category_id\":718,...}]"),
+// 本函数将其还原为真正的对象/数组。仅处理以 { 或 [ 开头且能完整解析
+// 为 object/array 的字符串,普通文本与数字字符串不受影响;嵌套解析使用
+// UseNumber,大整数 ID 不丢精度。
+func UnwrapJSONStrings(v interface{}) interface{} {
+	switch t := v.(type) {
+	case map[string]interface{}:
+		for k, val := range t {
+			t[k] = UnwrapJSONStrings(val)
+		}
+		return t
+	case []interface{}:
+		for i, val := range t {
+			t[i] = UnwrapJSONStrings(val)
+		}
+		return t
+	case []map[string]interface{}:
+		for i, val := range t {
+			t[i] = UnwrapJSONStrings(val).(map[string]interface{})
+		}
+		return t
+	case map[string]map[string]interface{}:
+		m := make(map[string]interface{}, len(t))
+		for k, val := range t {
+			m[k] = UnwrapJSONStrings(val)
+		}
+		return m
+	case string:
+		s := strings.TrimSpace(t)
+		if len(s) > 1 && (s[0] == '{' || s[0] == '[') {
+			dec := json.NewDecoder(strings.NewReader(s))
+			dec.UseNumber()
+			var parsed interface{}
+			if err := dec.Decode(&parsed); err == nil {
+				switch parsed.(type) {
+				case map[string]interface{}, []interface{}:
+					return UnwrapJSONStrings(parsed)
+				}
+			}
+		}
+		return t
+	default:
+		return v
+	}
+}
+
+// reencodeUnwrapped 解析上游响应文本,解包 JSON 字符串后重新序列化。
+// 解析失败时原样返回;UseNumber 保证大整数 ID 不丢精度
+func reencodeUnwrapped(text string) string {
+	dec := json.NewDecoder(strings.NewReader(text))
+	dec.UseNumber()
+	var v interface{}
+	if err := dec.Decode(&v); err != nil {
+		return text
+	}
+	return marshalNoEscape(UnwrapJSONStrings(v))
+}
+
 // ============ 设备和密钥管理 ============
 
 // getDeviceHeader 获取设备header（从设备池）
@@ -110,7 +260,7 @@ func getDeviceHeader() string {
 
 // removeVersionFromHeader 移除header中的version_name参数
 func removeVersionFromHeader(header string) string {
-	return strings.Replace(header, "&version_name=5.8.9.32", "", -1)
+	return strings.Replace(header, "&version_name="+ClientVersionName, "", -1)
 }
 
 // ============ API参数构建工具 ============
@@ -125,25 +275,20 @@ func BuildURL(fullURL string, customParams ...string) string {
 		"channel=0",
 		"device_platform=android",
 		"os_version=0",
-		"version_code=58932",
+		"version_code=" + ClientVersionCode,
 	}
-	
+
 	// 添加设备header
 	header := getDeviceHeader()
 	if header != "" {
 		allParams = append(allParams, header)
 	}
-	
+
 	// 添加自定义参数
 	allParams = append(allParams, customParams...)
-	
-	// 合并、拆分、排序
-	joined := strings.Join(allParams, "&")
-	paramList := strings.Split(joined, "&")
-	sort.Strings(paramList)
-	params := strings.Join(paramList, "&")
-	
-	return fullURL + "?" + params
+
+	// form 编码 + 排序（机型含空格等特殊字符时保证 URL 与签名一致）
+	return fullURL + "?" + buildSortedQuery(allParams...)
 }
 
 // ============ 缓存处理工具函数 ============
@@ -218,11 +363,11 @@ func parseStringToInt(s string) (int, error) {
 	// 简单实现，避免导入strconv
 	result := 0
 	negative := false
-	
+
 	if len(s) == 0 {
 		return 0, nil
 	}
-	
+
 	start := 0
 	if s[0] == '-' {
 		negative = true
@@ -230,18 +375,18 @@ func parseStringToInt(s string) (int, error) {
 	} else if s[0] == '+' {
 		start = 1
 	}
-	
+
 	for i := start; i < len(s); i++ {
 		if s[i] < '0' || s[i] > '9' {
 			break
 		}
 		result = result*10 + int(s[i]-'0')
 	}
-	
+
 	if negative {
 		result = -result
 	}
-	
+
 	return result, nil
 }
 
@@ -250,7 +395,7 @@ func ParseStringParam(param interface{}, defaultVal string) string {
 	if param == nil || param == "" {
 		return defaultVal
 	}
-	
+
 	switch v := param.(type) {
 	case string:
 		if v != "" {
@@ -262,4 +407,3 @@ func ParseStringParam(param interface{}, defaultVal string) string {
 	}
 	return defaultVal
 }
-

internal/fqapi/content_utils_test.go

@@ -0,0 +1,31 @@
+package fqapi
+
+import "testing"
+
+// TestBuildSortedQuery form 编码 + 排序（机型含空格时 URL 与签名一致的关键）
+func TestBuildSortedQuery(t *testing.T) {
+	got := buildSortedQuery("b=2", "a=1", "device_type=Pixel 6")
+	want := "a=1&b=2&device_type=Pixel+6"
+	if got != want {
+		t.Fatalf("buildSortedQuery = %q, want %q", got, want)
+	}
+}
+
+// TestNormalizeNovelImageURL 插图/封面/已永久化链接的归一化
+func TestNormalizeNovelImageURL(t *testing.T) {
+	cases := map[string]string{
+		// 正文插图（纯 md5）→ origin 原图
+		"//p9-novel.byteimg.com/img/novel-pic/0123456789abcdef0123456789abcdef": "https://p6-novel.byteimg.com/origin/novel-pic/0123456789abcdef0123456789abcdef",
+		// 已永久化的链接幂等
+		"https://p6-novel.byteimg.com/origin/novel-pic/0123456789abcdef0123456789abcdef": "https://p6-novel.byteimg.com/origin/novel-pic/0123456789abcdef0123456789abcdef",
+		// 封面模板图（~tplv 缩放）→ 保留原路径仅换域名
+		"https://p3-novel.byteimg.com/novel-pic/0123456789abcdef0123456789abcdef~tplv-novel-pic-large.webp": "https://p6-novel.byteimg.com/novel-pic/0123456789abcdef0123456789abcdef~tplv-novel-pic-large.webp",
+		// 非 novel-pic 链接原样返回
+		"https://example.com/other.jpg": "https://example.com/other.jpg",
+	}
+	for in, want := range cases {
+		if got := NormalizeNovelImageURL(in); got != want {
+			t.Errorf("NormalizeNovelImageURL(%q) = %q, want %q", in, got, want)
+		}
+	}
+}

internal/fqapi/detail.go

@@ -8,8 +8,14 @@ import (
 
 var detailLogger = common.NewLogger("detail", "INFO", "")
 
-// HandleGetDetail 处理获取书籍详情
+// HandleGetDetail 处理获取书籍详情,详情数据基本不变,缓存 24 小时
 func HandleGetDetail(bookID string) (string, error) {
+	return withCache("detail_"+bookID, 86400, func() (string, error) {
+		return fetchDetail(bookID)
+	})
+}
+
+func fetchDetail(bookID string) (string, error) {
 	if bookID == "" {
 		return BuildErrorResponse("需要参数 book_id"), nil
 	}
@@ -36,13 +42,17 @@ func HandleGetDetail(bookID string) (string, error) {
 	}
 
 	if code, ok := respJSON["code"].(float64); ok && code == 0 {
-		// 删除content字段
 		if data, ok := respJSON["data"].(map[string]interface{}); ok {
+			// 删除content字段
 			delete(data, "content")
+			// 封面链接永久化（原链接带临时参数会过期）
+			if thumb, ok := data["thumb_url"].(string); ok && thumb != "" {
+				data["thumb_url"] = NormalizeNovelImageURL(thumb)
+			}
 		}
 
-		// 重新序列化
-		resultBytes, err := json.Marshal(respJSON)
+		// 重新序列化（解包 JSON 字符串字段）
+		resultBytes, err := json.Marshal(UnwrapJSONStrings(respJSON))
 		if err != nil {
 			return BuildErrorResponse("序列化失败"), err
 		}
@@ -52,4 +62,3 @@ func HandleGetDetail(bookID string) (string, error) {
 
 	return BuildErrorResponse("获取失败"), nil
 }
-

internal/fqapi/device_register.go

@@ -5,6 +5,7 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"fanqie/internal/common"
+	"fanqie/internal/config"
 	"fmt"
 	"math/big"
 	"net"
@@ -40,7 +41,7 @@ func currentMillis() int64 {
 // custom_bt = current_millis - elapsed_ms_since_boot
 func getCustomBT() string {
 	var uptimeSeconds float64
-	
+
 	if runtime.GOOS == "linux" {
 		// 在Linux上读取/proc/uptime
 		data, err := os.ReadFile("/proc/uptime")
@@ -54,7 +55,7 @@ func getCustomBT() string {
 				}
 			}
 		}
-		
+
 		// 如果读取失败，使用time.monotonic作为备选
 		if uptimeSeconds == 0 {
 			// Go没有直接的monotonic API，使用启动时间估算
@@ -65,17 +66,17 @@ func getCustomBT() string {
 		// 这里可以使用进程启动时间作为近似
 		uptimeSeconds = float64(time.Now().Unix() % 86400)
 	}
-	
+
 	return fmt.Sprintf("%d", currentMillis()-int64(uptimeSeconds*1000))
 }
 
 // generateDeviceInfo 随机生成设备及操作系统信息
 func generateDeviceInfo() map[string]interface{} {
 	osVersion := androidVersions[randInt(len(androidVersions))]
-	
+
 	// 随机选择品牌
 	deviceBrand := deviceBrands[randInt(len(deviceBrands))]
-	
+
 	// 根据品牌选择对应的型号
 	models := brandModels[deviceBrand]
 	deviceModel := models[randInt(len(models))]
@@ -88,19 +89,19 @@ func generateDeviceInfo() map[string]interface{} {
 	rand.Read(openUDIDBytes)
 
 	return map[string]interface{}{
-		"os":                   "Android",
-		"os_version":           osVersion[0],
-		"os_api":               osVersion[1],
-		"device_model":         deviceModel,
-		"device_brand":         deviceBrand,
-		"device_manufacturer":  deviceBrand,
-		"cpu_abi":              "arm64-v8a",
-		"release_build":        releaseBuild,
-		"cdid":                 generateUUID(),
-		"sig_hash":             "a4a27c2633195374c15651ffc3c4a497",
-		"openudid":             hex.EncodeToString(openUDIDBytes),
-		"clientudid":           generateUUID(),
-		"req_id":               generateUUID(),
+		"os":                  "Android",
+		"os_version":          osVersion[0],
+		"os_api":              osVersion[1],
+		"device_model":        deviceModel,
+		"device_brand":        deviceBrand,
+		"device_manufacturer": deviceBrand,
+		"cpu_abi":             "arm64-v8a",
+		"release_build":       releaseBuild,
+		"cdid":                generateUUID(),
+		"sig_hash":            "a4a27c2633195374c15651ffc3c4a497",
+		"openudid":            hex.EncodeToString(openUDIDBytes),
+		"clientudid":          generateUUID(),
+		"req_id":              generateUUID(),
 	}
 }
 
@@ -130,9 +131,9 @@ func generateOptionalFields() (map[string]interface{}, map[string]int64) {
 
 	genTime := currentMillis()
 	return map[string]interface{}{
-			"rom":                       rom,
-			"rom_version":               fmt.Sprintf("coloros__%s.%s.%s release-keys", part1, part2, part3),
-			"apk_first_install_time":    genTime - int64(randInt(365))*86400000,
+			"rom":                    rom,
+			"rom_version":            fmt.Sprintf("coloros__%s.%s.%s release-keys", part1, part2, part3),
+			"apk_first_install_time": genTime - int64(randInt(365))*86400000,
 		}, map[string]int64{
 			"_gen_time": genTime,
 		}
@@ -186,6 +187,22 @@ func generateIPv6List() []map[string]string {
 	}
 }
 
+// deviceIdentity 注册设备身份：pad（默认，历史行为）/ phone（对齐手机 App 书源注册 payload）
+func deviceIdentity() string {
+	if cfg := config.GetConfig(); cfg != nil && cfg.Fanqie.DeviceIdentity == "phone" {
+		return "phone"
+	}
+	return "pad"
+}
+
+// deviceCustomFields 注册身份对应的 custom 字段
+func deviceCustomFields() map[string]interface{} {
+	if deviceIdentity() == "phone" {
+		return map[string]interface{}{"host_bit": 64, "dragon_device_type": "phone"}
+	}
+	return map[string]interface{}{"host_bit": 32, "dragon_device_type": "pad"}
+}
+
 // GenerateFullRequestBody 生成完整的请求体数据
 func GenerateFullRequestBody() map[string]interface{} {
 	rawData := map[string]interface{}{
@@ -214,7 +231,7 @@ func GenerateFullRequestBody() map[string]interface{} {
 			"sim_serial_number":     []interface{}{},
 			"oaid_may_support":      false,
 			"device_platform":       "android",
-			"custom":                map[string]interface{}{"host_bit": 32, "dragon_device_type": "pad"},
+			"custom":                deviceCustomFields(),
 			"pre_installed_channel": "",
 			"is_system_app":         0,
 			"sdk_flavor":            "china",
@@ -234,6 +251,16 @@ func GenerateFullRequestBody() map[string]interface{} {
 	}
 	header["ipv6_list"] = generateIPv6List()
 
+	// phone 身份补充真机指纹字段（对齐书源注册 payload，规避 pad 身份的差异化风控）
+	if deviceIdentity() == "phone" {
+		rom, _ := header["rom"].(string)
+		header["hardware"] = "qcom"
+		header["device_device"] = rom
+		header["fingerprint"] = fmt.Sprintf("%v/%v/%v:%v/%s/%s:user/release-keys",
+			header["device_brand"], header["device_model"], header["device_model"],
+			header["os_version"], rom, rom)
+	}
+
 	for k, v := range genTime {
 		rawData[k] = v
 	}
@@ -252,9 +279,9 @@ func tryActivatePremium(header string) {
 		"channel=0",
 		"device_platform=android",
 		"os_version=0",
-		"version_code=58932",
-		"manifest_version_code=58932",
-		"update_version_code=58932",
+		"version_code=" + ClientVersionCode,
+		"manifest_version_code=" + ClientVersionCode,
+		"update_version_code=" + ClientVersionCode,
 		header,
 	}
 
@@ -307,7 +334,7 @@ func Register() (string, error) {
 
 	// 生成完整请求体数据
 	data := GenerateFullRequestBody()
-	
+
 	// 只记录关键设备信息
 	header := data["header"].(map[string]interface{})
 	logger.Info(fmt.Sprintf("生成设备信息 - 品牌: %s, 型号: %s, 系统: Android %v",
@@ -365,12 +392,12 @@ func Register() (string, error) {
 		}
 
 		deviceModel := data["header"].(map[string]interface{})["device_model"].(string)
-		header := fmt.Sprintf("device_id=%v&device_type=%s&iid=%v&version_name=5.8.9.32",
+		header := fmt.Sprintf("device_id=%v&device_type=%s&iid=%v&version_name="+ClientVersionName,
 			respData["device_id_str"],
 			deviceModel,
 			respData["install_id_str"])
 
-		logger.Info("设备注册成功！" )
+		logger.Info("设备注册成功！")
 
 		// 尝试激活特权
 		tryActivatePremium(header)
@@ -381,4 +408,3 @@ func Register() (string, error) {
 	logger.Warning("设备注册失败！")
 	return "", fmt.Errorf("设备注册失败")
 }
-

internal/fqapi/dhcry.go

@@ -1,185 +1,184 @@
-package fqapi
-
-import (
-	"crypto/aes"
-	"crypto/cipher"
-	"crypto/rand"
-	"encoding/base64"
-	"fmt"
-	"math/big"
-)
-
-// CM 加密管理器
-type CM struct {
-	bigC  *big.Int // 大素数C
-	bigB  int64    // 底数B
-	arryD []byte   // 固定密钥
-	thisD [2]*big.Int // 密钥对(私钥, 公钥)
-	thisC []byte      // 随机IV
-}
-
-// NewCM 创建新的CM实例
-func NewCM() *CM {
-	// 大素数C
-	bigCStr := "2410312426921032588552076022197566074856950548502459942654116941958108831682612228890093858261341614673227141477904012196503648957050582631942730706805009223062734745341073406696246014589361659774041027169249453200378729434170325843778659198143763193776859869524088940195577346119843545301547043747207749969763750084308926339295559968882457872412993810129130294592999947926365264059284647209730384947211681434464714438488520940127459844288859336526896320919633919"
-	bigC := new(big.Int)
-	bigC.SetString(bigCStr, 10)
-
-	// 固定密钥（base64解码）
-	arryD, _ := base64.StdEncoding.DecodeString("rCXGfd2POMGzeiNIgo4iLg==")
-
-	return &CM{
-		bigC:  bigC,
-		bigB:  2,
-		arryD: arryD,
-	}
-}
-
-// generateKeyPair 生成密钥对
-func (cm *CM) generateKeyPair() [2]*big.Int {
-	// 生成随机私钥
-	randomBytes := make([]byte, 32)
-	rand.Read(randomBytes)
-
-	x := new(big.Int).SetBytes(randomBytes)
-	x = x.Mod(x, new(big.Int).Sub(cm.bigC, big.NewInt(1)))
-
-	// 计算公钥: y = b^x mod c
-	y := new(big.Int).Exp(big.NewInt(cm.bigB), x, cm.bigC)
-
-	cm.thisD = [2]*big.Int{x, y}
-	return cm.thisD
-}
-
-// pairToBytes 将公钥转换为字节数组
-func (cm *CM) pairToBytes(keyPair [2]*big.Int) []byte {
-	return keyPair[1].Bytes()
-}
-
-// randIV 生成随机IV
-func (cm *CM) randIV() []byte {
-	iv := make([]byte, 16)
-	rand.Read(iv)
-	return iv
-}
-
-// encodeAES AES-CBC加密
-func (cm *CM) encodeAES(key, iv, data []byte) ([]byte, error) {
-	block, err := aes.NewCipher(key)
-	if err != nil {
-		return nil, err
-	}
-
-	// PKCS7填充
-	padding := aes.BlockSize - len(data)%aes.BlockSize
-	padText := make([]byte, padding)
-	for i := range padText {
-		padText[i] = byte(padding)
-	}
-	paddedData := append(data, padText...)
-
-	ciphertext := make([]byte, len(paddedData))
-	mode := cipher.NewCBCEncrypter(block, iv)
-	mode.CryptBlocks(ciphertext, paddedData)
-
-	return ciphertext, nil
-}
-
-// decodeAES AES-CBC解密
-func (cm *CM) decodeAES(key, iv, data []byte) ([]byte, error) {
-	block, err := aes.NewCipher(key)
-	if err != nil {
-		return nil, err
-	}
-
-	mode := cipher.NewCBCDecrypter(block, iv)
-	decrypted := make([]byte, len(data))
-	mode.CryptBlocks(decrypted, data)
-
-	// 移除PKCS7填充
-	padding := int(decrypted[len(decrypted)-1])
-	if padding > len(decrypted) || padding > aes.BlockSize {
-		return nil, fmt.Errorf("无效的填充")
-	}
-
-	return decrypted[:len(decrypted)-padding], nil
-}
-
-// ClientHandshake 客户端握手，生成请求头y
-func (cm *CM) ClientHandshake() string {
-	keyPair := cm.generateKeyPair()
-	cm.thisC = cm.randIV()
-
-	publicKeyBytes := cm.pairToBytes(keyPair)
-	encrypted, _ := cm.encodeAES(cm.arryD, cm.thisC, publicKeyBytes)
-
-	combined := append(cm.thisC, encrypted...)
-	return base64.StdEncoding.EncodeToString(combined)
-}
-
-// decryptF 解密函数
-func (cm *CM) decryptF(peerPublicKey []byte, keyPair [2]*big.Int, iv, data []byte) ([]byte, error) {
-	x := keyPair[0]
-
-	// 计算共享密钥: shared_secret = peer_public_key^x mod c
-	peerPubInt := new(big.Int).SetBytes(peerPublicKey)
-	sharedSecret := new(big.Int).Exp(peerPubInt, x, cm.bigC)
-
-	key := sharedSecret.Bytes()
-	// 确保key长度为32字节
-	if len(key) < 32 {
-		// 前面补0
-		paddedKey := make([]byte, 32)
-		copy(paddedKey[32-len(key):], key)
-		key = paddedKey
-	} else if len(key) > 32 {
-		key = key[:32]
-	}
-
-	return cm.decodeAES(key, iv, data)
-}
-
-// Decrypt 解密响应内容
-func (cm *CM) Decrypt(c, y, content string) (string, error) {
-	// c 应该为 "1" 表示启用加密
-	// y 是服务器返回的公钥
-	// content 是加密的内容
-
-	if c != "1" || y == "" {
-		return content, nil
-	}
-
-	// 解码content
-	contentDecoded, err := base64.StdEncoding.DecodeString(content)
-	if err != nil {
-		return "", err
-	}
-
-	if len(contentDecoded) < 16 {
-		return "", fmt.Errorf("内容太短")
-	}
-
-	// 提取IV和数据
-	iv := contentDecoded[:16]
-	data := contentDecoded[16:]
-
-	// 解码服务器公钥
-	peerPublicKey, err := base64.StdEncoding.DecodeString(y)
-	if err != nil {
-		return "", err
-	}
-
-	// 检查密钥对是否已初始化
-	if cm.thisD[0] == nil {
-		return "", fmt.Errorf("密钥对未初始化")
-	}
-
-	// 解密
-	decrypted, err := cm.decryptF(peerPublicKey, cm.thisD, iv, data)
-	if err != nil {
-		return "", err
-	}
-
-	return string(decrypted), nil
-}
-
+package fqapi
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"encoding/base64"
+	"fmt"
+	"math/big"
+)
+
+// CM 加密管理器
+type CM struct {
+	bigC  *big.Int    // 大素数C
+	bigB  int64       // 底数B
+	arryD []byte      // 固定密钥
+	thisD [2]*big.Int // 密钥对(私钥, 公钥)
+	thisC []byte      // 随机IV
+}
+
+// NewCM 创建新的CM实例
+func NewCM() *CM {
+	// 大素数C
+	bigCStr := "2410312426921032588552076022197566074856950548502459942654116941958108831682612228890093858261341614673227141477904012196503648957050582631942730706805009223062734745341073406696246014589361659774041027169249453200378729434170325843778659198143763193776859869524088940195577346119843545301547043747207749969763750084308926339295559968882457872412993810129130294592999947926365264059284647209730384947211681434464714438488520940127459844288859336526896320919633919"
+	bigC := new(big.Int)
+	bigC.SetString(bigCStr, 10)
+
+	// 固定密钥（base64解码）
+	arryD, _ := base64.StdEncoding.DecodeString("rCXGfd2POMGzeiNIgo4iLg==")
+
+	return &CM{
+		bigC:  bigC,
+		bigB:  2,
+		arryD: arryD,
+	}
+}
+
+// generateKeyPair 生成密钥对
+func (cm *CM) generateKeyPair() [2]*big.Int {
+	// 生成随机私钥
+	randomBytes := make([]byte, 32)
+	rand.Read(randomBytes)
+
+	x := new(big.Int).SetBytes(randomBytes)
+	x = x.Mod(x, new(big.Int).Sub(cm.bigC, big.NewInt(1)))
+
+	// 计算公钥: y = b^x mod c
+	y := new(big.Int).Exp(big.NewInt(cm.bigB), x, cm.bigC)
+
+	cm.thisD = [2]*big.Int{x, y}
+	return cm.thisD
+}
+
+// pairToBytes 将公钥转换为字节数组
+func (cm *CM) pairToBytes(keyPair [2]*big.Int) []byte {
+	return keyPair[1].Bytes()
+}
+
+// randIV 生成随机IV
+func (cm *CM) randIV() []byte {
+	iv := make([]byte, 16)
+	rand.Read(iv)
+	return iv
+}
+
+// encodeAES AES-CBC加密
+func (cm *CM) encodeAES(key, iv, data []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+
+	// PKCS7填充
+	padding := aes.BlockSize - len(data)%aes.BlockSize
+	padText := make([]byte, padding)
+	for i := range padText {
+		padText[i] = byte(padding)
+	}
+	paddedData := append(data, padText...)
+
+	ciphertext := make([]byte, len(paddedData))
+	mode := cipher.NewCBCEncrypter(block, iv)
+	mode.CryptBlocks(ciphertext, paddedData)
+
+	return ciphertext, nil
+}
+
+// decodeAES AES-CBC解密
+func (cm *CM) decodeAES(key, iv, data []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+
+	mode := cipher.NewCBCDecrypter(block, iv)
+	decrypted := make([]byte, len(data))
+	mode.CryptBlocks(decrypted, data)
+
+	// 移除PKCS7填充
+	padding := int(decrypted[len(decrypted)-1])
+	if padding > len(decrypted) || padding > aes.BlockSize {
+		return nil, fmt.Errorf("无效的填充")
+	}
+
+	return decrypted[:len(decrypted)-padding], nil
+}
+
+// ClientHandshake 客户端握手，生成请求头y
+func (cm *CM) ClientHandshake() string {
+	keyPair := cm.generateKeyPair()
+	cm.thisC = cm.randIV()
+
+	publicKeyBytes := cm.pairToBytes(keyPair)
+	encrypted, _ := cm.encodeAES(cm.arryD, cm.thisC, publicKeyBytes)
+
+	combined := append(cm.thisC, encrypted...)
+	return base64.StdEncoding.EncodeToString(combined)
+}
+
+// decryptF 解密函数
+func (cm *CM) decryptF(peerPublicKey []byte, keyPair [2]*big.Int, iv, data []byte) ([]byte, error) {
+	x := keyPair[0]
+
+	// 计算共享密钥: shared_secret = peer_public_key^x mod c
+	peerPubInt := new(big.Int).SetBytes(peerPublicKey)
+	sharedSecret := new(big.Int).Exp(peerPubInt, x, cm.bigC)
+
+	key := sharedSecret.Bytes()
+	// 确保key长度为32字节
+	if len(key) < 32 {
+		// 前面补0
+		paddedKey := make([]byte, 32)
+		copy(paddedKey[32-len(key):], key)
+		key = paddedKey
+	} else if len(key) > 32 {
+		key = key[:32]
+	}
+
+	return cm.decodeAES(key, iv, data)
+}
+
+// Decrypt 解密响应内容
+func (cm *CM) Decrypt(c, y, content string) (string, error) {
+	// c 应该为 "1" 表示启用加密
+	// y 是服务器返回的公钥
+	// content 是加密的内容
+
+	if c != "1" || y == "" {
+		return content, nil
+	}
+
+	// 解码content
+	contentDecoded, err := base64.StdEncoding.DecodeString(content)
+	if err != nil {
+		return "", err
+	}
+
+	if len(contentDecoded) < 16 {
+		return "", fmt.Errorf("内容太短")
+	}
+
+	// 提取IV和数据
+	iv := contentDecoded[:16]
+	data := contentDecoded[16:]
+
+	// 解码服务器公钥
+	peerPublicKey, err := base64.StdEncoding.DecodeString(y)
+	if err != nil {
+		return "", err
+	}
+
+	// 检查密钥对是否已初始化
+	if cm.thisD[0] == nil {
+		return "", fmt.Errorf("密钥对未初始化")
+	}
+
+	// 解密
+	decrypted, err := cm.decryptF(peerPublicKey, cm.thisD, iv, data)
+	if err != nil {
+		return "", err
+	}
+
+	return string(decrypted), nil
+}

internal/fqapi/emoji.go

@@ -1,230 +1,229 @@
-package fqapi
-
-import (
-	"encoding/json"
-	"fmt"
-	"io/ioutil"
-	"net/http"
-	"os"
-	"path/filepath"
-	"strings"
-	"sync"
-	"time"
-)
-
-// EmojiManager 表情管理器
-type EmojiManager struct {
-	emojiMap    map[string]string // 表情文本 -> 图片URL的映射
-	mutex       sync.RWMutex
-	lastUpdate  time.Time
-	cacheExpiry time.Duration
-}
-
-// DouyinEmojiResponse 抖音表情API响应结构
-type DouyinEmojiResponse struct {
-	EmojiList []DouyinEmoji `json:"emoji_list"`
-}
-
-// DouyinEmoji 抖音单个表情结构
-type DouyinEmoji struct {
-	OriginURI   string `json:"origin_uri"`
-	DisplayName string `json:"display_name"`
-	Hide        int    `json:"hide"`
-	EmojiURL    struct {
-		URI     string   `json:"uri"`
-		URLList []string `json:"url_list"`
-	} `json:"emoji_url"`
-}
-
-// LocalEmojiData 本地表情数据结构
-type LocalEmojiData struct {
-	Version int               `json:"version"`
-	Size    int               `json:"size"`
-	Datas   map[string]string `json:"datas"`
-}
-
-var (
-	globalEmojiManager *EmojiManager
-	emojiOnce          sync.Once
-)
-
-// GetEmojiManager 获取全局表情管理器实例
-func GetEmojiManager() *EmojiManager {
-	emojiOnce.Do(func() {
-		globalEmojiManager = &EmojiManager{
-			emojiMap:    make(map[string]string),
-			cacheExpiry: 24 * time.Hour, // 缓存24小时
-		}
-		// 初始化时加载表情
-		globalEmojiManager.LoadEmojis()
-	})
-	return globalEmojiManager
-}
-
-// LoadEmojis 加载表情映射（优先API，其次本地）
-func (em *EmojiManager) LoadEmojis() error {
-	em.mutex.Lock()
-	defer em.mutex.Unlock()
-
-	// 检查缓存是否过期
-	if time.Since(em.lastUpdate) < em.cacheExpiry && len(em.emojiMap) > 0 {
-		return nil
-	}
-
-	newMap := make(map[string]string)
-
-	// 1. 先尝试从抖音API获取表情
-	apiEmojis, err := em.fetchDouyinEmojis()
-	if err == nil && len(apiEmojis) > 0 {
-		for displayName, url := range apiEmojis {
-			newMap[displayName] = url
-		}
-	}
-
-	// 2. 加载本地表情作为补充
-	localEmojis, err := em.loadLocalEmojis()
-	if err == nil {
-		for displayName, url := range localEmojis {
-			// 如果API中没有，则使用本地的
-			if _, exists := newMap[displayName]; !exists {
-				newMap[displayName] = url
-			}
-		}
-	}
-
-	// 3. 更新缓存
-	if len(newMap) > 0 {
-		em.emojiMap = newMap
-		em.lastUpdate = time.Now()
-	}
-
-	return nil
-}
-
-// fetchDouyinEmojis 从抖音API获取表情映射
-func (em *EmojiManager) fetchDouyinEmojis() (map[string]string, error) {
-	client := &http.Client{
-		Timeout: 10 * time.Second,
-	}
-
-	resp, err := client.Get("https://www.douyin.com/aweme/v1/web/emoji/list")
-	if err != nil {
-		return nil, fmt.Errorf("获取抖音表情API失败: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("抖音表情API返回状态码: %d", resp.StatusCode)
-	}
-
-	body, err := ioutil.ReadAll(resp.Body)
-	if err != nil {
-		return nil, fmt.Errorf("读取响应失败: %w", err)
-	}
-
-	var apiResp DouyinEmojiResponse
-	if err := json.Unmarshal(body, &apiResp); err != nil {
-		return nil, fmt.Errorf("解析JSON失败: %w", err)
-	}
-
-	emojiMap := make(map[string]string)
-	for _, emoji := range apiResp.EmojiList {
-		if len(emoji.EmojiURL.URLList) > 0 {
-			// 使用第一个URL
-			emojiMap[emoji.DisplayName] = emoji.EmojiURL.URLList[0]
-		}
-	}
-
-	return emojiMap, nil
-}
-
-// loadLocalEmojis 从本地文件加载表情映射
-func (em *EmojiManager) loadLocalEmojis() (map[string]string, error) {
-	// 读取 data.json
-	dataPath := filepath.Join("emoji", "data.json")
-	data, err := ioutil.ReadFile(dataPath)
-	if err != nil {
-		return nil, fmt.Errorf("读取emoji/data.json失败: %w", err)
-	}
-
-	var localData LocalEmojiData
-	if err := json.Unmarshal(data, &localData); err != nil {
-		return nil, fmt.Errorf("解析emoji/data.json失败: %w", err)
-	}
-
-	emojiMap := make(map[string]string)
-	for id, displayName := range localData.Datas {
-		// 生成本地图片路径：emoji/images/emoji_dr_{id}.png
-		// 转换为相对URL路径
-		localPath := fmt.Sprintf("/emoji/images/emoji_dr_%s.png", id)
-		emojiMap[displayName] = localPath
-	}
-
-	return emojiMap, nil
-}
-
-// GetEmojiURL 获取表情图片URL
-func (em *EmojiManager) GetEmojiURL(displayName string) (string, bool) {
-	em.mutex.RLock()
-	defer em.mutex.RUnlock()
-
-	url, exists := em.emojiMap[displayName]
-	return url, exists
-}
-
-// GetAllEmojis 获取所有表情映射（用于生成JavaScript代码）
-func (em *EmojiManager) GetAllEmojis() map[string]string {
-	em.mutex.RLock()
-	defer em.mutex.RUnlock()
-
-	// 返回副本
-	result := make(map[string]string, len(em.emojiMap))
-	for k, v := range em.emojiMap {
-		result[k] = v
-	}
-	return result
-}
-
-// RefreshEmojis 手动刷新表情缓存
-func (em *EmojiManager) RefreshEmojis() error {
-	em.mutex.Lock()
-	em.lastUpdate = time.Time{} // 重置更新时间
-	em.mutex.Unlock()
-
-	return em.LoadEmojis()
-}
-
-// CheckLocalEmojiFiles 检查本地表情文件是否存在
-func CheckLocalEmojiFiles() error {
-	dataPath := filepath.Join("emoji", "data.json")
-	if _, err := os.Stat(dataPath); os.IsNotExist(err) {
-		return fmt.Errorf("emoji/data.json 文件不存在")
-	}
-
-	imagesDir := filepath.Join("emoji", "images")
-	if _, err := os.Stat(imagesDir); os.IsNotExist(err) {
-		return fmt.Errorf("emoji/images 目录不存在")
-	}
-
-	return nil
-}
-
-// ReplaceEmojisInText 替换文本中的表情为HTML img标签
-func ReplaceEmojisInText(text string) string {
-	em := GetEmojiManager()
-
-	// 匹配 [表情] 格式
-	result := text
-	for displayName, url := range em.GetAllEmojis() {
-		// 转义特殊字符
-		escapedName := strings.ReplaceAll(displayName, "[", "\\[")
-		escapedName = strings.ReplaceAll(escapedName, "]", "\\]")
-
-		// 替换为 img 标签
-		imgTag := fmt.Sprintf(`<img src="%s" class="emoji-img" alt="%s" />`, url, displayName)
-		result = strings.ReplaceAll(result, displayName, imgTag)
-	}
-
-	return result
-}
-
+package fqapi
+
+import (
+	"encoding/json"
+	"fmt"
+	"io/ioutil"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+)
+
+// EmojiManager 表情管理器
+type EmojiManager struct {
+	emojiMap    map[string]string // 表情文本 -> 图片URL的映射
+	mutex       sync.RWMutex
+	lastUpdate  time.Time
+	cacheExpiry time.Duration
+}
+
+// DouyinEmojiResponse 抖音表情API响应结构
+type DouyinEmojiResponse struct {
+	EmojiList []DouyinEmoji `json:"emoji_list"`
+}
+
+// DouyinEmoji 抖音单个表情结构
+type DouyinEmoji struct {
+	OriginURI   string `json:"origin_uri"`
+	DisplayName string `json:"display_name"`
+	Hide        int    `json:"hide"`
+	EmojiURL    struct {
+		URI     string   `json:"uri"`
+		URLList []string `json:"url_list"`
+	} `json:"emoji_url"`
+}
+
+// LocalEmojiData 本地表情数据结构
+type LocalEmojiData struct {
+	Version int               `json:"version"`
+	Size    int               `json:"size"`
+	Datas   map[string]string `json:"datas"`
+}
+
+var (
+	globalEmojiManager *EmojiManager
+	emojiOnce          sync.Once
+)
+
+// GetEmojiManager 获取全局表情管理器实例
+func GetEmojiManager() *EmojiManager {
+	emojiOnce.Do(func() {
+		globalEmojiManager = &EmojiManager{
+			emojiMap:    make(map[string]string),
+			cacheExpiry: 24 * time.Hour, // 缓存24小时
+		}
+		// 初始化时加载表情
+		globalEmojiManager.LoadEmojis()
+	})
+	return globalEmojiManager
+}
+
+// LoadEmojis 加载表情映射（优先API，其次本地）
+func (em *EmojiManager) LoadEmojis() error {
+	em.mutex.Lock()
+	defer em.mutex.Unlock()
+
+	// 检查缓存是否过期
+	if time.Since(em.lastUpdate) < em.cacheExpiry && len(em.emojiMap) > 0 {
+		return nil
+	}
+
+	newMap := make(map[string]string)
+
+	// 1. 先尝试从抖音API获取表情
+	apiEmojis, err := em.fetchDouyinEmojis()
+	if err == nil && len(apiEmojis) > 0 {
+		for displayName, url := range apiEmojis {
+			newMap[displayName] = url
+		}
+	}
+
+	// 2. 加载本地表情作为补充
+	localEmojis, err := em.loadLocalEmojis()
+	if err == nil {
+		for displayName, url := range localEmojis {
+			// 如果API中没有，则使用本地的
+			if _, exists := newMap[displayName]; !exists {
+				newMap[displayName] = url
+			}
+		}
+	}
+
+	// 3. 更新缓存
+	if len(newMap) > 0 {
+		em.emojiMap = newMap
+		em.lastUpdate = time.Now()
+	}
+
+	return nil
+}
+
+// fetchDouyinEmojis 从抖音API获取表情映射
+func (em *EmojiManager) fetchDouyinEmojis() (map[string]string, error) {
+	client := &http.Client{
+		Timeout: 10 * time.Second,
+	}
+
+	resp, err := client.Get("https://www.douyin.com/aweme/v1/web/emoji/list")
+	if err != nil {
+		return nil, fmt.Errorf("获取抖音表情API失败: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("抖音表情API返回状态码: %d", resp.StatusCode)
+	}
+
+	body, err := ioutil.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("读取响应失败: %w", err)
+	}
+
+	var apiResp DouyinEmojiResponse
+	if err := json.Unmarshal(body, &apiResp); err != nil {
+		return nil, fmt.Errorf("解析JSON失败: %w", err)
+	}
+
+	emojiMap := make(map[string]string)
+	for _, emoji := range apiResp.EmojiList {
+		if len(emoji.EmojiURL.URLList) > 0 {
+			// 使用第一个URL
+			emojiMap[emoji.DisplayName] = emoji.EmojiURL.URLList[0]
+		}
+	}
+
+	return emojiMap, nil
+}
+
+// loadLocalEmojis 从本地文件加载表情映射
+func (em *EmojiManager) loadLocalEmojis() (map[string]string, error) {
+	// 读取 data.json
+	dataPath := filepath.Join("emoji", "data.json")
+	data, err := ioutil.ReadFile(dataPath)
+	if err != nil {
+		return nil, fmt.Errorf("读取emoji/data.json失败: %w", err)
+	}
+
+	var localData LocalEmojiData
+	if err := json.Unmarshal(data, &localData); err != nil {
+		return nil, fmt.Errorf("解析emoji/data.json失败: %w", err)
+	}
+
+	emojiMap := make(map[string]string)
+	for id, displayName := range localData.Datas {
+		// 生成本地图片路径：emoji/images/emoji_dr_{id}.png
+		// 转换为相对URL路径
+		localPath := fmt.Sprintf("/emoji/images/emoji_dr_%s.png", id)
+		emojiMap[displayName] = localPath
+	}
+
+	return emojiMap, nil
+}
+
+// GetEmojiURL 获取表情图片URL
+func (em *EmojiManager) GetEmojiURL(displayName string) (string, bool) {
+	em.mutex.RLock()
+	defer em.mutex.RUnlock()
+
+	url, exists := em.emojiMap[displayName]
+	return url, exists
+}
+
+// GetAllEmojis 获取所有表情映射（用于生成JavaScript代码）
+func (em *EmojiManager) GetAllEmojis() map[string]string {
+	em.mutex.RLock()
+	defer em.mutex.RUnlock()
+
+	// 返回副本
+	result := make(map[string]string, len(em.emojiMap))
+	for k, v := range em.emojiMap {
+		result[k] = v
+	}
+	return result
+}
+
+// RefreshEmojis 手动刷新表情缓存
+func (em *EmojiManager) RefreshEmojis() error {
+	em.mutex.Lock()
+	em.lastUpdate = time.Time{} // 重置更新时间
+	em.mutex.Unlock()
+
+	return em.LoadEmojis()
+}
+
+// CheckLocalEmojiFiles 检查本地表情文件是否存在
+func CheckLocalEmojiFiles() error {
+	dataPath := filepath.Join("emoji", "data.json")
+	if _, err := os.Stat(dataPath); os.IsNotExist(err) {
+		return fmt.Errorf("emoji/data.json 文件不存在")
+	}
+
+	imagesDir := filepath.Join("emoji", "images")
+	if _, err := os.Stat(imagesDir); os.IsNotExist(err) {
+		return fmt.Errorf("emoji/images 目录不存在")
+	}
+
+	return nil
+}
+
+// ReplaceEmojisInText 替换文本中的表情为HTML img标签
+func ReplaceEmojisInText(text string) string {
+	em := GetEmojiManager()
+
+	// 匹配 [表情] 格式
+	result := text
+	for displayName, url := range em.GetAllEmojis() {
+		// 转义特殊字符
+		escapedName := strings.ReplaceAll(displayName, "[", "\\[")
+		escapedName = strings.ReplaceAll(escapedName, "]", "\\]")
+
+		// 替换为 img 标签
+		imgTag := fmt.Sprintf(`<img src="%s" class="emoji-img" alt="%s" />`, url, displayName)
+		result = strings.ReplaceAll(result, displayName, imgTag)
+	}
+
+	return result
+}

internal/fqapi/gorgon_utils.go

@@ -14,6 +14,16 @@ func CreateMD5(s string) string {
 	return hex.EncodeToString(hasher.Sum(nil))
 }
 
+// setCommonHeaders 注入番茄客户端通用请求头（与签名头不冲突，对齐书源实现降低风控特征）
+func setCommonHeaders(headers map[string]string) {
+	if _, ok := headers["x-tt-store-region"]; ok {
+		return
+	}
+	headers["x-tt-store-region"] = "cn-zj"
+	headers["x-tt-store-region-src"] = "did"
+	headers["sdk-version"] = "2"
+}
+
 // GorgonRequest Gorgon请求（使用签名切换器）
 func GorgonRequest(urlStr string, options map[string]interface{}) (*common.ClientResponse, error) {
 	headers, ok := options["headers"].(map[string]string)
@@ -21,6 +31,7 @@ func GorgonRequest(urlStr string, options map[string]interface{}) (*common.Clien
 		headers = make(map[string]string)
 		options["headers"] = headers
 	}
+	setCommonHeaders(headers)
 
 	dataMD5 := ""
 	if body, ok := options["body"].(string); ok && body != "" {
@@ -53,6 +64,7 @@ func GorgonRequestSync(urlStr string, options map[string]interface{}) (*common.C
 		headers = make(map[string]string)
 		options["headers"] = headers
 	}
+	setCommonHeaders(headers)
 
 	dataMD5 := ""
 	if body, ok := options["body"].(string); ok && body != "" {
@@ -69,9 +81,7 @@ func GorgonRequestSync(urlStr string, options map[string]interface{}) (*common.C
 	signedHeaders := algos.GlobalSignatureSwitcher.Sign(urlStr, headers)
 
 	// 删除x-ss-stub（如果存在）
-	if _, exists := signedHeaders["x-ss-stub"]; exists {
-		delete(signedHeaders, "x-ss-stub")
-	}
+	delete(signedHeaders, "x-ss-stub")
 
 	// 更新headers
 	for k, v := range signedHeaders {
@@ -90,6 +100,7 @@ func ContentRequest(urlStr string, options map[string]interface{}) (*common.Clie
 		headers = make(map[string]string)
 		options["headers"] = headers
 	}
+	setCommonHeaders(headers)
 
 	dataMD5 := ""
 	if body, ok := options["body"].(string); ok && body != "" {
@@ -114,4 +125,3 @@ func ContentRequest(urlStr string, options map[string]interface{}) (*common.Clie
 	client := common.NewHTTPClient()
 	return client.Request(urlStr, options)
 }
-

internal/fqapi/item_summary.go

@@ -7,8 +7,14 @@ import (
 
 var itemSummaryLogger = common.NewLogger("item_summary", "INFO", "")
 
-// HandleItemSummary 处理获取章节摘要
+// HandleItemSummary 处理获取章节摘要,章节摘要数据基本不变,缓存 24 小时
 func HandleItemSummary(itemIDs, bookID string) (string, error) {
+	return withCache("item_summary_"+bookID+"_"+itemIDs, 86400, func() (string, error) {
+		return fetchItemSummary(itemIDs, bookID)
+	})
+}
+
+func fetchItemSummary(itemIDs, bookID string) (string, error) {
 	if itemIDs == "" || bookID == "" {
 		return BuildErrorResponseWithCode(100144, "参数错误"), nil
 	}
@@ -37,9 +43,8 @@ func HandleItemSummary(itemIDs, bookID string) (string, error) {
 	}
 
 	if code, ok := respJSON["code"].(float64); ok && code == 0 {
-		return resp.Text, nil
+		return reencodeUnwrapped(resp.Text), nil
 	}
 
 	return BuildErrorResponse("获取失败"), nil
 }
-

internal/fqapi/manga.go

@@ -58,9 +58,14 @@ type ImageResult struct {
 	Index  int    `json:"index"`
 }
 
-// HandleGetManga 处理漫画请求
+// HandleGetManga 处理漫画请求；设备池签名路线全部失败时降级 wkbrowser 免签名兜底
 func HandleGetManga(itemID string, showHTML bool, urlOutputMode string) (interface{}, error) {
-	return getMangaWithRetry(itemID, showHTML, urlOutputMode, 0)
+	res, err := getMangaWithRetry(itemID, showHTML, urlOutputMode, 0)
+	if err == nil {
+		return res, nil
+	}
+	mangaLogger.Warning(fmt.Sprintf("签名路线失败，尝试 wkbrowser 免签名兜底: %v", err))
+	return fetchMangaFallback(itemID, showHTML)
 }
 
 // getMangaWithRetry 获取漫画内容，支持设备切换重试
@@ -71,14 +76,14 @@ func getMangaWithRetry(itemID string, showHTML bool, urlOutputMode string, retry
 		mangaLogger.Warning(fmt.Sprintf("已重试 %d 次，获取漫画失败", maxRetries))
 		return nil, fmt.Errorf("已重试 %d 次，所有设备均失败", maxRetries)
 	}
-	
+
 	// 1. 从设备密钥池获取设备
 	pool := GetDeviceKeyPool()
 	item, err := pool.GetNext()
 	if err != nil {
 		return nil, fmt.Errorf("从设备池获取设备失败: %w", err)
 	}
-	
+
 	header := item.DeviceHeader
 	keyInfo := &KeyInfo{
 		Key: item.Key,
@@ -87,7 +92,7 @@ func getMangaWithRetry(itemID string, showHTML bool, urlOutputMode string, retry
 	mangaLogger.Debug(fmt.Sprintf("使用池中设备 ID=%d (重试次数: %d)", item.ID, retryCount))
 
 	// 2. 构建URL - 使用 BuildURL 添加设备参数
-	headerWithoutVersion := strings.Replace(header, "&version_name=5.8.9.32", "", -1)
+	headerWithoutVersion := removeVersionFromHeader(header)
 
 	url := BuildURL("https://reading.snssdk.com/reading/reader/full/v/",
 		"aid=1967",
@@ -146,7 +151,7 @@ func getMangaWithRetry(itemID string, showHTML bool, urlOutputMode string, retry
 			mangaLogger.Warning("密钥版本不匹配，重新获取密钥")
 			newKeyInfo, err := GetKey(header)
 			if err == nil {
-				UpdateKeyInPool(header, newKeyInfo.Key, newKeyInfo.Ver)
+				UpdateKeyInPool(header, newKeyInfo)
 				keyInfo = newKeyInfo
 			} else {
 				mangaLogger.Warning("获取密钥失败，切换设备重试")
@@ -171,18 +176,18 @@ func getMangaWithRetry(itemID string, showHTML bool, urlOutputMode string, retry
 		// 是漫画，决定输出模式
 		// 优先级：URL参数 > 配置文件 > 默认值
 		outputMode := "proxy" // 默认值
-		
+
 		// 从配置文件读取
 		cfg := config.GetConfig()
 		if cfg != nil && cfg.Fanqie.Manga.OutputMode != "" {
 			outputMode = cfg.Fanqie.Manga.OutputMode
 		}
-		
+
 		// URL参数优先级最高
 		if urlOutputMode != "" {
 			outputMode = urlOutputMode
 		}
-		
+
 		// 解析漫画图片（传入keyInfo用于解密模式）
 		images, err := parseMangaImages(decrypted, showHTML, outputMode, itemID, keyInfo)
 		if err != nil {
@@ -234,8 +239,11 @@ func decryptAESContent(encrypted, secretKey string) (string, error) {
 	plaintext := make([]byte, len(ciphertext))
 	mode.CryptBlocks(plaintext, ciphertext)
 
-	// PKCS7 unpadding
+	// PKCS7 unpadding（无效填充说明密钥不匹配，返回错误触发上层重试）
 	plaintext = pkcs7Unpad(plaintext)
+	if plaintext == nil {
+		return "", fmt.Errorf("解密失败（无效填充，密钥可能不匹配）")
+	}
 
 	// 尝试gzip解压
 	if len(plaintext) > 2 && plaintext[0] == 0x1f && plaintext[1] == 0x8b {
@@ -257,13 +265,20 @@ func decryptAESContent(encrypted, secretKey string) (string, error) {
 func pkcs7Unpad(data []byte) []byte {
 	length := len(data)
 	if length == 0 {
-		return data
+		return nil
 	}
 	unpadding := int(data[length-1])
-	if unpadding > length {
-		return data
+	// 完整校验：值 1-16 且尾部 unpadding 个字节全等于填充值。
+	// 密钥错误时解密结果是随机字节，弱校验会让乱码静默通过
+	if unpadding < 1 || unpadding > 16 || unpadding > length {
+		return nil
 	}
-	return data[:(length - unpadding)]
+	for _, b := range data[length-unpadding:] {
+		if int(b) != unpadding {
+			return nil
+		}
+	}
+	return data[:length-unpadding]
 }
 
 // buildMangaResponse 构建漫画响应（统一HTML和JSON格式输出）
@@ -279,7 +294,7 @@ func buildMangaResponse(images []ImageResult, showHTML bool) interface{} {
 			"content": htmlContent.String(),
 		}
 	}
-	
+
 	return map[string]interface{}{
 		"images": images,
 	}
@@ -289,7 +304,7 @@ func buildMangaResponse(images []ImageResult, showHTML bool) interface{} {
 func processURLMode(mangaData *MangaData) []ImageResult {
 	baseDomain := "https://p6-novel.byteimg.com/origin/"
 	validPath := detectMangaPath(baseDomain, mangaData.PicInfos[0].Md5)
-	
+
 	images := make([]ImageResult, len(mangaData.PicInfos))
 	for i, pic := range mangaData.PicInfos {
 		imageURL := baseDomain + validPath + pic.Md5
@@ -309,7 +324,7 @@ func processProxyMode(mangaData *MangaData, itemID string) []ImageResult {
 	images := make([]ImageResult, len(mangaData.PicInfos))
 	for i, pic := range mangaData.PicInfos {
 		cacheKey := fmt.Sprintf("%s_%d", itemID, i)
-		
+
 		// 存储图片信息到缓存
 		mangaCacheMutex.Lock()
 		mangaImageCache[cacheKey] = &MangaImageInfo{
@@ -320,7 +335,7 @@ func processProxyMode(mangaData *MangaData, itemID string) []ImageResult {
 			CachedAt:   time.Now(),
 		}
 		mangaCacheMutex.Unlock()
-		
+
 		// 返回短的代理URL
 		imageData := fmt.Sprintf("/manga/image/%s/%d", itemID, i)
 		images[i] = ImageResult{
@@ -390,7 +405,7 @@ func processDataURIMode(mangaData *MangaData) []ImageResult {
 
 		// Base64编码图片数据
 		base64Data := base64.StdEncoding.EncodeToString(decryptedData)
-		
+
 		// Data URI模式：返回完整的Base64编码
 		mimeType := fmt.Sprintf("image/%s", format)
 		if format == "jpg" {
@@ -542,31 +557,31 @@ func decryptImage(encryptedData, keyBytes []byte) ([]byte, error) {
 func detectMangaPath(baseDomain, firstMd5 string) string {
 	// 优先尝试 novel-images/
 	testURL := baseDomain + "novel-images/" + firstMd5
-	
+
 	client := &http.Client{
 		Timeout: 8 * time.Second,
 	}
-	
+
 	resp, err := client.Get(testURL)
 	if err != nil {
 		// 请求失败，使用novel-pic/
 		return "novel-pic/"
 	}
 	defer resp.Body.Close()
-	
+
 	// 读取响应内容
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
 		return "novel-pic/"
 	}
-	
+
 	// 检查是否为JSON响应（错误响应通常是JSON）
 	var jsonData interface{}
 	if json.Unmarshal(body, &jsonData) == nil {
 		// 是JSON，说明路径无效，切换到novel-pic/
 		return "novel-pic/"
 	}
-	
+
 	// 不是JSON，说明返回的是图片，路径有效
 	return "novel-images/"
 }
@@ -605,12 +620,11 @@ func getImageFormat(data []byte, url string) string {
 	}
 
 	// WEBP: RIFF...WEBP
-	if bytes.HasPrefix(data, []byte{0x52, 0x49, 0x46, 0x46}) && 
-	   len(data) >= 12 && 
-	   bytes.Equal(data[8:12], []byte{0x57, 0x45, 0x42, 0x50}) {
+	if bytes.HasPrefix(data, []byte{0x52, 0x49, 0x46, 0x46}) &&
+		len(data) >= 12 &&
+		bytes.Equal(data[8:12], []byte{0x57, 0x45, 0x42, 0x50}) {
 		return "webp"
 	}
 
 	return "png"
 }
-

internal/fqapi/manga_fallback.go

@@ -0,0 +1,212 @@
+package fqapi
+
+import (
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+
+	"fanqie/internal/common"
+)
+
+// 漫画免签名兜底（对齐书源 20261012 的 wkbrowser 路线）：
+// 设备池签名路线全部失败时，直接从 m.wkbrowser.com 取章节图片，
+// 无需注册设备/签名/解密，返回原图直链。
+
+var (
+	mangaFallbackItemIDRe = regexp.MustCompile(`^\d+$`)
+	trailingNumberRe      = regexp.MustCompile(`(\d+)$`)
+)
+
+const mangaFallbackOrigin = "https://p6-novel.byteimg.com/origin/"
+
+// fetchMangaFallback 免签名获取漫画章节图片（wkbrowser 原图直链）
+func fetchMangaFallback(itemID string, showHTML bool) (interface{}, error) {
+	if !mangaFallbackItemIDRe.MatchString(itemID) {
+		return nil, fmt.Errorf("无效的 item_id: %s", itemID)
+	}
+
+	client := common.NewHTTPClient()
+	resp, err := client.Get("https://m.wkbrowser.com/i"+itemID+"/info/v2/", map[string]string{
+		"User-Agent": "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Mobile Safari/537.36",
+		"Accept":     "application/json, text/plain, */*",
+	})
+	if err != nil {
+		return nil, fmt.Errorf("wkbrowser 请求失败: %w", err)
+	}
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(resp.Content, &body); err != nil {
+		return nil, fmt.Errorf("wkbrowser 响应解析失败: %w", err)
+	}
+	data, _ := body["data"].(map[string]interface{})
+	if data == nil {
+		return nil, fmt.Errorf("wkbrowser 响应缺少 data（code=%v）", body["code"])
+	}
+
+	// content 为 JSON 字符串或对象，内含 materials/skeleton 图片清单
+	payload := data["content"]
+	if s, ok := payload.(string); ok {
+		var p map[string]interface{}
+		if err := json.Unmarshal([]byte(s), &p); err != nil {
+			return nil, fmt.Errorf("wkbrowser 图片内容解析失败: %w", err)
+		}
+		payload = p
+	}
+
+	uris := collectMangaFallbackURIs(payload)
+	if len(uris) == 0 {
+		return nil, fmt.Errorf("wkbrowser 未找到图片")
+	}
+
+	images := make([]ImageResult, len(uris))
+	for i, u := range uris {
+		images[i] = ImageResult{Data: u, Format: "unknown", Index: i}
+	}
+
+	if showHTML {
+		var b strings.Builder
+		for _, img := range images {
+			fmt.Fprintf(&b, "<img src=\"%s\">\n", img.Data)
+		}
+		return map[string]interface{}{"content": b.String(), "source": "wkbrowser"}, nil
+	}
+	return map[string]interface{}{"images": images, "source": "wkbrowser"}, nil
+}
+
+// collectMangaFallbackURIs 按书源三段策略收集图片链接（保证页序）：
+// 1) skeleton.data 顺序引用 materials 的 key
+// 2) materials key 按末尾数字排序
+// 3) 递归遍历全树兜底（顺序不保证，仅防白屏）
+func collectMangaFallbackURIs(payload interface{}) []string {
+	p, _ := payload.(map[string]interface{})
+	if p == nil {
+		return nil
+	}
+
+	images := make([]string, 0, 32)
+	seen := map[string]bool{}
+	push := func(uri string) {
+		src := mangaFallbackImageURL(uri)
+		if src != "" && !seen[src] {
+			seen[src] = true
+			images = append(images, src)
+		}
+	}
+
+	materials, _ := p["materials"].(map[string]interface{})
+	skeletonWrapper, _ := p["skeleton"].(map[string]interface{})
+	skeleton, _ := skeletonWrapper["data"].([]interface{})
+
+	if materials != nil && skeleton != nil {
+		for _, s := range skeleton {
+			node, _ := s.(map[string]interface{})
+			if node == nil {
+				continue
+			}
+			key := ""
+			for _, k := range []string{"elementInfo", "key", "id"} {
+				if v, _ := node[k].(string); v != "" {
+					key = v
+					break
+				}
+			}
+			if m, ok := materials[key].(map[string]interface{}); ok {
+				if uri := mangaFallbackNodeURI(m); uri != "" {
+					push(uri)
+				}
+			}
+		}
+		if len(images) > 0 {
+			return images
+		}
+	}
+
+	if materials != nil {
+		keys := make([]string, 0, len(materials))
+		for k := range materials {
+			keys = append(keys, k)
+		}
+		sort.Slice(keys, func(i, j int) bool {
+			return trailingNumber(keys[i]) < trailingNumber(keys[j])
+		})
+		for _, k := range keys {
+			if m, ok := materials[k].(map[string]interface{}); ok {
+				if uri := mangaFallbackNodeURI(m); uri != "" {
+					push(uri)
+				}
+			}
+		}
+		if len(images) > 0 {
+			return images
+		}
+	}
+
+	var walk func(node interface{})
+	walk = func(node interface{}) {
+		switch t := node.(type) {
+		case []interface{}:
+			for _, item := range t {
+				walk(item)
+			}
+		case map[string]interface{}:
+			if uri := mangaFallbackNodeURI(t); uri != "" {
+				push(uri)
+				return
+			}
+			for _, v := range t {
+				switch v.(type) {
+				case map[string]interface{}, []interface{}:
+					walk(v)
+				}
+			}
+		}
+	}
+	walk(p)
+	return images
+}
+
+// mangaFallbackNodeURI 从 materials 节点取图片资源（web_uri 优先，其次 novel-pic/md5）
+func mangaFallbackNodeURI(node map[string]interface{}) string {
+	if d, ok := node["data"].(map[string]interface{}); ok {
+		if u, _ := d["web_uri"].(string); u != "" {
+			return u
+		}
+	}
+	if u, _ := node["web_uri"].(string); u != "" {
+		return u
+	}
+	if d, ok := node["data"].(map[string]interface{}); ok {
+		if md5, _ := d["md5"].(string); md5 != "" {
+			return "novel-pic/" + md5
+		}
+	}
+	return ""
+}
+
+// mangaFallbackImageURL web_uri 转可访问的原图直链
+func mangaFallbackImageURL(uri string) string {
+	u := strings.TrimPrefix(uri, "/")
+	if u == "" {
+		return ""
+	}
+	if strings.HasPrefix(u, "http://") {
+		return "https://" + strings.TrimPrefix(u, "http://")
+	}
+	if strings.HasPrefix(u, "https://") {
+		return u
+	}
+	return mangaFallbackOrigin + u
+}
+
+// trailingNumber 取字符串末尾数字（materials key 排序用），无数字排最后
+func trailingNumber(s string) int {
+	m := trailingNumberRe.FindStringSubmatch(s)
+	if m == nil {
+		return 1 << 30
+	}
+	n, _ := strconv.Atoi(m[1])
+	return n
+}

internal/fqapi/manga_fallback_test.go

@@ -0,0 +1,44 @@
+package fqapi
+
+import "testing"
+
+// TestCollectMangaFallbackURIs skeleton 顺序优先、web_uri/md5 取值与原图直链拼接
+func TestCollectMangaFallbackURIs(t *testing.T) {
+	payload := map[string]interface{}{
+		"materials": map[string]interface{}{
+			"img_1": map[string]interface{}{"data": map[string]interface{}{"web_uri": "novel-pic/aaa"}},
+			"img_2": map[string]interface{}{"data": map[string]interface{}{"web_uri": "/novel-pic/bbb"}},
+			"img_3": map[string]interface{}{"data": map[string]interface{}{"md5": "c0ffee"}},
+		},
+		"skeleton": map[string]interface{}{
+			"data": []interface{}{
+				map[string]interface{}{"elementInfo": "img_2"},
+				map[string]interface{}{"key": "img_1"},
+				map[string]interface{}{"id": "img_3"},
+			},
+		},
+	}
+
+	// 页序以 skeleton 引用顺序为准
+	want := []string{
+		"https://p6-novel.byteimg.com/origin/novel-pic/bbb",
+		"https://p6-novel.byteimg.com/origin/novel-pic/aaa",
+		"https://p6-novel.byteimg.com/origin/novel-pic/c0ffee",
+	}
+	got := collectMangaFallbackURIs(payload)
+	if len(got) != len(want) {
+		t.Fatalf("got %d 张 want %d 张: %v", len(got), len(want), got)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Errorf("[%d] got %s want %s", i, got[i], want[i])
+		}
+	}
+
+	// 无 skeleton 时退化为 materials key 末尾数字排序
+	delete(payload, "skeleton")
+	got = collectMangaFallbackURIs(payload)
+	if got[0] != want[1] || got[1] != want[0] {
+		t.Errorf("key 排序错误: %v", got)
+	}
+}

internal/fqapi/manga_proxy.go

@@ -1,72 +1,71 @@
-package fqapi
-
-import (
-	"encoding/hex"
-	"fmt"
-	"time"
-)
-
-// HandleMangaImageProxy 处理漫画图片代理请求
-func HandleMangaImageProxy(itemID string, index int) ([]byte, string, error) {
-	// 从缓存获取图片信息
-	cacheKey := fmt.Sprintf("%s_%d", itemID, index)
-	
-	mangaCacheMutex.RLock()
-	imageInfo, exists := mangaImageCache[cacheKey]
-	mangaCacheMutex.RUnlock()
-	
-	if !exists {
-		return nil, "", fmt.Errorf("图片信息不存在，请先调用 /manga 接口")
-	}
-	
-	// 检查缓存是否过期（5分钟）
-	if time.Since(imageInfo.CachedAt) > 5*time.Minute {
-		// 清理过期缓存
-		mangaCacheMutex.Lock()
-		delete(mangaImageCache, cacheKey)
-		mangaCacheMutex.Unlock()
-		return nil, "", fmt.Errorf("图片信息已过期，请重新调用 /manga 接口")
-	}
-	
-	// 下载加密图片
-	encryptedData, err := downloadImageWithRetry(imageInfo.PicURL, 2)
-	if err != nil {
-		return nil, "", fmt.Errorf("下载图片失败: %w", err)
-	}
-	
-	// 解密图片
-	keyBytes, err := hex.DecodeString(imageInfo.EncryptKey)
-	if err != nil {
-		return nil, "", fmt.Errorf("密钥解码失败: %w", err)
-	}
-	
-	decryptedData, err := decryptImage(encryptedData, keyBytes)
-	if err != nil {
-		return nil, "", fmt.Errorf("解密失败: %w", err)
-	}
-	
-	// 识别格式
-	format := getImageFormat(decryptedData, imageInfo.PicURL)
-	
-	// 返回图片数据和MIME类型
-	mimeType := fmt.Sprintf("image/%s", format)
-	if format == "jpg" {
-		mimeType = "image/jpeg"
-	}
-	
-	return decryptedData, mimeType, nil
-}
-
-// CleanExpiredMangaCache 清理过期的漫画图片缓存
-func CleanExpiredMangaCache() {
-	mangaCacheMutex.Lock()
-	defer mangaCacheMutex.Unlock()
-	
-	now := time.Now()
-	for key, info := range mangaImageCache {
-		if now.Sub(info.CachedAt) > 5*time.Minute {
-			delete(mangaImageCache, key)
-		}
-	}
-}
-
+package fqapi
+
+import (
+	"encoding/hex"
+	"fmt"
+	"time"
+)
+
+// HandleMangaImageProxy 处理漫画图片代理请求
+func HandleMangaImageProxy(itemID string, index int) ([]byte, string, error) {
+	// 从缓存获取图片信息
+	cacheKey := fmt.Sprintf("%s_%d", itemID, index)
+
+	mangaCacheMutex.RLock()
+	imageInfo, exists := mangaImageCache[cacheKey]
+	mangaCacheMutex.RUnlock()
+
+	if !exists {
+		return nil, "", fmt.Errorf("图片信息不存在，请先调用 /manga 接口")
+	}
+
+	// 检查缓存是否过期（5分钟）
+	if time.Since(imageInfo.CachedAt) > 5*time.Minute {
+		// 清理过期缓存
+		mangaCacheMutex.Lock()
+		delete(mangaImageCache, cacheKey)
+		mangaCacheMutex.Unlock()
+		return nil, "", fmt.Errorf("图片信息已过期，请重新调用 /manga 接口")
+	}
+
+	// 下载加密图片
+	encryptedData, err := downloadImageWithRetry(imageInfo.PicURL, 2)
+	if err != nil {
+		return nil, "", fmt.Errorf("下载图片失败: %w", err)
+	}
+
+	// 解密图片
+	keyBytes, err := hex.DecodeString(imageInfo.EncryptKey)
+	if err != nil {
+		return nil, "", fmt.Errorf("密钥解码失败: %w", err)
+	}
+
+	decryptedData, err := decryptImage(encryptedData, keyBytes)
+	if err != nil {
+		return nil, "", fmt.Errorf("解密失败: %w", err)
+	}
+
+	// 识别格式
+	format := getImageFormat(decryptedData, imageInfo.PicURL)
+
+	// 返回图片数据和MIME类型
+	mimeType := fmt.Sprintf("image/%s", format)
+	if format == "jpg" {
+		mimeType = "image/jpeg"
+	}
+
+	return decryptedData, mimeType, nil
+}
+
+// CleanExpiredMangaCache 清理过期的漫画图片缓存
+func CleanExpiredMangaCache() {
+	mangaCacheMutex.Lock()
+	defer mangaCacheMutex.Unlock()
+
+	now := time.Now()
+	for key, info := range mangaImageCache {
+		if now.Sub(info.CachedAt) > 5*time.Minute {
+			delete(mangaImageCache, key)
+		}
+	}
+}

internal/fqapi/media_utils.go

@@ -32,15 +32,15 @@ func extractDeviceParam(deviceHeader, paramName string) string {
 	return ""
 }
 
-// downloadMediaWithRetry 带重试的媒体下载，自动切换设备
-func downloadMediaWithRetry(url, deviceID string, headers map[string]string, maxRetries int) ([]byte, string, error) {
+// downloadMediaWithRetry 带重试的流式媒体下载，自动切换设备（仅响应阶段可重试）
+func downloadMediaWithRetry(url, deviceID string, headers map[string]string, maxRetries int) (io.ReadCloser, string, error) {
 	var lastErr error
 	currentDeviceID := deviceID
 
 	for i := 0; i <= maxRetries; i++ {
-		data, contentType, err := downloadMedia(url, currentDeviceID, headers)
-		if err == nil && len(data) > 0 {
-			return data, contentType, nil
+		body, contentType, err := downloadMedia(url, currentDeviceID, headers)
+		if err == nil {
+			return body, contentType, nil
 		}
 		lastErr = err
 
@@ -58,9 +58,10 @@ func downloadMediaWithRetry(url, deviceID string, headers map[string]string, max
 	return nil, "", fmt.Errorf("下载失败（已重试%d次）: %w", maxRetries, lastErr)
 }
 
-// downloadMedia 下载媒体内容
-func downloadMedia(url, deviceID string, headers map[string]string) ([]byte, string, error) {
-	// 创建专用的媒体下载客户端，超时时间更长
+// downloadMedia 流式下载媒体内容：拿到响应头即返回，Body 由调用方消费
+// 大文件不再整体驻留内存；Body 读取中途的错误无法重试，由客户端自行重试
+func downloadMedia(url, deviceID string, headers map[string]string) (io.ReadCloser, string, error) {
+	// 创建专用的媒体下载客户端，超时时间更长（Timeout 覆盖整个响应周期含 Body 传输）
 	client := &http.Client{
 		Timeout: 300 * time.Second, // 5分钟超时，适合大文件
 	}
@@ -70,6 +71,30 @@ func downloadMedia(url, deviceID string, headers map[string]string) ([]byte, str
 		return nil, "", err
 	}
 
+	setMediaHeaders(req, deviceID, headers)
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, "", fmt.Errorf("下载失败: %v", err)
+	}
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		resp.Body.Close()
+		return nil, "", fmt.Errorf("HTTP状态码: %d", resp.StatusCode)
+	}
+
+	// 获取Content-Type
+	contentType := resp.Header.Get("Content-Type")
+	if contentType == "" {
+		// 根据文件后缀推断
+		contentType = getContentTypeFromURL(url)
+	}
+
+	return resp.Body, contentType, nil
+}
+
+// setMediaHeaders 设置媒体下载请求头（CDN 伪装 + 设备信息 + 自定义头）
+func setMediaHeaders(req *http.Request, deviceID string, headers map[string]string) {
 	// 设置CDN请求头，模拟安卓客户端请求
 	req.Header.Set("User-Agent", "com.dragon.read/7.9.9.32 (Linux; U; Android 13; zh_CN; M2102K1AC; Build/TKQ1.220807.001; Cronet/113.0.5672.62)")
 	req.Header.Set("Accept", "*/*")
@@ -89,31 +114,6 @@ func downloadMedia(url, deviceID string, headers map[string]string) ([]byte, str
 	for k, v := range headers {
 		req.Header.Set(k, v)
 	}
-
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, "", fmt.Errorf("下载失败: %v", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return nil, "", fmt.Errorf("HTTP状态码: %d", resp.StatusCode)
-	}
-
-	// 读取内容
-	data, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return nil, "", fmt.Errorf("读取内容失败: %w", err)
-	}
-
-	// 获取Content-Type
-	contentType := resp.Header.Get("Content-Type")
-	if contentType == "" {
-		// 根据文件后缀推断
-		contentType = getContentTypeFromURL(url)
-	}
-
-	return data, contentType, nil
 }
 
 // getContentTypeFromURL 根据URL推断Content-Type
@@ -179,11 +179,16 @@ func processMediaURL(originalURL, deviceID string, headers map[string]string, ou
 		// 其他类型返回原始URL
 		return originalURL
 	case "data_uri":
-		// 直接下载并返回base64
-		data, contentType, err := downloadMediaWithRetry(originalURL, deviceID, headers, 2)
+		// 直接下载并返回base64（data_uri 模式本就要求全量驻留内存）
+		body, contentType, err := downloadMediaWithRetry(originalURL, deviceID, headers, 2)
 		if err != nil {
 			return originalURL
 		}
+		data, readErr := io.ReadAll(body)
+		body.Close()
+		if readErr != nil {
+			return originalURL
+		}
 		return fmt.Sprintf("data:%s;base64,%s", contentType, base64.StdEncoding.EncodeToString(data))
 	default:
 		// 直接返回原始URL

internal/fqapi/multi_content.go

@@ -1,14 +1,9 @@
 package fqapi
 
 import (
-	"bytes"
-	"compress/zlib"
-	"encoding/base64"
 	"encoding/json"
 	"fanqie/internal/common"
 	"fmt"
-	"io"
-	"sort"
 	"strings"
 	"sync"
 )
@@ -17,57 +12,29 @@ var (
 	multiContentLogger = common.NewLogger("multi_content", "INFO", "")
 )
 
-// handleDecryptTask 处理解密任务
+// handleDecryptTask 处理解密任务（crypt_status 分支见 decodeContentBody）
 func handleDecryptTask(itemID string, itemData map[string]interface{}, keyInfo *KeyInfo, textMode, imageMode bool) (string, map[string]interface{}) {
 	if code, ok := itemData["code"].(float64); !ok || code != 0 {
 		return itemID, itemData
 	}
 
-	contentEncoded, ok := itemData["content"].(string)
-	if !ok {
+	if _, ok := itemData["content"].(string); !ok {
 		return itemID, itemData
 	}
 
-	// 解码content
-	contentBytes, err := base64.StdEncoding.DecodeString(contentEncoded)
-	if err != nil || len(contentBytes) < 16 {
+	// 解密（含压缩与明文分支）
+	contentStr, err := decodeContentBody(itemData, keyInfo)
+	if err != nil || contentStr == "" {
+		// 解密失败保留上游原样（ignore_failed 默认跳过失败章节）
 		return itemID, itemData
 	}
 
-	iv := contentBytes[0:16]
-	encryptedData := contentBytes[16:]
-
-	// 解密
-	if keyInfo == nil {
-		return itemID, itemData
-	}
-
-	keyBytes, _ := base64.StdEncoding.DecodeString(keyInfo.Key)
-	decrypted, err := De(encryptedData, keyBytes, iv)
-	if err != nil {
-		return itemID, itemData
-	}
-
-	// 检查是否需要解压
-	compressStatus, _ := itemData["compress_status"].(float64)
-	if compressStatus != 0 {
-		// zlib解压
-		reader, err := zlib.NewReader(bytes.NewReader(decrypted))
-		if err == nil {
-			decompressed, err := io.ReadAll(reader)
-			reader.Close()
-			if err == nil {
-				decrypted = decompressed
-			}
-		}
-	}
-
 	// 更新内容
 	bodyCopy := make(map[string]interface{})
 	for k, v := range itemData {
 		bodyCopy[k] = v
 	}
-	bodyCopy["content"] = string(decrypted)
+	bodyCopy["content"] = contentStr
 
 	// 缓存
 	cacheData := buildCacheData(bodyCopy)
@@ -75,16 +42,16 @@ func handleDecryptTask(itemID string, itemData map[string]interface{}, keyInfo *
 
 	// 解析内容
 	parser := NewContentParser()
-	bodyCopy["content"] = parser.Parse(string(decrypted), textMode, imageMode)
+	bodyCopy["content"] = parser.Parse(contentStr, textMode, imageMode)
 
 	return itemID, bodyCopy
 }
 
 // MultiContent 批量获取内容
 func MultiContent(itemIDs interface{}, bookID string, textMode, imageMode, ignoreFailed interface{}, depth int) (string, error) {
-	// 参数转换
-	textModeBool := parseBoolParam(textMode)
-	imageModeBool := parseBoolParamDefault(imageMode, true)
+	// 参数转换（URL 参数优先，未传时回退配置）
+	textModeBool := parseBoolParamDefault(textMode, getContentConfig().RemoveHTMLTags)
+	imageModeBool := parseBoolParamDefault(imageMode, !getContentConfig().RemoveImages)
 	ignoreFailedBool := parseBoolParamDefault(ignoreFailed, true)
 
 	if depth > 3 {
@@ -116,15 +83,16 @@ func MultiContent(itemIDs interface{}, bookID string, textMode, imageMode, ignor
 	if err != nil {
 		return `{"code": -1, "msg": "从设备池获取设备失败"}`, err
 	}
-	
+
 	header := item.DeviceHeader
 	currentKeyInfo := &KeyInfo{
 		Key: item.Key,
 		Ver: item.KeyVer,
+		Ts:  item.KeyTs,
 	}
 	multiContentLogger.Debug(fmt.Sprintf("使用池中设备 ID=%d (depth: %d)", item.ID, depth))
 
-	// 构建参数
+	// 构建参数（form 编码，见 buildSortedQuery 注释）
 	headerWithoutVersion := removeVersionFromHeader(header)
 
 	params := []string{
@@ -133,18 +101,15 @@ func MultiContent(itemIDs interface{}, bookID string, textMode, imageMode, ignor
 		"channel=0",
 		"device_platform=android",
 		"os_version=0",
-		"version_code=66.9",
+		"version_code=" + ClientVersionCode,
 		"book_id=" + bookID,
 		"item_ids=" + itemIDStr,
 		"novel_text_type=1",
 		"req_type=1",
+		fmt.Sprintf("key_register_ts=%d", currentKeyInfo.Ts),
 		headerWithoutVersion,
 	}
-
-	allParams := strings.Join(params, "&")
-	paramList := strings.Split(allParams, "&")
-	sort.Strings(paramList)
-	sortedParams := strings.Join(paramList, "&")
+	sortedParams := buildSortedQuery(params...)
 
 	url := "https://reading.snssdk.com/reading/reader/batch_full/v/?" + sortedParams
 
@@ -205,7 +170,7 @@ func MultiContent(itemIDs interface{}, bookID string, textMode, imageMode, ignor
 					multiContentLogger.Warning("密钥版本不匹配，重新获取密钥")
 					newKeyInfo, err := GetKey(header)
 					if err == nil {
-						UpdateKeyInPool(header, newKeyInfo.Key, newKeyInfo.Ver)
+						UpdateKeyInPool(header, newKeyInfo)
 					} else {
 						// 获取密钥失败，切换设备
 						multiContentLogger.Warning(fmt.Sprintf("获取密钥失败，切换设备重试 (depth: %d)", depth))
@@ -256,7 +221,7 @@ func MultiContent(itemIDs interface{}, bookID string, textMode, imageMode, ignor
 
 		// 构建响应
 		response := buildCacheData(results)
-		return buildJSONResponse(response), nil
+		return buildJSONResponse(UnwrapJSONStrings(response)), nil
 	}
 
 	// 响应code不为0，切换设备重试
@@ -270,4 +235,3 @@ func MultiContent(itemIDs interface{}, bookID string, textMode, imageMode, ignor
 func HandleMultiContent(itemIDs interface{}, bookID string, textMode, imageMode, ignoreFailed interface{}) (string, error) {
 	return MultiContent(itemIDs, bookID, textMode, imageMode, ignoreFailed, 0)
 }
-

internal/fqapi/multi_detail.go

@@ -1,9 +1,9 @@
 package fqapi
 
 import (
-	"encoding/json"
 	"fanqie/internal/common"
 	"fmt"
+	"sort"
 	"strings"
 	"sync"
 )
@@ -107,8 +107,44 @@ func chunkArray(arr []string, size int) [][]string {
 	return chunks
 }
 
-// HandleGetMultiDetail 处理批量获取书籍详情
+// HandleGetMultiDetail 处理批量获取书籍详情,详情数据基本不变,缓存 24 小时
 func HandleGetMultiDetail(bookID interface{}) (string, error) {
+	// 缓存 key 归一化：ID 排序去重，相同集合不同顺序共享缓存
+	ids := normalizeIDList(bookID)
+	if ids == "" {
+		return fetchMultiDetail(bookID)
+	}
+	return withCache("multi_detail_"+ids, 86400, func() (string, error) {
+		return fetchMultiDetail(bookID)
+	})
+}
+
+// normalizeIDList 将 book_id 参数归一化为排序去重后的逗号串
+func normalizeIDList(bookID interface{}) string {
+	var list []string
+	switch v := bookID.(type) {
+	case string:
+		list = strings.Split(v, ",")
+	case []string:
+		list = v
+	default:
+		return ""
+	}
+	seen := make(map[string]bool, len(list))
+	out := make([]string, 0, len(list))
+	for _, id := range list {
+		id = strings.TrimSpace(id)
+		if id == "" || seen[id] {
+			continue
+		}
+		seen[id] = true
+		out = append(out, id)
+	}
+	sort.Strings(out)
+	return strings.Join(out, ",")
+}
+
+func fetchMultiDetail(bookID interface{}) (string, error) {
 	if bookID == nil {
 		return BuildErrorResponse("需要参数 book_id"), nil
 	}
@@ -209,7 +245,5 @@ func HandleGetMultiDetail(bookID interface{}) (string, error) {
 		"data":    res,
 	}
 
-	resultBytes, _ := json.Marshal(response)
-	return string(resultBytes), nil
+	return marshalNoEscape(UnwrapJSONStrings(response)), nil
 }
-

internal/fqapi/rank.go

@@ -0,0 +1,77 @@
+package fqapi
+
+import (
+	"fanqie/internal/common"
+	"fmt"
+	"net/url"
+)
+
+var rankLogger = common.NewLogger("rank", "INFO", "")
+
+// rankSDKHosts 免签名榜单接口的可用域名（依次容错）
+var rankSDKHosts = []string{
+	"https://novel.snssdk.com",
+	"https://api.fanqiesdk.com",
+	"https://api-lf.fanqiesdk.com",
+}
+
+const rankSDKUA = "com.ss.android.article.news/7.0.3 (Linux; U; Android 12; zh_CN; Pixel 6)"
+
+// RankTypes 榜单类型
+var RankTypes = map[int]string{
+	10: "推荐榜",
+	11: "完结榜",
+	12: "热搜榜",
+	13: "黑马榜",
+	15: "爆更榜",
+}
+
+// HandleGetRank 处理获取榜单,榜单数据动态,短缓存 10 分钟
+// sideType 见 RankTypes（无效值回退推荐榜）；page 从 1 起，每页 20 本
+func HandleGetRank(sideType, page int) (string, error) {
+	if _, ok := RankTypes[sideType]; !ok {
+		sideType = 10
+	}
+	if page < 1 {
+		page = 1
+	}
+	return withCache(fmt.Sprintf("rank_%d_%d", sideType, page), 600, func() (string, error) {
+		return fetchRank(sideType, page)
+	})
+}
+
+// fetchRank 免签名 SDK 接口获取榜单（无设备/签名依赖，多域名容错）
+func fetchRank(sideType, page int) (string, error) {
+	vals := url.Values{
+		"aid":       {"13"},
+		"type":      {"1"},
+		"side_type": {fmt.Sprintf("%d", sideType)},
+		"offset":    {fmt.Sprintf("%d", page-1)},
+		"limit":     {"20"},
+	}
+	path := "/api/novel/channel/homepage/rank/rank_list/v2/?" + vals.Encode()
+
+	var lastErr error
+	client := common.NewHTTPClient()
+	for _, host := range rankSDKHosts {
+		resp, err := client.Get(host+path, map[string]string{
+			"User-Agent": rankSDKUA,
+			"Accept":     "application/json, text/plain, */*",
+		})
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		respJSON, err := resp.JSON()
+		if err != nil {
+			lastErr = fmt.Errorf("响应解析失败: %w", err)
+			continue
+		}
+		if code, ok := respJSON["code"].(float64); ok && code == 0 {
+			return reencodeUnwrapped(resp.Text), nil
+		}
+		lastErr = fmt.Errorf("code=%.0f msg=%v", respJSON["code"], respJSON["message"])
+	}
+	rankLogger.Error(fmt.Sprintf("获取榜单失败: %v", lastErr))
+	return BuildErrorResponse("获取榜单失败"), lastErr
+}

internal/fqapi/rebind_test.go

@@ -0,0 +1,20 @@
+package fqapi
+
+import "testing"
+
+// TestRebind 验证占位符方言转换
+func TestRebind(t *testing.T) {
+	in := "INSERT INTO cache (key, value) VALUES (?, ?)"
+
+	if got := q(in); got != in {
+		t.Errorf("sqlite 下应保持 ?: %s", got)
+	}
+
+	dbDriver = "pgx"
+	defer func() { dbDriver = "sqlite3" }()
+
+	want := "INSERT INTO cache (key, value) VALUES ($1, $2)"
+	if got := q(in); got != want {
+		t.Errorf("pg 下应转换占位符: got %s want %s", got, want)
+	}
+}

internal/fqapi/register_key.go

@@ -12,15 +12,13 @@ import (
 	"fmt"
 	"math/rand"
 	"regexp"
-	"sort"
-	"strings"
-	"time"
 )
 
 // KeyInfo 密钥信息
 type KeyInfo struct {
 	Key string `json:"key"`
 	Ver int    `json:"ver"`
+	Ts  int64  `json:"ts"` // 密钥注册时间戳（key_register_ts），随正文请求上传可降低密钥不匹配重试
 }
 
 var (
@@ -70,11 +68,17 @@ func createSymmetricCrypto(algorithm string, key, iv []byte) (func([]byte) ([]by
 		decrypted := make([]byte, len(data))
 		mode.CryptBlocks(decrypted, data)
 
-		// 移除PKCS7填充
+		// 移除PKCS7填充（完整校验：密钥错误时尾部为随机字节，
+		// 弱校验会让乱码静默通过并返回 200）
 		padding := int(decrypted[len(decrypted)-1])
-		if padding > len(decrypted) || padding > aes.BlockSize {
+		if padding < 1 || padding > len(decrypted) || padding > aes.BlockSize {
 			return nil, fmt.Errorf("无效的填充")
 		}
+		for _, b := range decrypted[len(decrypted)-padding:] {
+			if int(b) != padding {
+				return nil, fmt.Errorf("无效的填充")
+			}
+		}
 
 		return decrypted[:len(decrypted)-padding], nil
 	}
@@ -148,25 +152,22 @@ func GetKey(header string) (*KeyInfo, error) {
 
 	keyLogger.Info("正在获取密钥...")
 
-	// 构建参数
+	// 构建参数（form 编码：机型含空格等字符时 URL 与签名一致才不会注册失败）
 	params := []string{
 		"aid=1967",
 		"app_name=novelapp",
 		"channel=0",
 		"device_platform=android",
 		"os_version=0",
-		"version_code=5.8.9.32",
+		"version_code=" + ClientVersionCode,
 		header,
 	}
-
-	allParams := strings.Join(params, "&")
-	paramList := strings.Split(allParams, "&")
-	sort.Strings(paramList)
-	sortedParams := strings.Join(paramList, "&")
+	sortedParams := buildSortedQuery(params...)
 
 	// 准备请求体
 	requestBody := map[string]string{
 		"content": content,
+		"keyver":  "1",
 	}
 
 	bodyJSON, _ := json.Marshal(requestBody)
@@ -197,6 +198,12 @@ func GetKey(header string) (*KeyInfo, error) {
 		var respData map[string]interface{}
 		json.Unmarshal(resp.Content, &respData)
 
+		// 上游判定该设备无需解密（正文明文下发），返回空密钥信息由调用方分支处理
+		if code, ok := respData["code"].(float64); ok && int(code) == 500003 {
+			keyLogger.Info("上游标记无需解密（code=500003）")
+			return &KeyInfo{}, nil
+		}
+
 		dataObj, ok := respData["data"].(map[string]interface{})
 		if !ok {
 			return nil, fmt.Errorf("响应格式错误")
@@ -225,12 +232,17 @@ func GetKey(header string) (*KeyInfo, error) {
 		finalKey := base64.StdEncoding.EncodeToString(decryptedKey)
 
 		keyVer, _ := dataObj["keyver"].(float64)
+		keyTs, _ := dataObj["key_register_ts"].(float64)
+		if keyTs == 0 {
+			keyTs, _ = dataObj["register_time"].(float64)
+		}
 		keyInfo = &KeyInfo{
 			Key: finalKey,
 			Ver: int(keyVer),
+			Ts:  int64(keyTs),
 		}
 
-		keyLogger.Info(fmt.Sprintf("密钥获取成功！"))
+		keyLogger.Info("密钥获取成功！")
 
 		return keyInfo, nil
 	}
@@ -242,8 +254,3 @@ func GetKey(header string) (*KeyInfo, error) {
 func GetKeyInfo() *KeyInfo {
 	return keyInfo
 }
-
-func init() {
-	rand.Seed(time.Now().UnixNano())
-}
-

internal/fqapi/request_log.go

@@ -0,0 +1,315 @@
+package fqapi
+
+import (
+	"fanqie/internal/config"
+	"fmt"
+	"strings"
+	"time"
+)
+
+// 请求日志：只记元数据（时间/IP/方法/路径/状态/耗时）与错误响应摘要，不存响应体。
+// 全量响应与正文缓存重复且体积不可控；要看重放一个请求即可。
+
+// RequestLogEntry 一条请求日志
+type RequestLogEntry struct {
+	Ts         int64  `json:"ts"`
+	IP         string `json:"ip"`
+	Method     string `json:"method"`
+	Path       string `json:"path"`
+	Query      string `json:"query"`     // 解码后查询串（key 参数值已脱敏）
+	Status     int    `json:"status"`
+	DurationMs int64  `json:"duration_ms"`
+	ErrorMsg   string `json:"error_msg"`  // 仅 status>=400 时截断保留
+	UserAgent  string `json:"user_agent"` // 客户端 UA，排障时区分调用方
+}
+
+// ErrMsgMax 错误响应摘要的最大保留字节数
+const ErrMsgMax = 4096
+
+const (
+	reqLogChanSize   = 256          // channel 满则丢弃，日志绝不阻塞请求
+	reqLogFlushBatch = 50           // 攒批上限
+	reqLogFlushEvery = time.Second  // 兜底 flush 间隔
+	reqLogCleanEvery = time.Hour    // 过期清理间隔
+)
+
+var (
+	reqLogCh   chan RequestLogEntry
+	reqLogQuit chan struct{}
+	reqLogDone chan struct{}
+)
+
+// InitRequestLog 建表并启动后台落库协程（未启用时为空操作）
+func InitRequestLog() error {
+	if !requestLogEnabled() {
+		return nil
+	}
+
+	ddl := `CREATE TABLE IF NOT EXISTS request_log (
+		id INTEGER PRIMARY KEY AUTOINCREMENT,
+		ts INTEGER NOT NULL,
+		ip TEXT,
+		method TEXT,
+		path TEXT,
+		query TEXT,
+		status INTEGER,
+		duration_ms INTEGER,
+		error_msg TEXT,
+		user_agent TEXT,
+		created_at INTEGER DEFAULT (strftime('%s', 'now')),
+		updated_at INTEGER DEFAULT (strftime('%s', 'now'))
+	)`
+	if dbDriver == "pgx" {
+		ddl = `CREATE TABLE IF NOT EXISTS request_log (
+		id BIGSERIAL PRIMARY KEY,
+		ts BIGINT NOT NULL,
+		ip TEXT,
+		method TEXT,
+		path TEXT,
+		query TEXT,
+		status INTEGER,
+		duration_ms BIGINT,
+		error_msg TEXT,
+		user_agent TEXT,
+		created_at BIGINT DEFAULT extract(epoch FROM now())::bigint,
+		updated_at BIGINT DEFAULT extract(epoch FROM now())::bigint
+	)`
+	}
+	if _, err := cacheDB.Exec(ddl); err != nil {
+		return fmt.Errorf("创建request_log表失败: %w", err)
+	}
+	// 旧表补列（表已存在时 CREATE 不会加列；PG 支持 IF NOT EXISTS，SQLite 报错即视为已存在）
+	if dbDriver == "pgx" {
+		for _, col := range []string{
+			`ALTER TABLE request_log ADD COLUMN IF NOT EXISTS user_agent TEXT`,
+			`ALTER TABLE request_log ADD COLUMN IF NOT EXISTS created_at BIGINT DEFAULT 0`,
+			`ALTER TABLE request_log ADD COLUMN IF NOT EXISTS updated_at BIGINT DEFAULT 0`,
+		} {
+			if _, err := cacheDB.Exec(col); err != nil {
+				cacheLogger.Warning("补加列失败: " + err.Error())
+			}
+		}
+	} else {
+		for _, col := range []string{
+			`ALTER TABLE request_log ADD COLUMN user_agent TEXT`,
+			`ALTER TABLE request_log ADD COLUMN created_at INTEGER DEFAULT 0`,
+			`ALTER TABLE request_log ADD COLUMN updated_at INTEGER DEFAULT 0`,
+		} {
+			if _, err := cacheDB.Exec(col); err != nil {
+				cacheLogger.Debug("补列跳过（已存在）: " + err.Error())
+			}
+		}
+	}
+	// append-only 日志表：旧行按 ts 回填两个时间列（幂等）
+	if _, err := cacheDB.Exec(q(`UPDATE request_log SET created_at = ts, updated_at = ts WHERE created_at = 0`)); err != nil {
+		cacheLogger.Warning("request_log时间列回填失败: " + err.Error())
+	}
+	for _, idx := range []string{
+		`CREATE INDEX IF NOT EXISTS idx_request_log_ts ON request_log(ts)`,
+		`CREATE INDEX IF NOT EXISTS idx_request_log_ip ON request_log(ip)`,
+		`CREATE INDEX IF NOT EXISTS idx_request_log_status ON request_log(status)`,
+	} {
+		if _, err := cacheDB.Exec(idx); err != nil {
+			cacheLogger.Warning("创建request_log索引失败: " + err.Error())
+		}
+	}
+
+	reqLogCh = make(chan RequestLogEntry, reqLogChanSize)
+	reqLogQuit = make(chan struct{})
+	reqLogDone = make(chan struct{})
+	go reqLogWorker()
+	cacheLogger.Info("请求日志已启用")
+	return nil
+}
+
+// CloseRequestLog 停止后台协程并落盘剩余日志
+func CloseRequestLog() {
+	if reqLogQuit == nil {
+		return
+	}
+	close(reqLogQuit)
+	<-reqLogDone
+	reqLogQuit = nil
+}
+
+// LogRequest 非阻塞投递一条请求日志（未启用/队列满时静默丢弃）
+func LogRequest(e RequestLogEntry) {
+	if reqLogCh == nil {
+		return
+	}
+	select {
+	case reqLogCh <- e:
+	default:
+	}
+}
+
+// GetRecentRequests 查询最近 limit 条请求日志
+func GetRecentRequests(limit int) []RequestLogEntry {
+	if cacheDB == nil || reqLogCh == nil {
+		return nil
+	}
+	rows, err := cacheDB.Query(
+		q("SELECT ts, ip, method, path, query, status, duration_ms, COALESCE(error_msg, ''), COALESCE(user_agent, '') FROM request_log ORDER BY id DESC LIMIT ?"), limit)
+	if err != nil {
+		cacheLogger.Warning("查询请求日志失败: " + err.Error())
+		return nil
+	}
+	defer rows.Close()
+
+	entries := make([]RequestLogEntry, 0, limit)
+	for rows.Next() {
+		var e RequestLogEntry
+		if err := rows.Scan(&e.Ts, &e.IP, &e.Method, &e.Path, &e.Query, &e.Status, &e.DurationMs, &e.ErrorMsg, &e.UserAgent); err != nil {
+			cacheLogger.Warning("读取请求日志失败: " + err.Error())
+			break
+		}
+		entries = append(entries, e)
+	}
+	return entries
+}
+
+// DailyStat 一天的请求量统计
+type DailyStat struct {
+	Day      string `json:"day"`       // 本地时区 MM-DD
+	Count    int64  `json:"count"`
+	Pct      int    `json:"pct"`       // 相对窗口峰值的百分比（进度条宽度）
+	MaxCount bool   `json:"max_count"` // 是否为窗口内峰值（前端高亮用）
+}
+
+// GetDailyRequestStats 按本地时区分天统计最近 days 天（含今天）的请求量，依赖 request_log。
+// ponytail: (ts+固定偏移)/86400 分组，DST 切换日边界误差 1 小时，趋势展示可接受
+func GetDailyRequestStats(days int) []DailyStat {
+	if cacheDB == nil || reqLogCh == nil || days <= 0 {
+		return nil
+	}
+	_, off := time.Now().Zone()
+	day := func(ts int64) int64 { return (ts + int64(off)) / 86400 }
+	cutoff := (day(time.Now().Unix()) - int64(days) + 1) * 86400 - int64(off)
+
+	rows, err := cacheDB.Query(q(
+		"SELECT (ts + ?) / 86400, COUNT(*) FROM request_log WHERE ts >= ? GROUP BY 1 ORDER BY 1"),
+		int64(off), cutoff)
+	if err != nil {
+		cacheLogger.Warning("按天聚合请求量失败: " + err.Error())
+		return nil
+	}
+	defer rows.Close()
+
+	counts := make(map[int64]int64, days)
+	var maxCount int64
+	for rows.Next() {
+		var d, c int64
+		if err := rows.Scan(&d, &c); err != nil {
+			cacheLogger.Warning("读取按天统计失败: " + err.Error())
+			break
+		}
+		counts[d] = c
+		if c > maxCount {
+			maxCount = c
+		}
+	}
+
+	// 补齐无请求的日期，升序返回
+	stats := make([]DailyStat, 0, days)
+	for i := int64(days) - 1; i >= 0; i-- {
+		d := day(time.Now().Unix()) - i
+		c := counts[d]
+		var pct int
+		if maxCount > 0 {
+			pct = int(c * 100 / maxCount)
+		}
+		stats = append(stats, DailyStat{
+			Day:      time.Unix(d*86400-int64(off), 0).Format("01-02"),
+			Count:    c,
+			Pct:      pct,
+			MaxCount: c > 0 && c == maxCount,
+		})
+	}
+	return stats
+}
+
+// reqLogWorker 攒批落库 + 定期清理过期日志
+func reqLogWorker() {
+	defer close(reqLogDone)
+
+	batch := make([]RequestLogEntry, 0, reqLogFlushBatch)
+	flush := func() {
+		if len(batch) == 0 {
+			return
+		}
+		if err := insertRequestLogs(batch); err != nil {
+			cacheLogger.Warning("写入请求日志失败: " + err.Error())
+		}
+		batch = batch[:0]
+	}
+	defer flush()
+
+	ticker := time.NewTicker(reqLogFlushEvery)
+	cleanTicker := time.NewTicker(reqLogCleanEvery)
+	defer ticker.Stop()
+	defer cleanTicker.Stop()
+
+	for {
+		select {
+		case e := <-reqLogCh:
+			batch = append(batch, e)
+			if len(batch) >= reqLogFlushBatch {
+				flush()
+			}
+		case <-ticker.C:
+			flush()
+		case <-cleanTicker.C:
+			cleanupRequestLog()
+		case <-reqLogQuit:
+			// 排空 channel 后退出
+			for {
+				select {
+				case e := <-reqLogCh:
+					batch = append(batch, e)
+				default:
+					return
+				}
+			}
+		}
+	}
+}
+
+// insertRequestLogs 多值 INSERT 一次往返写入整批（单条语句自带原子性）
+// ponytail: 批量上限 50 行 × 9 列 = 450 参数，远低于 SQLite(999)/PG(65535) 占位符上限
+func insertRequestLogs(batch []RequestLogEntry) error {
+	var b strings.Builder
+	b.WriteString("INSERT INTO request_log (ts, ip, method, path, query, status, duration_ms, error_msg, user_agent) VALUES ")
+	args := make([]interface{}, 0, len(batch)*9)
+	for i, e := range batch {
+		if i > 0 {
+			b.WriteByte(',')
+		}
+		b.WriteString("(?, ?, ?, ?, ?, ?, ?, ?, ?)")
+		args = append(args, e.Ts, e.IP, e.Method, e.Path, e.Query, e.Status, e.DurationMs, e.ErrorMsg, e.UserAgent)
+	}
+	_, err := cacheDB.Exec(q(b.String()), args...)
+	return err
+}
+
+// cleanupRequestLog 删除超过保留期的日志
+func cleanupRequestLog() {
+	if !requestLogEnabled() {
+		return
+	}
+	days := 7
+	if cfg := config.GetAppConfig(); cfg != nil && cfg.Server.RequestLog.RetentionDays > 0 {
+		days = cfg.Server.RequestLog.RetentionDays
+	}
+	cutoff := time.Now().Unix() - int64(days)*86400
+	if result, err := cacheDB.Exec(q("DELETE FROM request_log WHERE ts < ?"), cutoff); err != nil {
+		cacheLogger.Warning("清理请求日志失败: " + err.Error())
+	} else if n, _ := result.RowsAffected(); n > 0 {
+		cacheLogger.Info(fmt.Sprintf("已清理 %d 条过期请求日志（保留 %d 天）", n, days))
+	}
+}
+
+// requestLogEnabled 配置启用且数据库可用
+func requestLogEnabled() bool {
+	cfg := config.GetAppConfig()
+	return cfg != nil && cfg.Server.RequestLog.Enabled && cacheDB != nil
+}

internal/fqapi/review.go

@@ -6,6 +6,8 @@ import (
 	"encoding/json"
 	"fanqie/internal/common"
 	"fmt"
+	"regexp"
+	"strconv"
 	"strings"
 )
 
@@ -62,8 +64,11 @@ func postReviewAPI(url string, requestBody interface{}) (map[string]interface{},
 		return nil, fmt.Errorf("解析响应失败: %w", err)
 	}
 
-	// 提取 data 字段
+	// 提取 data 字段（并解包 JSON 字符串字段，如 post_data.content）
 	if data, ok := result["data"].(map[string]interface{}); ok {
+		if unwrapped, ok := UnwrapJSONStrings(data).(map[string]interface{}); ok {
+			return unwrapped, nil
+		}
 		return data, nil
 	}
 
@@ -169,8 +174,11 @@ func GetParaReview(itemID, bookID, commentID string, para, sort, offset, count i
 		return nil, fmt.Errorf("解析响应失败: %w", err)
 	}
 
-	// 提取 data 字段
+	// 提取 data 字段（并解包 JSON 字符串字段，如 post_data.content）
 	if data, ok := result["data"].(map[string]interface{}); ok {
+		if unwrapped, ok := UnwrapJSONStrings(data).(map[string]interface{}); ok {
+			return unwrapped, nil
+		}
 		return data, nil
 	}
 
@@ -235,103 +243,33 @@ func GenerateParagraphsWithComments(itemID, bookID, content, baseURL string) (st
 		strings.Contains(content, "<div") ||
 		strings.Contains(content, "<article")
 
-	// 关键：如果检测到有段评数据，强制使用HTML模式（包裹<p>标签）
-	// 因为<comment>标签需要XML兼容的格式
-	hasAnyComments := len(commentData) > 0
-	if hasAnyComments && !isHTMLContent {
-		isHTMLContent = true
+	// 纯文本模式下 <comment> 标签无法承载，保持纯文本原样返回（不注入段评）；
+	// 需要段评标记时配置 remove_html_tags: false 或 text_mode=html
+	if !isHTMLContent {
+		return content, nil
 	}
 
-	lines := strings.Split(content, "\n")
-	var result strings.Builder
-	paragraphIndex := 0
-
-	for i, line := range lines {
-		isLastLine := i == len(lines)-1
-		trimmedLine := strings.TrimSpace(line)
-
-		// 完全空行：直接输出换行符
-		if trimmedLine == "" {
-			if !isLastLine {
-				result.WriteString("\n")
-			}
-			continue
-		}
-
-		// 跳过图片标签和div标签
-		if strings.HasPrefix(trimmedLine, "<img") ||
-			strings.HasPrefix(trimmedLine, "<div") ||
-			strings.HasPrefix(trimmedLine, "</div>") ||
-			strings.HasPrefix(trimmedLine, "<article") ||
-			strings.HasPrefix(trimmedLine, "</article") {
-			result.WriteString(line)
-			if !isLastLine {
-				result.WriteString("\n")
-			}
-			continue
-		}
-
-		// 如果原内容已经有<p>标签，在</p>之前插入段评标记
-		if strings.HasPrefix(trimmedLine, "<p>") && strings.HasSuffix(trimmedLine, "</p>") {
-			// 提取<p>和</p>之间的内容
-			innerContent := trimmedLine[3 : len(trimmedLine)-4]
-			result.WriteString("<p>")
-			result.WriteString(innerContent)
-
-			// 添加评论标记
-			key := fmt.Sprintf("%d", paragraphIndex)
-			if commentInfo, exists := commentData[key]; exists && commentInfo.Count > 0 {
-				commentTag := fmt.Sprintf(`<comment ident="%s/review_html?item_id=%s&book_id=%s&para=%d" count="%d" />`,
-					baseURL, itemID, bookID, paragraphIndex, commentInfo.Count)
-				result.WriteString(commentTag)
-			}
-
-			result.WriteString("</p>")
-			if !isLastLine {
-				result.WriteString("\n")
-			}
-			paragraphIndex++
-			continue
-		}
-
-		// 如果是HTML模式，包裹<p>标签
-		if isHTMLContent {
-			result.WriteString("<p>")
-			result.WriteString(line)
-
-			// 添加评论标记
-			key := fmt.Sprintf("%d", paragraphIndex)
-			if commentInfo, exists := commentData[key]; exists && commentInfo.Count > 0 {
-				commentTag := fmt.Sprintf(`<comment ident="%s/review_html?item_id=%s&book_id=%s&para=%d" count="%d" />`,
-					baseURL, itemID, bookID, paragraphIndex, commentInfo.Count)
-				result.WriteString(commentTag)
-			}
-
-			result.WriteString("</p>")
-			if !isLastLine {
-				result.WriteString("\n")
-			}
-		} else {
-			// 纯文本模式：只在行尾添加comment标记
-			result.WriteString(line)
-
-			// 添加评论标记（纯文本格式）
-			key := fmt.Sprintf("%d", paragraphIndex)
-			if commentInfo, exists := commentData[key]; exists && commentInfo.Count > 0 {
-				commentTag := fmt.Sprintf(`<comment ident="%s/review_html?item_id=%s&book_id=%s&para=%d" count="%d" />`,
-					baseURL, itemID, bookID, paragraphIndex, commentInfo.Count)
-				result.WriteString(commentTag)
-			}
-
-			if !isLastLine {
-				result.WriteString("\n")
+	// HTML 内容：在每个 </p> 前插入段评标记。
+	// 兼容 <p idx="n">（HTML 模式结构）与无属性的 <p>；段号取 idx，无 idx 时按出现顺序。
+	// header/article/div/img 等非段落标签不受影响。
+	pRe := regexp.MustCompile(`(?s)<p\b[^>]*>.*?</p>`)
+	idxRe := regexp.MustCompile(`idx="(\d+)"`)
+	order := 0
+	return pRe.ReplaceAllStringFunc(content, func(m string) string {
+		defer func() { order++ }()
+		para := order
+		if idx := idxRe.FindStringSubmatch(m); idx != nil {
+			if n, err := strconv.Atoi(idx[1]); err == nil {
+				para = n
 			}
 		}
-
-		paragraphIndex++
-	}
-
-	return result.String(), nil
+		if commentInfo, exists := commentData[fmt.Sprintf("%d", para)]; exists && commentInfo.Count > 0 {
+			commentTag := fmt.Sprintf(`<comment ident="%s/review_html?item_id=%s&book_id=%s&para=%d" count="%d" />`,
+				baseURL, itemID, bookID, para, commentInfo.Count)
+			return m[:len(m)-len("</p>")] + commentTag + "</p>"
+		}
+		return m
+	}), nil
 }
 
 // extractDeviceID 从 device header 中提取 device_id

internal/fqapi/search.go

@@ -1,36 +1,144 @@
 package fqapi
 
 import (
+	"bytes"
+	"encoding/json"
 	"fanqie/internal/common"
 	"fmt"
 	"net/url"
+	"regexp"
+	"strconv"
+	"time"
 )
 
 var searchLogger = common.NewLogger("search", "INFO", "")
 
-// GetDeviceHeader 获取设备header（需要从外部注入）
-var GetDeviceHeader func() string
+// 搜索分页与上游续传参数（对齐书源 20261012：上游翻页依赖上一页返回的
+// passback/search_id/next_offset/corrected_query 续传，仅传数字 offset 深翻页会拿到重复/错序结果）
+const (
+	searchPageSize     = 10 // 对外每页书数
+	searchMaxUpstreams = 24 // 单次搜索累计上游翻页上限（对齐书源）
+)
 
-// HandleBookSearch 处理书籍搜索
+// bookIDKeyRe 纯数字 15~20 位关键词按书 ID 直搜详情
+var bookIDKeyRe = regexp.MustCompile(`^\d{15,20}$`)
+
+// HandleBookSearch 处理书籍搜索,搜索结果短缓存 10 分钟,减轻上游压力
 func HandleBookSearch(key string, offset int, tabType int) (string, error) {
+	return withCache(fmt.Sprintf("search_%s_%d_%d", key, offset, tabType), 600, func() (string, error) {
+		return fetchBookSearch(key, offset, tabType)
+	})
+}
+
+func fetchBookSearch(key string, offset int, tabType int) (string, error) {
 	if key == "" {
 		return BuildErrorResponseWithCode(1, "需要参数 key"), nil
 	}
-
 	if tabType == 0 {
 		tabType = 3
 	}
+	if offset < 0 {
+		offset = 0
+	}
 
-	// 编码查询关键字
-	encodedKey := url.QueryEscape(key)
+	// 书 ID 直搜：跳过搜索接口直接查详情，精确命中单本
+	if bookIDKeyRe.MatchString(key) {
+		return idSearchResult(key)
+	}
 
-	// 使用新的参数构建函数
-	reqURL := BuildURL("https://reading.snssdk.com/reading/bookapi/search/tab/v/",
-		fmt.Sprintf("tab_type=%d", tabType),
-		"update_version_code=58932",
-		"query="+encodedKey,
-		fmt.Sprintf("passback=%d", offset),
+	// 累计翻页直到凑够本页书：上游单页 count=20，按 book_id 去重后切出 offset 起的 10 本
+	session := strconv.FormatInt(time.Now().UnixNano(), 10)
+	var (
+		rows      []interface{} // 上游搜索行（含 book_data 包装），原样透传
+		seen      = map[string]bool{}
+		passback  = "0"
+		searchID  = ""
+		corrected = ""
+		nextOff   = 0
+		hasMore   = true
 	)
+	want := offset + searchPageSize
+
+	for i := 0; i < searchMaxUpstreams && hasMore && len(rows) < want; i++ {
+		params := []string{
+			fmt.Sprintf("tab_type=%d", tabType),
+			"update_version_code=" + ClientVersionCode,
+			"query=" + url.QueryEscape(key),
+			"passback=" + passback,
+			fmt.Sprintf("offset=%d", nextOff),
+			"count=20",
+			fmt.Sprintf("is_first_enter_search=%t", i == 0),
+			"normal_session_id=" + session,
+			"cold_start_session_id=" + session,
+		}
+		if searchID != "" {
+			params = append(params, "search_id="+searchID)
+		}
+		if corrected != "" {
+			params = append(params, "corrected_query="+corrected)
+		}
+
+		tab, err := fetchSearchTab(params, tabType)
+		if err != nil {
+			if i == 0 {
+				return BuildErrorResponseWithCode(1, "搜索请求失败"), err
+			}
+			break // 已有数据时后续页失败，降级返回现有结果
+		}
+		if tab == nil {
+			break
+		}
+
+		if data, ok := tab["data"].([]interface{}); ok {
+			for _, r := range data {
+				row, _ := r.(map[string]interface{})
+				if row == nil {
+					continue
+				}
+				// 行 ID 取 book_data[0].book_id；无包装的行按行本身的 book_id
+				bd, _ := row["book_data"].([]interface{})
+				if len(bd) > 0 {
+					if b, ok := bd[0].(map[string]interface{}); ok {
+						if id := searchRowID(b); id != "" && !seen[id] {
+							seen[id] = true
+							rows = append(rows, row)
+						}
+						continue
+					}
+				}
+				if id := searchRowID(row); id != "" && !seen[id] {
+					seen[id] = true
+					rows = append(rows, row)
+				}
+			}
+		}
+
+		hasMore = searchHasMore(tab["has_more"])
+		nextOff = searchInt(tab["next_offset"])
+		passback = searchStr(tab["passback"])
+		searchID = searchStr(tab["search_id"])
+		corrected = searchStr(tab["corrected_query"])
+	}
+
+	start, end := offset, offset+searchPageSize
+	if start > len(rows) {
+		start = len(rows)
+	}
+	if end > len(rows) {
+		end = len(rows)
+	}
+	return marshalNoEscape(UnwrapJSONStrings(map[string]interface{}{
+		"code":        0,
+		"message":     "SUCCESS",
+		"data":        rows[start:end],
+		"has_more":    hasMore || end < len(rows),
+		"next_offset": offset + searchPageSize,
+	})), nil
+}
+
+// fetchSearchTab 请求一页搜索并返回目标 tab_type 的 tab；nil 表示该页无匹配 tab
+func fetchSearchTab(params []string, tabType int) (map[string]interface{}, error) {
+	reqURL := BuildURL("https://reading.snssdk.com/reading/bookapi/search/tab/v/", params...)
 
 	resp, err := GorgonRequest(reqURL, map[string]interface{}{
 		"method": "GET",
@@ -38,22 +146,124 @@ func HandleBookSearch(key string, offset int, tabType int) (string, error) {
 			"User-Agent": "com.dragon.read",
 		},
 	})
-
 	if err != nil {
 		searchLogger.Error(fmt.Sprintf("搜索请求失败: %v", err))
-		return BuildErrorResponseWithCode(1, "搜索请求失败"), err
+		return nil, err
 	}
 
-	respJSON, err := resp.JSON()
-	if err != nil {
+	// UseNumber 重新解析后按 tab_type 过滤:
+	// 上游 search/tab/v/ 固定返回所有 tab 的 search_tabs;
+	// 大整数 ID 经 float64 重组会丢精度,必须 UseNumber
+	dec := json.NewDecoder(bytes.NewReader(resp.Content))
+	dec.UseNumber()
+	var pageJSON map[string]interface{}
+	if err := dec.Decode(&pageJSON); err != nil {
 		searchLogger.Error(fmt.Sprintf("解析响应失败: %v", err))
-		return BuildErrorResponseWithCode(1, "解析响应失败"), err
+		return nil, fmt.Errorf("解析失败")
+	}
+	if code, _ := pageJSON["code"].(float64); code != 0 {
+		return nil, fmt.Errorf("搜索失败 code=%v", pageJSON["code"])
 	}
 
-	if code, ok := respJSON["code"].(float64); ok && code == 0 {
-		return resp.Text, nil
+	filterSearchTabs(pageJSON, tabType)
+	tabs, _ := pageJSON["search_tabs"].([]interface{})
+	for _, t := range tabs {
+		m, ok := t.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		if tt, ok := m["tab_type"].(json.Number); ok {
+			if v, err := tt.Int64(); err == nil && int(v) == tabType {
+				return m, nil
+			}
+		}
 	}
-
-	return BuildErrorResponseWithCode(1, "搜索失败"), nil
+	return nil, nil
 }
 
+// idSearchResult 书 ID 直搜：复用详情接口（24h 缓存），包成上游搜索行形状（book_data 包装）
+func idSearchResult(bookID string) (string, error) {
+	detailJSON, err := HandleGetDetail(bookID)
+	if err != nil {
+		return BuildErrorResponseWithCode(1, "ID 搜索失败"), err
+	}
+	var detail map[string]interface{}
+	if err := json.Unmarshal([]byte(detailJSON), &detail); err != nil {
+		return detailJSON, nil // 透传上游错误响应
+	}
+	if code, _ := detail["code"].(float64); code != 0 {
+		return detailJSON, nil
+	}
+	return marshalNoEscape(UnwrapJSONStrings(map[string]interface{}{
+		"code":        0,
+		"message":     "SUCCESS",
+		"data":        []interface{}{map[string]interface{}{"book_data": []interface{}{detail["data"]}}},
+		"has_more":    false,
+		"next_offset": 0,
+	})), nil
+}
+
+// filterSearchTabs 按 tab_type 只保留 search_tabs 中匹配的项;无匹配时保留原样
+func filterSearchTabs(respJSON map[string]interface{}, tabType int) {
+	tabs, ok := respJSON["search_tabs"].([]interface{})
+	if !ok {
+		return
+	}
+	filtered := make([]interface{}, 0, 1)
+	for _, t := range tabs {
+		m, ok := t.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		if tt, ok := m["tab_type"].(json.Number); ok {
+			if v, err := tt.Int64(); err == nil && int(v) == tabType {
+				filtered = append(filtered, m)
+			}
+		}
+	}
+	if len(filtered) > 0 {
+		respJSON["search_tabs"] = filtered
+	}
+}
+
+// searchRowID 取行的 book_id（UseNumber 下为 json.Number，也可能是字符串）
+func searchRowID(m map[string]interface{}) string {
+	if m == nil {
+		return ""
+	}
+	if s, _ := m["book_id"].(string); s != "" {
+		return s
+	}
+	if n, ok := m["book_id"].(json.Number); ok {
+		return n.String()
+	}
+	return ""
+}
+
+func searchStr(v interface{}) string {
+	s, _ := v.(string)
+	return s
+}
+
+func searchInt(v interface{}) int {
+	switch t := v.(type) {
+	case json.Number:
+		n, _ := t.Int64()
+		return int(n)
+	case string:
+		n, _ := strconv.Atoi(t)
+		return n
+	}
+	return 0
+}
+
+func searchHasMore(v interface{}) bool {
+	switch t := v.(type) {
+	case bool:
+		return t
+	case json.Number:
+		n, _ := t.Int64()
+		return n != 0
+	}
+	return false
+}

internal/fqapi/search_test.go

@@ -0,0 +1,63 @@
+package fqapi
+
+import (
+	"bytes"
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// TestFilterSearchTabs 上游返回全部 tab 时,应只保留请求的 tab_type;无匹配时保留原样
+func TestFilterSearchTabs(t *testing.T) {
+	raw := `{"code":0,"search_tabs":[
+		{"tab_type":1,"title":"综合"},
+		{"tab_type":3,"title":"书籍","book_id":7123456789012345678}
+	]}`
+
+	decode := func(s string) map[string]interface{} {
+		dec := json.NewDecoder(strings.NewReader(s))
+		dec.UseNumber()
+		var m map[string]interface{}
+		if err := dec.Decode(&m); err != nil {
+			t.Fatal(err)
+		}
+		return m
+	}
+
+	m := decode(raw)
+	filterSearchTabs(m, 3)
+	tabs := m["search_tabs"].([]interface{})
+	if len(tabs) != 1 {
+		t.Fatalf("tab_type=3 应只剩 1 个 tab, got %d", len(tabs))
+	}
+	// 大整数 ID 不得丢精度
+	want := "7123456789012345678"
+	got := tabs[0].(map[string]interface{})["book_id"].(json.Number).String()
+	if got != want {
+		t.Errorf("book_id 精度丢失: got %s want %s", got, want)
+	}
+
+	// 无匹配 tab 时保留原样
+	m = decode(raw)
+	filterSearchTabs(m, 99)
+	if len(m["search_tabs"].([]interface{})) != 2 {
+		t.Error("无匹配时应保留原始 search_tabs")
+	}
+}
+
+// TestToJSONPreservesNumberID 重组后大整数 ID 字符串不变
+func TestToJSONPreservesNumberID(t *testing.T) {
+	dec := json.NewDecoder(bytes.NewReader([]byte(`{"id":7123456789012345678}`)))
+	dec.UseNumber()
+	var m map[string]interface{}
+	if err := dec.Decode(&m); err != nil {
+		t.Fatal(err)
+	}
+	out, err := ToJSON(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out, "7123456789012345678") {
+		t.Errorf("重组丢失精度: %s", out)
+	}
+}

internal/fqapi/shelf.go

@@ -0,0 +1,194 @@
+package fqapi
+
+import (
+	"fanqie/internal/common"
+	"fmt"
+	"strings"
+)
+
+var shelfLogger = common.NewLogger("shelf", "INFO", "")
+
+// HandleBookshelf 获取登录用户书架。个人动态数据不缓存。
+// group 非空时只返回该分组的书；书架接口对无效/过期 sessionid 也返回空书架，无法区分——
+// 空结果时提示重新登录
+func HandleBookshelf(sessionID, group string) (string, error) {
+	if sessionID == "" {
+		return BuildErrorResponse("需要参数 sessionid（在 fanqienovel.com 登录后从浏览器 Cookie 中获取）"), nil
+	}
+
+	resp, err := signedBookAPIGet("/reading/bookapi/bookshelf/info/v/", nil, sessionID)
+	if err != nil {
+		shelfLogger.Error(fmt.Sprintf("获取书架失败: %v", err))
+		return BuildErrorResponse("获取书架失败"), err
+	}
+
+	items, err := bookAPIList(resp, "book_shelf_info")
+	if err != nil {
+		return BuildErrorResponse("获取书架失败: " + err.Error()), nil
+	}
+
+	// 过滤分组并收集 book_id
+	type shelfRow struct {
+		id        string
+		groupName string
+	}
+	rows := make([]shelfRow, 0, len(items))
+	for _, it := range items {
+		m, ok := it.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		id := bookIDOf(m)
+		if id == "" {
+			continue
+		}
+		gn, _ := m["group_name"].(string)
+		if group != "" && gn != group {
+			continue
+		}
+		rows = append(rows, shelfRow{id: id, groupName: gn})
+	}
+
+	if len(rows) == 0 {
+		return BuildErrorResponse("书架为空：sessionid 可能无效或已过期，请重新获取"), nil
+	}
+
+	ids := make([]string, len(rows))
+	for i, row := range rows {
+		ids[i] = row.id
+	}
+	details := detailMapByIDs(ids)
+	result := make([]map[string]interface{}, 0, len(rows))
+	for _, row := range rows {
+		d := details[row.id]
+		if d == nil {
+			d = map[string]interface{}{"book_id": row.id}
+		}
+		d["group_name"] = row.groupName
+		result = append(result, d)
+	}
+
+	return marshalNoEscape(UnwrapJSONStrings(buildCacheData(result))), nil
+}
+
+// HandleReadHistory 获取登录用户阅读历史。个人动态数据不缓存。
+// offset 从 0 起，每页 20 条；每项合并书籍详情并保留原始记录（进度等）于 history 字段
+func HandleReadHistory(sessionID string, offset int) (string, error) {
+	if sessionID == "" {
+		return BuildErrorResponse("需要参数 sessionid（在 fanqienovel.com 登录后从浏览器 Cookie 中获取）"), nil
+	}
+	if offset < 0 {
+		offset = 0
+	}
+
+	resp, err := signedBookAPIGet("/reading/bookapi/read_history/list/v/",
+		[]string{fmt.Sprintf("offset=%d", offset), "book_type=0"}, sessionID)
+	if err != nil {
+		shelfLogger.Error(fmt.Sprintf("获取阅读历史失败: %v", err))
+		return BuildErrorResponse("获取阅读历史失败"), err
+	}
+
+	items, err := bookAPIList(resp, "data_list")
+	if err != nil {
+		return BuildErrorResponse("获取阅读历史失败: " + err.Error()), nil
+	}
+
+	type historyRow struct {
+		id  string
+		raw map[string]interface{}
+	}
+	rows := make([]historyRow, 0, len(items))
+	for _, it := range items {
+		m, ok := it.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		id := bookIDOf(m)
+		if id == "" {
+			continue
+		}
+		rows = append(rows, historyRow{id: id, raw: m})
+	}
+
+	if len(rows) == 0 {
+		return marshalNoEscape(buildCacheData([]interface{}{})), nil
+	}
+
+	ids := make([]string, len(rows))
+	for i, row := range rows {
+		ids[i] = row.id
+	}
+	details := detailMapByIDs(ids)
+	result := make([]map[string]interface{}, 0, len(rows))
+	for _, row := range rows {
+		d := details[row.id]
+		if d == nil {
+			d = map[string]interface{}{"book_id": row.id}
+		}
+		// 原始记录（含阅读进度/时间）挂 history 字段保留
+		d["history"] = row.raw
+		result = append(result, d)
+	}
+
+	return marshalNoEscape(UnwrapJSONStrings(buildCacheData(result))), nil
+}
+
+// signedBookAPIGet 个人书架/历史接口：常规签名请求 + 登录态 Cookie
+func signedBookAPIGet(path string, extraParams []string, sessionID string) (*common.ClientResponse, error) {
+	reqURL := BuildURL("https://reading.snssdk.com"+path, extraParams...)
+	return GorgonRequest(reqURL, map[string]interface{}{
+		"method": "GET",
+		"headers": map[string]string{
+			"User-Agent": "com.dragon.read",
+			"Cookie":     "sessionid=" + sessionID,
+		},
+	})
+}
+
+// bookAPIList 校验上游响应并取出 data 下的指定列表字段
+func bookAPIList(resp *common.ClientResponse, field string) ([]interface{}, error) {
+	respJSON, err := resp.JSON()
+	if err != nil {
+		return nil, fmt.Errorf("响应解析失败: %w", err)
+	}
+	if code, ok := respJSON["code"].(float64); !ok || code != 0 {
+		msg, _ := respJSON["message"].(string)
+		return nil, fmt.Errorf("code=%.0f msg=%s", respJSON["code"], msg)
+	}
+	data, _ := respJSON["data"].(map[string]interface{})
+	items, _ := data[field].([]interface{})
+	return items, nil
+}
+
+// bookIDOf 兼容提取 book_id / book_id_str（数字或字符串）
+func bookIDOf(m map[string]interface{}) string {
+	for _, k := range []string{"book_id_str", "book_id", "bookId"} {
+		switch v := m[k].(type) {
+		case string:
+			if v != "" {
+				return v
+			}
+		case float64:
+			return fmt.Sprintf("%.0f", v)
+		}
+	}
+	return ""
+}
+
+// detailMapByIDs 按 book_id 建立详情映射（复用批量详情接口，分批请求）
+func detailMapByIDs(ids []string) map[string]map[string]interface{} {
+	m := make(map[string]map[string]interface{}, len(ids))
+	for _, chunk := range chunkArray(ids, 100) {
+		list, err := multiDetail(strings.Join(chunk, ","))
+		if err != nil {
+			shelfLogger.Warning(fmt.Sprintf("批量获取详情失败（该批保留 book_id）: %v", err))
+			continue
+		}
+		for _, d := range list {
+			if id, ok := d["book_id"].(string); ok {
+				m[id] = d
+			}
+		}
+	}
+	return m
+}

internal/fqapi/store_redis.go

@@ -0,0 +1,88 @@
+package fqapi
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+)
+
+// audioProxyEntry 音频代理缓存条目（Redis 版）
+type audioProxyEntry struct {
+	OriginalURL string            `json:"original_url"`
+	DeviceID    string            `json:"device_id"`
+	Headers     map[string]string `json:"headers"`
+}
+
+const (
+	redisCacheKeyPrefix = "fq:cache:"
+	redisAudioKeyPrefix = "fq:audio:"
+	// audioCacheTTL 音频代理缓存有效期（匹配 CDN 链接有效期）
+	audioCacheTTL = 2 * time.Hour
+)
+
+// redisGetCache 从 Redis 获取正文缓存
+func redisGetCache(key string) string {
+	// 读操作同样加 3s 超时，防止远程 Redis 网络抖动拖垮请求（与写路径一致）
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	val, err := redisCache.Get(ctx, redisCacheKeyPrefix+key).Result()
+	if err != nil {
+		return "" // miss 或错误都视为未命中
+	}
+
+	var cacheData CacheData
+	if err := json.Unmarshal([]byte(val), &cacheData); err != nil {
+		cacheLogger.Error("解析Redis缓存数据失败: " + err.Error())
+		return ""
+	}
+
+	cacheLogger.Debug("Redis缓存命中: " + key)
+	if time.Now().Unix() < int64(cacheData.Expi) {
+		return cacheData.Data
+	}
+	return ""
+}
+
+// redisUpdateCache 写入 Redis 正文缓存（TTL 与过期时间一致）
+func redisUpdateCache(key string, value string, expi int) error {
+	cacheData := CacheData{
+		Data: value,
+		Expi: float64(time.Now().Unix() + int64(expi)),
+	}
+	jsonData, err := json.Marshal(cacheData)
+	if err != nil {
+		return err
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	return redisCache.Set(ctx, redisCacheKeyPrefix+key, jsonData, time.Duration(expi)*time.Second).Err()
+}
+
+// saveAudioProxyEntry 将音频代理信息存入 Redis
+func saveAudioProxyEntry(key string, entry *audioProxyEntry) {
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	jsonData, _ := json.Marshal(entry)
+	if err := redisCache.Set(ctx, redisAudioKeyPrefix+key, jsonData, audioCacheTTL).Err(); err != nil {
+		audioLogger.Error("保存音频缓存到Redis失败: " + err.Error())
+	}
+}
+
+// loadAudioProxyEntry 从 Redis 读取音频代理信息，未命中或过期返回错误
+func loadAudioProxyEntry(key string) (*audioProxyEntry, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	val, err := redisCache.Get(ctx, redisAudioKeyPrefix+key).Result()
+	if err != nil {
+		return nil, fmt.Errorf("媒体信息不存在或已过期，请重新调用 /audio 或 /video 接口")
+	}
+
+	var entry audioProxyEntry
+	if err := json.Unmarshal([]byte(val), &entry); err != nil {
+		return nil, fmt.Errorf("解析音频缓存失败: %w", err)
+	}
+	return &entry, nil
+}

internal/fqapi/ttencrypt.go

@@ -193,4 +193,3 @@ func Decrypt(encryptedStr string) ([]byte, error) {
 	}
 	return TTDecrypt(encryptedData)
 }
-

internal/fqapi/video.go

@@ -1,17 +1,27 @@
 package fqapi
 
 import (
+	"bytes"
 	"encoding/base64"
 	"encoding/json"
 	"fanqie/internal/common"
+	"fanqie/internal/config"
 	"fmt"
+	"io"
 	"math"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
 )
 
 var videoLogger = common.NewLogger("video", "INFO", "")
 
-// HandleVideo 处理获取视频（支持批量和单个接口）
-func HandleVideo(itemIDs interface{}) (string, error) {
+// HandleVideo 处理获取视频（支持批量和单个接口）。
+// output: url（默认，返回原始CDN链接，内容为 CENC 加密）/ proxy（返回本地解密代理链接，可直接播放）
+// quality: 清晰度过滤，支持 max（最高档，默认）、definition（360p/480p/...）或档位 key（video_1..N），空为全部；
+// 未传时回退 config fanqie.video.quality，output 为空时回退 fanqie.video.output_mode
+func HandleVideo(itemIDs, output, quality interface{}) (string, error) {
 	if itemIDs == nil || itemIDs == "" {
 		return BuildSuccessResponse([]interface{}{}), nil
 	}
@@ -44,6 +54,26 @@ func HandleVideo(itemIDs interface{}) (string, error) {
 	requestBody := fmt.Sprintf(`{"biz_param":{"device_level":3,"need_all_video_definition":true,"need_mp4_align":false,"use_os_player":false,"video_platform":1024},"video_id":"%s"}`,
 		itemIDStr)
 
+	outputMode := ParseStringParam(output, "")
+	qualityFilter := ParseStringParam(quality, "")
+	if cfg := config.GetAppConfig(); cfg != nil {
+		if outputMode == "" {
+			outputMode = cfg.Fanqie.Video.OutputMode
+		}
+		if qualityFilter == "" {
+			qualityFilter = cfg.Fanqie.Video.Quality
+		}
+	}
+	if outputMode == "" {
+		outputMode = "url"
+	}
+	deviceID := ""
+	if outputMode == "proxy" {
+		if dev := GetCurrentDevice(); dev != nil {
+			deviceID = dev.DeviceHeader
+		}
+	}
+
 	// 使用 GorgonRequest 添加签名和设备信息
 	resp, err := GorgonRequest(url, map[string]interface{}{
 		"method": "POST",
@@ -86,7 +116,14 @@ func HandleVideo(itemIDs interface{}) (string, error) {
 
 		if data != nil {
 			if videoModelStr, ok := data["video_model"].(string); ok && isSingle {
-				decodedModel := decodeVideoModelAsJSON(videoModelStr)
+				decodedModel := decodeVideoModelAsJSON(videoModelStr, outputMode, deviceID, qualityFilter)
+
+				// 清晰度过滤无匹配时报错（调用方能立即发现参数写错）
+				if qualityFilter != "" {
+					if vl, ok := decodedModel.(map[string]interface{})["video_list"].(map[string]interface{}); ok && len(vl) == 0 {
+						return BuildErrorResponse(fmt.Sprintf("无匹配清晰度: %s（可用档位见 video_list）", qualityFilter)), nil
+					}
+				}
 
 				// 单个接口直接返回 video_model
 				response := map[string]interface{}{
@@ -95,8 +132,7 @@ func HandleVideo(itemIDs interface{}) (string, error) {
 					"data":    decodedModel,
 				}
 
-				resultBytes, _ := json.Marshal(response)
-				return string(resultBytes), nil
+				return marshalNoEscape(response), nil
 			} else {
 				// 批量接口：data 是一个map，key是ID，value包含video_model
 				result := make(map[string]interface{})
@@ -104,7 +140,7 @@ func HandleVideo(itemIDs interface{}) (string, error) {
 				for itemID, itemData := range data {
 					if itemMap, ok := itemData.(map[string]interface{}); ok {
 						if videoModelStr, ok := itemMap["video_model"].(string); ok {
-							decodedModel := decodeVideoModelAsJSON(videoModelStr)
+							decodedModel := decodeVideoModelAsJSON(videoModelStr, outputMode, deviceID, qualityFilter)
 							result[itemID] = map[string]interface{}{
 								"video_model": decodedModel,
 							}
@@ -119,8 +155,7 @@ func HandleVideo(itemIDs interface{}) (string, error) {
 					"data":    result,
 				}
 
-				resultBytes, _ := json.Marshal(response)
-				return string(resultBytes), nil
+				return marshalNoEscape(response), nil
 			}
 		}
 	}
@@ -136,21 +171,29 @@ func HandleVideo(itemIDs interface{}) (string, error) {
 	return BuildErrorResponse(errMsg), nil
 }
 
-// decodeVideoModelAsJSON 解析并解码 video_model，返回关键字段的 JSON 对象
-func decodeVideoModelAsJSON(videoModelStr string) interface{} {
+// decodeVideoModelAsJSON 解析并解码 video_model，返回关键字段的 JSON 对象。
+// outputMode=proxy 时把 CDN 链接替换为本地解密代理链接（/video/proxy/{key}）
+// qualityFilter 非空时只保留匹配的清晰度（definition 或档位 key，大小写不敏感）
+func decodeVideoModelAsJSON(videoModelStr, outputMode, deviceID, qualityFilter string) interface{} {
 	// 解析 video_model JSON 字符串
 	var videoModel map[string]interface{}
 	if err := json.Unmarshal([]byte(videoModelStr), &videoModel); err != nil {
 		// 解析失败，返回空对象
 		return map[string]interface{}{}
 	}
-	
+	// 解包嵌套的 JSON 字符串字段（category_schema、recommend_info 等）
+	if unwrapped, ok := UnwrapJSONStrings(videoModel).(map[string]interface{}); ok {
+		videoModel = unwrapped
+	}
+
 	// 构建精简的返回结果，只包含关键字段
 	result := make(map[string]interface{})
-	
+
 	// 提取关键字段
-	if videoID, ok := videoModel["video_id"].(string); ok {
-		result["video_id"] = videoID
+	videoID := ""
+	if v, ok := videoModel["video_id"].(string); ok {
+		result["video_id"] = v
+		videoID = v
 	}
 	if duration, ok := videoModel["video_duration"].(float64); ok {
 		result["video_duration"] = formatDuration(duration)
@@ -158,16 +201,47 @@ func decodeVideoModelAsJSON(videoModelStr string) interface{} {
 	if posterURL, ok := videoModel["poster_url"].(string); ok {
 		result["poster_url"] = posterURL
 	}
-	
+	// 加密信息：视频为 CENC 加密（encrypt=true），解密需要 key_seed/kid
+	if keySeed, ok := videoModel["key_seed"].(string); ok {
+		result["key_seed"] = keySeed
+	}
+
 	// 处理 video_list
 	if videoList, ok := videoModel["video_list"].(map[string]interface{}); ok {
+		// max/best：解析为实际最高档位 key（不同视频可用档位不同，按 vheight/definition 取最大）
+		if strings.EqualFold(qualityFilter, "max") || strings.EqualFold(qualityFilter, "best") {
+			bestKey, bestH := "", 0
+			for q, qd := range videoList {
+				qm, ok := qd.(map[string]interface{})
+				if !ok {
+					continue
+				}
+				if h := qualityHeight(qm); h > bestH {
+					bestH, bestKey = h, q
+				}
+			}
+			qualityFilter = bestKey
+		}
+
 		processedVideoList := make(map[string]interface{})
-		
+
 		for quality, qualityData := range videoList {
 			if qualityMap, ok := qualityData.(map[string]interface{}); ok {
+				// 清晰度过滤：匹配档位 key（video_1）或 definition（720p）
+				if qualityFilter != "" {
+					def, _ := qualityMap["definition"].(string)
+					if !strings.EqualFold(quality, qualityFilter) && !strings.EqualFold(def, qualityFilter) {
+						continue
+					}
+				}
+				// spade_a（PlayAuth）：解出 CENC 内容密钥的种子，proxy 模式随代理下发
+				spadeA := ""
+				if v, ok := qualityMap["spade_a"].(string); ok {
+					spadeA = v
+				}
 				// 只保留关键字段
 				qualityInfo := make(map[string]interface{})
-				
+
 				if definition, ok := qualityMap["definition"].(string); ok {
 					qualityInfo["definition"] = definition
 				}
@@ -189,39 +263,69 @@ func decodeVideoModelAsJSON(videoModelStr string) interface{} {
 				if fps, ok := qualityMap["fps"].(float64); ok {
 					qualityInfo["fps"] = int(fps)
 				}
-				
-				// 解码 main_url
+				if encrypt, ok := qualityMap["encrypt"].(bool); ok && encrypt {
+					qualityInfo["encrypt"] = true
+					if em, ok := qualityMap["encryption_method"].(string); ok {
+						qualityInfo["encryption_method"] = em
+					}
+					if kid, ok := qualityMap["kid"].(string); ok {
+						qualityInfo["kid"] = kid
+					}
+				}
+
+				// 解码 main_url / backup_url_1（base64 的CDN链接），proxy 模式替换为解密代理。
+				// 代理 key 用 videoID+档位（稳定），同一视频重复调用复用磁盘缓存
+				processURL := func(b64 string) interface{} {
+					decoded, err := base64.StdEncoding.DecodeString(b64)
+					if err != nil {
+						return b64
+					}
+					if outputMode == "proxy" && spadeA != "" && videoID != "" {
+						return GenerateVideoProxyURL(videoID+"_"+quality, string(decoded), deviceID, spadeA)
+					}
+					return string(decoded)
+				}
 				if mainURL, ok := qualityMap["main_url"].(string); ok {
-					if decoded, err := base64.StdEncoding.DecodeString(mainURL); err == nil {
-						qualityInfo["main_url"] = string(decoded)
-					}
+					qualityInfo["main_url"] = processURL(mainURL)
 				}
-				
-				// 解码 backup_url_1
 				if backupURL, ok := qualityMap["backup_url_1"].(string); ok {
-					if decoded, err := base64.StdEncoding.DecodeString(backupURL); err == nil {
-						qualityInfo["backup_url_1"] = string(decoded)
-					}
+					qualityInfo["backup_url_1"] = processURL(backupURL)
 				}
-				
+
 				processedVideoList[quality] = qualityInfo
 			}
 		}
-		
+
 		result["video_list"] = processedVideoList
 	}
-	
+
 	return result
 }
 
+// qualityHeight 取清晰度的比较高度：优先 vheight，缺失时从 definition（如 "720p"）解析
+func qualityHeight(qm map[string]interface{}) int {
+	if h, ok := qm["vheight"].(float64); ok && h > 0 {
+		return int(h)
+	}
+	def, _ := qm["definition"].(string)
+	n := 0
+	for _, c := range def {
+		if c < '0' || c > '9' {
+			break
+		}
+		n = n*10 + int(c-'0')
+	}
+	return n
+}
+
 // formatDuration 将秒数转换为可读的时间格式
 func formatDuration(seconds float64) string {
 	totalSeconds := int(math.Round(seconds))
-	
+
 	hours := totalSeconds / 3600
 	minutes := (totalSeconds % 3600) / 60
 	secs := totalSeconds % 60
-	
+
 	if hours > 0 {
 		return fmt.Sprintf("%d小时%d分%d秒", hours, minutes, secs)
 	} else if minutes > 0 {
@@ -236,17 +340,17 @@ func formatFileSize(bytes float64) string {
 	if bytes < unit {
 		return fmt.Sprintf("%.0f B", bytes)
 	}
-	
+
 	kb := bytes / unit
 	if kb < unit {
 		return fmt.Sprintf("%.2f KB", kb)
 	}
-	
+
 	mb := kb / unit
 	if mb < unit {
 		return fmt.Sprintf("%.2f MB", mb)
 	}
-	
+
 	gb := mb / unit
 	return fmt.Sprintf("%.2f GB", gb)
 }
@@ -255,12 +359,131 @@ func formatFileSize(bytes float64) string {
 func formatBitrate(bitrate float64) string {
 	const unit = 1000.0
 	kbps := bitrate / unit
-	
+
 	if kbps < unit {
 		return fmt.Sprintf("%.0f Kbps", kbps)
 	}
-	
+
 	mbps := kbps / unit
 	return fmt.Sprintf("%.2f Mbps", mbps)
 }
 
+// GenerateVideoProxyURL 生成视频解密代理URL。
+// cacheKey 需稳定（videoID+档位）：映射表覆盖式更新，磁盘缓存按 key 复用
+func GenerateVideoProxyURL(cacheKey, originalURL, deviceID, spadeA string) string {
+	headers := map[string]string{"x-spade-a": spadeA}
+	if redisCache != nil {
+		saveAudioProxyEntry(cacheKey, &audioProxyEntry{
+			OriginalURL: originalURL,
+			DeviceID:    deviceID,
+			Headers:     headers,
+		})
+		return "/video/proxy/" + cacheKey
+	}
+	headersJSON, _ := json.Marshal(headers)
+	if cacheDB != nil {
+		cacheDB.Exec(q(`
+			INSERT INTO audio_cache (key, original_url, device_id, headers, created_at, updated_at)
+			VALUES (?, ?, ?, ?, ?, ?)
+			ON CONFLICT(key) DO UPDATE SET original_url = excluded.original_url,
+				device_id = excluded.device_id, headers = excluded.headers, updated_at = excluded.updated_at
+		`), cacheKey, originalURL, deviceID, string(headersJSON), time.Now().Unix(), time.Now().Unix())
+	}
+	return "/video/proxy/" + cacheKey
+}
+
+// videoCachePath 解密后视频的磁盘缓存路径；缓存未启用返回空串
+func videoCachePath(key string) string {
+	cfg := config.GetAppConfig()
+	if cfg == nil || !cfg.Fanqie.Video.CacheEnabled || cfg.Fanqie.Video.CachePath == "" {
+		return ""
+	}
+	return filepath.Join(cfg.Fanqie.Video.CachePath, key+".mp4")
+}
+
+// HandleVideoProxy 处理视频代理请求：磁盘缓存命中直接返回；否则下载 CENC 加密 MP4 →
+// SpadeA 解 key → 解密 → 写入缓存。返回 ReadSeeker 供 http.ServeContent（支持 Range/seek）。
+func HandleVideoProxy(key string) (io.ReadSeeker, string, error) {
+	// 磁盘缓存命中：直接返回文件（映射记录即使过期也不影响已缓存的视频）
+	if p := videoCachePath(key); p != "" {
+		if f, err := os.Open(p); err == nil {
+			return f, "video/mp4", nil
+		}
+	}
+
+	entry, err := loadMediaProxyEntry(key)
+	if err != nil {
+		return nil, "", err
+	}
+	spadeA := entry.Headers["x-spade-a"]
+	if spadeA == "" {
+		return nil, "", fmt.Errorf("视频信息缺少 spade_a，请重新调用 /video 接口")
+	}
+
+	body, _, err := downloadMediaWithRetry(entry.OriginalURL, entry.DeviceID, entry.Headers, 3)
+	if err != nil {
+		return nil, "", fmt.Errorf("下载视频失败: %w", err)
+	}
+	defer body.Close()
+	data, err := io.ReadAll(body)
+	if err != nil {
+		return nil, "", fmt.Errorf("读取视频失败: %w", err)
+	}
+
+	contentKey, err := DecodeSpadeKey(spadeA)
+	if err != nil {
+		return nil, "", fmt.Errorf("解密视频失败: %w", err)
+	}
+	if err := DecryptCENCMP4(data, contentKey); err != nil {
+		return nil, "", fmt.Errorf("解密视频失败: %w", err)
+	}
+
+	// 写入磁盘缓存（临时文件 + rename 原子替换；失败不影响本次返回）
+	if p := videoCachePath(key); p != "" {
+		if err := os.MkdirAll(filepath.Dir(p), 0755); err == nil {
+			if tmp, err := os.CreateTemp(filepath.Dir(p), ".tmp-*"); err == nil {
+				if _, werr := tmp.Write(data); werr == nil {
+					tmp.Close()
+					if err := os.Rename(tmp.Name(), p); err != nil {
+						os.Remove(tmp.Name())
+					}
+				} else {
+					tmp.Close()
+					os.Remove(tmp.Name())
+				}
+			}
+		}
+	}
+	return bytes.NewReader(data), "video/mp4", nil
+}
+
+// CleanupVideoCache 清理磁盘视频缓存中 mtime 过早的文件，挂接在缓存定期清理任务中
+func CleanupVideoCache() {
+	cfg := config.GetAppConfig()
+	if cfg == nil || !cfg.Fanqie.Video.CacheEnabled {
+		return
+	}
+	dir := cfg.Fanqie.Video.CachePath
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return // 目录不存在等：无缓存可清
+	}
+	const maxAge = 7 * 24 * time.Hour // ponytail: 固定 7 天，需要更长保留时改配置语义
+	cutoff := time.Now().Add(-maxAge)
+	removed := 0
+	for _, e := range entries {
+		info, err := e.Info()
+		if err != nil || info.IsDir() {
+			continue
+		}
+		if info.ModTime().Before(cutoff) {
+			if os.Remove(filepath.Join(dir, e.Name())) == nil {
+				removed++
+			}
+		}
+	}
+	if removed > 0 {
+		videoLogger.Info(fmt.Sprintf("已清理 %d 个过期视频缓存文件", removed))
+	}
+}
+

internal/fqapi/video_decrypt.go

@@ -0,0 +1,360 @@
+package fqapi
+
+import (
+	"bytes"
+	"crypto/aes"
+	"crypto/cipher"
+	"encoding/base64"
+	"encoding/binary"
+	"fmt"
+)
+
+// ============ SpadeA（黑桃A）PlayAuth 解码 ============
+//
+// 番茄短剧/汽水音乐同源的本地 DRM：video_model 每个清晰度的 spade_a
+// （PlayAuth）经混淆变换直接还原 16 字节 AES-128 内容密钥（32 位 hex 字符串）。
+// 算法逆向自 SodaMusic v3.5.1（qishui-decrypt-tool），与番茄短剧样本实测一致。
+
+func bitCount32(v uint32) int {
+	c := v
+	c -= (c >> 1) & 0x55555555
+	c = (c & 0x33333333) + ((c >> 2) & 0x33333333)
+	return int(((c + (c>>4)) & 0x0f0f0f0f) * 0x01010101 >> 24)
+}
+
+func decodeBase36Byte(v byte) int {
+	switch {
+	case v >= '0' && v <= '9':
+		return int(v - '0')
+	case v >= 'a' && v <= 'z':
+		return int(v-'a') + 10
+	}
+	return 0xff
+}
+
+// decodeSpadeInner 逐字节去混淆：与前一字节异或后减去索引 popcount 与常数
+func decodeSpadeInner(data []byte) []byte {
+	result := make([]byte, len(data))
+	buff := append([]byte{0xfa, 0x55}, data...)
+	for i := 0; i < len(data); i++ {
+		raw := int(data[i]^buff[i]) - bitCount32(uint32(i)) - 21
+		if raw >= 0 {
+			result[i] = byte(raw)
+		} else {
+			result[i] = byte(((raw % 255) + 255) % 255)
+		}
+	}
+	return result
+}
+
+// DecodeSpadeKey 从 spade_a（PlayAuth base64）解出 16 字节 AES 内容密钥
+func DecodeSpadeKey(playAuthB64 string) ([]byte, error) {
+	raw, err := base64.StdEncoding.DecodeString(playAuthB64)
+	if err != nil {
+		return nil, fmt.Errorf("spade_a base64 解码失败: %w", err)
+	}
+	if len(raw) < 4 {
+		return nil, fmt.Errorf("spade_a 长度不足: %d", len(raw))
+	}
+	padding := int(raw[0]^raw[1]^raw[2]) - 48
+	if padding < 0 || padding >= len(raw)-3 {
+		return nil, fmt.Errorf("spade_a padding 非法: %d", padding)
+	}
+	body := raw[1 : len(raw)-padding]
+	tmp := decodeSpadeInner(body)
+	keyLen := decodeBase36Byte(tmp[0])
+	if keyLen == 0xff {
+		return nil, fmt.Errorf("spade_a key 长度字符非法: %q", tmp[0])
+	}
+	end := len(body) - keyLen
+	if end < 1 || end > len(tmp) {
+		return nil, fmt.Errorf("spade_a key 范围非法: end=%d len=%d", end, len(tmp))
+	}
+	keyHex := string(tmp[1:end])
+	if len(keyHex) != 32 {
+		return nil, fmt.Errorf("spade_a key 长度异常: %d", len(keyHex))
+	}
+	key := make([]byte, 16)
+	for i := 0; i < 16; i++ {
+		if _, err := fmt.Sscanf(keyHex[i*2:i*2+2], "%02x", &key[i]); err != nil {
+			return nil, fmt.Errorf("spade_a key hex 非法: %s", keyHex)
+		}
+	}
+	return key, nil
+}
+
+// ============ CENC (cenc-aes-ctr) MP4 解密 ============
+//
+// 容器为标准 CENC MP4：moov 明文；加密 sample entry（encv/enca）+ senc box
+// （version 0，每个 sample 8 字节 IV，整样本 AES-128-CTR，无 subsample）。
+// 解密后把 entry 类型改回原始 codec（sinf/frma 指示），得到可播放文件。
+
+type mp4Box struct {
+	typ         string
+	contentStar int
+	end         int
+}
+
+// walkBoxes 迭代 [start,end) 内的顶层 box，fn 返回 false 时停止迭代
+func walkBoxes(data []byte, start, end int, fn func(mp4Box) bool) error {
+	p := start
+	for p+8 <= end {
+		size := int(binary.BigEndian.Uint32(data[p : p+4]))
+		typ := string(data[p+4 : p+8])
+		if size == 1 { // largesize
+			if p+16 > end {
+				return fmt.Errorf("box %s largesize 越界", typ)
+			}
+			size = int(binary.BigEndian.Uint64(data[p+8 : p+16]))
+			// ponytail: >2GB 文件不支持，截断风险可接受
+			if size > len(data) {
+				return fmt.Errorf("box %s 过大", typ)
+			}
+		}
+		if size < 8 || p+size > end {
+			return fmt.Errorf("box %s 尺寸非法 size=%d at %d", typ, size, p)
+		}
+		if !fn(mp4Box{typ: typ, contentStar: p + 8, end: p + size}) {
+			return nil
+		}
+		p += size
+	}
+	return nil
+}
+
+// DecryptCENCMP4 原地解密 CENC 加密的 MP4 字节并修复 stsd entry 类型。
+// 仅支持 senc version 0 + 无 subsample 标志（番茄实测形态），其他形态返回错误。
+func DecryptCENCMP4(data []byte, key []byte) error {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return fmt.Errorf("内容密钥非法: %w", err)
+	}
+
+	decryptStream := func(ct []byte, iv8 []byte) error {
+		if len(iv8) != 8 {
+			return fmt.Errorf("senc IV 长度异常: %d", len(iv8))
+		}
+		iv := make([]byte, 16)
+		copy(iv, iv8) // 8 字节 IV 置于高位，低 8 字节为块计数器（CENC 标准）
+		cipher.NewCTR(block, iv).XORKeyStream(ct, ct)
+		return nil
+	}
+
+	// 找 moov 并遍历其下所有 trak，逐 trak 解密
+	var trakErr error
+	foundMoov := false
+	if err := walkBoxes(data, 0, len(data), func(b mp4Box) bool {
+		if b.typ != "moov" {
+			return true
+		}
+		foundMoov = true
+		_ = walkBoxes(data, b.contentStar, b.end, func(trak mp4Box) bool {
+			if trak.typ != "trak" {
+				return true
+			}
+			if err := decryptTrak(data, trak, decryptStream); err != nil {
+				trakErr = err
+				return false
+			}
+			return true
+		})
+		return false
+	}); err != nil {
+		return err
+	}
+	if !foundMoov {
+		return fmt.Errorf("moov box 未找到")
+	}
+	return trakErr
+}
+
+// decryptTrak 处理单个 trak：解析 sample 表 + senc，逐样本解密，修补 stsd
+func decryptTrak(data []byte, trak mp4Box, decryptStream func([]byte, []byte) error) error {
+	// 定位 mdia→minf→stbl
+	stbl, err := findBox(data, trak, "mdia", "minf", "stbl")
+	if err != nil || stbl == nil {
+		return err // 无 stbl 的 trak 跳过
+	}
+
+	var (
+		sizes         []int
+		chunkOffsets  []int
+		stscEntries   [][2]int // {first_chunk, samples_per_chunk}
+		ivs           [][]byte
+		stsd          *mp4Box
+		haveSizes     bool
+		haveOffsets   bool
+		haveStsc      bool
+		parseErr      error
+	)
+
+	if err := walkBoxes(data, stbl.contentStar, stbl.end, func(b mp4Box) bool {
+		switch b.typ {
+		case "stsd":
+			stsd = &b
+		case "stsz":
+			constSize := int(binary.BigEndian.Uint32(data[b.contentStar+4 : b.contentStar+8]))
+			count := int(binary.BigEndian.Uint32(data[b.contentStar+8 : b.contentStar+12]))
+			if constSize != 0 {
+				for i := 0; i < count; i++ {
+					sizes = append(sizes, constSize)
+				}
+			} else {
+				sizes = make([]int, count)
+				for i := 0; i < count; i++ {
+					sizes[i] = int(binary.BigEndian.Uint32(data[b.contentStar+12+i*4 : b.contentStar+16+i*4]))
+				}
+			}
+			haveSizes = true
+		case "stco":
+			count := int(binary.BigEndian.Uint32(data[b.contentStar+4 : b.contentStar+8]))
+			for i := 0; i < count; i++ {
+				chunkOffsets = append(chunkOffsets, int(binary.BigEndian.Uint32(data[b.contentStar+8+i*4:b.contentStar+12+i*4])))
+			}
+			haveOffsets = true
+		case "co64":
+			count := int(binary.BigEndian.Uint32(data[b.contentStar+4 : b.contentStar+8]))
+			for i := 0; i < count; i++ {
+				v := binary.BigEndian.Uint64(data[b.contentStar+8+i*8 : b.contentStar+16+i*8])
+				if v > uint64(len(data)) {
+					parseErr = fmt.Errorf("co64 偏移越界")
+					return false
+				}
+				chunkOffsets = append(chunkOffsets, int(v))
+			}
+			haveOffsets = true
+		case "stsc":
+			count := int(binary.BigEndian.Uint32(data[b.contentStar+4 : b.contentStar+8]))
+			for i := 0; i < count; i++ {
+				first := int(binary.BigEndian.Uint32(data[b.contentStar+8+i*12 : b.contentStar+12+i*12]))
+				spc := int(binary.BigEndian.Uint32(data[b.contentStar+12+i*12 : b.contentStar+16+i*12]))
+				stscEntries = append(stscEntries, [2]int{first, spc})
+			}
+			haveStsc = true
+		case "senc":
+			verFlags := binary.BigEndian.Uint32(data[b.contentStar : b.contentStar+4])
+			if verFlags>>24 != 0 {
+				parseErr = fmt.Errorf("senc version %d 不支持", verFlags>>24)
+				return false
+			}
+			if verFlags&0b10 != 0 {
+				parseErr = fmt.Errorf("senc subsample 加密模式不支持")
+				return false
+			}
+			count := int(binary.BigEndian.Uint32(data[b.contentStar+4 : b.contentStar+8]))
+			p := b.contentStar + 8
+			if p+8*count > b.end {
+				parseErr = fmt.Errorf("senc IV 表越界")
+				return false
+			}
+			for i := 0; i < count; i++ {
+				ivs = append(ivs, data[p+8*i:p+8*i+8])
+			}
+		}
+		return true
+	}); err != nil {
+		return fmt.Errorf("stbl 解析失败: %w", err)
+	}
+	if parseErr != nil {
+		return parseErr
+	}
+
+	if len(ivs) == 0 {
+		return nil // 本 trak 未加密
+	}
+	if !haveSizes || !haveOffsets || !haveStsc {
+		return fmt.Errorf("sample 表不完整（stsz=%v stco=%v stsc=%v）", haveSizes, haveOffsets, haveStsc)
+	}
+
+	// stsc+stco+stsz 重建每样本绝对偏移（标准 sample table 遍历）
+	sampleIdx := 0
+	for ci, off := range chunkOffsets {
+		spc := stscEntries[len(stscEntries)-1][1]
+		for _, e := range stscEntries {
+			if e[0] <= ci+1 {
+				spc = e[1]
+			} else {
+				break
+			}
+		}
+		pos := off
+		for s := 0; s < spc && sampleIdx < len(sizes); s++ {
+			size := sizes[sampleIdx]
+			if sampleIdx >= len(ivs) {
+				break
+			}
+			if pos+size > len(data) {
+				return fmt.Errorf("sample %d 越界 pos=%d size=%d", sampleIdx, pos, size)
+			}
+			if err := decryptStream(data[pos:pos+size], ivs[sampleIdx]); err != nil {
+				return err
+			}
+			pos += size
+			sampleIdx++
+		}
+	}
+
+	if stsd != nil {
+		patchStsdEntry(data, *stsd)
+	}
+	return nil
+}
+
+// findBox 沿 path 逐层查找唯一子 box；任意一层缺失返回 (nil, nil)
+func findBox(data []byte, parent mp4Box, path ...string) (*mp4Box, error) {
+	cur := parent
+	for _, name := range path {
+		var next *mp4Box
+		if err := walkBoxes(data, cur.contentStar, cur.end, func(b mp4Box) bool {
+			if b.typ == name {
+				next = &b
+				return false
+			}
+			return true
+		}); err != nil {
+			return nil, err
+		}
+		if next == nil {
+			return nil, nil
+		}
+		cur = *next
+	}
+	return &cur, nil
+}
+
+// patchStsdEntry 把加密 sample entry（encv/enca）的类型改回 sinf/frma 指示的原始 codec。
+// 番茄实测单 entry；entry 头部长度因音/视频而异，直接在 entry 字节里定位 "sinf"。
+func patchStsdEntry(data []byte, stsd mp4Box) {
+	entryCount := int(binary.BigEndian.Uint32(data[stsd.contentStar+4 : stsd.contentStar+8]))
+	if entryCount != 1 {
+		return // ponytail: 多 entry 形态按需扩展
+	}
+	entryStart := stsd.contentStar + 8
+	entryEnd := stsd.end
+
+	// 在 entry 内定位 "sinf"（box 类型魔数），再验证其 box 头合法性
+	sinfOff := bytes.Index(data[entryStart:entryEnd], []byte("sinf"))
+	for sinfOff >= 0 {
+		boxStart := entryStart + sinfOff - 4 // size 字段起点
+		if boxStart >= entryStart+8 {
+			size := int(binary.BigEndian.Uint32(data[boxStart : boxStart+4]))
+			if size >= 12 && boxStart+size <= entryEnd {
+				sinfContent, sinfEnd := boxStart+8, boxStart+size
+				frmaOff := bytes.Index(data[sinfContent:sinfEnd], []byte("frma"))
+				if frmaOff >= 0 {
+					frmaContent := sinfContent + frmaOff + 4
+					if frmaContent+4 <= sinfEnd {
+						// entry 类型字段在 box 头的 type 位置（entryStart+4）
+						copy(data[entryStart+4:entryStart+8], data[frmaContent:frmaContent+4])
+						return
+					}
+				}
+			}
+		}
+		next := bytes.Index(data[entryStart+sinfOff+1:entryEnd], []byte("sinf"))
+		if next < 0 {
+			return
+		}
+		sinfOff = sinfOff + 1 + next
+	}
+}

internal/fqapi/videodecrypt_test.go

@@ -0,0 +1,178 @@
+package fqapi
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"encoding/binary"
+	"bytes"
+	"encoding/base64"
+	"encoding/hex"
+	"io"
+	"os"
+	"strings"
+	"testing"
+)
+
+// 番茄短剧真实样本（video_model video_1..4 共用同一 spade_a）
+const testSpadeA = "kbwfwFiKI8RuvCnHV4ss9lK6HMFmvS/2f7wv7H+mAfRRvxmXlw=="
+
+func TestDecodeSpadeKey(t *testing.T) {
+	key, err := DecodeSpadeKey(testSpadeA)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "4f04d75b0df5cee67dbe13738872e965"
+	if got := hex.EncodeToString(key); got != want {
+		t.Fatalf("key mismatch: got %s want %s", got, want)
+	}
+}
+
+// 端到端：下载真实 360p 视频 → DecryptCENCMP4 → 输出文件（ffprobe 验证）
+func TestDecryptRealVideo(t *testing.T) {
+	mainURLB64 := os.Getenv("FQ_VIDEO_URL")
+	spadeA := strings.TrimSpace(os.Getenv("FQ_VIDEO_SPADE"))
+	if mainURLB64 == "" || spadeA == "" {
+		t.Skip("need FQ_VIDEO_URL (main_url base64) and FQ_VIDEO_SPADE")
+	}
+	url, err := base64.StdEncoding.DecodeString(mainURLB64)
+	if err != nil {
+		t.Fatal(err)
+	}
+	body, _, err := downloadMedia(string(bytes.TrimSpace(url)), "", map[string]string{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer body.Close()
+	data, err := io.ReadAll(body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Logf("downloaded %d bytes", len(data))
+
+	key, err := DecodeSpadeKey(spadeA)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Logf("key=%x", key)
+	if err := DecryptCENCMP4(data, key); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile("/tmp/video_decrypted.mp4", data, 0644); err != nil {
+		t.Fatal(err)
+	}
+	t.Log("written /tmp/video_decrypted.mp4")
+}
+
+// ---- 合成 CENC MP4 单元测试：加密 → 解密 → 比对明文 ----
+
+func box(typ string, payload ...[]byte) []byte {
+	var body []byte
+	for _, p := range payload {
+		body = append(body, p...)
+	}
+	b := make([]byte, 8+len(body))
+	binary.BigEndian.PutUint32(b[:4], uint32(len(b)))
+	copy(b[4:8], typ)
+	copy(b[8:], body)
+	return b
+}
+
+func u32(v uint32) []byte { b := make([]byte, 4); binary.BigEndian.PutUint32(b, v); return b }
+
+func TestDecryptCENCMP4Synthetic(t *testing.T) {
+	key := []byte("0123456789abcdef")
+	plain1 := []byte("HELLO_CENC_SAMPLE_1_PADPADP")
+	plain2 := []byte("SECOND_SAMPLE")
+	plain3 := []byte("THIRD")
+
+	enc := func(pt []byte, iv8 []byte) []byte {
+		iv := make([]byte, 16)
+		copy(iv, iv8)
+		block, _ := aes.NewCipher(key)
+		ct := make([]byte, len(pt))
+		cipher.NewCTR(block, iv).XORKeyStream(ct, pt)
+		return ct
+	}
+	iv1 := []byte{1, 2, 3, 4, 5, 6, 7, 8}
+	iv2 := []byte{8, 7, 6, 5, 4, 3, 2, 1}
+	iv3 := []byte{0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x11, 0x22}
+	ct1, ct2, ct3 := enc(plain1, iv1), enc(plain2, iv2), enc(plain3, iv3)
+
+	// buildFile(off1, off2)：chunk 绝对偏移写入 stco；偏移依赖 moov 长度，先占位测长再重建
+	buildFile := func(off1, off2 uint32) []byte {
+		entry := box("enca", make([]byte, 8), box("sinf", box("frma", []byte("mp4a"))))
+		stsd := box("stsd", u32(0), u32(1), entry)
+		stsz := box("stsz", u32(0), u32(0), u32(3), u32(uint32(len(plain1))), u32(uint32(len(plain2))), u32(uint32(len(plain3))))
+		stsc := box("stsc", u32(0), u32(2),
+			u32(1), u32(2), u32(1), // entry1: chunk1 起，每 chunk 2 样本
+			u32(2), u32(1), u32(1)) // entry2: chunk2 起，每 chunk 1 样本
+		stco := box("stco", u32(0), u32(2), u32(off1), u32(off2))
+		sencBody := append(append(append(append(u32(0), u32(3)...), iv1...), iv2...), iv3...)
+		senc := box("senc", sencBody)
+		moov := box("moov", box("trak", box("mdia", box("minf", box("stbl", stsd, stsz, stsc, stco, senc)))))
+		ftyp := box("ftyp", []byte("isom"))
+		return append(append(ftyp, moov...), box("mdat", ct1, ct2, ct3)...)
+	}
+
+	// 占位构造测 moov 总长，得到真实 chunk 偏移后重建
+	probe := buildFile(0, 0)
+	chunk1Off := uint32(len(probe) - len(ct1) - len(ct2) - len(ct3))
+	chunk2Off := chunk1Off + uint32(len(ct1)+len(ct2))
+	data := buildFile(chunk1Off, chunk2Off)
+
+	if err := DecryptCENCMP4(data, key); err != nil {
+		t.Fatal(err)
+	}
+	if got := data[chunk1Off : chunk1Off+uint32(len(plain1))]; string(got) != string(plain1) {
+		t.Errorf("sample1 解密不符: %q", got)
+	}
+	s2 := chunk1Off + uint32(len(plain1))
+	if got := data[s2 : s2+uint32(len(plain2))]; string(got) != string(plain2) {
+		t.Errorf("sample2 解密不符: %q", got)
+	}
+	if got := data[chunk2Off : chunk2Off+uint32(len(plain3))]; string(got) != string(plain3) {
+		t.Errorf("sample3 解密不符: %q", got)
+	}
+	// stsd entry 类型应被 patch 为 frma 指示的 mp4a（原 enca 四字已不存在）
+	if bytes.Index(data, []byte("enca")) >= 0 || bytes.Index(data, []byte("mp4a")) < 0 {
+		t.Error("stsd entry 类型未修复为 mp4a")
+	}
+}
+
+// 清晰度过滤：按 definition 与档位 key 均可命中；无匹配返回空列表由上层报错
+func TestDecodeVideoModelQualityFilter(t *testing.T) {
+	vm := `{"video_id":"v123","video_duration":1.5,"video_list":{
+		"video_1":{"definition":"360p","vtype":"mp4","main_url":"` + base64.StdEncoding.EncodeToString([]byte("https://a/360")) + `"},
+		"video_4":{"definition":"720p","vtype":"mp4","main_url":"` + base64.StdEncoding.EncodeToString([]byte("https://a/720")) + `"}}}`
+	got := decodeVideoModelAsJSON(vm, "url", "", "720p").(map[string]interface{})
+	vl := got["video_list"].(map[string]interface{})
+	if len(vl) != 1 || vl["video_4"] == nil {
+		t.Fatalf("definition 过滤失败: %v", vl)
+	}
+	got = decodeVideoModelAsJSON(vm, "url", "", "VIDEO_1").(map[string]interface{})
+	vl = got["video_list"].(map[string]interface{})
+	if len(vl) != 1 || vl["video_1"] == nil {
+		t.Fatalf("档位key过滤失败: %v", vl)
+	}
+	if u := vl["video_1"].(map[string]interface{})["main_url"].(string); u != "https://a/360" {
+		t.Fatalf("main_url 未解码: %s", u)
+	}
+	got = decodeVideoModelAsJSON(vm, "url", "", "1080p").(map[string]interface{})
+	if len(got["video_list"].(map[string]interface{})) != 0 {
+		t.Fatal("无匹配应返回空列表")
+	}
+	// max 取最高档（vheight 缺失时按 definition 数字比较）
+	got = decodeVideoModelAsJSON(vm, "url", "", "max").(map[string]interface{})
+	vl = got["video_list"].(map[string]interface{})
+	if len(vl) != 1 || vl["video_4"] == nil {
+		t.Fatalf("max 应只保留最高档: %v", vl)
+	}
+	// vheight 存在时优先按 vheight
+	vm2 := `{"video_list":{
+		"video_1":{"definition":"360p","vwidth":360,"vheight":640},
+		"video_2":{"definition":"540p","vwidth":540,"vheight":960}}}`
+	got = decodeVideoModelAsJSON(vm2, "url", "", "max").(map[string]interface{})
+	if len(got["video_list"].(map[string]interface{})) != 1 || got["video_list"].(map[string]interface{})["video_2"] == nil {
+		t.Fatal("max 应按 vheight 取 video_2")
+	}
+}

internal/handlers/book.go

@@ -4,7 +4,6 @@ import (
 	"fanqie/internal/fqapi"
 	"fmt"
 	"net/http"
-	"strconv"
 )
 
 // HandleSearch 搜索处理
@@ -16,22 +15,29 @@ func HandleSearch(w http.ResponseWriter, r *http.Request) {
 	if query == "" {
 		query = r.URL.Query().Get("key")
 	}
-
-	offsetStr := r.URL.Query().Get("offset")
-	offset := 0
-	if offsetStr != "" {
-		offset, _ = strconv.Atoi(offsetStr)
+	if query == "" {
+		respondError(w, "缺少 query 参数", true)
+		return
 	}
 
-	tabTypeStr := r.URL.Query().Get("tab_type")
-	tabType := 3
-	if tabTypeStr != "" {
-		tabType, _ = strconv.Atoi(tabTypeStr)
+	offset, err := parseIntParam(r.URL.Query().Get("offset"), "offset")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	tabType, err := parseIntParam(r.URL.Query().Get("tab_type"), "tab_type")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+	if tabType == 0 {
+		tabType = 3
 	}
 
 	result, err := fqapi.HandleBookSearch(query, offset, tabType)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "搜索失败: %s"}`, err.Error())
+		respondError(w, "搜索失败: "+err.Error(), false)
 		return
 	}
 
@@ -43,11 +49,15 @@ func HandleDetail(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "detail")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
-
-	result, err := fqapi.HandleGetDetail(bookID)
+	params, err := validateParams(r, "book_id")
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取详情失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleGetDetail(params["book_id"])
+	if err != nil {
+		respondError(w, "获取详情失败: "+err.Error(), false)
 		return
 	}
 
@@ -59,11 +69,15 @@ func HandleCatalog(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "catalog")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
-
-	result, err := fqapi.HandleGetCatalog(bookID)
+	params, err := validateParams(r, "book_id")
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取目录失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleGetCatalog(params["book_id"])
+	if err != nil {
+		respondError(w, "获取目录失败: "+err.Error(), false)
 		return
 	}
 
@@ -72,16 +86,91 @@ func HandleCatalog(w http.ResponseWriter, r *http.Request) {
 
 // HandleMultiDetail 批量详情处理
 func HandleMultiDetail(w http.ResponseWriter, r *http.Request) {
+	incrementStat("total", "detail")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
-
-	result, err := fqapi.HandleGetMultiDetail(bookID)
+	params, err := validateParams(r, "book_id")
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "批量获取详情失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleGetMultiDetail(params["book_id"])
+	if err != nil {
+		respondError(w, "批量获取详情失败: "+err.Error(), false)
 		return
 	}
 
 	fmt.Fprint(w, result)
 }
 
+// HandleRank 榜单处理（推荐/完结/热搜/黑马/爆更榜，免签名接口）
+func HandleRank(w http.ResponseWriter, r *http.Request) {
+	incrementStat("total", "category")
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+
+	sideType, err := parseIntParam(r.URL.Query().Get("side_type"), "side_type")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+	page, err := parseIntParam(r.URL.Query().Get("page"), "page")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleGetRank(sideType, page)
+	if err != nil {
+		respondError(w, "获取榜单失败: "+err.Error(), false)
+		return
+	}
+
+	fmt.Fprint(w, result)
+}
+
+// HandleBookshelf 书架处理（需登录 sessionid）
+func HandleBookshelf(w http.ResponseWriter, r *http.Request) {
+	incrementStat("total", "category")
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+
+	params, err := validateParams(r, "sessionid")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleBookshelf(params["sessionid"], r.URL.Query().Get("group"))
+	if err != nil {
+		respondError(w, "获取书架失败: "+err.Error(), false)
+		return
+	}
+
+	fmt.Fprint(w, result)
+}
+
+// HandleReadHistory 阅读历史处理（需登录 sessionid）
+func HandleReadHistory(w http.ResponseWriter, r *http.Request) {
+	incrementStat("total", "category")
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+
+	params, err := validateParams(r, "sessionid")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	offset, err := parseIntParam(r.URL.Query().Get("offset"), "offset")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleReadHistory(params["sessionid"], offset)
+	if err != nil {
+		respondError(w, "获取阅读历史失败: "+err.Error(), false)
+		return
+	}
+
+	fmt.Fprint(w, result)
+}

internal/handlers/category.go

@@ -15,7 +15,7 @@ func HandleCategoryFront(w http.ResponseWriter, r *http.Request) {
 
 	result, err := fqapi.HandleCategoryFront(tab)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取分类列表失败: %s"}`, err.Error())
+		respondError(w, "获取分类列表失败: "+err.Error(), false)
 		return
 	}
 
@@ -32,13 +32,14 @@ func HandleCategoryLanding(w http.ResponseWriter, r *http.Request) {
 	wordNumber := r.URL.Query().Get("word_number")
 	bookStatus := r.URL.Query().Get("book_status")
 	sortBy := r.URL.Query().Get("sort_by")
+	// 新版分类标签自带的筛选项（见 /category-front 返回的 category_landpage_url 参数）
+	selectedItems := r.URL.Query().Get("selected_items")
 
-	result, err := fqapi.HandleCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy)
+	result, err := fqapi.HandleCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy, selectedItems)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取分类详情失败: %s"}`, err.Error())
+		respondError(w, "获取分类详情失败: "+err.Error(), false)
 		return
 	}
 
 	fmt.Fprint(w, result)
 }
-

internal/handlers/common.go

@@ -1,13 +1,19 @@
 package handlers
 
 import (
+	"crypto/subtle"
 	"encoding/json"
 	"fanqie/internal/config"
 	"fanqie/internal/fqapi"
 	"fmt"
+	"net"
 	"net/http"
+	"strings"
+	"sync"
 	"sync/atomic"
 	"time"
+
+	"golang.org/x/time/rate"
 )
 
 var (
@@ -61,7 +67,7 @@ func LoadStatistics() {
 		fmt.Printf("加载统计数据失败: %v\n", err)
 		return
 	}
-	
+
 	for k, v := range stats {
 		if c, ok := requestStats[k]; ok {
 			c.Store(v)
@@ -96,36 +102,199 @@ func StopStatisticsSaver() {
 	}
 }
 
+// getQueryWithAlias 读 URL 参数，主名未传时回退到别名（兼容 README 历史参数名）
+func getQueryWithAlias(r *http.Request, name, alias string) string {
+	if v := r.URL.Query().Get(name); v != "" {
+		return v
+	}
+	return r.URL.Query().Get(alias)
+}
+
+// respondError 统一错误响应（JSON 安全编码；isClientErr 为 true 时返回 400，否则 500）
+func respondError(w http.ResponseWriter, msg string, isClientErr bool) {
+	status := http.StatusInternalServerError
+	if isClientErr {
+		status = http.StatusBadRequest
+	}
+	respondJSON(w, status, map[string]interface{}{"code": -1, "msg": msg})
+}
+
+// RateLimit 每 IP 限流（server.rate_limit_qps > 0 时启用）
+// ponytail: 配置启动时读取一次，热更新不生效；visitor 表由后台协程清理防泄漏
+func RateLimit(handler http.HandlerFunc) http.HandlerFunc {
+	cfg := config.GetAppConfig()
+	qps := 0.0
+	if cfg != nil {
+		qps = cfg.Server.RateLimitQPS
+	}
+	if qps <= 0 {
+		return handler
+	}
+
+	const burst = 10
+	var mu sync.Mutex
+	limitters := map[string]*rate.Limiter{}
+	lastSeen := map[string]time.Time{}
+
+	go func() {
+		for range time.Tick(time.Minute) {
+			mu.Lock()
+			for ip, t := range lastSeen {
+				if time.Since(t) > 10*time.Minute {
+					delete(lastSeen, ip)
+					delete(limitters, ip)
+				}
+			}
+			mu.Unlock()
+		}
+	}()
+
+	return func(w http.ResponseWriter, r *http.Request) {
+		ip := clientIP(r)
+		mu.Lock()
+		l, ok := limitters[ip]
+		if !ok {
+			l = rate.NewLimiter(rate.Limit(qps), burst)
+			limitters[ip] = l
+		}
+		lastSeen[ip] = time.Now()
+		mu.Unlock()
+
+		if !l.Allow() {
+			respondJSON(w, http.StatusTooManyRequests, map[string]interface{}{
+				"code": -1, "msg": "请求过于频繁，请稍后再试",
+			})
+			return
+		}
+		handler(w, r)
+	}
+}
+
+// clientIP 取客户端 IP：优先 X-Forwarded-For 首段（反代场景），否则 RemoteAddr
+func clientIP(r *http.Request) string {
+	if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
+		return strings.TrimSpace(strings.Split(xff, ",")[0])
+	}
+	if host, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
+		return host
+	}
+	return r.RemoteAddr
+}
+
 // RequireAccessKey 验证访问密钥中间件
 func RequireAccessKey(handler http.HandlerFunc) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		cfg := config.GetConfig()
-		
+
 		// 如果未配置 access_key 或为空，则不启用验证
 		if cfg == nil || cfg.Server.AccessKey == "" {
 			handler(w, r)
 			return
 		}
-		
+
 		// 从查询参数或 Header 中获取 key
 		key := r.URL.Query().Get("key")
 		if key == "" {
 			key = r.Header.Get("X-Access-Key")
 		}
-		
-		// 验证密钥
-		if key != cfg.Server.AccessKey {
+
+		// 验证密钥（常量时间比较，防时序攻击）
+		if subtle.ConstantTimeCompare([]byte(key), []byte(cfg.Server.AccessKey)) != 1 {
 			w.Header().Set("Content-Type", "application/json; charset=utf-8")
 			w.WriteHeader(http.StatusUnauthorized)
 			fmt.Fprintf(w, `{"code": -1, "msg": "访问被拒绝：无效的访问密钥"}`)
 			return
 		}
-		
+
 		// 验证通过，继续处理请求
 		handler(w, r)
 	}
 }
 
+// OptionalAccessKey 业务接口保护（仅 server.protect_all 开启时校验）
+func OptionalAccessKey(handler http.HandlerFunc) http.HandlerFunc {
+	cfg := config.GetAppConfig()
+	if cfg == nil || !cfg.Server.ProtectAll {
+		return handler
+	}
+	return RequireAccessKey(handler)
+}
+
+// statusWriter 捕获状态码；status>=400 时截断留存响应体前 ErrMsgMax 字节用于排障
+type statusWriter struct {
+	http.ResponseWriter
+	status int
+	errBuf []byte
+}
+
+func (w *statusWriter) WriteHeader(code int) {
+	w.status = code
+	w.ResponseWriter.WriteHeader(code)
+}
+
+func (w *statusWriter) Write(p []byte) (int, error) {
+	if w.status >= 400 && len(w.errBuf) < fqapi.ErrMsgMax {
+		n := min(len(p), fqapi.ErrMsgMax-len(w.errBuf))
+		w.errBuf = append(w.errBuf, p[:n]...)
+	}
+	return w.ResponseWriter.Write(p)
+}
+
+// LogRequestMiddleware 异步记录请求元数据（时间/IP/方法/路径/状态/耗时）到数据库
+// ponytail: 配置启动时读取一次，热更新不生效；未启用时零开销直通
+func LogRequestMiddleware(handler http.HandlerFunc) http.HandlerFunc {
+	cfg := config.GetAppConfig()
+	if cfg == nil || !cfg.Server.RequestLog.Enabled {
+		return handler
+	}
+	return func(w http.ResponseWriter, r *http.Request) {
+		start := time.Now()
+		sw := &statusWriter{ResponseWriter: w, status: http.StatusOK}
+		handler(sw, r)
+
+		ua := r.UserAgent()
+		if len(ua) > 512 { // 防恶意超长 UA 撑爆日志
+			ua = ua[:512]
+		}
+		fqapi.LogRequest(fqapi.RequestLogEntry{
+			Ts:         start.Unix(),
+			IP:         clientIP(r),
+			Method:     r.Method,
+			Path:       r.URL.Path,
+			Query:      decodedQuery(r),
+			Status:     sw.status,
+			DurationMs: time.Since(start).Milliseconds(),
+			ErrorMsg:   string(sw.errBuf),
+			UserAgent:  ua,
+		})
+	}
+}
+
+// decodedQuery 重组解码后的查询串（keyword=%E6%B5%8B → keyword=测），日志可读；
+// key 参数值脱敏（访问密钥不落日志）
+// ponytail: map 遍历乱序、%26 解码后与分隔符同名 —— 展示用途可接受
+func decodedQuery(r *http.Request) string {
+	vals := r.URL.Query() // 已解码
+	if len(vals) == 0 {
+		return ""
+	}
+	parts := make([]string, 0, len(vals))
+	for k, vs := range vals {
+		for _, v := range vs {
+			if strings.EqualFold(k, "key") && v != "" {
+				v = "***"
+			}
+			parts = append(parts, k+"="+v)
+		}
+	}
+	return strings.Join(parts, "&")
+}
+
+// HandleHealth 存活探针（供容器/反向代理使用）
+func HandleHealth(w http.ResponseWriter, r *http.Request) {
+	fmt.Fprint(w, "ok")
+}
+
 // HandleMain 主页处理
 func HandleMain(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
@@ -136,22 +305,3 @@ func HandleMain(w http.ResponseWriter, r *http.Request) {
 	}
 	json.NewEncoder(w).Encode(response)
 }
-
-// HandleSelfInfo 设备信息处理
-func HandleSelfInfo(w http.ResponseWriter, r *http.Request) {
-	w.Header().Set("Content-Type", "application/json; charset=utf-8")
-	
-	// 获取设备池统计信息
-	pool := fqapi.GetDeviceKeyPool()
-	poolStats := pool.GetStats()
-	
-	response := map[string]interface{}{
-		"code":    0,
-		"message": "SUCCESS",
-		"data": map[string]interface{}{
-			"device_pool_enabled": pool.IsEnabled(),
-			"device_pool_stats":   poolStats,
-		},
-	}
-	json.NewEncoder(w).Encode(response)
-}

internal/handlers/content.go

@@ -12,33 +12,35 @@ func HandleContent(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "content")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	// 从查询参数获取item_id
-	itemID := r.URL.Query().Get("item_id")
-	
-	// 获取URL参数（支持动态覆盖配置）
-	textMode := r.URL.Query().Get("text_mode")     // 1=纯文本模式
-	imageMode := r.URL.Query().Get("image_mode")   // 0=移除图片, 1=保留图片
-	reviewParam := r.URL.Query().Get("review")     // 1=启用段评, 0=禁用段评
+	params, err := validateParams(r, "item_id")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+	itemID := params["item_id"]
+
+	// 获取URL参数（支持动态覆盖配置；image_mode/review 兼容 README 的 img_mode/review_mode 别名）
+	textMode := r.URL.Query().Get("text_mode") // plain/1=纯文本, html/0=HTML
+	imageMode := getQueryWithAlias(r, "image_mode", "img_mode")
+	reviewParam := getQueryWithAlias(r, "review", "review_mode") // keep/1=启用段评, remove/0=禁用段评
 
 	result, err := fqapi.HandleGetContent(itemID, textMode, imageMode)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取内容失败: %s"}`, err.Error())
+		respondError(w, "获取内容失败: "+err.Error(), false)
 		return
 	}
 
 	// 判断是否启用段评功能
 	// 优先使用URL参数，如果没有则使用配置文件
-	enableReview := false
-	if reviewParam == "1" {
-		enableReview = true
-	} else if reviewParam == "0" {
-		enableReview = false
-	} else {
+	var enableReview bool
+	if reviewParam == "" {
 		// 没有URL参数时，使用配置文件
 		cfg := config.GetConfig()
 		if cfg != nil {
 			enableReview = cfg.Fanqie.Content.EnableReview
 		}
+	} else {
+		enableReview = fqapi.ParseBoolParam(reviewParam)
 	}
 
 	// 如果启用了段评功能，处理正文内容添加段评标记
@@ -51,17 +53,22 @@ func HandleContent(w http.ResponseWriter, r *http.Request) {
 
 // HandleMultiContent 批量内容处理
 func HandleMultiContent(w http.ResponseWriter, r *http.Request) {
+	incrementStat("total", "content")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
-	itemIDs := r.URL.Query().Get("item_ids")
+	params, err := validateParams(r, "book_id", "item_ids")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
 	textMode := r.URL.Query().Get("text_mode")
-	imageMode := r.URL.Query().Get("image_mode")
+	imageMode := getQueryWithAlias(r, "image_mode", "img_mode")
 	ignoreFailed := r.URL.Query().Get("ignore_failed")
 
-	result, err := fqapi.HandleMultiContent(itemIDs, bookID, textMode, imageMode, ignoreFailed)
+	result, err := fqapi.HandleMultiContent(params["item_ids"], params["book_id"], textMode, imageMode, ignoreFailed)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "批量获取内容失败: %s"}`, err.Error())
+		respondError(w, "批量获取内容失败: "+err.Error(), false)
 		return
 	}
 
@@ -72,12 +79,15 @@ func HandleMultiContent(w http.ResponseWriter, r *http.Request) {
 func HandleItemSummary(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
-	itemIDs := r.URL.Query().Get("item_ids")
-
-	result, err := fqapi.HandleItemSummary(itemIDs, bookID)
+	params, err := validateParams(r, "book_id", "item_ids")
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取章节摘要失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleItemSummary(params["item_ids"], params["book_id"])
+	if err != nil {
+		respondError(w, "获取章节摘要失败: "+err.Error(), false)
 		return
 	}
 
@@ -91,19 +101,19 @@ func addReviewToContent(jsonResult, itemID string, r *http.Request) string {
 	if err := fqapi.ParseJSON([]byte(jsonResult), &resultData); err != nil {
 		return jsonResult
 	}
-	
+
 	// 获取 data 字段
 	data, ok := resultData["data"].(map[string]interface{})
 	if !ok {
 		return jsonResult
 	}
-	
+
 	// 获取 content 字段
 	content, ok := data["content"].(string)
 	if !ok || content == "" {
 		return jsonResult
 	}
-	
+
 	// 从响应数据中提取 book_id (data.novel_data.book_id)
 	bookID := ""
 	if novelData, ok := data["novel_data"].(map[string]interface{}); ok {
@@ -113,43 +123,36 @@ func addReviewToContent(jsonResult, itemID string, r *http.Request) string {
 			bookID = fmt.Sprintf("%.0f", bookIDVal)
 		}
 	}
-	
-	// 获取基础 URL
+
+	// 获取基础 URL（反代场景识别 X-Forwarded-Proto，避免生成 http:// 被 301）
 	cfg := config.GetConfig()
 	baseURL := ""
-	if cfg != nil {
+	if r.Host != "" {
+		baseURL = externalBaseURL(r)
+	} else if cfg != nil {
 		host := cfg.Server.Host
 		if host == "0.0.0.0" {
 			host = "localhost"
 		}
-		port := cfg.Server.Port
-		scheme := "http"
-		
-		// 检查是否来自外部请求
-		if r.Host != "" {
-			baseURL = scheme + "://" + r.Host
-		} else {
-			baseURL = scheme + "://" + host + ":" + port
-		}
+		baseURL = "http://" + host + ":" + cfg.Server.Port
 	}
-	
+
 	// 生成带段评标记的内容
 	newContent, err := fqapi.GenerateParagraphsWithComments(itemID, bookID, content, baseURL)
 	if err != nil {
 		// 如果失败，返回原始内容
 		return jsonResult
 	}
-	
+
 	// 替换 content 字段
 	data["content"] = newContent
 	resultData["data"] = data
-	
+
 	// 重新序列化为 JSON
 	newJSON, err := fqapi.ToJSON(resultData)
 	if err != nil {
 		return jsonResult
 	}
-	
+
 	return newJSON
 }
-

internal/handlers/error_response_test.go

@@ -0,0 +1,62 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// TestRespondErrorProducesValidJSON 错误信息含引号/换行时输出仍须是合法 JSON
+func TestRespondErrorProducesValidJSON(t *testing.T) {
+	w := httptest.NewRecorder()
+	respondError(w, "上游返回了 \"引号\" 和\n换行", false)
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {
+		t.Fatalf("非法 JSON: %v, body: %s", err, w.Body.String())
+	}
+	if body["code"].(float64) != -1 {
+		t.Errorf("code 应为 -1, got %v", body["code"])
+	}
+	if w.Code != 500 {
+		t.Errorf("服务端错误应返回 500, got %d", w.Code)
+	}
+}
+
+// TestRespondErrorClientErr 客户端错误应返回 400
+func TestRespondErrorClientErr(t *testing.T) {
+	w := httptest.NewRecorder()
+	respondError(w, "缺少 book_id 参数", true)
+	if w.Code != 400 {
+		t.Errorf("客户端错误应返回 400, got %d", w.Code)
+	}
+}
+
+// TestHandleDetailMissingParam 缺少必需参数返回 400 而非透传到上游
+func TestHandleDetailMissingParam(t *testing.T) {
+	w := httptest.NewRecorder()
+	HandleDetail(w, httptest.NewRequest("GET", "/detail", nil))
+	if w.Code != 400 {
+		t.Errorf("缺参应返回 400, got %d, body: %s", w.Code, w.Body.String())
+	}
+}
+
+// TestOptionalAccessKeyDisabled protect_all 未启用（或配置未加载）时直接放行
+func TestOptionalAccessKeyDisabled(t *testing.T) {
+	called := false
+	h := OptionalAccessKey(func(w http.ResponseWriter, r *http.Request) { called = true })
+	h(httptest.NewRecorder(), httptest.NewRequest("GET", "/search?query=x", nil))
+	if !called {
+		t.Error("protect_all 未启用时应直接放行")
+	}
+}
+
+// TestHandleHealth 存活探针返回 200 ok
+func TestHandleHealth(t *testing.T) {
+	w := httptest.NewRecorder()
+	HandleHealth(w, httptest.NewRequest("GET", "/healthz", nil))
+	if w.Code != 200 || w.Body.String() != "ok" {
+		t.Errorf("应返回 200 ok, got %d %q", w.Code, w.Body.String())
+	}
+}

internal/handlers/gzip.go

@@ -0,0 +1,74 @@
+package handlers
+
+import (
+	"compress/gzip"
+	"net/http"
+	"strings"
+)
+
+// Gzip 对 JSON/文本响应启用 gzip 压缩（仅客户端声明 Accept-Encoding: gzip 时）。
+// 图片/音频等二进制响应不在白名单内，原样透传。
+func Gzip(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !strings.Contains(r.Header.Get("Accept-Encoding"), "gzip") {
+			next.ServeHTTP(w, r)
+			return
+		}
+		gw := &gzipWriter{ResponseWriter: w}
+		defer gw.close()
+		next.ServeHTTP(gw, r)
+	})
+}
+
+type gzipWriter struct {
+	http.ResponseWriter
+	zw         *gzip.Writer
+	decided    bool // 是否已根据 Content-Type 做过压缩决定
+	headerSent bool
+}
+
+func (g *gzipWriter) WriteHeader(status int) {
+	if g.headerSent {
+		return
+	}
+	if !g.decided {
+		g.decide()
+	}
+	g.ResponseWriter.WriteHeader(status)
+	g.headerSent = true
+}
+
+func (g *gzipWriter) Write(b []byte) (int, error) {
+	if !g.headerSent {
+		// handler 未显式 WriteHeader（fmt.Fprint 直接写）时的隐式 200
+		if !g.decided {
+			g.decide()
+		}
+		g.ResponseWriter.WriteHeader(http.StatusOK)
+		g.headerSent = true
+	}
+	if g.zw != nil {
+		return g.zw.Write(b)
+	}
+	return g.ResponseWriter.Write(b)
+}
+
+// decide 在首个响应头确定时判断是否压缩（此时 handler 已设置 Content-Type）
+func (g *gzipWriter) decide() {
+	g.decided = true
+	ct := g.Header().Get("Content-Type")
+	for _, prefix := range []string{"application/json", "text/html", "text/plain"} {
+		if strings.HasPrefix(ct, prefix) {
+			g.Header().Set("Content-Encoding", "gzip")
+			g.Header().Del("Content-Length")
+			g.zw = gzip.NewWriter(g.ResponseWriter)
+			return
+		}
+	}
+}
+
+func (g *gzipWriter) close() {
+	if g.zw != nil {
+		g.zw.Close()
+	}
+}

internal/handlers/manga_proxy.go

@@ -13,32 +13,31 @@ func HandleMangaImageProxy(w http.ResponseWriter, r *http.Request) {
 	// 从URL路径提取参数: /manga/image/{itemID}/{index}
 	path := strings.TrimPrefix(r.URL.Path, "/manga/image/")
 	parts := strings.Split(path, "/")
-	
+
 	if len(parts) != 2 {
 		http.Error(w, "Invalid URL format. Expected: /manga/image/{itemID}/{index}", http.StatusBadRequest)
 		return
 	}
-	
+
 	itemID := parts[0]
 	index, err := strconv.Atoi(parts[1])
 	if err != nil {
 		http.Error(w, "Invalid index parameter", http.StatusBadRequest)
 		return
 	}
-	
+
 	// 获取解密后的图片数据
 	imageData, mimeType, err := fqapi.HandleMangaImageProxy(itemID, index)
 	if err != nil {
 		http.Error(w, fmt.Sprintf("Failed to get image: %s", err.Error()), http.StatusInternalServerError)
 		return
 	}
-	
+
 	// 设置响应头
 	w.Header().Set("Content-Type", mimeType)
 	w.Header().Set("Cache-Control", "public, max-age=3600") // 缓存1小时
 	w.Header().Set("Content-Length", strconv.Itoa(len(imageData)))
-	
+
 	// 返回图片数据
 	w.Write(imageData)
 }
-

internal/handlers/media.go

@@ -4,8 +4,10 @@ import (
 	"encoding/json"
 	"fanqie/internal/fqapi"
 	"fmt"
+	"io"
 	"net/http"
 	"strings"
+	"time"
 )
 
 // HandleAudio 音频处理
@@ -13,22 +15,27 @@ func HandleAudio(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "audio")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	itemIDs := r.URL.Query().Get("item_ids")
+	params, err := validateParams(r, "item_ids")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
 	toneID := r.URL.Query().Get("tone_id")
 	output := r.URL.Query().Get("output")
 
-	result, err := fqapi.HandleAudio(itemIDs, toneID, output)
+	result, err := fqapi.HandleAudio(params["item_ids"], toneID, output)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取音频失败: %s"}`, err.Error())
+		respondError(w, "获取音频失败: "+err.Error(), false)
 		return
 	}
 
 	fmt.Fprint(w, result)
 }
 
-// HandleAudioProxy 音频代理处理
+// HandleAudioProxy 音频代理处理（流式转发，音频不全量驻留内存）
 func HandleAudioProxy(w http.ResponseWriter, r *http.Request) {
-	incrementStat("total")
+	incrementStat("total", "audio")
 
 	// 从URL路径提取key: /audio/proxy/{key}
 	path := r.URL.Path
@@ -39,11 +46,12 @@ func HandleAudioProxy(w http.ResponseWriter, r *http.Request) {
 	}
 
 	// 调用代理处理函数
-	data, contentType, err := fqapi.HandleAudioProxy(key)
+	body, contentType, err := fqapi.HandleAudioProxy(key)
 	if err != nil {
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return
 	}
+	defer body.Close()
 
 	// 设置正确的Content-Type
 	if contentType != "" {
@@ -54,7 +62,7 @@ func HandleAudioProxy(w http.ResponseWriter, r *http.Request) {
 
 	// 直接播放，不强制下载
 	// 浏览器会根据Content-Type决定是播放还是下载
-	w.Write(data)
+	io.Copy(w, body)
 }
 
 // HandleVideo 视频处理
@@ -62,28 +70,57 @@ func HandleVideo(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "video")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	itemIDs := r.URL.Query().Get("item_ids")
-
-	result, err := fqapi.HandleVideo(itemIDs)
+	params, err := validateParams(r, "item_ids")
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取视频失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	output := r.URL.Query().Get("output")
+	quality := r.URL.Query().Get("quality")
+	result, err := fqapi.HandleVideo(params["item_ids"], output, quality)
+	if err != nil {
+		respondError(w, "获取视频失败: "+err.Error(), false)
 		return
 	}
 
 	fmt.Fprint(w, result)
 }
 
+// HandleVideoProxy 视频解密代理处理（磁盘缓存优先；http.ServeContent 支持 Range/seek/HEAD，
+// 播放器拖动进度条时按需分片返回）
+func HandleVideoProxy(w http.ResponseWriter, r *http.Request) {
+	incrementStat("total", "video")
+
+	path := r.URL.Path
+	key := strings.TrimPrefix(path, "/video/proxy/")
+	if key == "" || key == path {
+		http.Error(w, "缺少视频key", http.StatusBadRequest)
+		return
+	}
+
+	content, contentType, err := fqapi.HandleVideoProxy(key)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if closer, ok := content.(io.Closer); ok {
+		defer closer.Close()
+	}
+	w.Header().Set("Content-Type", contentType)
+	http.ServeContent(w, r, key+".mp4", time.Time{}, content)
+}
+
 // HandleManga 漫画处理
 func HandleManga(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "manga")
+
 	itemID := r.URL.Query().Get("item_ids")
 	if itemID == "" {
 		itemID = r.URL.Query().Get("item_id")
 	}
-
 	if itemID == "" {
-		w.Header().Set("Content-Type", "application/json; charset=utf-8")
-		fmt.Fprint(w, `{"code": -1, "msg": "缺少item_ids参数"}`)
+		respondError(w, "缺少 item_ids 参数", true)
 		return
 	}
 
@@ -96,8 +133,7 @@ func HandleManga(w http.ResponseWriter, r *http.Request) {
 
 	result, err := fqapi.HandleGetManga(itemID, showHTML, outputMode)
 	if err != nil {
-		w.Header().Set("Content-Type", "application/json; charset=utf-8")
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取漫画失败: %s"}`, err.Error())
+		respondError(w, "获取漫画失败: "+err.Error(), false)
 		return
 	}
 
@@ -113,17 +149,16 @@ func HandleManga(w http.ResponseWriter, r *http.Request) {
 		fmt.Fprint(w, `<p>未找到漫画内容</p>`)
 	} else {
 		// 返回JSON格式
-		w.Header().Set("Content-Type", "application/json; charset=utf-8")
 		jsonData, err := json.Marshal(map[string]interface{}{
 			"code": 0,
 			"msg":  "success",
 			"data": result,
 		})
 		if err != nil {
-			fmt.Fprintf(w, `{"code": -1, "msg": "JSON编码失败: %s"}`, err.Error())
+			respondError(w, "JSON编码失败: "+err.Error(), false)
 			return
 		}
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
 		fmt.Fprint(w, string(jsonData))
 	}
 }
-

internal/handlers/templates/review.html

@@ -0,0 +1,802 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
+    <title>番茄段评 · 第 {{.ParaPlus1}} 段</title>
+    <link rel="stylesheet" href="https://cdn.bootcdn.net/ajax/libs/font-awesome/6.4.0/css/all.css">
+    <meta name="color-scheme" content="light dark">
+    <style>
+        :root {
+            /* 浅色模式变量 */
+            --bg-primary: #f5f5f5;
+            --bg-secondary: #ffffff;
+            --text-primary: #333333;
+            --text-secondary: #666666;
+            --text-tertiary: #999999;
+            --border-color: #e5e5e5;
+            --shadow: rgba(0, 0, 0, 0.05);
+            --badge-bg: #f0f5ff;
+            --badge-color: #4a80f0;
+            --tag-bg: #f0f0f0;
+            --tag-color: #666666;
+            --avatar-bg: #f0f0f0;
+            --loading-color: #666666;
+        }
+        
+        /* 深色模式变量 */
+        @media (prefers-color-scheme: dark) {
+            :root {
+                --bg-primary: #000000;
+                --bg-secondary: #1c1c1e;
+                --text-primary: #ffffff;
+                --text-secondary: #ebebf5;
+                --text-tertiary: #8e8e93;
+                --border-color: #38383a;
+                --shadow: rgba(0, 0, 0, 0.3);
+                --badge-bg: #1c3a5f;
+                --badge-color: #64a3ff;
+                --tag-bg: #2c2c2e;
+                --tag-color: #ebebf5;
+                --avatar-bg: #2c2c2e;
+                --loading-color: #8e8e93;
+            }
+        }
+        
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+        }
+        html, body { height: 100%; }
+        body {
+            background-color: var(--bg-primary);
+            color: var(--text-primary);
+            max-width: 600px;
+            margin: 0 auto;
+            display: flex;
+            flex-direction: column;
+            overflow: hidden;
+            transition: background-color 0.3s ease, color 0.3s ease;
+        }
+        .header {
+            flex-shrink: 0;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            padding: 10px 15px 12px;
+            background: var(--bg-secondary);
+            border-radius: 20px 20px 0 0;
+            border-bottom: 1px solid var(--border-color);
+            box-shadow: 0 2px 8px var(--shadow);
+            position: relative;
+            z-index: 10;
+            transition: background-color 0.3s ease;
+        }
+        /* BottomSheet 顶部拖拽把手 */
+        .header::before {
+            content: '';
+            position: absolute;
+            top: 6px;
+            left: 50%;
+            transform: translateX(-50%);
+            width: 36px;
+            height: 4px;
+            border-radius: 2px;
+            background: var(--border-color);
+        }
+        #comment-list {
+            flex: 1;
+            overflow-y: auto;
+            -webkit-overflow-scrolling: touch;
+            padding: 15px;
+            overscroll-behavior: contain;
+        }
+        .header h1 {
+            font-size: 18px;
+            color: var(--text-primary);
+            margin: 0;
+            flex: 1;
+        }
+        .source-tag {
+            display: inline-block;
+            padding: 3px 8px;
+            background-color: var(--tag-bg);
+            border-radius: 4px;
+            font-size: 14px;
+            margin-left: 8px;
+            color: var(--tag-color);
+            transition: background-color 0.3s ease, color 0.3s ease;
+        }
+        .comment-item {
+            background: var(--bg-secondary);
+            border-radius: 12px;
+            padding: 15px;
+            box-shadow: 0 2px 8px var(--shadow);
+            margin-bottom: 15px;
+            transition: background-color 0.3s ease;
+        }
+        .user-info {
+            display: flex;
+            align-items: center;
+            margin-bottom: 10px;
+        }
+        .user-avatar, .reply-avatar {
+            width: 40px;
+            height: 40px;
+            border-radius: 50%;
+            margin-right: 10px;
+            background: var(--avatar-bg);
+            object-fit: cover;
+        }
+        .reply-avatar {
+            width: 32px;
+            height: 32px;
+        }
+        .user-name {
+            font-weight: 500;
+            font-size: 15px;
+            color: var(--text-primary);
+        }
+        .author-badge {
+            background: var(--badge-bg);
+            color: var(--badge-color);
+            font-size: 12px;
+            padding: 0 6px;
+            border-radius: 3px;
+            margin-left: 6px;
+        }
+        .user-sticker {
+            height: 18px;
+            margin-left: 6px;
+            vertical-align: middle;
+        }
+        .comment-content {
+            font-size: 15px;
+            line-height: 1.5;
+            margin-bottom: 10px;
+            white-space: pre-line;
+        }
+        .comment-img {
+            max-width: 100%;
+            border-radius: 6px;
+            margin: 8px 0;
+            cursor: pointer;
+            background: #eee;
+        }
+        .emoji-img {
+            width: 22px;
+            height: 22px;
+            vertical-align: middle;
+            margin: 0 2px;
+        }
+        .comment-time {
+            font-size: 12px;
+            color: var(--text-tertiary);
+            margin-bottom: 10px;
+        }
+        .comment-meta {
+            display: flex;
+            align-items: center;
+            gap: 15px;
+            font-size: 13px;
+            color: var(--text-secondary);
+        }
+        .comment-meta i {
+            margin-right: 4px;
+            font-size: 14px;
+        }
+        .comment-meta span {
+            cursor: pointer;
+            display: inline-flex;
+            align-items: center;
+            padding: 4px 8px;
+            border-radius: 6px;
+            transition: all 0.2s ease;
+        }
+        .comment-meta span:hover {
+            background: var(--bg-secondary);
+            color: var(--text-primary);
+        }
+        .comment-meta span:hover i {
+            transform: scale(1.1);
+        }
+        .reply-btn {
+            transition: all 0.2s ease;
+        }
+        .reply-btn:active {
+            transform: scale(0.95);
+            opacity: 0.4;
+        }
+        .replies-container {
+            margin-top: 15px;
+            padding-left: 25px;
+            position: relative;
+            display: none;
+        }
+        .replies-container.show {
+            display: block;
+        }
+        .replies-container::before {
+            content: '';
+            position: absolute;
+            left: 8px;
+            top: 0;
+            bottom: 0;
+            width: 2px;
+            background: var(--border-color);
+        }
+        .reply-item {
+            display: flex;
+            align-items: flex-start;
+            margin-bottom: 15px;
+        }
+        .reply-content {
+            flex: 1;
+            padding-top: 2px;
+        }
+        .reply-username {
+            font-weight: 500;
+            font-size: 14px;
+            margin-right: 5px;
+            color: var(--text-primary);
+        }
+        .reply-text {
+            font-size: 14px;
+            line-height: 1.4;
+            margin: 5px 0;
+            color: var(--text-primary);
+        }
+        .reply-time {
+            font-size: 11px;
+            color: var(--text-tertiary);
+            margin-top: 3px;
+        }
+        .image-viewer {
+            position: fixed;
+            top: 0;
+            left: 0;
+            right: 0;
+            bottom: 0;
+            background: rgba(0,0,0,0.9);
+            display: none;
+            justify-content: center;
+            align-items: center;
+            z-index: 1000;
+        }
+        .image-viewer.show {
+            display: flex;
+        }
+        .image-viewer img {
+            max-width: 90%;
+            max-height: 90%;
+        }
+        .close-btn {
+            position: absolute;
+            top: 20px;
+            right: 20px;
+            color: #fff;
+            font-size: 30px;
+            cursor: pointer;
+        }
+        .empty, .loading {
+            text-align: center;
+            color: var(--text-tertiary);
+        }
+        .empty {
+            padding: 20px;
+            background: var(--bg-secondary);
+            border-radius: 12px;
+        }
+        .loading {
+            padding: 10px;
+            color: var(--loading-color);
+        }
+        .sort-tabs {
+            display: flex;
+            gap: 0;
+            background: var(--bg-primary);
+            border-radius: 20px;
+            padding: 3px;
+        }
+        .sort-tab {
+            padding: 6px 16px;
+            background: transparent;
+            border: none;
+            border-radius: 17px;
+            cursor: pointer;
+            font-size: 14px;
+            color: var(--text-secondary);
+            transition: all 0.2s ease;
+            user-select: none;
+            white-space: nowrap;
+        }
+        .sort-tab.active {
+            background: var(--bg-secondary);
+            color: var(--text-primary);
+            font-weight: 500;
+            box-shadow: 0 1px 3px var(--shadow);
+        }
+        .sort-tab:hover:not(.active) {
+            opacity: 0.7;
+        }
+        .back-to-top {
+            position: fixed;
+            bottom: 30px;
+            right: 30px;
+            width: 50px;
+            height: 50px;
+            background: var(--bg-secondary);
+            border-radius: 50%;
+            display: none;
+            align-items: center;
+            justify-content: center;
+            cursor: pointer;
+            box-shadow: 0 4px 12px var(--shadow);
+            transition: all 0.3s ease;
+            z-index: 999;
+            border: 1px solid var(--border-color);
+        }
+        .back-to-top.show {
+            display: flex;
+        }
+        .back-to-top:hover {
+            transform: translateY(-5px);
+            box-shadow: 0 6px 16px var(--shadow);
+        }
+        .back-to-top i {
+            font-size: 20px;
+            color: var(--text-primary);
+        }
+    </style>
+</head>
+<body>
+    <div class="header">
+        <h1><span class="source-tag">段落评论 · {{.Total}} 条</span></h1>
+        <span style="display: flex; align-items: center;">
+            <i class="fas fa-book-open" style="color: var(--text-tertiary); font-size: 16px; margin: 0 10px;"></i>
+        </span>
+        <div class="sort-tabs">
+            <div class="sort-tab{{if eq .Sort 1}} active{{end}}" onclick="switchSort(1, this)">最热</div>
+            <div class="sort-tab{{if eq .Sort 3}} active{{end}}" onclick="switchSort(3, this)">最新</div>
+        </div>
+    </div>
+    <div id="comment-list">
+{{if not .Comments}}        <div class="empty">暂无评论</div>{{else}}{{range $i, $c := .Comments}}        <div class="comment-item" id="comment-{{$i}}">
+        <div class="user-info">
+            <img src="{{$c.UserAvatar}}" class="user-avatar" alt="{{$c.UserName}}的头像" onerror="this.style.display='none'" loading="lazy">
+            <div class="user-name">{{$c.UserName}}{{if $c.IsAuthor}}<span class="author-badge">作者</span>{{end}}{{if $c.StickerImageURL}}<img src="{{$c.StickerImageURL}}" class="user-sticker" alt="勋章">{{end}}</div>
+        </div>
+        <div class="comment-content">{{$c.CommentTextHTML}}</div>
+{{if $c.ImageURL}}        <img src="{{$c.ImageURL}}" class="comment-img" alt="评论图片" onclick="showImage('{{$c.ImageLargeURL}}')" onerror="this.style.display='none'" loading="lazy">
+{{end}}        <div class="comment-time">{{$c.CreateTime}}</div>
+        <div class="comment-meta">
+            <span><i class="far fa-heart"></i>{{$c.DiggCount}}</span>
+            <span class="reply-btn" onclick="loadReplies({{$i}}, '{{$c.CommentID}}', {{$c.ReplyCount}})"><i class="far fa-comment-dots"></i>{{$c.ReplyCount}}</span>
+        </div>
+        <div class="replies-container" id="replies-{{$i}}"></div>
+       </div>
+{{end}}{{end}}{{if and (not .HasMore) .Comments}}
+        <div class="empty">没有更多评论了</div>{{end}}
+    </div>
+    
+    <div class="image-viewer" id="imageViewer">
+        <span class="close-btn" onclick="closeImage()">&times;</span>
+        <img id="previewImage" src="" alt="图片预览">
+    </div>
+    
+    <div class="back-to-top" id="backToTop" onclick="scrollToTop()">
+        <i class="fas fa-arrow-up"></i>
+    </div>
+
+    <script>
+        const itemID = '{{.ItemID}}';
+        const bookID = '{{.BookID}}';
+        const para = {{.Para}};
+        let currentSort = {{.Sort}};
+        // 服务端注入的绝对地址：弹窗 WebView(loadDataWithBaseURL) 中相对路径解析不可靠
+        const API_BASE = '{{.BaseURL}}';
+    
+        const commentList = document.getElementById('comment-list');
+        const imageViewer = document.getElementById('imageViewer');
+        const backToTopBtn = document.getElementById('backToTop');
+
+        const LOADING_HTML = '<div class="loading"><i class="fas fa-spinner fa-spin"></i> 加载中...</div>';
+        
+        // 已加载回复的评论
+        const loadedReplies = new Set();
+        
+        // URL 构建（绝对地址，兼容弹窗 WebView）
+        function buildReviewURL(params) {
+            const baseParams = {
+                item_id: itemID,
+                book_id: bookID,
+                para: para
+            };
+            const query = new URLSearchParams({...baseParams, ...params});
+            return API_BASE + '/review?' + query.toString();
+        }
+        
+        // 时间格式化
+        function formatTime(timestamp, format = 'simple') {
+            const date = new Date(timestamp * 1000);
+            if (format === 'full') {
+                return date.toLocaleString('zh-CN', {
+                    year: 'numeric',
+                    month: '2-digit',
+                    day: '2-digit',
+                    hour: '2-digit',
+                    minute: '2-digit'
+                }).replace(/\//g, '-');
+            }
+            return date.toLocaleString('zh-CN');
+        }
+        
+        // 图片渲染
+        function renderImage(imageData, type = 'comment') {
+            if (!imageData?.[0]) return '';
+            const imgUrl = imageData[0].expand_web_url || imageData[0].web_uri || '';
+            if (!imgUrl) return '';
+            
+            const escapedUrl = escapeHtml(imgUrl);
+            if (type === 'reply') {
+                return '<img src="' + escapedUrl + '" class="comment-img" alt="回复图片" onclick="showImage(\'' + escapedUrl + '\')" onerror="this.style.display=\'none\'" style="max-width:200px;margin-top:5px;border-radius:4px;cursor:pointer;" loading="lazy">';
+            }
+            const largeUrl = escapeHtml(imageData[0].expand_web_url || imgUrl);
+            return '<img src="' + escapedUrl + '" class="comment-img" alt="评论图片" onclick="showImage(\'' + largeUrl + '\')" onerror="this.style.display=\'none\'" loading="lazy">';
+        }
+        
+        // 防抖
+        function debounce(fn, delay) {
+            let timer;
+            return function(...args) {
+                clearTimeout(timer);
+                timer = setTimeout(() => fn.apply(this, args), delay);
+            };
+        }
+        
+        // 滚动信息获取（评论区为独立滚动容器）
+        function getScrollInfo() {
+            const scrollTop = commentList.scrollTop;
+            const scrollHeight = commentList.scrollHeight;
+            const clientHeight = commentList.clientHeight;
+            return {
+                scrollTop,
+                scrollHeight,
+                clientHeight,
+                distanceFromBottom: scrollHeight - (scrollTop + clientHeight)
+            };
+        }
+        
+        // 切换排序
+        async function switchSort(newSort, tab) {
+            if (currentSort === newSort) return;
+
+            document.querySelectorAll('.sort-tab').forEach(t => t.classList.remove('active'));
+            if (tab) tab.classList.add('active');
+            
+            commentList.innerHTML = LOADING_HTML;
+            
+            try {
+                currentSort = newSort;
+                currentOffset = 0;
+                
+                const url = buildReviewURL({ offset: 0, count: 20, sort: newSort });
+                const response = await fetch(url);
+                const result = await response.json();
+                
+                if (result.code === 0 && result.data && result.data.comments) {
+                    hasMore = result.data.has_more || false;
+                    currentOffset = result.data.next_offset || 0;
+                    
+                    const comments = result.data.comments || [];
+                    
+                    if (comments.length === 0) {
+                        commentList.innerHTML = '<div class="empty">暂无评论</div>';
+                        commentIndex = 0;
+                    } else {
+                        commentList.innerHTML = comments.map((comment, idx) => renderComment(comment, idx)).join('');
+                        commentIndex = comments.length;
+                        
+                        // 如果没有更多数据，显示提示
+                        if (!hasMore) {
+                            commentList.insertAdjacentHTML('beforeend', '<div class="empty">没有更多评论了</div>');
+                        }
+                    }
+                    
+                    loadedReplies.clear();
+                    commentList.scrollTo({ top: 0, behavior: 'smooth' });
+                } else {
+                    commentList.innerHTML = '<div class="empty">加载失败，请重试</div>';
+                    commentIndex = 0;
+                }
+            } catch (error) {
+                console.error('切换排序失败:', error);
+                commentList.innerHTML = '<div class="empty">加载失败，请重试</div>';
+            }
+        }
+        
+        // 加载回复
+        async function loadReplies(idx, commentID, count) {
+            const container = document.getElementById('replies-' + idx);
+            
+            if (count === 0) {
+                if (container.classList.contains('show')) {
+                    container.classList.remove('show');
+                    return;
+                }
+                container.innerHTML = '<div class="loading" style="color: #999;">暂无回复</div>';
+                container.classList.add('show');
+                loadedReplies.add(commentID);
+                return;
+            }
+            
+            if (loadedReplies.has(commentID)) {
+                container.classList.toggle('show');
+                return;
+            }
+            
+            container.innerHTML = LOADING_HTML;
+            container.classList.add('show');
+            
+            try {
+                const url = buildReviewURL({ comment_id: commentID, offset: 0, count: 20 });
+                const response = await fetch(url);
+                const result = await response.json();
+                
+                if (result.code !== 0 || !result.data) {
+                    container.innerHTML = '<div class="loading">暂无回复</div>';
+                    return;
+                }
+
+                const replies = result.data.reply_list || [];
+                const totalCount = result.data.count || replies.length;
+                const hasMore = result.data.has_more || false;
+                const nextOffset = result.data.next_offset || 0;
+                
+                if (replies.length === 0) {
+                    container.innerHTML = '<div class="loading">暂无回复</div>';
+                    return;
+                }
+                
+                let html = replies.map(renderReply).join('');
+                
+                if (hasMore) {
+                    html += '<div class="load-more-replies" style="text-align:center;padding:10px;color:var(--text-secondary);cursor:pointer;" ' +
+                           'onclick="loadMoreReplies(\'' + escapeHtml(commentID) + '\', ' + nextOffset + ', this)">' +
+                           '<i class="fas fa-angle-down"></i> 加载更多回复 (还有 ' + (totalCount - replies.length) + ' 条)' +
+                           '</div>';
+                }
+                
+                container.innerHTML = html;
+                loadedReplies.add(commentID);
+            } catch (error) {
+                console.error('加载回复失败:', error);
+                container.innerHTML = '<div class="loading">加载失败</div>';
+            }
+        }
+        
+        // 加载更多回复
+        async function loadMoreReplies(commentID, offset, button) {
+            button.innerHTML = '<i class="fas fa-spinner fa-spin"></i> 加载中...';
+            
+            try {
+                const url = buildReviewURL({ comment_id: commentID, offset: offset, count: 20 });
+                const response = await fetch(url);
+                const result = await response.json();
+                
+                if (result.code !== 0 || !result.data) {
+                    button.textContent = '加载失败';
+                    return;
+                }
+                
+                const replies = result.data.reply_list || [];
+                const totalCount = result.data.count || 0;
+                const hasMore = result.data.has_more || false;
+                const nextOffset = result.data.next_offset || 0;
+                
+                button.insertAdjacentHTML('beforebegin', replies.map(renderReply).join(''));
+                
+                if (hasMore) {
+                    const loadedCount = offset + replies.length;
+                    button.innerHTML = '<i class="fas fa-angle-down"></i> 加载更多回复 (还有 ' + (totalCount - loadedCount) + ' 条)';
+                    button.onclick = () => loadMoreReplies(commentID, nextOffset, button);
+                } else {
+                    button.remove();
+                }
+            } catch (error) {
+                console.error('加载更多回复失败:', error);
+                button.textContent = '加载失败，点击重试';
+            }
+        }
+        
+        // HTML 转义
+        const htmlEscapeMap = {
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&quot;',
+            "'": '&#39;'
+        };
+        function escapeHtml(text) {
+            return text.replace(/[&<>"']/g, m => htmlEscapeMap[m]);
+        }
+        
+        // 表情替换
+        const emojiMap = {{.EmojiMapJS}};
+        const emojiPattern = new RegExp(
+            Object.keys(emojiMap)
+                .map(e => e.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+                .join('|'),
+            'g'
+        );
+        
+        function replaceEmoji(text) {
+            return text.replace(emojiPattern, match => 
+                '<img src="' + emojiMap[match] + '" class="emoji-img" alt="' + match + '" title="' + match + '" loading="lazy">'
+            );
+        }
+        
+        // 渲染单个回复
+        function renderReply(reply) {
+            const userName = reply.user_info?.user_name || '匿名用户';
+            const userAvatar = reply.user_info?.user_avatar || '';
+            const text = reply.text || '';
+            const time = formatTime(reply.create_timestamp || 0);
+            const imageHTML = renderImage(reply.image_data, 'reply');
+            
+            return '<div class="reply-item">' +
+                '<img src="' + escapeHtml(userAvatar) + '" class="reply-avatar" alt="' + escapeHtml(userName) + '的头像" onerror="this.style.display=\'none\';" loading="lazy">' +
+                '<div class="reply-content">' +
+                    '<span class="reply-username">' + escapeHtml(userName) + '</span>' +
+                    '<div class="reply-text">' + replaceEmoji(escapeHtml(text)) + imageHTML + '</div>' +
+                    '<div class="reply-time">' + time + '</div>' +
+                '</div>' +
+            '</div>';
+        }
+        
+        // 渲染单个评论
+        function renderComment(comment, idx) {
+            const userName = comment.user_info?.user_name || '匿名用户';
+            const userAvatar = comment.user_info?.user_avatar || '';
+            const isAuthor = comment.user_info?.is_author || false;
+            const commentText = comment.text || '';
+            const commentID = comment.comment_id || '';
+            const diggCount = comment.digg_count || 0;
+            const replyCount = comment.reply_count || 0;
+            const createTime = formatTime(comment.create_timestamp || 0, 'full');
+            const imageHTML = renderImage(comment.image_data);
+            
+            return '<div class="comment-item" id="comment-' + idx + '">' +
+                   '<div class="user-info">' +
+                   '<img src="' + escapeHtml(userAvatar) + '" class="user-avatar" alt="' + escapeHtml(userName) + '的头像" onerror="this.style.display=\'none\'" loading="lazy">' +
+                   '<div class="user-name">' + escapeHtml(userName) +
+                   (isAuthor ? '<span class="author-badge">作者</span>' : '') +
+                   '</div></div>' +
+                   '<div class="comment-content">' + replaceEmoji(escapeHtml(commentText)) + '</div>' +
+                   imageHTML +
+                   '<div class="comment-time">' + createTime + '</div>' +
+                   '<div class="comment-meta">' +
+                   '<span><i class="far fa-heart"></i>' + diggCount + '</span>' +
+                   '<span class="reply-btn" onclick="loadReplies(' + idx + ', \'' + escapeHtml(commentID) + '\', ' + replyCount + ')">' +
+                   '<i class="far fa-comment-dots"></i>' + replyCount + '</span>' +
+                   '</div>' +
+                   '<div class="replies-container" id="replies-' + idx + '"></div>' +
+                   '</div>';
+        }
+        
+        // 显示图片
+        function showImage(url) {
+            document.getElementById('previewImage').src = url;
+            imageViewer.classList.add('show');
+            document.body.style.overflow = 'hidden';
+        }
+        
+        // 关闭图片
+        function closeImage() {
+            imageViewer.classList.remove('show');
+            document.body.style.overflow = '';
+        }
+        
+        // 点击空白处关闭
+        imageViewer.addEventListener('click', e => {
+            if (e.target.id === 'imageViewer') closeImage();
+        });
+        
+        // ESC 键关闭
+        document.addEventListener('keydown', e => {
+            if (e.key === 'Escape') closeImage();
+        });
+        
+        // 懒加载相关变量
+        let currentOffset = {{.NextOffset}};
+        const pageSize = {{.PageSize}};
+        let hasMore = {{if .HasMore}}true{{else}}false{{end}};
+        let isLoading = false;
+        let commentIndex = {{.CommentCount}};
+        
+        // 懒加载更多评论
+        async function loadMoreComments() {
+            if (isLoading || !hasMore) return;
+            
+            isLoading = true;
+            
+            let loadingDiv = document.getElementById('loading-indicator');
+            if (!loadingDiv) {
+                loadingDiv = document.createElement('div');
+                loadingDiv.id = 'loading-indicator';
+                loadingDiv.className = 'loading';
+                loadingDiv.innerHTML = LOADING_HTML;
+                commentList.appendChild(loadingDiv);
+            }
+            loadingDiv.style.display = 'block';
+            
+            try {
+                const url = buildReviewURL({ offset: currentOffset, count: pageSize, sort: currentSort });
+                const response = await fetch(url);
+                const result = await response.json();
+                
+                if (result.code === 0 && result.data) {
+                    const comments = result.data.comments || [];
+                    
+                    if (comments.length > 0) {
+                        loadingDiv?.remove();
+                        
+                        hasMore = result.data.has_more === true;
+                        currentOffset = result.data.next_offset || 0;
+                        
+                        comments.forEach((comment, idx) => {
+                            commentList.insertAdjacentHTML('beforeend', renderComment(comment, commentIndex + idx));
+                        });
+                        
+                        commentIndex += comments.length;
+                        
+                        if (!hasMore) {
+                            commentList.insertAdjacentHTML('beforeend', '<div class="empty">没有更多评论了</div>');
+                        }
+                    } else {
+                        loadingDiv.className = 'empty';
+                        loadingDiv.textContent = '没有更多评论了';
+                        hasMore = false;
+                    }
+                } else {
+                    loadingDiv.className = 'empty';
+                    loadingDiv.textContent = '没有更多评论了';
+                    hasMore = false;
+                }
+            } catch (error) {
+                console.error('加载失败:', error);
+                if (loadingDiv) {
+                    loadingDiv.textContent = '加载失败';
+                    setTimeout(() => loadingDiv.remove(), 2000);
+                }
+            } finally {
+                isLoading = false;
+            }
+        }
+        
+        // 回到顶部
+        function scrollToTop() {
+            commentList.scrollTo({
+                top: 0,
+                behavior: 'smooth'
+            });
+        }
+
+        // 滚动监听（挂在评论容器上，顶栏固定不参与滚动）
+        const handleScroll = debounce(() => {
+            const scroll = getScrollInfo();
+
+            // 显示/隐藏回到顶部按钮
+            backToTopBtn.classList.toggle('show', scroll.scrollTop > 300);
+
+            // 距离底部 200px 时触发加载
+            if (scroll.distanceFromBottom <= 200) {
+                loadMoreComments();
+            }
+        }, 100);
+
+        commentList.addEventListener('scroll', handleScroll, { passive: true });
+    </script>
+</body>

internal/handlers/templates/status.html

@@ -0,0 +1,806 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>番茄小说 API · 运行状态</title>
+    <style>
+        /* finesse · register=product · A=brick-tomato/warm-oat · B=system-sans+mono
+         * C=single-col-strip · D=none · E=warm-glass · SOUL=5 SPECTACLE=2 DENSITY=7 */
+        :root {
+            --page: #f3efe6;
+            --bg: #ffffff;
+            --panel-2: #f9f6ef;
+            --border: rgba(44, 30, 22, 0.07);
+            --ink-1: #1e1712;
+            --ink-2: #4a3e35;
+            --ink-3: #776a5b;
+            --accent: #a8402c;
+            --accent-soft: rgba(168, 64, 44, 0.10);
+            --on-accent: #ffffff;
+            --accent-2: #5c5a3a;
+            --accent-2-soft: rgba(92, 90, 58, 0.12);
+            --up: #35704a;
+            --up-soft: rgba(62, 122, 82, 0.12);
+            --up-ring: rgba(62, 122, 82, 0.40);
+            --down: #c22e22;
+            --down-soft: rgba(194, 46, 34, 0.10);
+            --term-bg: #1b1511;
+            --term-ink: #e6d9c8;
+            --shadow: 0 1px 3px rgba(56, 36, 24, 0.05);
+            --border-strong: rgba(44, 30, 22, 0.14);
+            --accent-line: rgba(168, 64, 44, 0.35);
+            --accent-shadow: 0 2px 6px rgba(168, 64, 44, 0.28);
+            --btn-hl: inset 0 1px 0 rgba(255, 255, 255, 0.20);
+            --glass: rgba(255, 255, 255, 0.62);
+            --glass-bar: rgba(243, 239, 230, 0.78);
+            --wash-1: rgba(168, 64, 44, 0.07);
+            --wash-2: rgba(92, 90, 58, 0.05);
+            --r: 18px;
+            --r-sm: 12px;
+            --mono: "SF Mono", ui-monospace, "Cascadia Mono", Consolas, Menlo, monospace;
+        }
+        @media (prefers-color-scheme: dark) {
+            :root {
+                --page: #16110d;
+                --bg: #211b16;
+                --panel-2: #2b241d;
+                --border: rgba(255, 255, 255, 0.07);
+                --ink-1: #f2ece3;
+                --ink-2: #c9bcab;
+                --ink-3: #9a8d7c;
+                --accent: #e0705a;
+                --accent-soft: rgba(224, 112, 90, 0.14);
+                --on-accent: #200e06;
+                --accent-2: #b5b37a;
+                --accent-2-soft: rgba(181, 179, 122, 0.14);
+                --up: #5fc489;
+                --up-soft: rgba(95, 196, 137, 0.14);
+                --up-ring: rgba(95, 196, 137, 0.40);
+                --down: #ff6b5a;
+                --down-soft: rgba(255, 107, 90, 0.13);
+                --term-bg: #120e0a;
+                --term-ink: #d9cdbd;
+                --shadow: none;
+                --border-strong: rgba(255, 255, 255, 0.13);
+                --accent-line: rgba(224, 112, 90, 0.42);
+                --accent-shadow: 0 1px 2px rgba(0, 0, 0, 0.4);
+                --btn-hl: inset 0 1px 0 rgba(255, 255, 255, 0.22);
+                --glass: rgba(33, 27, 22, 0.60);
+                --glass-bar: rgba(22, 17, 13, 0.74);
+                --wash-1: rgba(224, 112, 90, 0.08);
+                --wash-2: rgba(181, 179, 122, 0.045);
+            }
+        }
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        html, body { overflow-x: clip; }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
+            background: var(--page);
+            color: var(--ink-1);
+            min-height: 100vh;
+            padding: 28px 20px 20px;
+            font-size: 14px;
+            -webkit-font-smoothing: antialiased;
+        }
+        .num { font-variant-numeric: tabular-nums; letter-spacing: -0.01em; }
+        /* 品牌色晕：给玻璃层提供可模糊的内容 */
+        body::before {
+            content: '';
+            position: fixed; inset: 0; z-index: -1; pointer-events: none;
+            background:
+                radial-gradient(640px 420px at 85% -5%, var(--wash-1), transparent 65%),
+                radial-gradient(760px 540px at -10% 105%, var(--wash-2), transparent 65%);
+        }
+        .page { max-width: 1120px; margin: 0 auto; }
+
+        /* ── 顶部品牌行 ─────────────────────── */
+        .tophead {
+            display: flex; align-items: center; gap: 12px;
+            position: sticky; top: 0; z-index: 10;
+            margin: -28px -20px 16px; padding: 20px 20px 14px;
+            background: var(--glass-bar);
+            -webkit-backdrop-filter: blur(14px) saturate(1.3);
+            backdrop-filter: blur(14px) saturate(1.3);
+            border-bottom: 1px solid var(--border);
+        }
+        .glyph {
+            width: 38px; height: 38px; border-radius: 12px; flex-shrink: 0;
+            background: var(--accent); color: var(--on-accent);
+            display: grid; place-items: center;
+            font-size: 18px; font-weight: 800; line-height: 1;
+            box-shadow: var(--btn-hl), var(--accent-shadow);
+        }
+        .tophead h1 { font-size: 18px; font-weight: 800; letter-spacing: -0.02em; line-height: 1.3; }
+        .tophead .sub { display: block; font-size: 12px; font-weight: 400; color: var(--ink-3); margin-top: 1px; }
+        .clock { margin-left: auto; font-size: 12.5px; color: var(--ink-3); }
+
+        /* ── 卡片基底 ───────────────────────── */
+        .card {
+            background: var(--glass);
+            -webkit-backdrop-filter: blur(14px) saturate(1.35);
+            backdrop-filter: blur(14px) saturate(1.35);
+            border: 1px solid var(--border);
+            border-radius: var(--r);
+            padding: 18px 20px;
+            box-shadow: var(--shadow);
+        }
+        .card-head { display: flex; align-items: baseline; justify-content: space-between; gap: 10px; margin-bottom: 10px; }
+        .card-title { font-size: 13px; font-weight: 700; }
+        .head-side { font-size: 11.5px; color: var(--ink-3); }
+
+        /* ── 服务状态条 ─────────────────────── */
+        .hero { display: flex; flex-wrap: wrap; align-items: center; gap: 16px 28px; padding: 20px 22px; margin-bottom: 14px; }
+        .hero-status { min-width: 0; }
+        .live-pill {
+            display: inline-flex; align-items: center; gap: 7px;
+            font-size: 12px; font-weight: 600; color: var(--up);
+            background: var(--up-soft); border-radius: 999px; padding: 4px 11px;
+        }
+        .dot { width: 8px; height: 8px; border-radius: 999px; background: var(--up); animation: ripple 2.2s ease-out infinite; }
+        @keyframes ripple {
+            0% { box-shadow: 0 0 0 0 var(--up-ring); }
+            70%, 100% { box-shadow: 0 0 0 7px transparent; }
+        }
+        .uptime-label { font-size: 12px; color: var(--ink-3); margin: 10px 0 2px; }
+        .uptime { font-size: 26px; font-weight: 800; letter-spacing: -0.02em; line-height: 1.2; }
+        .hero-meta { margin-left: auto; min-width: 220px; }
+        .hero-meta .kv { padding: 4px 0; }
+
+        /* ── KPI 卡 ─────────────────────────── */
+        .kpis { display: grid; grid-template-columns: repeat(auto-fit, minmax(230px, 1fr)); gap: 14px; margin-bottom: 14px; }
+        .kpi-top { display: flex; align-items: center; gap: 10px; margin-bottom: 12px; }
+        .chip-ic {
+            width: 30px; height: 30px; border-radius: 9px; flex-shrink: 0;
+            background: var(--panel-2); color: var(--ink-2);
+            display: grid; place-items: center;
+        }
+        .chip-ic svg { width: 15px; height: 15px; stroke: currentColor; fill: none; stroke-width: 1.8; }
+        .kpi-label { font-size: 12px; font-weight: 600; color: var(--ink-3); text-transform: uppercase; letter-spacing: 0.05em; line-height: 1.5; }
+        .big { font-size: 24px; font-weight: 800; letter-spacing: -0.02em; line-height: 1.2; }
+        .big-aside { font-size: 14px; font-weight: 600; color: var(--ink-3); letter-spacing: 0; }
+        .big-sub { font-size: 12px; color: var(--ink-3); margin-top: 3px; }
+        .kpi .kv { border-top: 1px solid var(--border); margin-top: 8px; padding-top: 8px; }
+        .kpi .kv:first-of-type { margin-top: 14px; }
+        .kv { display: flex; justify-content: space-between; gap: 12px; font-size: 12.5px; min-width: 0; }
+        .kv .k { color: var(--ink-3); flex-shrink: 0; }
+        .kv .v { font-weight: 600; text-align: right; overflow-wrap: anywhere; }
+
+        /* 比例条 */
+        .meter { margin: 12px 0 2px; }
+        .meter-cap { display: flex; justify-content: space-between; font-size: 11.5px; color: var(--ink-3); margin-bottom: 5px; }
+        .track { height: 6px; border-radius: 999px; background: var(--panel-2); overflow: hidden; }
+        .pfill { display: block; height: 100%; border-radius: inherit; background: var(--accent); width: 0; transition: width 0.7s cubic-bezier(0.22, 0.61, 0.36, 1); }
+        .no-anim .pfill, .no-anim .sfill { transition: none !important; }
+
+        /* 状态小徽章 */
+        .chip { display: inline-flex; align-items: center; font-size: 11.5px; font-weight: 600; border-radius: 999px; padding: 3px 10px; border: 1px solid var(--border); }
+        .chip-up { background: var(--up-soft); color: var(--up); }
+        .chip-off { background: var(--panel-2); color: var(--ink-3); }
+        .chip-row { margin-top: 10px; }
+
+        /* 请求分类细条 */
+        .srows { margin-top: 12px; display: flex; flex-direction: column; gap: 7px; }
+        .srow { display: grid; grid-template-columns: 40px 1fr 48px; gap: 8px; align-items: center; }
+        .slabel { font-size: 11.5px; color: var(--ink-3); }
+        .strack { height: 5px; border-radius: 999px; background: var(--panel-2); overflow: hidden; }
+        .sfill { display: block; height: 100%; border-radius: inherit; background: var(--accent); width: 0; transition: width 0.7s cubic-bezier(0.22, 0.61, 0.36, 1); }
+        .sval { font-size: 12px; font-weight: 600; color: var(--ink-2); text-align: right; }
+        /* 每日请求行：结构同 srow，宽度服务端算好，不参与 .srow 的 JS 归一化 */
+        .drows { margin-top: 10px; padding-top: 10px; border-top: 1px dashed var(--border); display: flex; flex-direction: column; gap: 7px; }
+        .drow { display: grid; grid-template-columns: 44px 1fr 52px; gap: 8px; align-items: center; }
+        .dlabel { font-size: 11.5px; color: var(--ink-3); font-variant-numeric: tabular-nums; }
+        .dval { font-size: 12px; font-weight: 600; color: var(--ink-2); text-align: right; }
+        .drow.is-max .dlabel, .drow.is-max .dval { color: var(--accent); }
+
+        /* ── 最近请求表 ─────────────────────── */
+        .req-card { margin-bottom: 14px; overflow: hidden; }
+        .twrap { overflow-x: auto; margin: 0 -20px; padding: 0 20px; }
+        table { width: 100%; min-width: 640px; border-collapse: collapse; font-size: 12.5px; }
+        th {
+            text-align: left; font-weight: 600; color: var(--ink-3);
+            font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; line-height: 1.5;
+            padding: 7px 10px; border-bottom: 1px solid var(--border); white-space: nowrap;
+        }
+        td { padding: 8px 10px; border-bottom: 1px solid var(--border); white-space: nowrap; }
+        tbody tr { transition: background 0.12s; }
+        tbody tr:hover { background: var(--panel-2); }
+        tbody tr:last-child td { border-bottom: none; }
+        td.code { font-family: var(--mono); font-size: 12px; }
+        td.r, th.r { text-align: right; }
+        .q { color: var(--ink-3); font-size: 11.5px; }
+        .path-cell { max-width: 380px; overflow: hidden; text-overflow: ellipsis; }
+        .mth {
+            font-family: var(--mono); font-size: 10.5px; font-weight: 700; letter-spacing: 0.03em;
+            background: var(--accent-2-soft); color: var(--accent-2);
+            padding: 2px 7px; border-radius: 6px;
+            border: 1px solid var(--border);
+        }
+        .stc { display: inline-flex; align-items: center; gap: 6px; font-weight: 700; font-family: var(--mono); font-size: 11.5px; }
+        .stc i { width: 7px; height: 7px; border-radius: 999px; }
+        .stc-ok { color: var(--up); } .stc-ok i { background: var(--up); }
+        .stc-err { color: var(--down); } .stc-err i { background: var(--down); }
+        .empty { padding: 30px 10px; text-align: center; }
+        .empty .e-title { font-size: 13px; font-weight: 700; margin-bottom: 6px; }
+        .empty .e-desc { font-size: 12px; color: var(--ink-3); line-height: 1.6; }
+        .empty code { font-family: var(--mono); font-size: 11.5px; background: var(--panel-2); border-radius: 6px; padding: 1px 6px; }
+
+        /* ── API 文档 ───────────────────────── */
+        .docs details { border-top: 1px solid var(--border); }
+        .docs details:first-of-type { border-top: none; }
+        .docs summary {
+            list-style: none; display: flex; align-items: center; gap: 10px;
+            padding: 12px 8px; margin: 0 -8px; border-radius: 10px; cursor: pointer;
+        }
+        .docs summary::-webkit-details-marker { display: none; }
+        .docs summary:hover { background: var(--panel-2); }
+        .chev { display: grid; place-items: center; color: var(--ink-3); transition: transform 0.2s ease; }
+        .chev svg { width: 14px; height: 14px; stroke: currentColor; fill: none; stroke-width: 2; }
+        details[open] .chev { transform: rotate(90deg); }
+        .grp-name { font-size: 13.5px; font-weight: 700; }
+        .cnt {
+            font-size: 11px; font-weight: 600; color: var(--ink-3);
+            background: var(--panel-2); border-radius: 999px; padding: 1px 8px;
+            border: 1px solid var(--border);
+        }
+        .eps { padding: 2px 0 10px; }
+        .api-endpoint { padding: 10px 10px; margin: 0 -10px 2px; border-top: 1px solid var(--border); border-radius: 10px; }
+        .api-endpoint:first-child { border-top: none; }
+        .api-endpoint:hover { background: var(--panel-2); }
+        .ep-head { display: flex; align-items: center; gap: 9px; flex-wrap: wrap; min-width: 0; }
+        .api-path { font-family: var(--mono); font-size: 13px; font-weight: 700; letter-spacing: -0.01em; }
+        .ep-desc { font-size: 12px; color: var(--ink-3); }
+        .api-params { display: flex; flex-wrap: wrap; gap: 5px 16px; margin-top: 8px; }
+        .param-item { display: inline-flex; align-items: baseline; gap: 6px; font-size: 12px; }
+        .param-name { font-family: var(--mono); font-size: 12px; font-weight: 600; color: var(--accent); }
+        .req, .opt { font-size: 10.5px; font-weight: 700; border-radius: 5px; padding: 1px 6px; border: 1px solid var(--border); }
+        .req { background: var(--accent-soft); color: var(--accent); }
+        .opt { background: var(--panel-2); color: var(--ink-3); }
+        .param-desc { color: var(--ink-3); font-size: 11.5px; }
+
+        /* ── 行内测试 ───────────────────────── */
+        .test-btn {
+            margin-left: auto; font-size: 11.5px; font-weight: 600; white-space: nowrap;
+            color: var(--accent); background: var(--bg);
+            border: 1px solid var(--accent-line); border-radius: 999px;
+            padding: 4px 13px; cursor: pointer;
+            box-shadow: var(--shadow);
+            transition: background 0.15s, border-color 0.15s, box-shadow 0.15s, transform 0.1s;
+        }
+        .test-btn:hover, .test-btn.on { background: var(--accent-soft); border-color: var(--accent); }
+        .test-btn:active { transform: translateY(1px); }
+        .test-box { margin-top: 10px; padding: 12px; background: var(--panel-2); border: 1px solid var(--border); border-radius: var(--r-sm); }
+        .test-param { display: flex; align-items: center; gap: 8px; margin: 5px 0; }
+        .test-param > span {
+            width: 110px; flex-shrink: 0; font-size: 11.5px; color: var(--ink-3);
+            font-family: var(--mono);
+        }
+        .test-param input {
+            flex: 1; min-width: 0; padding: 7px 10px; font-size: 12.5px; font-family: var(--mono);
+            border: 1px solid var(--border); border-radius: 9px;
+            background: var(--bg); color: var(--ink-1); outline: none;
+            transition: border-color 0.12s, box-shadow 0.12s;
+        }
+        .test-param input:hover:not(:focus) { border-color: var(--border-strong); }
+        .test-param input:focus { border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft); }
+        .test-send {
+            margin-top: 9px; padding: 7px 18px; font-size: 12.5px; font-weight: 700;
+            background: var(--accent); color: var(--on-accent);
+            border: none; border-radius: 9px; cursor: pointer;
+            box-shadow: var(--btn-hl), var(--accent-shadow);
+            transition: filter 0.15s, box-shadow 0.15s, transform 0.1s;
+        }
+        .test-send:hover { filter: brightness(1.07); }
+        .test-send:active { transform: translateY(1px); box-shadow: var(--btn-hl); }
+        .test-result {
+            margin-top: 10px; max-height: 300px; overflow: auto;
+            background: var(--term-bg); color: var(--term-ink);
+            padding: 12px; border-radius: 10px;
+            font-family: var(--mono); font-size: 11.5px; line-height: 1.6;
+            white-space: pre-wrap; word-break: break-all;
+        }
+        .twrap, .test-result { scrollbar-width: thin; scrollbar-color: var(--border-strong) transparent; }
+        .twrap::-webkit-scrollbar, .test-result::-webkit-scrollbar { width: 8px; height: 8px; }
+        .twrap::-webkit-scrollbar-track, .test-result::-webkit-scrollbar-track { background: transparent; }
+        .twrap::-webkit-scrollbar-thumb, .test-result::-webkit-scrollbar-thumb { background: var(--border-strong); border-radius: 999px; }
+
+        /* ── 页脚与焦点 ─────────────────────── */
+        .foot { font-size: 11.5px; color: var(--ink-3); text-align: center; margin: 20px 0 4px; }
+        :focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+        @media (max-width: 640px) {
+            body { padding: 20px 14px 14px; }
+            .card { padding: 16px; border-radius: 16px; }
+            .twrap { margin: 0 -16px; padding: 0 16px; }
+            .uptime { font-size: 21px; }
+            .hero-meta { margin-left: 0; width: 100%; }
+            .ep-desc { display: none; }
+            .tophead { margin: -20px -14px 14px; padding: 12px 16px 10px; }
+            .kpis { grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); }
+        }
+        /* 不支持毛玻璃时退回实色卡片 */
+        @supports not (backdrop-filter: blur(1px)) {
+            :root { --glass: #ffffff; --glass-bar: #f3efe6; }
+        }
+        @media (prefers-color-scheme: dark) {
+            @supports not (backdrop-filter: blur(1px)) {
+                :root { --glass: #211b16; --glass-bar: #16110d; }
+            }
+        }
+        @media (prefers-reduced-transparency: reduce) {
+            body::before { display: none; }
+            .card, .tophead { -webkit-backdrop-filter: none; backdrop-filter: none; }
+        }
+        @media (prefers-reduced-motion: reduce) {
+            *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
+        }
+    </style>
+    <script type="text/javascript">
+        var RM = window.matchMedia && matchMedia('(prefers-reduced-motion: reduce)').matches;
+        var firstLoad = true;
+
+        window.onload = function () {
+            enhance();
+            injectTestButtons();
+            setInterval(autoRefresh, 3000);
+        };
+
+        // 自动刷新：只更新数据区（状态条/KPI/最近请求），不清空文档区和正在使用的测试表单
+        function autoRefresh() {
+            fetch(window.location.href)
+                .then(function (response) { return response.text(); })
+                .then(function (html) {
+                    var doc = new DOMParser().parseFromString(html, 'text/html');
+                    var fresh = doc.getElementById('stats');
+                    if (!fresh) return;
+                    var stats = document.getElementById('stats');
+                    stats.classList.add('no-anim'); // 刷新时条形图直接落位，不重播生长动画
+                    stats.innerHTML = fresh.innerHTML;
+                    firstLoad = false;
+                    enhance();
+                    requestAnimationFrame(function () {
+                        requestAnimationFrame(function () { stats.classList.remove('no-anim'); });
+                    });
+                })
+                .catch(function (err) { console.error('刷新失败:', err); });
+        }
+
+        // 条形图宽度 + 首次载入的数字滚动
+        function enhance() {
+            var rows = document.querySelectorAll('.srow');
+            var max = 1, i;
+            for (i = 0; i < rows.length; i++) max = Math.max(max, +rows[i].getAttribute('data-count') || 0);
+            for (i = 0; i < rows.length; i++) {
+                var v = +rows[i].getAttribute('data-count') || 0;
+                rows[i].querySelector('.sfill').style.width = (v / max * 100) + '%';
+            }
+            document.querySelectorAll('.pfill').forEach(function (el) {
+                var a = +el.getAttribute('data-ratio'), b = +el.getAttribute('data-of') || 1;
+                if (isFinite(a)) el.style.width = Math.max(0, Math.min(100, a / b * 100)) + '%';
+            });
+            if (firstLoad && !RM) {
+                document.querySelectorAll('[data-count-num]').forEach(function (el) {
+                    var target = +el.getAttribute('data-count-num') || 0;
+                    if (target <= 0) return;
+                    var t0 = performance.now(), dur = 600;
+                    (function tick(t) {
+                        var p = Math.min(1, (t - t0) / dur);
+                        p = 1 - Math.pow(1 - p, 3);
+                        el.textContent = String(Math.round(target * p));
+                        if (p < 1) requestAnimationFrame(tick);
+                    })(t0);
+                });
+            }
+        }
+
+        // 为每个业务接口注入"测试"按钮（状态页自身除外）
+        function injectTestButtons() {
+            document.querySelectorAll('.api-endpoint').forEach(function (ep) {
+                var path = ep.querySelector('.api-path').textContent.trim();
+                if (path === '/status') return;
+                var btn = document.createElement('button');
+                btn.type = 'button';
+                btn.className = 'test-btn';
+                btn.textContent = '测试';
+                btn.onclick = function () { toggleTest(ep, path); };
+                ep.querySelector('.ep-head').appendChild(btn);
+            });
+        }
+
+        // 展开/收起测试表单；参数清单直接读该接口的参数文档 DOM，零重复维护
+        function toggleTest(ep, path) {
+            var existing = ep.querySelector('.test-box');
+            var btn = ep.querySelector('.test-btn');
+            if (btn) btn.classList.toggle('on', !existing); // 面板开着时按钮保持点亮
+            if (existing) { existing.remove(); return; }
+
+            var box = document.createElement('div');
+            box.className = 'test-box';
+            ep.querySelectorAll('.param-item').forEach(function (p) {
+                var name = p.querySelector('.param-name').textContent.trim();
+                var required = p.querySelector('.req') ? ' *' : '';
+                box.insertAdjacentHTML('beforeend',
+                    '<div class="test-param"><span>' + name + required + '</span>' +
+                    '<input data-name="' + name + '" placeholder="' + name + '"></div>');
+            });
+            if (!box.children.length) {
+                box.insertAdjacentHTML('beforeend', '<div class="test-param">无参数</div>');
+            }
+            var send = document.createElement('button');
+            send.type = 'button';
+            send.className = 'test-send';
+            send.textContent = '发送请求';
+            send.onclick = function () { sendTest(ep, path); };
+            box.appendChild(send);
+            var result = document.createElement('pre');
+            result.className = 'test-result';
+            box.appendChild(result);
+            ep.appendChild(box);
+        }
+
+        function sendTest(ep, path) {
+            var result = ep.querySelector('.test-result');
+            var sp = new URLSearchParams();
+            var key = new URLSearchParams(location.search).get('key');
+            if (key) sp.set('key', key); // protect_all 开启时业务接口需要密钥
+            ep.querySelectorAll('.test-box input[data-name]').forEach(function (i) {
+                if (i.value.trim() !== '') sp.set(i.dataset.name, i.value.trim());
+            });
+            result.textContent = '请求中...';
+            fetch(path + '?' + sp.toString())
+                .then(function (r) { return r.text(); })
+                .then(function (t) {
+                    try { t = JSON.stringify(JSON.parse(t), null, 2); } catch (e) {}
+                    result.textContent = t; // textContent 写入，无注入面
+                })
+                .catch(function (err) { result.textContent = '请求失败: ' + err.message; });
+        }
+    </script>
+</head>
+<body>
+    <div class="page">
+        <div id="stats">
+            <header class="tophead">
+                <span class="glyph" aria-hidden="true">番</span>
+                <div>
+                    <h1>番茄小说 API</h1>
+                    <span class="sub">自部署实例 · 运行状态</span>
+                </div>
+                <span class="clock num">{{.NowTime}}</span>
+            </header>
+
+            <section class="hero card">
+                <div class="hero-status">
+                    <span class="live-pill"><i class="dot" aria-hidden="true"></i>服务运行中</span>
+                    <div class="uptime-label">持续运行</div>
+                    <div class="uptime num">{{.Uptime}}</div>
+                </div>
+                <div class="hero-meta">
+                    <div class="kv"><span class="k">签名算法</span><span class="v num">{{.Signature}}</span></div>
+                    <div class="kv"><span class="k">启动时间</span><span class="v num">{{.StartTime}}</span></div>
+                    <div class="kv"><span class="k">限流</span><span class="v num">{{.RateLimit}}</span></div>
+                </div>
+            </section>
+
+            <div class="kpis">
+                <section class="card kpi">
+                    <div class="kpi-top">
+                        <span class="chip-ic" aria-hidden="true"><svg viewBox="0 0 24 24"><ellipse cx="12" cy="5" rx="8" ry="3"/><path d="M4 5v14c0 1.66 3.58 3 8 3s8-1.34 8-3V5"/><path d="M4 12c0 1.66 3.58 3 8 3s8-1.34 8-3"/></svg></span>
+                        <span class="kpi-label">数据库</span>
+                    </div>
+                    <div class="big num">{{.DBTotal}}</div>
+                    <div class="big-sub">数据库文件大小</div>
+                    <div class="meter">
+                        <div class="meter-cap"><span>空间占用</span><span class="num">{{printf "%.1f" .DBUsedPct}}%</span></div>
+                        <div class="track"><i class="pfill" data-ratio="{{.DBUsedPct}}" data-of="100"></i></div>
+                    </div>
+                    <div class="kv"><span class="k">已用空间</span><span class="v num">{{.DBUsed}}</span></div>
+                    <div class="kv"><span class="k">空闲空间</span><span class="v num">{{.DBFree}}</span></div>
+                </section>
+
+                <section class="card kpi">
+                    <div class="kpi-top">
+                        <span class="chip-ic" aria-hidden="true"><svg viewBox="0 0 24 24"><circle cx="8" cy="15" r="4.5"/><path d="M11.5 11.5 21 2m-5 1 3 3m-6 0 3 3"/></svg></span>
+                        <span class="kpi-label">设备密钥池</span>
+                    </div>
+                    <div class="big num"><span data-count-num="{{.PoolValid}}">{{.PoolValid}}</span><span class="big-aside"> / {{.PoolTotal}}</span></div>
+                    <div class="big-sub">有效设备 / 总设备数</div>
+                    <div class="chip-row"><span class="chip {{if eq .PoolStatus "已启用"}}chip-up{{else}}chip-off{{end}}">{{.PoolStatus}}</span></div>
+                    <div class="meter">
+                        <div class="meter-cap"><span>有效率</span></div>
+                        <div class="track"><i class="pfill" data-ratio="{{.PoolValid}}" data-of="{{.PoolTotal}}"></i></div>
+                    </div>
+                    <div class="kv"><span class="k">无效设备</span><span class="v num">{{.PoolInvalid}}</span></div>
+                    <div class="kv"><span class="k">当前索引</span><span class="v num">{{.PoolIndex}}</span></div>
+                </section>
+
+                <section class="card kpi">
+                    <div class="kpi-top">
+                        <span class="chip-ic" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M3 12h4l3-8 4 16 3-8h4"/></svg></span>
+                        <span class="kpi-label">请求统计</span>
+                    </div>
+                    <div class="big num" data-count-num="{{.StatTotal}}">{{.StatTotal}}</div>
+                    <div class="big-sub">累计业务请求 · 今日 <span class="num">{{.TodayCount}}</span> 次</div>
+                    <div class="srows">
+                        <div class="srow" data-count="{{.StatSearch}}"><span class="slabel">搜索</span><span class="strack"><i class="sfill"></i></span><span class="sval num">{{.StatSearch}}</span></div>
+                        <div class="srow" data-count="{{.StatDetail}}"><span class="slabel">详情</span><span class="strack"><i class="sfill"></i></span><span class="sval num">{{.StatDetail}}</span></div>
+                        <div class="srow" data-count="{{.StatCatalog}}"><span class="slabel">目录</span><span class="strack"><i class="sfill"></i></span><span class="sval num">{{.StatCatalog}}</span></div>
+                        <div class="srow" data-count="{{.StatContent}}"><span class="slabel">正文</span><span class="strack"><i class="sfill"></i></span><span class="sval num">{{.StatContent}}</span></div>
+                        <div class="srow" data-count="{{.StatManga}}"><span class="slabel">漫画</span><span class="strack"><i class="sfill"></i></span><span class="sval num">{{.StatManga}}</span></div>
+                        <div class="srow" data-count="{{.StatAudio}}"><span class="slabel">音频</span><span class="strack"><i class="sfill"></i></span><span class="sval num">{{.StatAudio}}</span></div>
+                        <div class="srow" data-count="{{.StatVideo}}"><span class="slabel">视频</span><span class="strack"><i class="sfill"></i></span><span class="sval num">{{.StatVideo}}</span></div>
+                        <div class="srow" data-count="{{.StatCategory}}"><span class="slabel">分类</span><span class="strack"><i class="sfill"></i></span><span class="sval num">{{.StatCategory}}</span></div>
+                    </div>
+                    {{if .DailyStats}}
+                    <div class="drows">
+                        {{range .DailyStats}}
+                        <div class="drow{{if .MaxCount}} is-max{{end}}"><span class="dlabel">{{.Day}}</span><span class="strack"><i class="sfill" style="width: {{.Pct}}%"></i></span><span class="dval num">{{.Count}}</span></div>
+                        {{end}}
+                    </div>
+                    {{end}}
+                </section>
+
+                <section class="card kpi">
+                    <div class="kpi-top">
+                        <span class="chip-ic" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M3 8h18v12a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V8z"/><path d="M2 4h20v4H2z"/><path d="M10 12h4"/></svg></span>
+                        <span class="kpi-label">缓存</span>
+                    </div>
+                    <div class="big num" data-count-num="{{.CacheCount}}">{{.CacheCount}}</div>
+                    <div class="big-sub">正文缓存条数</div>
+                    <div class="chip-row"><span class="chip {{if eq .CacheStatus "已启用"}}chip-up{{else}}chip-off{{end}}">{{.CacheStatus}}</span></div>
+                    <div class="kv"><span class="k">自动清理</span><span class="v">{{.CleanupStatus}}</span></div>
+                    <div class="kv"><span class="k">清理间隔</span><span class="v">{{.CleanupInterval}}</span></div>
+                </section>
+            </div>
+
+            <section class="card req-card">
+                <div class="card-head">
+                    <span class="card-title">最近请求</span>
+                    <span class="head-side num">20 条 · 3 秒自动刷新</span>
+                </div>
+                {{if .RecentRequests}}
+                <div class="twrap">
+                    <table>
+                        <thead>
+                            <tr>
+                                <th>时间</th>
+                                <th>方法</th>
+                                <th>路径</th>
+                                <th>IP</th>
+                                <th>UA</th>
+                                <th>状态</th>
+                                <th class="r">耗时</th>
+                            </tr>
+                        </thead>
+                        <tbody>
+                            {{range .RecentRequests}}
+                            <tr>
+                                <td class="num">{{.Time}}</td>
+                                <td><span class="mth">{{.Method}}</span></td>
+                                <td class="code path-cell" title="{{.Path}}">{{.Path}}{{if .Query}} <span class="q">?{{.Query}}</span>{{end}}</td>
+                                <td class="code">{{.IP}}</td>
+                                <td class="code" title="{{.UA}}">{{.UA}}</td>
+                                <td><span class="stc {{if .IsErr}}stc-err{{else}}stc-ok{{end}}"><i aria-hidden="true"></i>{{.Status}}</span></td>
+                                <td class="r num">{{.Duration}}</td>
+                            </tr>
+                            {{end}}
+                        </tbody>
+                    </table>
+                </div>
+                {{else}}
+                <div class="empty">
+                    <div class="e-title">暂无请求记录</div>
+                    <div class="e-desc">未开启请求日志，或服务启动后还没有收到业务请求。<br>可在配置文件中将 <code>server.request_log.enabled</code> 设为 <code>true</code> 后重启。</div>
+                </div>
+                {{end}}
+            </section>
+        </div>
+
+        <section class="docs card">
+            <div class="card-head">
+                <span class="card-title">API 接口文档</span>
+                <span class="head-side">分组可折叠 · 点"测试"直接调试</span>
+            </div>
+
+            <details class="grp" open>
+                <summary>
+                    <span class="chev" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M9 5l7 7-7 7"/></svg></span>
+                    <span class="grp-name">书籍相关</span>
+                    <span class="cnt num">6</span>
+                </summary>
+                <div class="eps">
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/search</span><span class="ep-desc">搜索书籍</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">query</span><span class="req">必需</span><span class="param-desc">搜索关键字</span></div>
+                            <div class="param-item"><span class="param-name">offset</span><span class="opt">可选</span><span class="param-desc">偏移量，默认0</span></div>
+                            <div class="param-item"><span class="param-name">tab_type</span><span class="opt">可选</span><span class="param-desc">类型，默认3</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/detail</span><span class="ep-desc">获取书籍详情</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">book_id</span><span class="req">必需</span><span class="param-desc">书籍ID</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/info</span><span class="ep-desc">获取书籍详情（同 detail）</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">book_id</span><span class="req">必需</span><span class="param-desc">书籍ID</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/catalog</span><span class="ep-desc">获取书籍目录</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">book_id</span><span class="req">必需</span><span class="param-desc">书籍ID</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/directory/all_items</span><span class="ep-desc">获取书籍目录（同 catalog）</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">book_id</span><span class="req">必需</span><span class="param-desc">书籍ID</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/multi-detail</span><span class="ep-desc">批量获取书籍详情</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">book_id</span><span class="req">必需</span><span class="param-desc">书籍ID列表，逗号分隔</span></div>
+                        </div>
+                    </div>
+                </div>
+            </details>
+
+            <details class="grp">
+                <summary>
+                    <span class="chev" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M9 5l7 7-7 7"/></svg></span>
+                    <span class="grp-name">内容相关</span>
+                    <span class="cnt num">3</span>
+                </summary>
+                <div class="eps">
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/content</span><span class="ep-desc">获取章节正文内容</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">item_id</span><span class="req">必需</span><span class="param-desc">章节ID，支持路径参数或查询参数</span></div>
+                            <div class="param-item"><span class="param-name">text_mode</span><span class="opt">可选</span><span class="param-desc">纯文本模式：1/true=纯文本，0/false=HTML</span></div>
+                            <div class="param-item"><span class="param-name">image_mode</span><span class="opt">可选</span><span class="param-desc">图片处理：1/true=保留图片，0/false=移除图片</span></div>
+                            <div class="param-item"><span class="param-name">review</span><span class="opt">可选</span><span class="param-desc">段评功能：1=启用，0=禁用</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/multi-content</span><span class="ep-desc">批量获取多个章节正文</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">book_id</span><span class="req">必需</span><span class="param-desc">书籍ID</span></div>
+                            <div class="param-item"><span class="param-name">item_ids</span><span class="req">必需</span><span class="param-desc">章节ID列表，多个ID用逗号分隔，如：123,456,789</span></div>
+                            <div class="param-item"><span class="param-name">text_mode</span><span class="opt">可选</span><span class="param-desc">纯文本模式：1/true=纯文本，0/false=HTML</span></div>
+                            <div class="param-item"><span class="param-name">image_mode</span><span class="opt">可选</span><span class="param-desc">图片处理：1/true=保留图片，0/false=移除图片</span></div>
+                            <div class="param-item"><span class="param-name">ignore_failed</span><span class="opt">可选</span><span class="param-desc">忽略失败章节：1/true=忽略，0/false=不忽略</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/item-summary</span><span class="ep-desc">获取章节摘要信息</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">book_id</span><span class="req">必需</span><span class="param-desc">书籍ID</span></div>
+                            <div class="param-item"><span class="param-name">item_ids</span><span class="req">必需</span><span class="param-desc">章节ID列表，逗号分隔</span></div>
+                        </div>
+                    </div>
+                </div>
+            </details>
+
+            <details class="grp">
+                <summary>
+                    <span class="chev" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M9 5l7 7-7 7"/></svg></span>
+                    <span class="grp-name">段评相关</span>
+                    <span class="cnt num">3</span>
+                </summary>
+                <div class="eps">
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/chapter_review</span><span class="ep-desc">获取章节评论列表</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">book_id</span><span class="req">必需</span><span class="param-desc">书籍ID</span></div>
+                            <div class="param-item"><span class="param-name">item_id</span><span class="req">必需</span><span class="param-desc">章节ID</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/review</span><span class="ep-desc">获取段落评论、回复</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">item_id</span><span class="req">必需</span><span class="param-desc">章节ID</span></div>
+                            <div class="param-item"><span class="param-name">book_id</span><span class="req">必需</span><span class="param-desc">书籍ID</span></div>
+                            <div class="param-item"><span class="param-name">para</span><span class="req">必需</span><span class="param-desc">段落索引（从0开始）</span></div>
+                            <div class="param-item"><span class="param-name">comment_id</span><span class="opt">可选</span><span class="param-desc">评论ID（获取回复时需要）</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/review_html</span><span class="ep-desc">获取段落评论HTML页面</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">item_id</span><span class="req">必需</span><span class="param-desc">章节ID</span></div>
+                            <div class="param-item"><span class="param-name">book_id</span><span class="req">必需</span><span class="param-desc">书籍ID</span></div>
+                            <div class="param-item"><span class="param-name">para</span><span class="req">必需</span><span class="param-desc">段落索引（从0开始）</span></div>
+                        </div>
+                    </div>
+                </div>
+            </details>
+
+            <details class="grp">
+                <summary>
+                    <span class="chev" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M9 5l7 7-7 7"/></svg></span>
+                    <span class="grp-name">多媒体</span>
+                    <span class="cnt num">3</span>
+                </summary>
+                <div class="eps">
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/manga</span><span class="ep-desc">获取漫画内容</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">item_ids</span><span class="req">必需</span><span class="param-desc">章节ID</span></div>
+                            <div class="param-item"><span class="param-name">output</span><span class="opt">可选</span><span class="param-desc">输出格式：url/proxy/data_uri，默认url</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/audio</span><span class="ep-desc">获取音频信息</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">item_ids</span><span class="req">必需</span><span class="param-desc">章节ID</span></div>
+                            <div class="param-item"><span class="param-name">tone_id</span><span class="opt">可选</span><span class="param-desc">音色ID，默认1</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/video</span><span class="ep-desc">获取视频信息</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">item_ids</span><span class="req">必需</span><span class="param-desc">章节ID</span></div>
+                        </div>
+                    </div>
+                </div>
+            </details>
+
+            <details class="grp">
+                <summary>
+                    <span class="chev" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M9 5l7 7-7 7"/></svg></span>
+                    <span class="grp-name">分类</span>
+                    <span class="cnt num">2</span>
+                </summary>
+                <div class="eps">
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/category-front</span><span class="ep-desc">获取分类首页</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">tab</span><span class="opt">可选</span><span class="param-desc">标签页，默认0</span></div>
+                        </div>
+                    </div>
+
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/category-landing</span><span class="ep-desc">获取分类详情页</span></div>
+                        <div class="api-params">
+                            <div class="param-item"><span class="param-name">category_id</span><span class="req">必需</span><span class="param-desc">分类ID</span></div>
+                            <div class="param-item"><span class="param-name">offset</span><span class="opt">可选</span><span class="param-desc">偏移量，默认0</span></div>
+                            <div class="param-item"><span class="param-name">limit</span><span class="opt">可选</span><span class="param-desc">每页数量，默认20</span></div>
+                        </div>
+                    </div>
+                </div>
+            </details>
+
+            <details class="grp">
+                <summary>
+                    <span class="chev" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M9 5l7 7-7 7"/></svg></span>
+                    <span class="grp-name">系统</span>
+                    <span class="cnt num">1</span>
+                </summary>
+                <div class="eps">
+                    <div class="api-endpoint">
+                        <div class="ep-head"><span class="mth">GET</span><span class="api-path">/status</span><span class="ep-desc">系统状态页面（当前页面）</span></div>
+                    </div>
+                </div>
+            </details>
+        </section>
+
+        <footer class="foot">番茄小说 API · 状态每 3 秒自动刷新 · 测试请求直接发往本实例</footer>
+    </div>
+</body>
+</html>

openapi.yaml

@@ -0,0 +1,974 @@
+openapi: 3.1.0
+info:
+  title: 番茄小说 API
+  version: 2.0.0
+  description: |
+    番茄小说非官方 API 服务,支持书籍搜索、详情、目录、正文、批量接口、
+    段评/书评、漫画、音频/有声书、视频与分类浏览。
+
+    多数接口直接转发上游 JSON(结构随上游版本变化,`data` 字段以实际返回为准);
+    错误统一返回 `{"code": -1, "msg": "..."}`。
+    需要鉴权的端点(`/status`)通过查询参数 `key`
+    或请求头 `X-Access-Key` 携带访问密钥,未配置 `server.access_key` 时不启用验证。
+  license:
+    name: MIT
+    identifier: MIT
+servers:
+  - url: http://localhost:40180
+    description: 本地开发
+tags:
+  - name: 系统
+    description: 服务状态监控
+  - name: 书籍
+    description: 搜索、详情、目录与批量详情
+  - name: 内容
+    description: 章节正文、批量正文与摘要
+  - name: 评论
+    description: 段落评论与书评
+  - name: 多媒体
+    description: 音频/有声书、视频、漫画及其代理
+  - name: 分类
+    description: 分类首页与分类详情
+  - name: 静态资源
+    description: 表情图片等静态文件
+
+paths:
+  /:
+    get:
+      tags: [系统]
+      summary: 服务心跳
+      operationId: getRoot
+      responses:
+        "200":
+          description: 服务存活
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: { type: integer, example: 0 }
+                  message: { type: string, example: success }
+                  data: { nullable: true }
+
+  /healthz:
+    get:
+      tags: [系统]
+      summary: 存活探针
+      description: 供容器/反向代理探活,不校验访问密钥。
+      operationId: getHealthz
+      responses:
+        "200":
+          description: 服务存活
+          content:
+            text/plain:
+              schema: { type: string }
+              example: ok
+
+  /status:
+    get:
+      tags: [系统]
+      summary: 运行状态监控面板
+      description: HTML 状态页,包含运行时长、签名方法、数据库大小、设备密钥池、
+        请求统计与内置 API 文档;页面每 3 秒自动刷新。
+      operationId: getStatus
+      security:
+        - accessKeyQuery: []
+        - accessKeyHeader: []
+      parameters:
+        - $ref: "#/components/parameters/AccessKeyQuery"
+      responses:
+        "200":
+          description: HTML 状态页
+          content:
+            text/html:
+              schema: { type: string }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+
+
+  /search:
+    get:
+      tags: [书籍]
+      summary: 搜索书籍
+      operationId: searchBooks
+      parameters:
+        - name: query
+          in: query
+          required: true
+          description: 搜索关键字(别名 `key`)
+          schema: { type: string }
+          example: 综漫
+        - name: key
+          in: query
+          description: "`query` 的别名,`query` 为空时生效"
+          schema: { type: string }
+        - name: offset
+          in: query
+          description: 结果偏移量,默认 0
+          schema: { type: integer, default: 0, minimum: 0 }
+          example: 0
+        - name: tab_type
+          in: query
+          description: |
+            搜索类型,默认 3;仅返回匹配该值的 tab:
+            * `1` 综合(混合:书籍 + 运营位 cell_data + 猜你喜欢 guess_you_like_data)
+            * `2` 听书(book_data)
+            * `3` 书籍(book_data,默认)
+            * `4` 社区(topic_data)
+            * `5` 全文(book_data)
+            * `6` 用户(search_user_data)
+            * `8` 漫画(book_data)
+            * `11` 短剧(video_data)
+          schema: { type: integer, default: 3, enum: [1, 2, 3, 4, 5, 6, 8, 11] }
+          example: 3
+      responses:
+        "200":
+          description: 搜索结果(tab 已展平:结果块在顶层 data,并提升 has_more/next_offset 分页字段)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SearchResponse"
+              example:
+                code: 0
+                message: SUCCESS
+                data:
+                  - book_data:
+                      - book_id: "7668727260244872254"
+                        book_name: 综漫：今天的告白，我也很期待哦
+                        author: 一念1浮生
+                        abstract: （评分五天从7.5涨到9.0，真的不看看吗，前期有点青涩，往后会好一点）……
+                        category: 动漫衍生
+                        word_number: "357281"
+                has_more: 1
+                next_offset: 10
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /detail:
+    get:
+      tags: [书籍]
+      summary: 获取书籍详情
+      operationId: getBookDetail
+      parameters:
+        - $ref: "#/components/parameters/BookId"
+      responses:
+        "200":
+          description: 书籍详情(上游转发)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /info:
+    get:
+      tags: [书籍]
+      summary: 获取书籍详情(/detail 别名)
+      operationId: getBookDetailAlias
+      parameters:
+        - $ref: "#/components/parameters/BookId"
+      responses:
+        "200":
+          description: 同 /detail
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /catalog:
+    get:
+      tags: [书籍]
+      summary: 获取章节目录(book_id → 每章 item_id)
+      description: |
+        传入 book_id,返回全部章节列表 `data.item_data_list[]`,
+        每项含 `item_id`、`title`、`chapter_word_number`、`volume_name`。
+        item_id 用于调用 /content、/multi-content、/item-summary、/audio、/manga、/video 等
+        需要 item_id 的接口;漫画/短剧的每集(话)item_id 也从这里获取。
+      operationId: getBookCatalog
+      parameters:
+        - $ref: "#/components/parameters/BookId"
+      responses:
+        "200":
+          description: 章节目录(上游转发,含每章 item_id)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /directory/all_items:
+    get:
+      tags: [书籍]
+      summary: 获取章节目录(/catalog 别名)
+      operationId: getBookCatalogAlias
+      parameters:
+        - $ref: "#/components/parameters/BookId"
+      responses:
+        "200":
+          description: 同 /catalog
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /multi-detail:
+    get:
+      tags: [书籍]
+      summary: 批量获取书籍详情
+      operationId: getMultiBookDetail
+      parameters:
+        - name: book_id
+          in: query
+          required: true
+          description: 书籍 ID 列表,逗号分隔
+          schema: { type: string }
+          example: "7123456789012345678,7234567890123456789"
+      responses:
+        "200":
+          description: 批量详情(上游转发)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /content:
+    get:
+      tags: [内容]
+      summary: 获取章节正文
+      description: |
+        返回章节正文。启用段评(`review=keep` 或配置 `fanqie.content.enable_review: true`)时,
+        正文 HTML 中会注入段评标记;纯文本输出(text_mode=plain 或配置 remove_html_tags: true)
+        时不注入段评标记(<comment> 为 XML 标签,纯文本无法承载)。
+        URL 参数优先于配置文件。
+      operationId: getItemContent
+      parameters:
+        - name: item_id
+          in: query
+          required: true
+          description: 章节 ID
+          schema: { type: string }
+          example: "7271032589123412345"
+        - name: text_mode
+          in: query
+          description: 文本模式,plain/1/true=纯文本,html/0/false=HTML;缺省用配置 remove_html_tags
+          schema: { type: string, enum: ["plain", "html", "0", "1", "true", "false"] }
+          example: "plain"
+        - name: image_mode
+          in: query
+          description: 图片处理,keep/1/true=保留,remove/0/false=移除(别名 `img_mode`);缺省用配置 remove_images 取反
+          schema: { type: string, enum: ["keep", "remove", "0", "1", "true", "false"] }
+          example: "keep"
+        - name: review
+          in: query
+          description: 段评开关,keep/1=启用,remove/0=禁用(别名 `review_mode`);缺省用配置 enable_review
+          schema: { type: string, enum: ["keep", "remove", "0", "1"] }
+      responses:
+        "200":
+          description: 章节正文
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/UpstreamResponse"
+                  - type: object
+                    properties:
+                      data:
+                        type: object
+                        properties:
+                          content:
+                            type: string
+                            description: 正文内容(HTML 或纯文本,取决于 text_mode)
+                          title: { type: string, description: 章节标题 }
+                          novel_data:
+                            type: object
+                            properties:
+                              book_id: { type: string, description: 所属书籍 ID }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /multi-content:
+    get:
+      tags: [内容]
+      summary: 批量获取章节正文
+      operationId: getMultiItemContent
+      parameters:
+        - $ref: "#/components/parameters/BookId"
+        - name: item_ids
+          in: query
+          required: true
+          description: 章节 ID 列表,逗号分隔
+          schema: { type: string }
+          example: "7271032589123412345,7271032589123412346"
+        - name: text_mode
+          in: query
+          description: 文本模式,plain/1/true=纯文本,html/0/false=HTML;缺省用配置 remove_html_tags
+          schema: { type: string, enum: ["plain", "html", "0", "1", "true", "false"] }
+        - name: image_mode
+          in: query
+          description: 图片处理,keep/1/true=保留,remove/0/false=移除(别名 `img_mode`);缺省用配置 remove_images 取反
+          schema: { type: string, enum: ["keep", "remove", "0", "1", "true", "false"] }
+        - name: ignore_failed
+          in: query
+          description: 忽略失败章节,1/true=在结果中跳过而非报错
+          schema: { type: string, enum: ["0", "1", "true", "false"] }
+      responses:
+        "200":
+          description: 批量正文(并发拉取)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /item-summary:
+    get:
+      tags: [内容]
+      summary: 获取章节摘要
+      operationId: getItemSummary
+      parameters:
+        - $ref: "#/components/parameters/BookId"
+        - name: item_ids
+          in: query
+          required: true
+          description: 章节 ID 列表,逗号分隔
+          schema: { type: string }
+      responses:
+        "200":
+          description: 章节摘要(上游转发)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /chapter_review:
+    get:
+      tags: [评论]
+      summary: 获取章节段评
+      description: 获取整个章节的段落评论数据。
+      operationId: getChapterReview
+      parameters:
+        - name: item_id
+          in: query
+          required: true
+          description: 章节 ID
+          schema: { type: string }
+        - name: book_id
+          in: query
+          description: 书籍 ID
+          schema: { type: string }
+      responses:
+        "200":
+          description: 章节段评数据
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequest"
+
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /review:
+    get:
+      tags: [评论]
+      summary: 获取段落评论/回复
+      description: 获取指定章节某一段落的评论;携带 `comment_id` 时返回该评论的回复。
+      operationId: getReview
+      parameters:
+        - name: item_id
+          in: query
+          required: true
+          description: 章节 ID
+          schema: { type: string }
+        - name: para
+          in: query
+          description: 段落索引(从 0 开始)
+          schema: { type: integer, minimum: 0 }
+          example: 0
+        - name: book_id
+          in: query
+          description: 书籍 ID(实际必传,缺省时上游返回 101003 错误)
+          schema: { type: string }
+        - name: comment_id
+          in: query
+          description: 评论 ID(获取回复时需要)
+          schema: { type: string }
+        - name: sort
+          in: query
+          description: 排序方式,默认 1(热门)
+          schema: { type: integer, default: 1 }
+        - name: offset
+          in: query
+          description: 分页偏移量,默认 0
+          schema: { type: integer, default: 0, minimum: 0 }
+        - name: count
+          in: query
+          description: 每页数量,默认 20
+          schema: { type: integer, default: 20, minimum: 1 }
+      responses:
+        "200":
+          description: 评论/回复数据
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequest"
+
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /review_html:
+    get:
+      tags: [评论]
+      summary: 获取段落评论 HTML 页面
+      description: 渲染好的评论 HTML 页面,可直接嵌入阅读器展示。
+      operationId: getReviewHtml
+      parameters:
+        - name: item_id
+          in: query
+          required: true
+          description: 章节 ID
+          schema: { type: string }
+        - name: para
+          in: query
+          required: true
+          description: 段落索引(从 0 开始)
+          schema: { type: integer, minimum: 0 }
+          example: 0
+        - name: book_id
+          in: query
+          description: 书籍 ID
+          schema: { type: string }
+        - name: page
+          in: query
+          description: 页码,默认 1
+          schema: { type: integer, default: 1, minimum: 1 }
+        - name: page_size
+          in: query
+          description: 每页数量,默认 20
+          schema: { type: integer, default: 20, minimum: 1 }
+        - name: sort
+          in: query
+          description: 排序方式,默认 1(热门)
+          schema: { type: integer, default: 1 }
+      responses:
+        "200":
+          description: 评论 HTML 页面
+          content:
+            text/html:
+              schema: { type: string }
+        "400":
+          $ref: "#/components/responses/BadRequest"
+
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /audio:
+    get:
+      tags: [多媒体]
+      summary: 获取音频/有声书信息
+      description: 返回章节的有声书播放信息,含本地音频代理地址。
+      operationId: getAudio
+      parameters:
+        - name: item_ids
+          in: query
+          required: true
+          description: 章节 ID
+          schema: { type: string }
+        - name: tone_id
+          in: query
+          description: 音色 ID,默认 1
+          schema: { type: string, default: "1" }
+        - name: output
+          in: query
+          description: 输出模式
+          schema: { type: string }
+      responses:
+        "200":
+          description: 音频信息(上游转发,含代理 URL)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /audio/proxy/{key}:
+    get:
+      tags: [多媒体]
+      summary: 音频代理
+      description: |
+        通过 /audio 返回的代理 key 拉取音频内容。
+        key 有效期 2 小时(与 CDN 链接有效期一致),过期后需重新调用 /audio。
+      operationId: getAudioProxy
+      parameters:
+        - name: key
+          in: path
+          required: true
+          description: /audio 接口生成的代理 key
+          schema: { type: string }
+          example: a3f8c92e1b7d4f60
+      responses:
+        "200":
+          description: 音频二进制内容
+          content:
+            audio/mpeg:
+              schema: { type: string, format: binary }
+            audio/aac:
+              schema: { type: string, format: binary }
+        "400":
+          description: key 无效、过期或下载失败
+          content:
+            text/plain:
+              schema: { type: string }
+              example: 音频信息已过期,请重新调用 /audio 接口
+
+  /video:
+    get:
+      tags: [多媒体]
+      summary: 获取视频信息
+      description: |
+        短剧视频流为 CENC 加密(encrypt=true, cenc-aes-ctr, HEVC+AAC):
+        播放 URL 可直接下载,但文件本身加密,通用播放器无法解码。
+        响应透传加密状态字段:顶层 key_seed(Base64,每次请求变化)、
+        video_list.*.encrypt/encryption_method/kid,供需要对接官方播放器的调用方使用。
+      operationId: getVideo
+      parameters:
+        - name: item_ids
+          in: query
+          required: true
+          description: 视频 ID,多个用逗号分隔;短剧每集的 item_id 从 /catalog 获取
+          schema: { type: string }
+      responses:
+        "200":
+          description: 视频信息(上游转发)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /manga:
+    get:
+      tags: [多媒体]
+      summary: 获取漫画内容
+      description: |
+        返回漫画章节内容,图片经解密处理。
+        设备池签名路线全部失败时自动降级 wkbrowser 免签名兜底(直接返回原图直链,响应附 `source: wkbrowser`)。
+        输出模式 `output` 优先于配置 `fanqie.manga.output_mode`:
+        - `url`: 返回原始图片 URL 数组(不可用:链接 404 且内容加密,仅作上游原始信息展示)
+        - `proxy`: 返回本地代理 URL(/manga/image/{item_id}/{index})——推荐,先调本接口再访问代理 URL(缓存 5 分钟)
+        - `data_uri`: 返回 Base64 编码(data:image/jpeg;base64,...)
+
+        CDN 链接说明(全接口通用):带 `x-signature` 签名的图片/音视频 URL 可直接 GET,
+        但不可修改 URL 任何部分(改尺寸模板/去参数即 403,签名覆盖整个 path)。
+        `x-expires` 为过期时间戳:图片约 30 天,音频约 2 小时,短剧视频约 6 小时,
+        过期后重新调用相应接口获取新 URL。无签名的 `audio_thumb_uri`/`horiz_thumb_url` 字段
+        为上游占位链接,不可用;封面请使用 `thumb_url`/`audio_thumb_url_hd`。
+      operationId: getManga
+      parameters:
+        - name: item_ids
+          in: query
+          required: true
+          description: 章节 ID(别名 `item_id`)
+          schema: { type: string }
+        - name: item_id
+          in: query
+          description: "`item_ids` 的别名"
+          schema: { type: string }
+        - name: show_html
+          in: query
+          description: 1=返回 HTML 阅读页
+          schema: { type: string, enum: ["0", "1"] }
+        - name: output
+          in: query
+          description: 输出模式,优先于配置文件
+          schema: { type: string, enum: [url, proxy, data_uri] }
+      responses:
+        "200":
+          description: 漫画内容
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+            text/html:
+              schema: { type: string }
+        "400":
+          $ref: "#/components/responses/BadRequest"
+
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /manga/image/{item_id}/{index}:
+    get:
+      tags: [多媒体]
+      summary: 漫画图片代理
+      description: 返回解密后的漫画图片,响应带 1 小时缓存头。
+      operationId: getMangaImage
+      parameters:
+        - name: item_id
+          in: path
+          required: true
+          description: 章节 ID
+          schema: { type: string }
+        - name: index
+          in: path
+          required: true
+          description: 图片序号(从 0 开始)
+          schema: { type: integer, minimum: 0 }
+      responses:
+        "200":
+          description: 图片二进制内容
+          headers:
+            Cache-Control:
+              schema: { type: string }
+              description: 固定为 public, max-age=3600
+          content:
+            image/jpeg:
+              schema: { type: string, format: binary }
+            image/png:
+              schema: { type: string, format: binary }
+            image/webp:
+              schema: { type: string, format: binary }
+        "400":
+          description: URL 格式或 index 参数错误
+          content:
+            text/plain:
+              schema: { type: string }
+        "500":
+          description: 图片获取/解密失败
+          content:
+            text/plain:
+              schema: { type: string }
+
+  /category-front:
+    get:
+      tags: [分类]
+      summary: 获取分类首页
+      operationId: getCategoryFront
+      parameters:
+        - name: tab
+          in: query
+          description: 标签页,默认 0
+          schema: { type: string, default: "0" }
+      responses:
+        "200":
+          description: 分类首页数据(上游转发)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /category-landing:
+    get:
+      tags: [分类]
+      summary: 获取分类详情页
+      description: 支持按分类筛选、排序与分页的书籍列表(每页固定 20 条)。
+      operationId: getCategoryLanding
+      parameters:
+        - name: category_id
+          in: query
+          required: true
+          description: 分类 ID(可从 /category-front 或搜索结果 book_data.category_schema 中解析)
+          schema: { type: string }
+        - name: offset
+          in: query
+          description: 偏移量,默认 0
+          schema: { type: integer, default: 0, minimum: 0 }
+        - name: word_number
+          in: query
+          description: 字数筛选,透传上游(0=不限)
+          schema: { type: integer, default: 0 }
+        - name: book_status
+          in: query
+          description: 连载状态筛选,透传上游(0=不限)
+          schema: { type: integer, default: 0 }
+        - name: sort_by
+          in: query
+          description: 排序方式,透传上游(0=默认)
+          schema: { type: integer, default: 0 }
+        - name: selected_items
+          in: query
+          description: 新版分类标签自带筛选项(从 /category-front 返回的 category_landpage_url 参数中获取),透传上游
+          schema: { type: string }
+      responses:
+        "200":
+          description: 分类书籍列表(上游转发)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /rank:
+    get:
+      tags: [榜单与个人数据]
+      summary: 获取书籍榜单
+      description: 免签名接口,支持五种榜单,每页 20 本,短缓存 10 分钟。
+      operationId: getRank
+      parameters:
+        - name: side_type
+          in: query
+          description: 榜单类型
+          schema:
+            type: integer
+            default: 10
+            enum: [10, 11, 12, 13, 15]
+            x-enum-varnames: [推荐榜, 完结榜, 热搜榜, 黑马榜, 爆更榜]
+        - name: page
+          in: query
+          description: 页码,从 1 起
+          schema: { type: integer, default: 1, minimum: 1 }
+      responses:
+        "200":
+          description: 榜单书籍列表(上游转发,data.result 为书籍数组)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /bookshelf:
+    get:
+      tags: [榜单与个人数据]
+      summary: 获取我的书架
+      description: 需要番茄网页版登录态;每本书合并详情数据并附带 group_name。个人动态数据不缓存。
+      operationId: getBookshelf
+      parameters:
+        - name: sessionid
+          in: query
+          required: true
+          description: 番茄网页版(fanqienovel.com)登录后的 Cookie sessionid
+          schema: { type: string }
+        - name: group
+          in: query
+          description: 按分组过滤,为空返回全部
+          schema: { type: string }
+      responses:
+        "200":
+          description: 书架书籍列表(data 为数组,每项含书籍详情 + group_name)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /read-history:
+    get:
+      tags: [榜单与个人数据]
+      summary: 获取阅读历史
+      description: 需要番茄网页版登录态;每页 20 条,每项合并书籍详情并保留原始记录(含阅读进度)于 history 字段。个人动态数据不缓存。
+      operationId: getReadHistory
+      parameters:
+        - name: sessionid
+          in: query
+          required: true
+          description: 番茄网页版(fanqienovel.com)登录后的 Cookie sessionid
+          schema: { type: string }
+        - name: offset
+          in: query
+          description: 偏移量,默认 0,每页 20 条
+          schema: { type: integer, default: 0, minimum: 0 }
+      responses:
+        "200":
+          description: 阅读历史列表(data 为数组)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UpstreamResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
+  /emoji/{file}:
+    get:
+      tags: [静态资源]
+      summary: 表情图片
+      description: 评论中使用的表情静态图片文件。
+      operationId: getEmoji
+      parameters:
+        - name: file
+          in: path
+          required: true
+          description: 表情文件名
+          schema: { type: string }
+          example: 1@2x.png
+      responses:
+        "200":
+          description: 图片文件
+          content:
+            image/png:
+              schema: { type: string, format: binary }
+            image/gif:
+              schema: { type: string, format: binary }
+        "404":
+          description: 文件不存在
+          content:
+            text/plain:
+              schema: { type: string }
+
+
+components:
+  securitySchemes:
+    accessKeyQuery:
+      type: apiKey
+      in: query
+      name: key
+      description: 访问密钥,对应配置 server.access_key(或环境变量 FQ_SERVER_ACCESS_KEY)
+    accessKeyHeader:
+      type: apiKey
+      in: header
+      name: X-Access-Key
+      description: 访问密钥(与查询参数 key 等效)
+
+  parameters:
+    BookId:
+      name: book_id
+      in: query
+      required: true
+      description: 书籍 ID
+      schema: { type: string }
+      example: "7123456789012345678"
+    AccessKeyQuery:
+      name: key
+      in: query
+      description: 访问密钥(仅配置了 server.access_key 时需要)
+      schema: { type: string }
+
+  responses:
+    Unauthorized:
+      description: 访问密钥缺失或无效(业务接口仅在 server.protect_all 开启时需要)
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example: { code: -1, msg: "访问被拒绝:无效的访问密钥" }
+    ServerError:
+      description: 服务端错误(上游请求失败等)
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example: { code: -1, msg: "获取内容失败: 请求超时" }
+    BadRequest:
+      description: 参数缺失或格式错误
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example: { code: -1, msg: "缺少 item_id 参数" }
+
+  schemas:
+    ErrorResponse:
+      type: object
+      required: [code, msg]
+      properties:
+        code:
+          type: integer
+          const: -1
+        msg:
+          type: string
+          description: 错误信息
+
+    SearchResponse:
+      type: object
+      description: |
+        搜索响应(已展平:原上游 `search_tabs[0]` 中的 `data` 提升为顶层 `data`,
+        并提升分页字段 `has_more`/`next_offset`;`search_tabs` 字段不再返回)。
+      required: [code, data]
+      properties:
+        code:
+          type: integer
+          description: 0=成功
+          example: 0
+        message:
+          type: string
+          example: SUCCESS
+        data:
+          type: array
+          description: |
+            搜索结果块,单个元素的 *_data 字段由 tab_type 决定:
+            `book_data`(tab_type 1/2/3/5/8:书籍/听书/全文/漫画,含 book_id/book_name/author/abstract 等)、
+            `topic_data`(tab_type 4 社区,含 title/comment)、
+            `search_user_data`(tab_type 6 用户,含 encode_user_id/is_author)、
+            `video_data`(tab_type 11 短剧)、
+            `cell_data`/`guess_you_like_data`(tab_type 1 的运营位与猜你喜欢)。
+            所有元素均附带 book_hot_content_data 等上游字段,以实际返回为准。
+          items:
+            type: object
+            properties:
+              book_data:
+                type: array
+                description: 书籍结果(tab_type 1/2/3/5)
+                items: { type: object }
+              topic_data:
+                type: array
+                description: 话题结果(tab_type 4)
+                items: { type: object }
+              search_user_data:
+                type: array
+                description: 用户结果(tab_type 6)
+                items: { type: object }
+              video_data:
+                type: array
+                description: 短剧结果(tab_type 11)
+                items: { type: object }
+              cell_data:
+                type: array
+                description: 运营位(tab_type 1 混合出现)
+                items: { type: object }
+              guess_you_like_data:
+                type: array
+                description: 猜你喜欢(tab_type 1 混合出现)
+                items: { type: object }
+        has_more:
+          type: integer
+          description: 是否还有更多结果(1=有)
+          example: 1
+        next_offset:
+          type: integer
+          description: 下一页 offset 值
+          example: 10
+        log_id:
+          type: string
+    UpstreamResponse:
+      type: object
+      description: |
+        通用响应包装。多数接口转发上游数据,`data` 的内部结构随上游接口变化,
+        以实际返回为准;此处仅约束外层字段。
+      required: [code, msg]
+      properties:
+        code:
+          type: integer
+          description: 0=成功,-1=失败
+          example: 0
+        msg:
+          type: string
+          example: success
+        data:
+          description: 业务数据,结构随接口不同