✨ feat(cache): 新增 Redis 缓存与 PostgreSQL 后端支持

- 新增 cache.redis 配置(独立 host/port/password/db 字段),启用后正文缓存与音频代理缓存走 Redis,键前缀 fq:cache:/fq:audio:,TTL 自动过期
- 新增 cache.backend: sqlite|postgres 切换,PG 连接用 net/url 构造 DSN,密码特殊字符自动转义;SQLite 顺手启用 WAL 与 busy_timeout
- SQL 方言收敛:q() 将 ? 占位符转换为 $n、INSERT OR IGNORE 与查询再插入统一为 ON CONFLICT、LastInsertId 改为 RETURNING id、建表 DDL 双版本分派
- PG 下 VACUUM 走 autovacuum 说明、状态页大小改查 pg_database_size
- 修复 PG 下设备保存失败:is_valid 列为 INTEGER,写入点补 boolToInt 转换
- 新增 .env 支持:敏感配置(密码/主机/访问密钥)由环境变量覆盖 config.yaml,.env 进 gitignore,仓库附 .env.example 模板
- 新增 openapi.yaml(OpenAPI 3.1):覆盖全部 24 个路径,含参数、响应结构与鉴权方案,README 增加指引
- 删除死代码 InitDevicePoolTable;新增 rebind_test.go 单测
- 更新 README 与 config.yaml 配置示例,go.mod 新增 go-redis/v9 与 pgx/v5 依赖

README.md

@@ -34,7 +34,7 @@ Go 语言实现的番茄小说非官方 API 服务，完整实现了签名算法
 
 - **签名算法** - Gorgon、8404、Argus、Ladon、Khronos
 - **设备密钥池** - 多设备轮换、自动补充
-- **SQLite 缓存** - 本地缓存、过期清理、数据库压缩
+- **SQLite 缓存** - 本地缓存、过期清理、数据库压缩；支持切换 PostgreSQL 与 Redis
 - **配置热更新** - 修改配置无需重启
 - **访问控制** - 支持 AccessKey 验证
 
@@ -127,6 +127,8 @@ go run ./cmd/fanqie
 
 ## API 接口文档
 
+机器可读的完整接口定义见 [openapi.yaml](openapi.yaml)(OpenAPI 3.1,可直接导入 Swagger UI / Apifox / Postman)。
+
 ### 基础接口
 
 | 接口 | 方法 | 说明 |
@@ -266,7 +268,22 @@ fanqie:
 # 缓存配置
 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 库）
+    enabled: false
+    host: "127.0.0.1"      # 主机
+    port: 6379             # 端口
+    password: ""           # 密码
+    db: 0                  # 数据库编号
   cleanup_enabled: true     # 启用自动清理
   cleanup_seconds: 86400    # 清理间隔（秒）
 
@@ -278,6 +295,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` 文件中的值。
+
 ### 配置说明表
 
 | 配置项 | 说明 | 默认值 |
@@ -289,8 +328,20 @@ device_key_pool:
 | `fanqie.signature` | 签名方法 `sign2` / `sign4` | `sign4` |
 | `fanqie.content.*` | 正文内容处理选项 | 见上文 |
 | `fanqie.manga.output_mode` | 漫画输出模式 | `url` |
-| `cache.enabled` | 是否启用 SQLite 缓存 | `true` |
+| `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` |