176 lines
4.4 KiB
Markdown
176 lines
4.4 KiB
Markdown
# SomeACG 随机图片服务
|
||
|
||
基于 someacg 提供的图片列表 API，开发的高性能随机图片服务。支持自动页数检测、智能缓存管理和定时更新功能。
|
||
|
||
## 功能特性
|
||
|
||
- 🚀 **高性能缓存**: 预加载全量图片数据，100% 缓存命中率
|
||
- 🔄 **自动更新**: 每日凌晨自动检测最大页数并更新缓存
|
||
- 📱 **多端支持**: 支持桌面端和移动端不同尺寸的图片
|
||
- 🛡️ **错误处理**: 完善的重试机制和降级策略
|
||
- 📊 **状态监控**: 提供详细的服务状态和缓存统计信息
|
||
- 🗂️ **智能管理**: 自动清理过期缓存，支持配置缓存大小限制
|
||
|
||
## 快速开始
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 配置环境变量
|
||
|
||
复制 `.env.example` 为 `.env` 并根据需要修改配置：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
主要配置项：
|
||
|
||
```env
|
||
# 服务端口
|
||
PORT=3000
|
||
|
||
# 缓存配置
|
||
CACHE_DIR=./cache
|
||
MAX_CACHE_SIZE_MB=1024
|
||
|
||
# API 配置
|
||
SOMEACG_API_BASE=https://someacg.vercel.app/api
|
||
SOMEACG_CDN_BASE=https://cdn.someacg.top/graph/origin
|
||
```
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
# 生产环境
|
||
npm start
|
||
|
||
# 开发环境
|
||
npm run dev
|
||
```
|
||
|
||
## API 接口
|
||
|
||
### 获取随机图片
|
||
|
||
```http
|
||
GET /api/random
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 说明 | 可选值 |
|
||
|------|------|------|--------|
|
||
| size | string/number | 图片尺寸类型 | `1`/`mobile`（移动端）, `2`/`desktop`（桌面端），不传则随机 |
|
||
| type | string | 返回类型 | `url`（默认，返回图片信息）, `image`（直接返回图片数据） |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"_id": "68889a7645c10a92ad0e8e94",
|
||
"quality": true,
|
||
"title": "「綺麗。」",
|
||
"desc": "",
|
||
"file_name": "132641568_p0.jpg",
|
||
"size": {
|
||
"width": 3024,
|
||
"height": 4536,
|
||
"_id": "6894f7e091dd1a5cfedcd845"
|
||
},
|
||
"url": "https://cdn.someacg.top/graph/origin/132641568_p0.jpg",
|
||
"cached": true
|
||
}
|
||
```
|
||
|
||
### 服务状态
|
||
|
||
```http
|
||
GET /api/status
|
||
```
|
||
|
||
返回服务运行状态、内存使用情况、缓存统计等信息。
|
||
|
||
### 首页
|
||
|
||
```http
|
||
GET /
|
||
```
|
||
|
||
返回服务基本信息。
|
||
|
||
## 核心功能
|
||
|
||
### 页数检测
|
||
|
||
- 启动时自动检测 someacg API 的最大页数
|
||
- 使用二分法高效探测页数范围
|
||
- 每日凌晨 2:00 自动更新页数范围
|
||
- 支持桌面端和移动端分别检测
|
||
|
||
### 缓存策略
|
||
|
||
1. **预加载**: 启动时和每日更新后，全量拉取所有页面的图片列表
|
||
2. **随机排序**: 将获取的图片列表随机打乱，确保随机性
|
||
3. **本地缓存**: 按顺序下载并缓存图片到本地存储
|
||
4. **智能清理**: 达到缓存大小限制时，自动清理最早访问的图片
|
||
5. **100% 命中**: 所有用户请求都从本地缓存获取，无需访问外部 CDN
|
||
|
||
### 错误处理
|
||
|
||
- **网络重试**: API 请求失败时自动重试 3 次
|
||
- **降级策略**: 页数检测失败时使用前一天的缓存数据
|
||
- **跳过机制**: 缓存中图片丢失时自动跳到下一张
|
||
- **限流处理**: 遇到 429 错误时自动延长等待时间
|
||
|
||
### 定时任务
|
||
|
||
- **每日更新**: 凌晨 2:00 自动检测页数并重新预加载缓存
|
||
- **健康检查**: 每小时检查服务状态和内存使用情况
|
||
- **日志清理**: 每 6 小时执行一次日志清理和垃圾回收
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/
|
||
├── app.js # 主应用入口
|
||
├── services/
|
||
│ ├── CacheManager.js # 缓存管理服务
|
||
│ ├── PageDetector.js # 页数检测服务
|
||
│ ├── ImageService.js # 图片服务（核心业务逻辑）
|
||
│ └── scheduler.js # 定时任务调度器
|
||
└── utils/
|
||
└── logger.js # 日志工具
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
| 配置项 | 默认值 | 说明 |
|
||
|--------|--------|------|
|
||
| PORT | 3000 | 服务端口 |
|
||
| CACHE_DIR | ./cache | 缓存目录 |
|
||
| MAX_CACHE_SIZE_MB | 1024 | 最大缓存大小（MB） |
|
||
| MAX_PAGE_DETECTION_TIMEOUT | 30000 | 页数检测超时时间（毫秒） |
|
||
| MAX_RETRY_ATTEMPTS | 3 | 最大重试次数 |
|
||
| LOG_LEVEL | info | 日志级别 |
|
||
|
||
## 性能优化
|
||
|
||
- 使用本地缓存避免频繁访问外部 CDN
|
||
- 批量并发下载图片，提高预加载效率
|
||
- 智能缓存清理策略，避免磁盘空间不足
|
||
- 内存使用监控和垃圾回收机制
|
||
|
||
## 注意事项
|
||
|
||
1. 首次启动需要较长时间进行预加载，请耐心等待
|
||
2. 确保有足够的磁盘空间用于图片缓存
|
||
3. someacg CDN 对单 IP 有并发限制，预加载过程中可能遇到 429 错误
|
||
4. 建议在服务器环境中运行，以获得更好的网络稳定性
|
||
|
||
## 许可证
|
||
|
||
MIT License |