[开源] PicHost - 部署在 Cloudflare 上的个人轻量图床

上传与管理#

• 拖拽 / 点击 / Ctrl+V 粘贴，单次最多 10 张
• 支持 JPEG / PNG / WebP / GIF（不接受 SVG，避免 XSS 面）
• 单张上限 10 MB
• 存储 key：images/YYYY/MM/<12位随机>.ext
• 列表 R2 cursor 分页（默认 30，最大 100）
• 按文件名或路径 搜索（对个人图床够用；本质是扫桶）
• 单张 / 批量删除（批量建议 POST /api/images/batch-delete，比 DELETE body 更稳）

浏览器端 WebP 压缩（可选）#

后台开关「上传前压缩为 WebP」默认开启：

• 仅处理 JPEG / PNG（GIF / WebP 原样上传）
• 最大宽度 2560px，质量 0.85
• 用 Canvas toBlob('image/webp') 转码后再走上传 API

这样大图进 R2 前体积会小一截，R2 出站流量和 Worker 回源次数都能降下来。

复制格式#

每张图可一键复制：

• 直链：https://img.example.com/images/2026/08/xxxxx.webp
• Markdown：![](url)
• HTML：<img src="url" alt="...">

鉴权与人机验证#

• 管理后台：ADMIN_SECRET 密钥登录（非用户名密码）
• 脚本上传：独立 API_UPLOAD_TOKEN（可与管理密钥分开轮换）
• Turnstile（可选）：仅在 登录 时校验，上传/列表不再重复验证

1. 管理后台登录#

1
GET /api/auth/config     → 是否启用 Turnstile、Secret 是否已配置
2
POST /api/auth/login     → 校验 Turnstile（若启用）+ ADMIN_SECRET
3
                         → Set-Cookie: pic_auth（httpOnly, 7天, Secure, SameSite=Lax）
4
GET /api/auth/me         → 校验 Cookie，未登录 401

Session 不是随机 session id，而是对固定盐值 pic-session 做 HMAC-SHA256(ADMIN_SECRET)，再用 timing-safe equal 比对 Cookie，避免时序攻击。未登录请求在鉴权层直接拒绝，不会触达 R2。

本地开发可设 DEV_BYPASS_ACCESS=true 跳过 Cookie 检查。

2. 上传（网页或脚本）#

1
客户端（可选 WebP 压缩）
2
    ↓ multipart
3
POST /api/images/upload
4
    ├─ Cookie 鉴权（管理员）
5
    └─ 或 Authorization: Bearer <API_UPLOAD_TOKEN>
6
    ↓
7
服务端 processSingleImageUpload：
8
    1. 大小 ≤ 10MB
9
    2. 读文件头魔数 → 识别真实 MIME（不信浏览器传的 type）
10
    3. 白名单 MIME + 签名校验
11
    4. generateImageKey → images/YYYY/MM/random.ext
12
    5. bucket.put + 返回 url / markdown / html

为什么一定要魔数校验？ 改扩展名把 .php 伪装成 .jpg 上传，在只靠 Content-Type 的图床里很常见。PicHost 用 file-signature.ts 读前几字节，MIME 与内容对不上直接拒。

3. 图片访问（Worker）#

1
GET/HEAD https://img.example.com/images/2026/08/xxxxx.webp
2
    ↓
3
解析 pathname → 校验 key（必须以 images/ 开头、禁止 .. 和 //）
4
    ↓
5
Referer 白名单（无 Referer → 放行）
6
    ↓
7
Cache API 查缓存（GET 且无 Range 时）
8
    ↓
9
R2 head/get → 支持 Range、ETag、304
10
    ↓
11
Cache-Control: public, max-age=86400, s-maxage=604800, stale-while-revalidate=86400

4. 删图与缓存 purge#

删除 R2 对象后，Pages 侧会 best-effort 调 Worker：

1
POST https://img.example.com/__internal/purge
2
Authorization: Bearer <INTERNAL_PURGE_TOKEN>
3
Body: { "keys": ["images/2026/08/xxxxx.webp"] }

INTERNAL_PURGE_TOKEN 在 pic-host 与 image-proxy 必须相同。purge 失败不会阻止删 R2，只是边缘缓存可能短暂残留旧图。

鉴权#

图片（管理端 Cookie）#

Twikoo / EasyImage 兼容#

这条链路是后来「改吧改吧」加上去的，专门给评论发图用——和网页后台登录是两套鉴权：

上传成功返回示例：

1
{
2
  "code": 200,
3
  "result": "success",
4
  "url": "https://img.example.com/images/2026/08/AbCdEfGhIjKl.webp",
5
  "markdown": "![](https://img.example.com/images/2026/08/AbCdEfGhIjKl.webp)",
6
  "html": "<img src=\"https://img.example.com/images/2026/08/AbCdEfGhIjKl.webp\" alt=\"\">"
7
}

Twikoo 后台：图床模式选 EasyImage 类接口，地址填 https://pic.example.com/api/index.php，Token 填 API_UPLOAD_TOKEN（不是管理密钥）。评论里展示的图片走 img 域，记得把博客域名写进 Worker 的 ALLOWED_REFERER_HOSTS，否则读者看图会 403。

1. 创建 R2 桶#

1
npx wrangler login
2
npx wrangler r2 bucket create personal-images

Dashboard → R2 → personal-images：

• 关闭 r2.dev 公共访问
• 不要绑定公开自定义域名

2. 部署 Pages（pic-host）#

1
npm install
2
cd workers/image-proxy && npm install && cd ../..
3
npm run build
4
npx wrangler pages deploy dist --project-name pic-host --branch=main

首次在 Dashboard → pic-host → 绑定：

• R2：personal-images，binding 名 IMAGES
• 自定义域：pic.example.com

Production 环境变量（Preview 不算，自定义域走 Production）：

自检：

1
curl https://pic.example.com/api/auth/config

应看到 "adminSecretConfigured": true、"apiUploadTokenConfigured": true。

Secret 写入命令示例：

1
npx wrangler pages secret put ADMIN_SECRET --project-name pic-host
2
npx wrangler pages secret put API_UPLOAD_TOKEN --project-name pic-host
3
npx wrangler pages secret put INTERNAL_PURGE_TOKEN --project-name pic-host

3. 部署图片 Worker（image-proxy）#

1
cd workers/image-proxy
2
npx wrangler secret put INTERNAL_PURGE_TOKEN
3
npx wrangler deploy

Dashboard → image-proxy → 域和路由 → 添加 img.example.com（custom_domain: true，pattern 写整域，不要 img.example.com/*）。

4. GitHub Actions 自动部署#

推送 main 或手动触发 Deploy to Cloudflare：

1. npm run lint + typecheck
2. nuxt build → 部署 pic-host
3. 部署 image-proxy Worker

GitHub Secrets：

根目录 wrangler.jsonc 不要写 account_id（Wrangler 4 Pages 会报错）。首次 CI 可能自动创建 pic-host 项目，R2 绑定和环境变量仍需在 Dashboard 手工补一次。

现象#

博客插图正常，重新 deploy Worker 或跑完 GitHub Actions 后，站内图片全部 403，控制台：Forbidden: hotlink protection。

原因#

wrangler deploy 会用 wrangler.jsonc 同步 Worker 配置。若文件里写了：

1
"vars": {
2
  "ALLOWED_REFERER_HOSTS": "example.com"
3
}

每次部署都会用文件覆盖 Dashboard 变量。你在控制台后来加的 muxui.com、www.muxui.com 会在下一次 CI 后全部丢失。

正确做法#

1. workers/image-proxy/wrangler.jsonc 不要写 vars 块（仓库已刻意留空）。
2. 只在 Dashboard 配置：

1
ALLOWED_REFERER_HOSTS=muxui.com,www.muxui.com,pic.example.com
2
PUBLIC_IMAGE_ORIGIN=https://img.example.com

3. INTERNAL_PURGE_TOKEN 用 wrangler secret put，deploy 不会清空 Secret。
4. Dashboard 改变量通常无需重新部署；但若 vars 写进了仓库，下次 deploy 仍会覆盖——从 wrangler.jsonc 删掉 vars 才是根治。

Referer 规则（实现细节）#

Worker 里 parseAllowedHosts 会：

• 把逗号分隔的 hostname 转小写放进 Set
• 自动加入 PUBLIC_IMAGE_ORIGIN 的 hostname（图片域本身永远在白名单）

www.example.com 与 example.com 要分别添加。子域绕过（evil.example.com）靠精确匹配挡住，但 blog.example.com 若也要用图，得单独加。

建议在 Dashboard 额外做的#

A. 预算警报：Billing → 设 1～5 美元 预算邮件。

B. WAF Rate Limiting（有套餐的话）：

免费版能力有限，至少开 Bot Fight Mode + 预算警报。