shumengya
f45a0068a2
- 重写 README.md，添加在线体验、API 文档、部署指南、技术栈等 - 添加 MIT LICENSE - 添加 CONTRIBUTING.md 贡献指南 - 添加 GitHub Issue/PR 模板 - 完善 .gitignore，防止原始图片和敏感文件误提交 - 从 git 中移除 25 个原始图片文件（.png/.jpg/非序号 webp） - 项目结构迁移：functions/ -> src/，根目录静态文件 -> public/ - 添加 wrangler.toml 与 package.json 配置
237 lines
7.1 KiB
Markdown
237 lines
7.1 KiB
Markdown
# RandBG API - 随机背景图片服务
|
||
|
||
[](https://workers.cloudflare.com/)
|
||
[](LICENSE)
|
||
[](https://randbg.smyhub.com)
|
||
|
||
> 一个基于 **Cloudflare Workers** 部署的轻量级随机背景图片 API，支持自动识别设备类型（移动端/桌面端），并提供优雅的 Web 演示界面。
|
||
|
||
---
|
||
|
||
## 在线体验
|
||
|
||
- **在线演示**: [https://randbg.smyhub.com](https://randbg.smyhub.com)
|
||
- **GitHub 仓库**: [https://github.com/shumengya/randbg-api](https://github.com/shumengya/randbg-api)
|
||
|
||
---
|
||
|
||
## 特性
|
||
|
||
- **自动设备识别**：根据 User-Agent 和 Client Hints 自动判断移动端/桌面端
|
||
- **双重响应格式**：支持 `302 Redirect` 直接跳转图片，或 `JSON` 返回图片元数据
|
||
- **静态资源优化**：使用 WebP 格式，配合 Cloudflare 静态资源缓存，加载极速
|
||
- **智能构建流程**：`build.py` 自动将原图转换为编号 WebP 并生成 `manifest.json`
|
||
- **一体化部署**：Worker 负责 API 逻辑，静态页面与图片通过 Assets 提供，单次部署即发布前后端
|
||
- **零成本部署**：基于 Cloudflare Workers Free Tier，完全免费
|
||
|
||
---
|
||
|
||
## API 文档
|
||
|
||
### `GET /api/random`
|
||
|
||
随机返回一张背景图片。
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `mode` | string | `auto` | 强制指定类型：`auto` / `mobile` / `desktop` |
|
||
| `orientation` | string | `auto` | 屏幕方向：`portrait` / `landscape` |
|
||
| `device` | string | `auto` | 设备类型：`mobile` / `desktop` |
|
||
| `format` | string | `redirect` | 响应格式：`redirect`（302 跳转）/ `json` |
|
||
|
||
**示例请求：**
|
||
|
||
```bash
|
||
# 默认 302 跳转到随机图片
|
||
curl https://randbg.smyhub.com/api/random
|
||
|
||
# 返回 JSON
|
||
curl https://randbg.smyhub.com/api/random?format=json
|
||
# 响应：
|
||
# {
|
||
# "variant": "desktop",
|
||
# "folder": "desketop-image",
|
||
# "filename": "7.webp",
|
||
# "url": "https://randbg.smyhub.com/desketop-image/7.webp",
|
||
# "count": 19
|
||
# }
|
||
|
||
# 强制使用移动端图片
|
||
curl https://randbg.smyhub.com/api/random?mode=mobile
|
||
|
||
# 强制桌面端并返回 JSON
|
||
curl https://randbg.smyhub.com/api/random?mode=desktop&format=json
|
||
```
|
||
|
||
### `GET /api/list`
|
||
|
||
返回各变体的图片清单与统计信息。
|
||
|
||
```bash
|
||
curl https://randbg.smyhub.com/api/list
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"generated_at": "2026-05-18T11:45:45.514521+00:00",
|
||
"variants": {
|
||
"mobile": {
|
||
"folder": "mobile-image",
|
||
"count": 6,
|
||
"images": ["1.webp", "2.webp", "3.webp", "4.webp", "5.webp", "6.webp"]
|
||
},
|
||
"desktop": {
|
||
"folder": "desketop-image",
|
||
"count": 19,
|
||
"images": ["1.webp", "2.webp", ...]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### `GET /manifest.json`
|
||
|
||
静态清单文件，由 `build.py` 自动生成，记录各变体的目录与文件名列表。
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| Runtime | [Cloudflare Workers](https://workers.cloudflare.com/) |
|
||
| 静态托管 | Cloudflare Workers Static Assets |
|
||
| 构建脚本 | Python 3 + [Pillow](https://pillow.readthedocs.io/) |
|
||
| 前端 | Vanilla HTML / CSS / JS |
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
randbg-api/
|
||
├── src/
|
||
│ ├── worker.js # Workers 入口路由
|
||
│ ├── api/
|
||
│ │ ├── random.js # /api/random 接口逻辑
|
||
│ │ └── list.js # /api/list 接口逻辑
|
||
│ └── lib/
|
||
│ └── background.js # 通用工具（清单加载、设备识别、URL 构建）
|
||
├── public/
|
||
│ ├── index.html # 演示与文档页面
|
||
│ ├── manifest.json # 图片清单（build.py 生成）
|
||
│ ├── _headers # 静态资源 HTTP 响应头
|
||
│ ├── mobile-image/ # 移动端 WebP 图片（构建产物）
|
||
│ └── desketop-image/ # 桌面端 WebP 图片（构建产物）
|
||
├── mobile-image/ # 原始图片（本地工作目录，不提交到 Git）
|
||
├── desketop-image/ # 原始图片（本地工作目录，不提交到 Git）
|
||
├── build.py # 构建脚本：原图 → WebP + manifest.json
|
||
├── wrangler.toml # Workers 部署配置
|
||
├── package.json # 依赖与脚本
|
||
└── README.md # 本文档
|
||
```
|
||
|
||
> **注意**：根目录下的 `mobile-image/` 和 `desketop-image/` 仅用于本地存放原始素材，不应提交到 GitHub。`build.py` 会将转换后的编号 WebP 输出到 `public/` 目录，只有 `public/` 下的内容会被部署。
|
||
|
||
---
|
||
|
||
## 部署指南
|
||
|
||
### 前置条件
|
||
|
||
- [Cloudflare 账号](https://dash.cloudflare.com/)
|
||
- [Node.js](https://nodejs.org/) 18+
|
||
- [Python 3](https://python.org/) 3.9+
|
||
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/)
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone https://github.com/shumengya/randbg-api.git
|
||
cd randbg-api
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 3. 准备图片
|
||
|
||
将原始图片放入对应目录：
|
||
|
||
```
|
||
mobile-image/ # 竖屏图片（移动端）
|
||
desketop-image/ # 横屏图片（桌面端）
|
||
```
|
||
|
||
支持格式：`.jpg` `.jpeg` `.png` `.bmp` `.gif` `.tif` `.tiff` `.webp`
|
||
|
||
### 4. 构建 WebP 与清单
|
||
|
||
```bash
|
||
python3 build.py
|
||
```
|
||
|
||
脚本会自动完成以下工作：
|
||
1. 将原图转换为高质量编号 WebP（`1.webp` `2.webp` ...）
|
||
2. 生成 `public/manifest.json`
|
||
3. 将转换后的文件输出到 `public/` 部署目录
|
||
|
||
如果 `public/` 下已有序号 WebP 且没有原图，脚本会**保留现有文件**，不会误删。
|
||
|
||
### 5. 本地预览
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
默认在 `http://localhost:8787` 启动预览。
|
||
|
||
### 6. 部署到 Cloudflare
|
||
|
||
```bash
|
||
npm run deploy
|
||
```
|
||
|
||
Wrangler 会将 `src/worker.js` 打包为 Worker，同时将 `public/` 作为静态 Assets 一起发布。
|
||
|
||
---
|
||
|
||
## 目录约定
|
||
|
||
- **`public/mobile-image/`**：竖屏图片（移动端）
|
||
- **`public/desketop-image/`**：横屏图片（桌面端）
|
||
- 注意拼写沿用历史目录名，API 内部已兼容
|
||
- **`public/manifest.json`**：构建产物，API 运行时通过内部请求读取该清单
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **原图不上传**：根目录下的 `mobile-image/` 和 `desketop-image/` 仅用于本地构建，已配置 `.gitignore` 避免误提交。GitHub 仓库中只保留构建后的 `public/` 资源。
|
||
2. **图片版权**：请确保上传的图片拥有合法使用权或来自版权友好的来源。
|
||
3. **Worker 体积限制**：静态资源通过 Cloudflare Assets 提供，不占用 Worker 脚本 4 MiB 限制，可放心使用大量图片。
|
||
4. **缓存策略**：`public/_headers` 已为图片配置了 `immutable` 长期缓存，为 `manifest.json` 配置了 5 分钟缓存。如需更新图片，请重新运行 `build.py` 并部署。
|
||
|
||
---
|
||
|
||
## 开源协议
|
||
|
||
本项目基于 [MIT License](LICENSE) 开源。
|
||
|
||
---
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！如果你有任何建议或发现问题，请随时反馈。
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
Made with ❤️ by <a href="https://github.com/shumengya">shumengya</a>
|
||
</p>
|