# RandomImageAPI

**Repository Path**: Dangks/random-image-api

## Basic Information

- **Project Name**: RandomImageAPI
- **Description**: 一个轻量级的 PHP 应用程序，旨在提供一个随机图片的API。该项目适用于需要动态展示随机图片的场景，如网站背景图片轮播等。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-10-07
- **Last Updated**: 2025-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: PHP, Linux

## README

# **Random-Image-API 随机图片接口**

## 项目说明
一个轻量级的 PHP 应用程序，旨在提供一个随机图片的API接口服务。用户可以通过 HTTP 请求访问 API 并返回随机图片。支持多种响应格式，包括 JSON 和 HTTP 重定向。该项目适用于需要动态展示随机图片的场景，如网站封面大图等。

**主要功能：**

1. **随机图片选择**：从指定目录中随机选择并展示图片
2. **缓存机制**：基于请求特征(IP+Referer+URI)的缓存系统，避免短时间请求过度刷新
3. **双模式输出**：
   - 直接输出图片模式：适用于`<img>`标签直接调用
   - JSON数据模式：返回图片URL，适用于前端AJAX调用
4. **CDN兼容**：支持CDN环境下的真实IP识别和缓存处理 (利用MD5生成请求ID，并不存储IP信息)

**主要特点：**
- 简单轻量：单文件设计，极简轻量化，易于部署
- 高效缓存：避免频繁文件IO，在缓存时间内输出不变
- 灵活配置：支持配置缓存时间和路径
- 安全可靠：路径处理安全，预防路径穿越
- 稳定可靠：可为自己的网站提供稳定的动图接口，从此不再依赖第三方接口

核心代码设计采用函数式编程思想，包含图片选择、缓存处理和响应输出三个主要模块，通过配置文件统一管理环境参数。


## 目录结构
```
random-image-api/
├── cache/                # 缓存目录
│   └── cache.json
├── config/              # 配置目录
│   └── config.php       # 配置文件
├── images/              # 图片目录
│   ├── example.jpg
│   └── ...
└── random.php          # 主程序文件
```

## 主要功能模块

### 1. 配置模块 (`config.php`)
```php


define('IMAGE_DIR', realpath(__DIR__ . '/../images')); // 图片目录路径
define('CACHE_FILE', realpath(__DIR__ . '/../cache/cache.json')); // 缓存文件路径
define('CACHE_TIME', 60); // 缓存时间(秒)
```

### 2. 图片处理模块
- 功能：随机选择图片
- 位置：`random.php` 中的 `getRandomImage()` 函数
- 说明：从图片目录中随机选择一张图片

### 3. 缓存处理模块
- 功能：缓存管理
- 位置：`random.php` 中的 `checkCache()` 和 `setCache()` 函数
- 说明：处理图片缓存的读取和写入


## API 使用说明

### 1. 直接获取图片
```bash
GET https://your-domain.com/random.php
```
- 返回：随机图片文件
- Content-Type: image/jpeg

### 2. 获取 JSON 格式数据
```bash
GET https://your-domain.com/random.php?type=json
```
- 返回：JSON 格式的图片路径
```json
{
    "image": "/images/example.jpg"
}
```

## 缓存机制
- 基于请求 ID 的缓存系统
- 缓存 ID 生成规则：MD5(客户端IP + Referer + 请求URI)
- 默认缓存时间：60秒

## 安装部署

### 1. 环境要求
- PHP 7.0+
- 文件读写权限

### 2. 安装步骤
```bash
# 创建项目目录
mkdir -p /var/www/random-image-api
cd /var/www/random-image-api

# 创建必要目录
mkdir -p cache images config

# 设置权限
chmod 766 -R cache/
chmod 755 config/config.php
```

### 3. 配置说明
1. 配置 `config.php`
2. 在 `images/` 目录中放置图片
3. 确保 `cache/` 目录可写

## 注意事项
1. 确保目录权限正确
2. 确保文件配置正确
3. 确保请求方式正确

## 更新日志
- [v1.0](https://gitee.com/Dangks/random-image-api/releases/tag/V1.0)
  - 初始版本发布
  - 支持随机图片输出
  - 支持缓存机制
  - 支持 JSON 格式返回
- [v1.1](https://gitee.com/Dangks/random-image-api/releases/tag/V1.1)
  - 替换images下的图片文件,更加丰富美观
  - 更新说明文档`README.md`
- [v2.0](https://gitee.com/Dangks/random-image-api/releases/tag/V2.0)
  - 从链接跳转模式改为本地图片输出
  - 增加了JSON格式支持
  - 优化了缓存记录格式
  - 增强了安全性检查
  - 功能模块化，代码结构更清晰


## License
[MIT](./LICENSE)