SomeACG-RANDOMPIC/README.md

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 自动更新页数范围
• 支持桌面端和移动端分别检测

缓存策略

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