# 小奏随机图片 API 系统

**Repository Path**: skychymeng/Xiaozou-Random-Image-API

## Basic Information

- **Project Name**: 小奏随机图片 API 系统
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-20
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ✨ Xiaozou Random Image API ✨

一个轻量级、高性能、安全优先的二次元随机图片 API 系统。

> 演示地址：[https://api.uelogin.cn](https://api.uelogin.cn)
> 安装文档：[https://docs.uelogin.cn](https://docs.uelogin.cn)

无论是搭建个人图床，还是提供公共图片服务，都能提供极致响应速度与企业级安全防护。

---

## 🎯 环境要求

| 项目 | 要求 | 说明 |
|:-----|:-----|:-----|
| **PHP 版本** | >= 7.4 | 推荐 PHP 8.0+ |
| **必要扩展** | PDO, cURL | 数据库连接与网络请求 |
| **图像处理** | GD 或 Imagick | 必须安装其中之一 |
| **Web 服务器** | Nginx (推荐) / Apache | Nginx 并发性能更优 |
| **数据库** | MySQL / SQLite | SQLite 无需安装服务，单文件即用 |

---

## 🌟 核心特性

- **👑 极致性能** — NO_SESSION 模式消除 Session 锁阻塞；内置文件索引缓存，百万级图片库秒级响应
- **🛡️ 安全设计** — SSRF 防御（内网 IP 探测）、SQL 注入防护（PDO 预处理）、目录保护（文件名哈希化）、CSRF Token 验证
- **⚙️ 管理后台** — 可视化管理系统设置、SEO 配置；支持从其他 API 自动采集图片并去重
- **🎨 模板系统** — 支持上传切换前端模板，ZIP 包自动解压，安全的变量提取机制
- **📱 PC/移动端分离** — 自适应 API 自动检测设备类型，PC / 移动端独立采集源和图片目录
- **🖼️ 格式转换** — WebP 自动转换，保证画质的同时大幅节省带宽
- **📊 访问日志** — 分页展示访问记录，支持 IP 地理位置显示
- **🔍 图片审核** — 集成 NSFWJS 审核服务，违规图片自动隔离

---

## 🚀 安装步骤

1. **下载源码** — 通过 Gitee 克隆或下载 ZIP，上传至服务器网站根目录
2. **设置权限** — 确保根目录及 `image/` 目录具有写入权限

   ```bash
   chmod -R 755 /www/wwwroot/your_site
   chown -R www:www /www/wwwroot/your_site
   ```

3. **运行安装向导** — 访问 `http://your-domain.com/install.php`，按照提示配置数据库
   
   > 💡 **新手推荐**：选择 **SQLite** 模式，无需配置数据库账号密码，即装即用

4. **配置 Nginx** — 为了启用伪静态和安全防御，请务必添加下方规则
5. **清理文件** — 安装完成后，手动删除 `install.php` 以确保安全

---

## 🔒 Nginx 伪静态与安全配置

将以下规则添加到 Nginx 配置文件的 `server` 块内：

```nginx
# --- 1. 伪静态规则 ---
location / {
    try_files $uri $uri/ $uri.php$is_args$args;
}

# --- 2. 安全防御 ---

# (A) 禁止下载敏感文件
location ~* \.(log|json|lock|sql|md|txt)$ {
    deny all;
    return 403;
}

# (B) 禁止访问敏感配置
location ~ /(db_config\.php|sys_config_cache\.php) {
    deny all;
    return 403;
}

# (C) 严禁在 image 目录执行 PHP (防 WebShell)
location ^~ /image/ {
    location ~* \.(jpg|jpeg|png|gif|webp|bmp|avif|heic)$ {
        expires 30d;
        error_log off;
        access_log off;
    }
    location ~ \.php$ {
        deny all;
    }
}
```

---

## 🤖 自动化任务 (Crontab)

建议添加计划任务以保持"自动采集"和"格式转换"功能的持续运行。

| 任务类型 | 建议频率 | API 地址 |
|:---------|:---------|:---------|
| **自动下载** | 每 10 分钟 | `/monitor_download.php?key=密钥&type=pc` 和 `type=mobile` |
| **自动转码** | 每 30 分钟 | `/monitor_convert.php?key=密钥` |

**Crontab 配置示例：**

```bash
# 每10分钟执行一次自动下载（PC端 + 移动端）
*/10 * * * * curl -s "http://your-domain.com/monitor_download.php?key=YOUR_SECRET_KEY&type=pc" > /dev/null
*/10 * * * * curl -s "http://your-domain.com/monitor_download.php?key=YOUR_SECRET_KEY&type=mobile" > /dev/null

# 每30分钟执行一次自动转码
*/30 * * * * curl -s "http://your-domain.com/monitor_convert.php?key=YOUR_SECRET_KEY" > /dev/null
```

---

## 📝 API 调用说明

### 基础调用

```
GET /api
```

响应：302 重定向到随机图片地址

### 设备专用接口

| 接口 | 说明 |
|:-----|:-----|
| `/api_pc.php` | PC 端专用，仅返回 PC 端图片 |
| `/api_mobile.php` | 移动端专用，仅返回移动端图片 |

### 前端 AJAX 调用

```javascript
// 支持 CORS，可直接跨域调用
fetch('https://api.uelogin.cn/api')
  .then(response => console.log(response.url));
```

### HTML 直接引用

```html
<img src="https://your-domain.com/api" alt="随机图片" />
```

---

## 📂 目录结构

```
Xiaozou-Random-Image-API/
├── api.php              # 自适应 API 入口
├── api_pc.php           # PC 端 API
├── api_mobile.php       # 移动端 API
├── config.php           # 核心配置（含迁移逻辑）
├── index.php            # 前端首页
├── install.php          # 安装向导（安装后删除）
├── admin/               # 后台管理
│   ├── index.php        # 仪表盘
│   ├── settings.php     # 网站设置
│   ├── collect.php      # 采集设置
│   ├── images.php       # 图片管理
│   ├── logs.php         # 访问日志
│   └── templates.php    # 模板管理
├── includes/
│   └── TemplateManager.php  # 模板引擎
├── templates/default/   # 默认前端模板
├── image/               # 图片存储
│   ├── pc/              # PC 端图片
│   └── mobile/          # 移动端图片
├── docs/                # 在线文档
└── moderation/          # 图片审核模块
```

---

## 🔄 升级指南

1. **备份现有系统**（重要！）
   - 备份数据库文件或导出 SQL
   - 备份 `image/` 目录
2. **上传新文件覆盖旧文件**
3. **访问后台** — 登录后自动完成数据库迁移
4. **检查设置** — 验证网站设置和采集配置是否正确

---

## 🌈 作者信息

| | |
|:-|:-|
| 👨‍💻 **开发者** | 小奏 (Xiaozou) |
| 📖 **博客** | [小奏笔记](https://blog.mofuc.cn/) |

---

## ❤️ 开源协议

欢迎使用、修改和传播这个项目！如果你觉得它对你有帮助，欢迎 Star ⭐

> ⚠️ **免责声明**：本项目仅供学习交流使用，请勿用于非法用途。