SomeACG 随机图片服务
基于 someacg 提供的图片列表 API，开发的高性能随机图片服务。支持自动页数检测、智能缓存管理和定时更新功能。
功能特性
- 🚀 高性能缓存: 预加载全量图片数据，100% 缓存命中率
- 🔄 自动更新: 每日凌晨自动检测最大页数并更新缓存
- 📱 多端支持: 支持桌面端和移动端不同尺寸的图片
- 🛡️ 错误处理: 完善的重试机制和降级策略
- 📊 状态监控: 提供详细的服务状态和缓存统计信息
- 🗂️ 智能管理: 自动清理过期缓存，支持配置缓存大小限制
快速开始
安装依赖
npm install
配置环境变量
复制 .env.example 为 .env 并根据需要修改配置：
cp .env.example .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
启动服务
# 生产环境
npm start
# 开发环境
npm run dev
API 接口
获取随机图片
GET /api/random
查询参数：
| 参数 | 类型 | 说明 | 可选值 |
|---|---|---|---|
| size | string/number | 图片尺寸类型 | 1/mobile（移动端）, 2/desktop（桌面端），不传则随机 |
| type | string | 返回类型 | url（默认，返回图片信息）, image（直接返回图片数据） |
响应示例：
{
"_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
}
服务状态
GET /api/status
返回服务运行状态、内存使用情况、缓存统计等信息。
首页
GET /
返回服务基本信息。
核心功能
页数检测
- 启动时自动检测 someacg API 的最大页数
- 使用二分法高效探测页数范围
- 每日凌晨 2:00 自动更新页数范围
- 支持桌面端和移动端分别检测
缓存策略
- 预加载: 启动时和每日更新后，全量拉取所有页面的图片列表
- 随机排序: 将获取的图片列表随机打乱，确保随机性
- 本地缓存: 按顺序下载并缓存图片到本地存储
- 智能清理: 达到缓存大小限制时，自动清理最早访问的图片
- 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
- 批量并发下载图片，提高预加载效率
- 智能缓存清理策略，避免磁盘空间不足
- 内存使用监控和垃圾回收机制
注意事项
- 首次启动需要较长时间进行预加载，请耐心等待
- 确保有足够的磁盘空间用于图片缓存
- someacg CDN 对单 IP 有并发限制，预加载过程中可能遇到 429 错误
- 建议在服务器环境中运行，以获得更好的网络稳定性
许可证
MIT License