CloudFlare-ImgBed 图床完整部署教程：Cloudflare Pages + R2 免费部署方案

基于真实部署流程整理 · 使用 Cloudflare Pages + R2 方案 · 每月成本 ¥0

教程概述

本教程将带你完成 CloudFlare-ImgBed 图床的完整部署流程。整体方案使用 MarSeventh 开源项目作为图床程序，使用 Cloudflare Pages 托管前端与函数逻辑，使用 Cloudflare R2 存放图片本体，并使用 Workers KV 存储图片元数据。

部署完成后，你将得到一个运行在 Cloudflare 全球边缘网络上的图床，具备以下能力：

图片上传与管理：通过网页后台上传、删除和查看图片
对象存储：图片本体存放在 Cloudflare R2
免费 CDN 与 HTTPS：借助 Cloudflare Pages 和自定义域名自动启用
接口扩展：支持 REST API、WebDAV，后续对接 LLM、Agent 或 MCP 更方便
低成本运行：个人使用通常可以长期保持在免费额度内

项目	说明
部署方案	CloudFlare-ImgBed + Cloudflare Pages + Cloudflare R2
预计耗时	30-45 分钟
月度成本	免费额度内为 ¥0
适用场景	个人博客图床、Markdown 图片托管、API 上传、WebDAV 管理

教程里出现的 gaoliming-imgbed、img.nanye.site 等均为示例，请在实际操作时替换为你自己的项目名和域名。

一、前置准备

1.1 你需要准备的东西

一个邮箱（注册 Cloudflare 和 GitHub）
一张可在境外服务付款的卡（Visa / Mastercard / PayPal，国内银联不行）
一个域名（可选但推荐）
一台能正常访问 Cloudflare 和 GitHub 的电脑

1.2 关于免费额度

整套方案的免费额度：

资源	免费额度
R2 存储	10 GB（约 5000-10000 张普通截图）
R2 写入 (Class A)	100 万次/月
R2 读取 (Class B)	1000 万次/月
R2 出站流量	无限免费（Cloudflare 杀手锏）
Pages Functions	10 万次请求/天
Workers KV	10 万次读/天 + 1000 次写/天 + 1GB 存储
自定义域名	不限数量

个人使用永远到不了限额。

二、Cloudflare 账号准备

2.1 注册账号（如果还没有）

浏览器打开 https://dash.cloudflare.com/sign-up
输入邮箱和密码，点 Sign Up
收件箱里点验证邮件

2.2 添加域名到 Cloudflare（如果你打算用自己的域名）

如果你想用自己的子域名（例如 img.yoursite.com）访问图床，要先把这个根域名托管到 Cloudflare：

登录 Cloudflare，主页点 添加站点 / Add a Site
输入你的根域名（例如 yoursite.com），点继续
选 Free 计划
Cloudflare 扫描你现有的 DNS 记录，确认无误后点继续
复制 Cloudflare 给你的两个 NS（名称服务器），格式类似 xxx.ns.cloudflare.com
去你的域名注册商那里（阿里云/腾讯云/Namesilo 等）修改域名的 NS 服务器为这两个
回 Cloudflare 等待全局生效（几分钟到 24 小时），状态变成 “活动” 即成功

如果不打算用自己的域名，跳过这一节，后面用 Cloudflare 免费提供的 *.pages.dev 域名即可。

2.3 绑定支付方式

R2 需要绑定支付方式才能开通（即使你只用免费额度）：

右上角点你的头像图标 → 账单 / Billing
左侧菜单 → 付款信息 / Payment Info
点 添加付款方式
输入信用卡信息，或选 PayPal
保存

⚠️ 绑卡 ≠ 扣钱。Cloudflare 只在你实际超出免费额度时才扣费。R2 10GB 内永久免费。

三、开通 R2 并创建存储桶

3.1 开通 R2 服务

Cloudflare 控制台左侧菜单 → 找 R2 对象存储（可能在”存储和数据库”分类下）
首次进入会看到 启用 R2 或 购买 R2 按钮 → 点击
同意服务条款 → 启用

启用成功后会自动进入 R2 控制台。

3.2 创建存储桶

R2 控制台点右上角 创建存储桶 / Create bucket
填写：
- 存储桶名称：全局唯一的英文名，推荐格式 yourname-imgbed（本教程示例：gaoliming-imgbed）
- 位置：展开”提供位置提示（可选）”，选 **亚太地区 (APAC)**（国内访问更快）
- 默认存储类：标准
点 创建存储桶

创建好后先不动它，后面在 Pages 项目里绑定。

四、Fork 项目到 GitHub

4.1 注册/登录 GitHub

如果还没账号，去 https://github.com 注册一个。

4.2 Fork 项目

浏览器打开 https://github.com/MarSeventh/CloudFlare-ImgBed
用你的 GitHub 账号登录
点页面右上角的 Fork 按钮
在弹出的页面里直接点 Create fork（保持所有默认设置）
Fork 完成后，你会自动跳到 你的用户名/CloudFlare-ImgBed 这个新仓库

记住这个仓库地址，下一步 Cloudflare Pages 要从这里拉代码。

五、创建 Cloudflare Pages 项目

5.1 进入 Pages 创建流程

Cloudflare 控制台左侧菜单 → 计算 → Workers 和 Pages
点 创建应用程序 或页面上的创建按钮
⚠️ 关键：进去后页面会默认显示创建 Worker 的选项（像 Connect GitHub、Hello World、Upload static files 等）。这不是 Pages。翻到页面最底部，找到一行小字：

想要部署 Pages?开始使用
点这行小字里的 开始使用 链接

5.2 连接 GitHub

进入 Pages 创建流程，顶部进度条显示 1 选择存储库 → 2 设置构建和部署 → 3 部署站点：

默认选中 GitHub 标签
点中间蓝色 连接 GitHub 按钮
跳到 GitHub 授权页面，按下表选择：
- 选 Only select repositories（只选择特定仓库）— 比 All 安全
- 在下方下拉框里勾选 CloudFlare-ImgBed
- 点 Install & Authorize（可能需要输入 GitHub 密码确认）
自动跳回 Cloudflare，在仓库列表里点 CloudFlare-ImgBed 旁边的 开始设置

5.3 配置构建参数（全程最关键的一步）

进入 2 设置构建和部署 页面，严格按下表填写：

配置项	填什么	备注
项目名称	`yourname-imgbed`（自定义）	全小写、英文、可带连字符
生产分支	`main`	默认就是
框架预设	无 / None	不要选 Vue/React 等
构建命令	`npm install`	⚠️ 必须填，不是默认的 `npm build`
构建输出目录	`frontend-dist`	输入框前面有固定的 `/`，你只在框里写 `frontend-dist`
根目录（高级）	不展开，留空
环境变量（高级）	不展开，留空	后台 UI 配置

⚠️ 最容易踩坑的两个字段（网上 90% 的老教程错的就是这两处）：

**构建命令必须是 npm install**（不是 npm run build，不是默认值）

构建输出目录必须是 frontend-dist

填完点页面右下角蓝色按钮 保存并部署。

5.4 等待首次部署

页面会自动跳到实时构建日志，你会看到这样的进度：

正在初始化构建环境
正在克隆 Git 存储库
正在构建应用程序（npm install 执行）
正在部署到 Cloudflare 全球网络

首次部署耗时约 2-5 分钟。完成后显示 **”成功!您的项目已部署到以下区域：全球”**，并给出一个 yourname-imgbed.pages.dev 形式的链接。

⚠️ 这次部署完成后先别访问这个链接。现在 KV 和 R2 还没绑定，访问会显示空白或者上传会报错。继续下一步。

六、创建并绑定 KV 数据库

KV（Workers KV）用来存图片的元数据（文件名、上传时间、所属存储渠道等）。

6.1 创建 KV 命名空间

Cloudflare 控制台左侧菜单 → 存储和数据库 → Workers KV
进入后点页面右上角的 + Create Instance（或 “创建实例”）
命名空间名称：输入 **img_url**（强烈建议就用这个名字）
点创建 / Create

创建后会回到 KV 列表，能看到 img_url 这条记录就 OK。

6.2 绑定 KV 到 Pages 项目

左侧菜单 → 计算 → Workers 和 Pages
点开你之前创建的 Pages 项目（例如 yourname-imgbed）
顶部切换到设置标签
左侧子菜单找绑定（在”变量和机密”下面）
找到”绑定”区域，点右侧 + 添加 按钮
在弹出菜单选 KV 命名空间
填：
- 变量名称：**img_url** ⚠️ 必须一字不差，大小写敏感，中间是下划线
- KV 命名空间：下拉选择你刚创建的 img_url
点保存

七、绑定 R2 存储桶到 Pages 项目

继续在同一个绑定页面操作：

再次点 + 添加 按钮
这次选 R2 存储桶
填：
- 变量名称：**img_r2** ⚠️ 必须一字不差，全小写，下划线
- R2 存储桶：下拉选你之前创建的桶（例如 yourname-imgbed）
点保存

完成后，绑定区域应该显示两条记录：

类型	名称	值
KV 命名空间	`img_url`	`img_url`
R2 存储桶	`img_r2`	`yourname-imgbed`

页面右下角会显示提示：此更改将在下次部署时生效。

八、重新部署使绑定生效

绑定不会自动应用到已部署的版本，必须手动触发一次重新部署：

项目顶部切到部署标签
找到最新的一次部署（就是你首次部署成功的那条）
点最右侧的 “…” 三点菜单
选 重试部署 / Retry deployment
等待约 1-3 分钟

部署日志中如果看到以下行，说明绑定都被正确识别：

✨ Compiled Worker successfully
✨ Upload complete!
🌎 Deploying...
Success: Your site was deployed!

九、初始化图床后台

9.1 首次访问后台

浏览器打开：

1	https://yourname-imgbed.pages.dev/dashboard

首次访问可能慢一些（冷启动，需要等几秒到十几秒），耐心等待。

会看到 管理端登录 界面。

9.2 设置管理员账密（优先级最高）

CloudFlare-ImgBed 首次部署默认空密码，任何人发现 /dashboard 都能进。这一步必须立刻做。

进入后台后，左侧菜单点 安全设置（盾牌图标）
找到 管理端认证 区域
填：
- 用户名：自定义（例如 admin）
- 密码：强密码（建议 12 位以上，包含大小写和数字）
- 确认密码：重复一遍
滚动到页面底部，点蓝色保存按钮
保存后会自动登出，用新账密重新登录

⚠️ 绝对不要跳过这一步。

9.3 启用 R2 上传渠道

重新登录后，左侧菜单点 上传设置
滚动到 CloudFlare R2 区域
应该已经自动出现一个名为 R2_env（标注”环境变量”）的渠道
确保它的开关是蓝色（启用）状态；如果是灰色，手动点一下打开
滚动到页面底部点保存

说明：因为你前面在 Pages 项目里绑定了 img_r2，系统会自动识别。无需填写任何 Access Key。

9.4 创建 API Token（为 LLM / MCP / CLI 调用预留）

左侧菜单回到 安全设置
找到 API Token 管理 区域
点右上角蓝色 + 按钮
弹出框里填：
- 名称：自定义（例如 llm-upload）
- 权限：勾选所有你需要的（建议都勾：上传、删除、列出、管理）
- 过期时间：永不过期 或自定义
创建后会生成 token 字符串，类似 imgbed_9927b91c...
立刻完整复制保存到密码管理器

⚠️ Token 只能完整看一次，以后只显示前缀。丢了只能删除重建。

十、测试上传

回到首页（注意是根目录不是 dashboard）：

1	https://yourname-imgbed.pages.dev

把任意图片拖到那个蓝色虚线框，或者点中间相机图标选文件
等 1-2 秒上传完成
成功的话，下方会出现：
- 文件名
- 4 种格式的链接（URL / Markdown / HTML / BBCode）
复制 URL 链接，在新标签页打开，能看到图就成功了 ✅
回 Cloudflare → R2 → 你的桶 → 应该看到刚上传的图片文件

到这里图床已经完全可用。如果不需要自定义域名，可以止步；想用自己的子域名，继续下一步。

十一、绑定自定义子域名

11.1 在 Pages 项目添加自定义域

Pages 项目顶部切到 自定义域 标签
点 设置自定义域 / Set up a custom domain
输入完整的子域名：img.yoursite.com（替换为你自己的）
点继续
看到 确认新 DNS 记录 页面后，点 激活域

11.2 处理 DNS 记录（分两种情况）

情况 A：根域名 DNS 表里没有 `*` 通配符记录

Cloudflare 自动给你加一条 img CNAME 指向 yourname-imgbed.pages.dev
状态自动变成 已激活
无需任何手动操作

情况 B：根域名有 `*.yoursite.com` 通配符记录（常见于 1Panel / 宝塔等场景）

Cloudflare 检测到通配符存在，不会自动加 CNAME，需要你手动确认：

左侧菜单 → 域名 → 点你的根域名（例如 yoursite.com）进域名管理页
左侧 DNS → 记录
在搜索框搜 img，看是否有一条名为 img、类型 CNAME、目标为 yourname-imgbed.pages.dev 的记录
- 如果已经有这条：确认 **代理状态是橙色”已代理”**（不是灰色”仅 DNS”）。如果是灰色，点一下让它变橙色。这一步必须做，否则 Pages 无法正常工作
- 如果没有：点右上角 + 添加记录，填：
  - 类型：CNAME
  - 名称：img（只填 img，系统自动补 .yoursite.com）
  - 目标：yourname-imgbed.pages.dev
  - 代理状态：🟠 已代理（打开橙色云朵）
  - TTL：自动
  - 点保存
回 Pages 项目 自定义域 页面，点蓝色 检查 DNS 记录 按钮

11.3 等待激活

DNS 验证 + SSL 证书签发通常需要 30 秒到几分钟。状态变化：

1	正在初始化 → 正在验证 → 已激活 ✅

11.4 添加放行域名（关键，容易遗漏）

新域名生效后，必须回图床后台告诉系统这是合法域名，否则可能被来源校验拦截：

用 admin 账户登录 https://yourname-imgbed.pages.dev/dashboard
系统设置 → 安全设置
滚动到底部，找 访问管理 → 放行域名

填入（英文逗号分隔）：

1	img.yoursite.com,yourname-imgbed.pages.dev

点最底部保存

十二、最终验证

完成所有步骤后，这三个地址都应该能正常访问：

https://yourname-imgbed.pages.dev — Cloudflare 默认域名
https://yourname-imgbed.pages.dev/dashboard — 管理后台
https://img.yoursite.com — 你的自定义子域名

最终测试：从 https://img.yoursite.com 上传一张图，获取链接后在新标签打开，能看到图就一切就绪 🎉

常见问题处理

Q1：访问 `pages.dev` 域名空白页

可能原因：

首次冷启动太慢 → 等 10 秒刷新
KV / R2 还没绑定或变量名错误 → 检查 Pages 设置 → 绑定，确保有 img_url 和 img_r2 两条
没重新部署 → 绑定完必须在部署页”重试部署”

Q2：部署日志显示构建失败

可能原因：构建命令或输出目录填错。
解决：Pages 项目 → 设置 → 构建配置 → 编辑，确保：

构建命令是 npm install（不是 npm build）
构建输出目录是 /frontend-dist

改完保存，然后回部署页重新部署。

Q3：自定义域一直显示”正在验证”，检查 DNS 记录也不通过

可能原因：

DNS 没正确加 CNAME → 去 DNS 记录页搜 img 确认存在
代理状态是灰色”仅 DNS”而不是橙色”已代理” → 点云朵图标切换
根域名有 * 通配符干扰 → 参考 11.2 情况 B 处理

Q4：从自定义域名上传成功但显示图片报错

可能原因：放行域名没加。
解决：后台 → 安全设置 → 访问管理 → 放行域名，加上新域名，保存。

Q5：上传报错”未配置上传渠道”

解决：后台 → 上传设置 → CloudFlare R2 → 确保 R2_env 渠道是启用状态（蓝色开关）→ 保存。

Q6：忘记管理员密码

解决：稍微麻烦但能做：

Cloudflare → Workers KV → img_url 命名空间 → 点进去看 KV 对
找到认证相关的 key（参考 https://cfbed.sanyue.de 文档说明）
删除该 key 即可让管理员密码重置为空，然后回 /dashboard 重新设置

维护与扩展

如何更新到最新版本

CloudFlare-ImgBed 更新频繁（几乎每月有 release）：

打开你 Fork 的仓库 https://github.com/你的用户名/CloudFlare-ImgBed
如果顶部显示 “This branch is X commits behind MarSeventh:main”
点 Sync fork → Update branch
Cloudflare Pages 监听到 GitHub push 自动重新部署（2-5 分钟内）
无需任何手动操作

备份建议

数据备份分两部分：

图片本体：已经在 R2 桶里，Cloudflare 自带高可用，几乎不会丢
元数据（KV）：后台 → 系统状态 → 系统维护 → 备份数据，会下载一份 JSON 文件，建议每月备份一次

恢复：同一页面的 恢复数据 按钮。

添加其他存储渠道

CloudFlare-ImgBed 支持多渠道并存（Telegram、Discord、S3、HuggingFace、WebDAV 等）：

后台 → 上传设置 → 选择对应渠道
填入凭证（每种渠道的凭证获取方式见 https://cfbed.sanyue.de/deployment/prerequisites.html）
启用

可以做”多通道负载均衡”或者”主备容灾”。

API 调用方式（对接 LLM / Agent / MCP）

用 curl 测试上传

1 2	curl -X POST "https://img.yoursite.com/upload?authCode=你的API_Token" \ -F "file=@本地图片.png"

返回 JSON 形如：

1	[{"src": "/file/xxxxx.png"}]

拼接 https://img.yoursite.com + /file/xxxxx.png 就是图片访问链接。

主要 API 端点

端点	用途
`POST /upload`	上传图片
`GET /api/manage/list`	列出图片
`POST /api/manage/delete`	删除图片
`GET /random`	随机图
`WebDAV /dav/`	WebDAV 协议挂载

完整文档：https://cfbed.sanyue.de/api/

部署架构总览

GitHub:你的用户名/CloudFlare-ImgBed (Fork)
            │
            └── push 触发自动部署 ──→
                                        │
Cloudflare Pages 项目                   ▼
  ├── 默认域名：yourname-imgbed.pages.dev
  ├── 自定义域：img.yoursite.com
  ├── 绑定：
  │     ├── img_url → KV 命名空间（图片元数据）
  │     └── img_r2  → R2 存储桶（图片本体）
  └── 监听 GitHub push，自动 CI/CD

月度成本核算

资源	个人使用预估	免费上限	费用
R2 存储	< 1 GB	10 GB	¥0
R2 写入	< 1000 次/月	100 万次	¥0
R2 读取	< 1 万次/月	1000 万次	¥0
R2 流量	任意	无限免费	¥0
Pages Functions	< 1000 次/天	10 万次/天	¥0
Workers KV	< 100 次写/天	1000 次/天	¥0
自定义域	1 个	不限	¥0

每月总成本：¥0

教程信息

整理日期：2026 年 5 月
基于版本：CloudFlare-ImgBed v2.7.x（2026 年 2 月版本）
官方项目：https://github.com/MarSeventh/CloudFlare-ImgBed
官方文档：https://cfbed.sanyue.de

祝部署顺利 🎉