CattoPic

如果你需要一个轻量、高效、可完全掌控的图片托管方案，是一个基于 Cloudflare 全家桶构建的开源图片托管服务，支持自动格式转换、标签管理、过期清理，以及一个功能丰富的随机图片 API，适合个人项目、内容聚合、爬虫配图、博客素材库等场景。

所有组件均运行在 Cloudflare 边缘网络上，无需自建服务器，成本极低，且具备良好的全球访问性能。

核心特性

• 多格式上传：支持 JPEG、PNG、GIF、WebP、AVIF 等主流图片格式。
• 自动格式转换：上传后自动生成 WebP 和 AVIF 版本，通过 Cloudflare Images 提供最优格式（基于浏览器支持自动协商）。
• 标签管理：为图片打标签，支持批量操作、重命名、删除，便于分类组织。
• 随机图片 API：提供公开接口 /api/random，支持按标签、方向、格式、排除条件等灵活筛选。
• 临时图片过期：可为图片设置过期时间，配合定时任务自动清理。
• 现代化 UI：基于 Next.js + Tailwind CSS 构建的管理界面，支持深色模式，操作直观。
• 完全自托管 & 开源：代码公开，无第三方依赖，所有数据存储于你的 Cloudflare 账户。

技术架构

CattoPic 充分利用了 Cloudflare 提供的边缘计算与存储服务，形成一套高内聚、低耦合的架构：

快速部署指南

前置条件

• Node.js ≥ 18
• pnpm 包管理器
• Cloudflare 账户（免费 tier 支持大部分功能）
• Vercel 或其他静态站点托管服务（用于前端）

步骤概览

1. 克隆项目并安装依赖

   git clone https://github.com/yourusername/cattopic.git
   cd cattopic
   pnpm install
   cd worker && pnpm install
   

2. 创建 Cloudflare 资源

   pnpm wrangler login
   pnpm wrangler r2 bucket create cattopic-r2
   pnpm wrangler d1 create CattoPic-D1
   pnpm wrangler kv namespace create CACHE_KV
   pnpm wrangler queues create cattopic-delete-queue
   pnpm wrangler d1 execute CattoPic-D1 --remote --file=schema.sql
   

3. 配置 wrangler.toml
   复制 wrangler.example.toml 并填入各资源 ID（R2、D1、KV、Queue）。
4. 部署 Worker
   • 手动：pnpm wrangler deploy
   • 自动（推荐）：通过 GitHub Actions 配置 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID，实现 CI/CD。
5. 添加 API 密钥

   INSERT INTO api_keys (key, created_at) VALUES ('your-secure-api-key', datetime('now'));
   

6. 部署前端
   在 Vercel 设置环境变量：
   • NEXT_PUBLIC_API_URL: 你的 Worker 地址（如 https://cattopic.yourname.workers.dev）
   • NEXT_PUBLIC_REMOTE_PATTERNS: 允许加载的域名（含 R2 和 Worker）

API 使用示例

公开接口：随机图片

# 获取横向自然风景图
curl "https://your-api.com/api/random?orientation=landscape&tags=nature,forest"

# 获取排除“私有”标签的 WebP 格式猫咪图
curl "https://your-api.com/api/random?tags=cat&exclude=private&format=webp"

支持参数：

• orientation: landscape / portrait / auto
• tags: 逗号分隔，必须全部匹配
• exclude: 逗号分隔，排除任一匹配
• format: original / webp / avif

受保护接口（需 Bearer Token）

• 上传图片：POST /api/upload/single
• 管理标签：GET/POST/PUT/DELETE /api/tags
• 图片 CRUD：GET/PUT/DELETE /api/images/:id

所有写操作均需在请求头中携带：

Authorization: Bearer your-api-key

适用场景

• 个人素材库：上传截图、壁纸、设计资源，打标签分类，通过 API 随机调用。
• 博客/网站配图：集成 /api/random?tags=header 实现动态封面。
• 开发者工具：为测试、演示提供可编程的图片源。
• 内容聚合项目：结合爬虫自动入库，用标签组织海量图片。

安全与隐私

CattoPic 完全运行在你的 Cloudflare 账户下：

• 所有图片存储于你的 R2，元数据在 D1；
• 无外部服务器、无第三方 API 调用；
• 前端与 API 分离，支持自定义域名与访问控制；
• 默认仅公开 /api/random，其余接口需 API Key 验证。