PicFlow

基于 Cloudflare Workers + D1 的图片代理、随机壁纸 API、管理与分享平台。

功能

• 图片代理 /proxy — 代理任意图片 URL，支持 Wallhaven cookie 透传，Origin/Referer/Host 来源检查
• 随机壁纸 API /random — 按分类(category)、纯净度(purity)、比例组(ratio_group)、图册(album)、标签(tag) 筛选，支持 JSON 返回或 302 跳转，自动识别 PC/移动端
• 公开图库 / — 展示所有公开图册，显示封面、图片数、调用次数
• 图册详情页 /album/:key — 图片网格 + 滤镜（分类/比例/纯度）+ 灯箱预览（缩放/旋转/拖拽）+ API 调用示例弹窗
• 图册管理 — 创建/编辑（名称、别名、描述、公开/私有切换），删除（支持 Shift 连图片一起删），别名用于 URL 调用
• 图片管理 — 编辑元数据（分类、宽高、纯度）、关联图册、批量删除、批量绑定图册
• 元数据自动补全 — Wallhaven 图片自动获取宽高、标签、Purity；批量扫描补全缺失元数据
• 自动分类 — 根据宽高比自动归类: square / standard / ultrawide / superwide / portrait / tall
• Wallhaven 收藏同步 — 列出收藏集，逐页批量同步到本地图册
• 图册封面自动识别 — 从图册中取首张图片作为封面
• 调用计数 — 每个图册记录公开访问次数，主页显示总调用量
• 内嵌管理后台 — Worker 内置完整管理页面（5 个标签页），无额外部署
• Cookie 鉴权 — admin_token HttpOnly Secure Cookie 认证，支持 ?secret= URL 参数回退
• 设置管理 — 通过管理页面修改 admin_secret、Wallhaven API Key/Cookie、允许域名白名单等，保存到 D1
• URL 哈希持久化 — 管理页面标签页、筛选条件、页码通过 URL hash 持久化，刷新和浏览器前进后退保持状态

部署

前置条件

• Node.js >= 18
• Wrangler CLI

npm install -g wrangler
wrangler login

创建 D1 数据库

wrangler d1 create picflow-db

记录输出的 database_id。

部署 Worker

# 首次部署
npx wrangler deploy image-proxy-worker.js \
  --name picflow \
  --compatibility-date 2025-04-01 \
  --d1 DB=picflow-db \
  --secret ADMIN_SECRET=yoursecret \
  --secret WALLHAVEN_API_KEY=your_api_key \
  --secret WALLHAVEN_USERNAME=your_username

环境变量

变量	必须	说明
ADMIN_SECRET	首次必须	管理后台登录密码（部署后可进入管理页面修改）
WALLHAVEN_API_KEY	推荐	Wallhaven API Key，用于自动获取图片元数据
WALLHAVEN_USERNAME	推荐	Wallhaven 用户名，用于同步收藏
ALLOWED_HOSTS	可选	允许代理的域名白名单（逗号分隔）
ALLOWED_ORIGINS	可选	CORS 允许的 Origin（逗号分隔，支持 * 通配符匹配多级子域）
DISABLE_ORIGIN_CHECK	可选	true 时关闭代理来源检查

部署后可通过管理后台「⚙️ 设置」TAB 修改所有配置项，保存在 D1 settings 表中，优先级高于环境变量。首次部署必须通过 --secret 设置 ADMIN_SECRET 才能登录管理页面。

管理后台

访问 https://your-worker.example.com/admin 进入管理后台。

TAB 说明

TAB	功能
📥 批量添加	每行一个 URL 批量添加图片，支持 Wallhaven 自动获取元数据；可选关联图册
📚 图册	查看/编辑（名称、别名、描述、公开/私有切换）、删除（Shift+删除同时删图片）、扫描补元、查看调用示例 URL
🖼 浏览	按图册/分类/比例组筛选，勾选"缺元"或"无图册"过滤，多选 + 全选 + 批量删除 + 批量绑定图册
🔄 Wallhaven	列出收藏集，逐页同步到本地图册
⚙️ 设置	管理后台密钥、Wallhaven API Key/用户名/Cookie、允许域名白名单、禁用来源检查

浏览 Tab 功能

• 网格展示图片缩略图，hover 显示编辑/删除/刷新元数据按钮
• 单个图片编辑模态框（分类、宽高、纯度、关联图册）
• 灯箱预览：全屏、缩放（+/-/滚轮）、旋转、拖拽，键盘快捷键（← → Esc + - R 0）
• 分页 + URL hash 持久化筛选状态

API 接口

公开接口

方法	路径	说明
GET	/	公开图库页面（HTML）
GET	/album/:key	图册详情页面（HTML，支持 alias 或 ID）
GET	/health	健康检查，返回 {"status":"ok"}
GET	/proxy?url=xxx	代理图片（支持 Wallhaven cookie 透传）
GET	/random	随机壁纸
GET	/api/albums	公开图册列表（JSON）
GET	/api/albums/:key	图册详情（JSON，含图片列表、调用次数）

/random 参数

参数	说明	可选值
category	分类	pc, mobile
purity	纯净度	sfw, sketchy, nsfw
ratio_group	比例组	square, standard, ultrawide, superwide, portrait, tall
album	图册（alias 或 ID）
tag	标签（逗号分隔，AND 查询）
redirect	1 时 302 跳转，否则返回 JSON
proxy	是否返回代理 URL	1 时 url 字段走 /proxy

管理接口（需要 admin_token Cookie 或 ?secret= 参数）

认证

方法	路径	说明
POST	/admin/login	登录，设置 admin_token Cookie
POST	/admin/logout	退出，清除 Cookie

图片管理

方法	路径	说明
GET	/admin/images	图片列表（支持 page, per_page, album_id, category, ratio_group, missing_meta, no_album, ids_only）
GET	/admin/images/:id	单张图片详情（含所属图册）
PATCH	/admin/images/:id	更新图片信息（category, width, height, purity, album_ids）
DELETE	/admin/images/:id	删除图片
POST	/admin/images/add	批量添加图片（Body 为换行分隔的 URL，支持 ?category= 和 ?album_id=）
POST	/admin/images/:id/refresh-meta	刷新单张图片的 Wallhaven 元数据
POST	/admin/images/fix-missing	全量扫描补全缺失元数据
GET	/admin/images/fix-missing/status	补元任务进度
POST	/admin/images/batch-delete	批量删除 { ids: [...] }
POST	/admin/images/batch-albums	批量绑定图册 { ids: [...], album_ids: [...] }

图册管理

方法	路径	说明
GET	/admin/albums	图册列表（含图片数）
POST	/admin/albums	创建图册（自动生成别名）
PUT	/admin/albums/:id	更新图册（name, alias, description, is_public）
DELETE	/admin/albums/:id	删除图册（支持 ?delete_images=1 同时删除图片）
POST	/admin/albums/:id/images	向图册添加图片 { image_ids: [...] }
DELETE	/admin/albums/:id/images/:imgId	从图册移除图片
POST	/admin/albums/:id/public	切换图册公开/私有
POST	/admin/albums/:id/scan-meta	扫描图册内图片补全元数据（支持 ?force=1 强制刷新）
GET	/admin/albums/:id/scan-meta/status	扫描任务进度

Wallhaven 同步

方法	路径	说明
POST	/admin/sync/favorites	列出收藏集
POST	/admin/sync/favorites?collection_id=&page=	同步指定收藏页到本地

设置

方法	路径	说明
GET	/admin/settings	获取当前设置（敏感值掩码）
POST	/admin/settings	保存设置

兼容

方法	路径	说明
GET	/admin/set-cookie?cookie=	更新 Wallhaven Cookie
GET	/admin/cookie-status	Cookie 状态查询

数据库

D1 表结构

表名	说明
images	图片元数据（URL、宽高、分类、纯度、比例组、Wallhaven ID、来源等）
albums	图册（名称、别名、描述、公开/私有、封面、调用次数）
album_images	图片-图册关联（复合主键，级联删除）
image_tags	图片标签
settings	系统设置（键值对，覆盖环境变量）

设置项

key	说明
admin_secret	管理后台密钥（空值时 fallback 到环境变量 ADMIN_SECRET）
wallhaven_api_key	Wallhaven API Key
wallhaven_username	Wallhaven 用户名
wallhaven_cookie	Wallhaven Cookie，用于访问 R18 图片
allowed_hosts	允许代理的域名白名单
allowed_origins	CORS 允许的 Origin
disable_origin_check	是否关闭代理来源检查

所有设置可在管理后台「⚙️ 设置」TAB 修改，保存后立即生效。修改 admin_secret 后需重新登录。

开发

# 本地开发
npx wrangler dev image-proxy-worker.js \
  --d1 DB=picflow-db \
  --test-scheduled \
  --env dev

# 部署
npx wrangler deploy image-proxy-worker.js \
  --name picflow \
  --compatibility-date 2025-04-01 \
  --d1 DB=picflow-db

许可证

MIT