416 lines
15 KiB
Markdown
416 lines
15 KiB
Markdown
# 番茄小说 API
|
||
|
||
Go 语言实现的番茄小说非官方 API 服务，完整实现了签名算法、设备注册、密钥管理等核心功能。
|
||
|
||
## 功能特性
|
||
|
||
### 核心功能
|
||
|
||
- **书籍搜索** - 关键词搜索，支持分页
|
||
- **书籍详情** - 获取书籍基本信息、封面、作者等
|
||
- **章节目录** - 获取完整章节列表
|
||
- **章节内容** - 获取正文内容，支持纯文本/HTML模式
|
||
- **批量接口** - 支持批量获取书籍详情和章节内容
|
||
|
||
### 内容类型
|
||
|
||
- 📖 小说/电子书
|
||
- 🎨 漫画
|
||
- 🎵 音频/有声书
|
||
- 🎬 视频
|
||
|
||
### 评论功能
|
||
|
||
- 章节段评（段落评论）
|
||
- 书籍书评
|
||
- 评论 HTML 渲染
|
||
|
||
### 分类体系
|
||
|
||
- 分类首页数据
|
||
- 分类详情页（支持筛选、排序、分页）
|
||
|
||
### 技术特性
|
||
|
||
- **签名算法** - Gorgon、8404、Argus、Ladon、Khronos
|
||
- **设备密钥池** - 多设备轮换、自动补充
|
||
- **多级缓存** - 正文/详情/目录等 24 小时缓存，搜索/分类短缓存；存储后端可选 SQLite / PostgreSQL / Redis
|
||
- **配置热更新** - 修改配置无需重启
|
||
- **访问控制** - AccessKey 验证（常量时间比较防时序攻击），可扩展保护全部业务接口
|
||
- **优雅退出** - 超时保护、信号驱动的平滑关闭
|
||
- **错误规范** - 统一 JSON 错误响应，缺参 400 / 服务端错误 500
|
||
|
||
## 项目结构
|
||
|
||
```tree
|
||
fanqie-go/
|
||
├── cmd/fanqie/ # 程序入口
|
||
│ └── main.go # 主函数，初始化服务
|
||
├── config/ # 配置文件
|
||
│ └── config.yaml # 配置文件
|
||
├── emoji/ # 表情图片静态资源
|
||
├── internal/
|
||
│ ├── algos/ # 签名算法实现
|
||
│ │ ├── gorgon.go # Gorgon 签名算法
|
||
│ │ ├── algo8404.go # 8404 签名算法
|
||
│ │ ├── argus.go # Argus 签名算法
|
||
│ │ ├── ladon.go # Ladon 签名算法
|
||
│ │ ├── signer.go # 签名管理器
|
||
│ │ ├── switcher.go # 算法切换器
|
||
│ │ ├── sm3.go # SM3 哈希算法
|
||
│ │ ├── simon.go # Simon 对称加密
|
||
│ │ ├── pkcs7.go # PKCS7 填充
|
||
│ │ ├── protobuf.go # Protobuf 协议
|
||
│ │ └── bytebuf.go # 字节缓冲区
|
||
│ ├── common/ # 公共工具
|
||
│ │ ├── logger.go # 日志工具
|
||
│ │ ├── http.go # HTTP 工具
|
||
│ │ └── utils.go # 通用工具
|
||
│ ├── config/ # 配置管理
|
||
│ │ ├── config.go # 配置加载
|
||
│ │ └── watcher.go # 配置热更新
|
||
│ ├── fqapi/ # API 封装层
|
||
│ │ ├── cache_manager.go # SQLite 缓存管理
|
||
│ │ ├── device_key_pool.go # 设备密钥池
|
||
│ │ ├── device_register.go # 设备注册
|
||
│ │ ├── register_key.go # 密钥注册
|
||
│ │ ├── dhcry.go # DH 加密交换
|
||
│ │ ├── ttencrypt.go # TTEncrypt 加密
|
||
│ │ ├── search.go # 搜索接口
|
||
│ │ ├── detail.go # 书籍详情
|
||
│ │ ├── catalog.go # 章节目录
|
||
│ │ ├── content.go # 章节内容
|
||
│ │ ├── multi_content.go # 批量内容
|
||
│ │ ├── multi_detail.go # 批量详情
|
||
│ │ ├── item_summary.go # 章节摘要
|
||
│ │ ├── category_front.go # 分类首页
|
||
│ │ ├── category_landing.go # 分类详情
|
||
│ │ ├── audio.go # 音频
|
||
│ │ ├── video.go # 视频
|
||
│ │ ├── manga.go # 漫画
|
||
│ │ ├── manga_proxy.go # 漫画代理
|
||
│ │ ├── review.go # 评论
|
||
│ │ ├── content_parser.go # 内容解析
|
||
│ │ ├── content_utils.go # 内容工具
|
||
│ │ ├── emoji.go # 表情管理
|
||
│ │ ├── device_config.go # 设备配置
|
||
│ │ └── gorgon_utils.go # Gorgon 请求封装
|
||
│ └── handlers/ # HTTP 处理器
|
||
│ ├── common.go # 通用处理
|
||
│ ├── book.go # 书籍接口
|
||
│ ├── content.go # 内容接口
|
||
│ ├── media.go # 媒体接口
|
||
│ ├── review.go # 评论接口
|
||
│ ├── category.go # 分类接口
|
||
│ ├── manga_proxy.go # 漫画代理
|
||
│ └── status.go # 状态页面
|
||
└── go.mod # Go 模块定义
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Go 1.25+
|
||
- SQLite3
|
||
|
||
### 安装运行
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone https://github.com/cyqddx/fanqie-go.git
|
||
cd fanqie-go
|
||
|
||
# 运行服务
|
||
go run ./cmd/fanqie
|
||
```
|
||
|
||
服务默认启动在 `http://0.0.0.0:40180`
|
||
|
||
## 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） |
|
||
| `POST /vacuum` | POST | 数据库压缩（需 AccessKey） |
|
||
|
||
### 书籍相关
|
||
|
||
| 接口 | 方法 | 说明 | 参数 |
|
||
| ------ | ------ | ------ | ------ |
|
||
| `/search` | GET | 搜索书籍 | `query`（或 `key`）, `tab_type`, `offset`（`search_tabs` 仅返回匹配 `tab_type` 的 tab） |
|
||
| `/detail` | GET | 书籍详情 | `book_id` |
|
||
| `/info` | GET | 书籍详情（同 detail） | `book_id` |
|
||
| `/catalog` | GET | 章节目录 | `book_id` |
|
||
| `/directory/all_items` | GET | 章节目录（同 catalog） | `book_id` |
|
||
| `/multi-detail` | GET | 批量书籍详情 | `book_id`（逗号分隔） |
|
||
|
||
### 内容相关
|
||
|
||
| 接口 | 方法 | 说明 | 参数 |
|
||
| ------ | ------ | ------ | ------ |
|
||
| `/content` | GET | 章节内容 | `item_id` |
|
||
| `/multi-content` | GET | 批量章节内容 | `book_id`, `item_ids`（逗号分隔） |
|
||
| `/item-summary` | GET | 章节摘要 | `book_id`, `item_ids`（逗号分隔） |
|
||
|
||
### 评论相关
|
||
|
||
| 接口 | 方法 | 说明 | 参数 |
|
||
| ------ | ------ | ------ | ------ |
|
||
| `/chapter_review` | GET | 章节评论 | `book_id`, `item_id` |
|
||
| `/review` | GET | 书评列表 | `book_id`, `item_id`, `para`, `comment_id`, `offset`, `limit` |
|
||
| `/review_html` | GET | 评论 HTML | `book_id`, `item_id`, `para` |
|
||
|
||
### 分类相关
|
||
|
||
| 接口 | 方法 | 说明 | 参数 |
|
||
| ------ | ------ | ------ | ------ |
|
||
| `/category-front` | GET | 分类首页 | - |
|
||
| `/category-landing` | GET | 分类详情 | `category_id`, `word_number`, `book_status`, `sort_by`, `offset` |
|
||
|
||
### 媒体相关
|
||
|
||
| 接口 | 方法 | 说明 | 参数 |
|
||
| ------ | ------ | ------ | ------ |
|
||
| `/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 | 漫画图片 | 路径参数 |
|
||
|
||
## 内容获取示例
|
||
|
||
### 搜索书籍
|
||
|
||
```bash
|
||
GET http://localhost:40180/search?keyword=斗罗大陆
|
||
```
|
||
|
||
### 获取书籍详情
|
||
|
||
```bash
|
||
GET http://localhost:40180/detail?book_id=xxx
|
||
```
|
||
|
||
### 获取章节目录
|
||
|
||
```bash
|
||
GET http://localhost:40180/catalog?book_id=xxx
|
||
```
|
||
|
||
### 获取章节内容
|
||
|
||
```bash
|
||
GET http://localhost:40180/content?book_id=xxx&chapter_id=xxx
|
||
```
|
||
|
||
支持以下 URL 参数覆盖默认配置：
|
||
|
||
| 参数 | 说明 | 可选值 |
|
||
| ------ | ------ | ------ |
|
||
| `text_mode` | 文本模式 | `plain`（纯文本）, `html`（HTML） |
|
||
| `img_mode` | 图片模式 | `remove`（移除）, `keep`（保留） |
|
||
| `review_mode` | 评论模式 | `remove`（移除）, `keep`（保留） |
|
||
|
||
### 批量获取
|
||
|
||
```bash
|
||
GET http://localhost:40180/multi-detail?book_ids=id1,id2,id3
|
||
|
||
GET http://localhost:40180/multi-content?chapter_ids=id1,id2,id3
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 完整配置项
|
||
|
||
配置文件位于 `config/config.yaml`：
|
||
|
||
```yaml
|
||
# 服务器配置
|
||
server:
|
||
host: "0.0.0.0" # 监听地址
|
||
port: "40180" # 监听端口
|
||
access_key: "" # 访问密钥（可选）
|
||
protect_all: false # 业务接口也要求访问密钥（公网部署建议开启）
|
||
|
||
# 番茄小说配置
|
||
fanqie:
|
||
# 签名算法: "gorgon" / "8404"
|
||
algorithm: "gorgon"
|
||
|
||
# 签名方法:
|
||
# - "sign2": X-Gorgon + X-Khronos
|
||
# - "sign4": X-Gorgon + X-Ladon + X-Argus + X-Khronos
|
||
signature: "sign4"
|
||
|
||
# 内容处理
|
||
content:
|
||
remove_images: false # 移除图片
|
||
remove_image_desc: true # 移除图片描述
|
||
remove_blank_lines: true # 移除空行
|
||
remove_html_tags: true # 移除 HTML 标签
|
||
remove_chapter_title: true # 移除章节标题
|
||
add_paragraph_indent: false # 添加段落缩进
|
||
double_newline: false # 段落间双换行
|
||
enable_review: true # 启用段评
|
||
|
||
# 漫画处理
|
||
manga:
|
||
# 输出模式:
|
||
# - "proxy": 代理模式
|
||
# - "url": 直接返回图片 URL
|
||
# - "data_uri": Base64 编码
|
||
output_mode: "url"
|
||
|
||
# 缓存配置
|
||
cache:
|
||
enabled: true # 启用缓存
|
||
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 # 清理间隔（秒）
|
||
|
||
# 设备密钥池
|
||
device_key_pool:
|
||
enabled: true # 启用设备池
|
||
initial_size: 20 # 初始设备数
|
||
min_size: 10 # 最小设备数
|
||
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` 文件中的值。
|
||
|
||
### 配置说明表
|
||
|
||
| 配置项 | 说明 | 默认值 |
|
||
| ------ | ------ | ------ |
|
||
| `server.host` | HTTP 服务监听地址 | `0.0.0.0` |
|
||
| `server.port` | HTTP 服务监听端口 | `40180` |
|
||
| `server.access_key` | 访问密钥，设为空则不验证 | - |
|
||
| `server.protect_all` | 业务接口是否也要求访问密钥 | `false` |
|
||
| `fanqie.algorithm` | 签名算法 `gorgon` / `8404` | `gorgon` |
|
||
| `fanqie.signature` | 签名方法 `sign2` / `sign4` | `sign4` |
|
||
| `fanqie.content.*` | 正文内容处理选项 | 见上文 |
|
||
| `fanqie.manga.output_mode` | 漫画输出模式 | `url` |
|
||
| `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` |
|
||
| `device_key_pool.max_size` | 最大设备数量 | `30` |
|
||
|
||
## 签名算法详解
|
||
|
||
### 算法实现
|
||
|
||
项目实现了番茄小说的核心签名算法：
|
||
|
||
| 算法 | 文件 | 说明 |
|
||
| ------ | ------ | ------ |
|
||
| **Gorgon** | `algos/gorgon.go` | 核心签名算法，生成 X-Gorgon、X-Khronos、X-SS-REQ-Ticket |
|
||
| **8404** | `algos/algo8404.go` | 另一种签名算法实现 |
|
||
| **Argus** | `algos/argus.go` | 增强签名，包含 ProtoBuf、SM3、Simon、AES 加密 |
|
||
| **Ladon** | `algos/ladon.go` | 附加签名，基于 MD5 变换 |
|
||
| **Khronos** | 内嵌于 Gorgon | 时间戳签名 |
|
||
|
||
### 签名方法
|
||
|
||
- **sign2**: X-Gorgon + X-Khronos（基础签名）
|
||
- **sign4**: X-Gorgon + X-Ladon + X-Argus + X-Khronos（完整签名）
|
||
|
||
## 设备密钥池
|
||
|
||
项目实现了设备密钥池管理：
|
||
|
||
- **自动注册** - 启动时自动注册多个设备
|
||
- **密钥轮换** - 请求时自动切换设备
|
||
- **自动补充** - 设备数量低于阈值时自动注册新设备
|
||
- **持久化存储** - 设备信息保存到 SQLite
|
||
|
||
## 缓存机制
|
||
|
||
- **接口缓存** - 命中直接返回，不打上游（Redis 启用时优先走 Redis）
|
||
- **自动清理** - 定期清理过期缓存（Redis 由 TTL 自动过期）
|
||
- **数据库压缩** - 支持 VACUUM 操作优化数据库
|
||
|
||
| 接口 | 缓存时长 |
|
||
| ------ | ------ |
|
||
| `/content` | 24 小时 |
|
||
| `/detail`、`/info`、`/catalog`、`/multi-detail`、`/item-summary` | 24 小时 |
|
||
| `/search`、`/category-front`、`/category-landing` | 10 分钟 |
|
||
| `/audio` 代理链接 | 2 小时（匹配 CDN 有效期） |
|
||
|
||
失败响应不缓存；评论类接口为动态数据，不缓存。
|
||
|
||
## 技术栈
|
||
|
||
- **Go 1.25** - 编程语言
|
||
- **net/http** - 标准库 HTTP 服务（超时保护 + 优雅退出）
|
||
- **SQLite3 / PostgreSQL / Redis** - 缓存与存储
|
||
- **Viper** - 配置管理
|
||
- **goquery** - HTML 解析
|
||
|
||
## 注意事项
|
||
|
||
- 本项目仅供学习和研究使用
|
||
- 请遵守番茄小说的服务条款
|
||
- 请合理使用，避免对官方服务造成影响
|
||
- 签名算法和设备注册可能随时失效
|
||
|
||
## License
|
||
|
||
MIT License
|