# api

**Repository Path**: liufuyouzi/api

## Basic Information

- **Project Name**: api
- **Description**: 图床
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-10-26
- **Last Updated**: 2026-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 随机图片 API

一个部署在 **EdgeOne Pages**（兼容 Cloudflare Pages）的随机图片接口，按横屏/竖屏 × 深色/浅色 四分类随机出图。

- 在线接口：`https://api.584528.xyz`
- 部署形态：EdgeOne Pages 一体化单项目（边缘函数 + 静态图片同仓库）
- 图片格式：`.webp`，连续编号存储于 `ri/` 目录

## 功能特性

- 横屏/竖屏（h / v）与深色/浅色（d / l）四分类随机
- 根据 UA 自动判断横竖屏，也可用参数强制指定
- 支持 JSON 返回与 302 跳转两种模式
- CORS 跨域支持
- 可配置防盗链域名白名单
- `count.json` 容错：加载失败时保留旧数据继续服务，不整段 404
- 提供自动统计脚本，构建时自动生成 `count.json`

## 目录结构

```
liufuyouzi/api
├── functions/
│   └── pic.js              # 边缘函数（随机逻辑 + 跳转/JSON）
├── ri/                     # 图片静态目录
│   ├── hd/                 # 横屏深色  001.webp ~ max.webp
│   ├── hl/                 # 横屏浅色
│   ├── vd/                 # 竖屏深色
│   ├── vl/                 # 竖屏浅色
│   └── count.json          # 各目录编号统计（max + exclude）
├── scripts/
│   └── gen-count.js        # 自动扫描目录生成 count.json
├── index.html
└── README.md
```

## 分类说明

| 目录 | 含义 |
|---|---|
| `hd` | 横屏 深色 |
| `hl` | 横屏 浅色 |
| `vd` | 竖屏 深色 |
| `vl` | 竖屏 浅色 |

## API 用法

### 1. 随机跳转（默认）

`GET /pic`

根据请求 UA 自动判断横竖屏，返回 `302` 跳转到随机图片：

```bash
curl -L https://api.584528.xyz/pic
# -> 302 Location: /ri/hd/127.webp
```

### 2. 指定横屏/竖屏

`GET /pic?img=h`（横屏） / `GET /pic?img=v`（竖屏）

```bash
curl -L "https://api.584528.xyz/pic?img=h"
```

### 3. JSON 返回

`GET /pic?json=h` / `GET /pic?json=v`

```bash
curl "https://api.584528.xyz/pic?json=h"
```

响应示例：

```json
{
  "theme": "dark",
  "url": "https://api.584528.xyz/ri/hd/129.webp"
}
```

- `theme`：`dark` / `light`
- 旧数据兜底时额外带 `"degraded": true`（见下方「容错」）

### 4. 调试模式

`GET /pic?debug=1`

返回本次选择的详细信息（文件夹、编号、防盗链判定、CORS 等），不跳转，便于排查：

```json
{
  "redirect": "/ri/hd/58.webp",
  "theme": "dark",
  "folder": "hd",
  "file": 58,
  "debug": { "leechCheck": {}, "corsOrigin": "*", "orientation": "h" }
}
```

## count.json 说明

`ri/count.json` 记录每个目录的最大编号与缺失编号：

```json
{
  "hd": { "max": 225, "exclude": [] },
  "hl": { "max": 0,   "exclude": [] },
  "vd": { "max": 100, "exclude": [] },
  "vl": { "max": 999, "exclude": [] }
}
```

- `max`：目录中最大的图片编号
- `exclude`：`1 ~ max` 之间缺失的编号，随机时会跳过，避免 404
- **图片必须连续编号**（如 `001.webp`、`002.webp`…），随机编号才准确

### 自动生成 count.json

手动维护易出错，提供了自动脚本：

```bash
node scripts/gen-count.js
```

脚本扫描 `ri/` 下四个目录，自动计算 `max` 和 `exclude`，原地更新 `count.json`，**不改文件名、不新增目录**。

**推荐：构建时自动执行** —— 在 EdgeOne Pages「项目设置 → 构建部署配置」将编译命令填为：

```
node scripts/gen-count.js
```

之后每次 push 部署，`count.json` 都会按实际图片自动重算。

## 环境变量

| 变量 | 说明 | 默认 |
|---|---|---|
| `ALLOWED_DOMAINS` | 防盗链白名单，逗号分隔多个域名；留空 = 公开（所有来源放行） | 空（公开） |
| `ALLOW_EMPTY_REQUEST` | 是否允许空 `Referer`/`Origin` 的请求（`true`/`1`） | `true` |

例：

```
ALLOWED_DOMAINS=example.com,sub.example.org
ALLOW_EMPTY_REQUEST=true
```

## 容错与降级

`pic.js` 读取 `count.json` 时做了容错：

- **404**（文件真不存在）→ 用空数据，30 秒错误缓存
- **网络错误 / 5xx**：
  - 已有旧数据 → **继续用旧数据出图**，10 秒后重试，不整段 404
  - 首次加载失败 → 用空数据，30 秒错误缓存
- 旧数据兜底时，JSON 响应会带 `"degraded": true`，便于判断是否在带病运行

## 部署

1. 代码推送到 Gitee 仓库 `liufuyouzi/api`（main 分支）
2. EdgeOne Pages 关联该仓库，自动部署
3. 如需 `count.json` 全自动，按上文配置编译命令 `node scripts/gen-count.js`

## 已知限制

- **EdgeOne Pages 有 3000 个文件数量上限**。当前 `ri/` 已有约 1324 张图片，继续增加会逼近上限。突破方案：将图片迁移到外部图床（如 K-Vault）或阿里云 OSS，`pic.js` 改为从外部图片列表随机跳转。