# 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