CloudFlare-ImgBed：从图床到自托管文件中心

博客插图、笔记截图、安装包和临时分享文件散落在不同服务后，麻烦很快从“文件放哪里”变成“怎样统一上传、检索、删除和迁移”。直接使用对象存储可以保存文件，却通常还缺少上传页面、目录管理、访问链接和权限控制；公共图床省事，但域名、数据位置与删除能力未必由自己掌握。

CloudFlare-ImgBed 在存储服务前增加了一层自托管管理入口。浏览器、上传工具、REST API 或 WebDAV 都可以把文件交给同一套应用，应用再将文件送往 Cloudflare R2、S3 兼容存储、Telegram、Discord、Hugging Face 或 WebDAV，并保存用于检索和管理的元数据。项目既能部署到 Cloudflare Pages/Workers，也提供使用 SQLite 与本地目录的 Docker 版本。

名字里的“ImgBed”容易让人只想到图片外链。当前版本实际管理的是一般文件，还包含目录、标签、批量操作、API Token 和 WebDAV。相应代价也更明确：CloudFlare-ImgBed 是管理层，不会替使用者决定存储服务的额度、数据耐久性、公开访问策略和备份责任。

GitHub 仓库信息

信息	内容
项目标题	CloudFlare-ImgBed
项目描述	基于 Cloudflare 构建的 Serverless 开源文件托管方案，支持图床、安全文件存储和个人云盘能力。
GitHub 仓库	MarSeventh/CloudFlare-ImgBed
官网地址	https://cfbed.sanyue.de
主要开发语言	JavaScript 99.71%，另含 HTML 0.15% 和 Dockerfile 0.14%
开源许可证	MIT
最近代码更新	2026-08-31（GitHub pushed_at，核对日期：2026-09-01）

项目轮廓

CloudFlare-ImgBed 的选择空间主要由两件事构成：应用运行在哪里，文件实际存在哪里。两者可以分别决定。

运行方式	元数据与配置	文件数据	更适合的阶段
Cloudflare Pages	KV 或 D1，二选一并绑定到项目	R2 或外部存储渠道	希望少维护服务器，并通过控制台完成部署
Cloudflare Workers	KV 或 D1；通过 GitHub Actions 配置	R2 或外部存储渠道	已熟悉 GitHub Actions，希望控制 Worker 名称和部署流程
Docker	/app/data/database.sqlite	/app/data/r2 或配置的外部渠道	有自己的服务器，希望掌握进程、磁盘和备份

Serverless 在这里表示应用运行在 Cloudflare 平台，不表示数据无需规划。D1 是关系型数据库，KV 是键值数据库；二者都通过 Cloudflare binding（平台注入的资源连接）交给应用。元数据数据库记录文件 ID、路径、标签、上传来源和渠道信息，存储后端保存实际字节；只备份其中一侧，都不足以完整恢复文件库。

核心能力

一个入口，多种存储

日常上传可以在网页中拖放、粘贴或选择文件夹，也可以调用 /upload、使用上传工具，或者把 /dav/ 挂到支持 WebDAV 的客户端。上传时可指定目录、命名方式、渠道类型和渠道名称。文件进入系统后，管理端提供浏览、移动、重命名、标签、批量删除和元数据操作。

存储渠道并非只能选一个。官方文档列出的渠道包括 Telegram、Discord、Cloudflare R2、S3 兼容服务、Hugging Face 和 WebDAV；同类渠道还可以配置多个实例。自动重试能够在上传失败时切换渠道，但这类重试能力不等于跨渠道复制，也不能替代独立备份。

对长期博客和文档资源，自己的域名配合 R2 或 S3 兼容存储通常更容易迁移和治理。Telegram、Discord 适合利用已有服务快速开始，但单文件限制、接口政策与访问路径受第三方控制；Hugging Face 提供专门的大文件直传流程；WebDAV 适合复用已有私有云或 NAS。具体额度、费用和服务条款要以各存储提供方的当前规则为准。

管理与访问分开

CloudFlare-ImgBed 将管理后台、普通用户认证、上传认证码和 API Token 分开。Token 可以限定为 upload、delete、list 或 manage 权限，并可设置过期时间。固定提交中的登录实现使用 PBKDF2 校验密码，登录成功后通过 HttpOnly Cookie 保存会话；HTTPS 场景还可以启用 Secure Cookie。

这种设计允许 PicGo 一类上传端只持有 upload 权限，不必拿到管理员身份。来源域名限制、IP 列表、文件白名单和内容审查则属于另一层访问控制，适合减少误用或公开暴露，不能替代真正的身份认证。

从图片外链到文件目录

普通图床往往以“上传后返回 URL”为终点。CloudFlare-ImgBed 还提供目录组织、公开画廊、随机文件接口、用于探测文件信息的 HEAD 请求、用于断点读取的 Range 请求与 WebDAV。WebDAV 端点为站点地址加 /dav/，支持 PROPFIND、GET、PUT、DELETE、OPTIONS 和 MKCOL，因此桌面文件管理器能够把远端文件库当作网络位置使用。

挂载后看到的是统一目录，但删除、公开链接、分片和大文件行为仍由具体渠道及部署平台决定。WebDAV 统一了操作入口，没有抹平底层差异；正式采用前需要用真实文件验证上传、读取、删除和恢复四条链路。

工作原理

下面的图只画出固定源码和官方文档能够确认的职责关系。Cloudflare 与 Docker 共享前端和 Functions 路由，Docker 适配层将 D1 换成 SQLite，并把 R2 binding 换成本地对象目录。

一次普通上传会经过认证与上传配置检查，选择目标渠道，将文件写入后端，再把文件 ID、路径、类型、渠道和上传信息写入元数据层。读取 /file/... 时，应用根据元数据定位渠道，并返回、代理或重定向到实际文件。这样的分层让管理界面与上传 API 保持一致，也意味着迁移需要同时处理元数据和对象内容。

Docker 镜像使用 Node.js 22 与 Hono 运行服务，监听容器内 8080 端口。启动时会读取初始化 SQL 和迁移文件；持久化目录 /app/data 内包含 database.sqlite 与本地对象目录 r2。这两个位置解释了为什么 Compose 中只有一个数据卷，却能同时保存数据库和文件。

Docker 试用

这条路径的目标是上传一个测试文件，再通过返回链接读回文件。上游 Compose 与官方 Docker 文档都使用 latest，所以下面的试用配置保持一致。latest 会随上游发布变化，不能精确复现；截至 2026 年 9 月 1 日，本文尚未核实与 v2.7.6 对应的镜像标签或 digest。正式部署前应在可访问 Docker Registry 的环境核对镜像标签与平台架构，并将配置固定到验证过的 digest。

前置条件

• 已安装 Docker Engine 或 Docker Desktop，以及 Compose V2；
• 本机 7658 端口未被占用；
• 准备一个空目录保存 Compose 文件和 data/；
• 只在本机或可信测试网络开始，不要把尚未配置管理员凭据的实例直接暴露到公网。

在空目录创建 compose.yaml：

services:
  imgbed:
    image: marseventh/cloudflare-imgbed:latest
    ports:
      - "127.0.0.1:7658:8080"
    volumes:
      - ./data:/app/data
    restart: unless-stopped

绑定到 127.0.0.1 是为了让第一次配置只在本机可见。若 Docker 运行在远程服务器，可先通过 SSH 端口转发访问，不必提前开放公网端口。

在 compose.yaml 所在目录执行：

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 imgbed

容器进入运行状态、日志没有持续启动错误，并且浏览器能够打开 http://127.0.0.1:7658/，说明基础服务已经响应。随后访问 http://127.0.0.1:7658/dashboard。官方配置文档明确说明管理后台默认无需密码；固定提交的登录代码也显示，管理员用户名和密码都未设置时会直接创建管理员会话。进入后台后的第一个动作应是设置独立的管理员用户名和强密码，再配置上传认证码或最小权限 Token。

回到上传页，选择 Docker 本地 R2 适配渠道，并上传一张不含隐私信息的测试图片。成功信号应包括：页面返回 /file/... 形式的地址；新地址能够读取刚才的文件；管理后台能找到对应条目；宿主机 data/ 中出现 database.sqlite，data/r2 中出现对象文件。若改用 S3、Telegram 等外部渠道，data/r2 不会成为通用成功信号，应到对应后端确认对象。本文没有实际启动容器，上述信号来自官方部署说明与固定源码，仍需在自己的环境核对。

常见卡点可以按现象排查：

• 页面打不开：检查 docker compose ps、端口占用和 docker compose logs imgbed；
• 容器反复重启：确认 data/ 可写，并查看 SQLite 初始化或迁移错误；
• 页面可用但上传失败：确认已选择并启用存储渠道，上传码或 Token 与客户端一致；
• 文件记录存在但读取失败：检查记录中的渠道配置、本地对象文件和反向代理路径；
• 经反向代理登录失效：使用 HTTPS 后开启 Secure Cookie，并确认代理保留 Cookie 与原始协议信息。

停止试用使用：

docker compose down

普通 down 不会删除绑定的 ./data。清理或升级前先备份整个目录，不要只复制 SQLite 文件。

API 上传

管理后台可以创建只有 upload 权限、带过期时间的 API Token。Token 完整值只在创建响应中返回，适合存入密码管理器或密钥系统。下面的命令需要站点已经配置可用渠道，并准备一张当前目录下的 sample.png：

export IMGBED_URL='https://img.example.com'
export IMGBED_TOKEN='your-upload-token'

curl -fsS -X POST \
  "$IMGBED_URL/upload?uploadChannel=cfr2&returnFormat=full" \
  -H "Authorization: Bearer $IMGBED_TOKEN" \
  -F 'file=@./sample.png'

img.example.com、Token 和 cfr2 都是占位值；存储渠道不是 R2 时要改成实际渠道。成功响应是数组，其中 src 指向 /file/...；若设置了默认 URL 前缀，还可能返回 publicUrl。HTTP 401/403 通常指向 Token、权限或过期时间；HTTP 400 多与文件、渠道名称或参数有关；服务端错误则应结合日志和存储渠道状态排查。

上传接口的中间件会检查数据库绑定，但不会自动要求管理员会话。公开站点必须单独启用上传认证码或 upload Token，不能把“后台有密码”误当作“上传接口已受保护”。Token 应按客户端拆分并定期轮换，不要把管理员 Token、Cloudflare API Token 或存储密钥写进前端代码和公开仓库。

WebDAV 接入

在“系统设置 → 其他设置 → WebDAV”中启用服务，设置独立用户名、强密码、上传渠道和可选渠道名称。客户端地址统一为：

https://img.example.com/dav/

macOS Finder 可以使用“前往 → 连接服务器”连接该地址；Windows 可以添加网络位置。能够列出目录、上传测试文件、下载同一文件并删除测试文件，才算完成 WebDAV 的最小闭环。公网使用必须配合 HTTPS，凭据不要复用管理员密码；若客户端兼容性或大文件行为影响使用，再用固定大小样本逐项验证 PUT、GET、Range 和删除。

Cloudflare 部署

希望通过 Cloudflare Dashboard 完成部署和自动构建时选择 Pages；已经使用 GitHub Actions，并希望显式管理 Worker 部署参数时选择 Workers。两条路径共享主要应用代码和核心使用入口，部署流程以及数据库、存储的绑定方式不同。

Pages 路径

官方 Pages 文档把 Pages 作为更容易开始的 Serverless 方式。操作主线如下：

1. Fork 仓库，在 Cloudflare Dashboard 创建 Pages 项目并连接该 Fork；
2. 生产分支选择 main，构建命令填写 npm install，输出目录填写 /frontend-dist；
3. 元数据数据库在 KV 与 D1 中选择一种：KV binding 必须命名为 img_url，D1 binding 必须命名为 img_d1；
4. 选择 D1 时先执行固定版本的 database/init.sql，绑定数据库后重新部署；
5. 进入管理后台设置管理员凭据、上传认证和实际存储渠道；使用 R2 时绑定名为 img_r2 的存储桶。

部署成功的信号不只是一条绿色构建记录。Pages 域名应能打开；管理后台应能读写设置；上传测试文件后，文件记录和实际对象都能找到；删除后两侧状态应一致。Cloudflare 控制台字段和免费额度会变化，操作前应再对照当前官方文档与 Cloudflare 规则。

Workers 路径

Workers 版本通过仓库内的 GitHub Actions 工作流部署。官方 Workers 文档给出控制台步骤；固定源码中的工作流要求 Fork 仓库，并读取以下 GitHub Actions Secrets：

Secret	用途	要求
CLOUDFLARE_API_TOKEN	部署 Worker	必填，按部署需要授予最小权限
CLOUDFLARE_ACCOUNT_ID	定位 Cloudflare 账户	必填
D1_DATABASE_ID 或 KV_NAMESPACE_ID	保存元数据	二选一
R2_BUCKET_NAME	绑定 R2	使用 R2 时填写
WORKER_NAME	自定义 Worker 名称	可选
WORKER_VARS	JSON 格式业务变量	可选，管理后台能配置的内容优先留在后台

在 Fork 的 Actions 页面手动运行 Deploy to Cloudflare Workers，或在配置完成后由 main 分支推送触发。成功后通常通过 https://<worker-name>.<account-subdomain>.workers.dev 访问。不要把 Token 写入 GitHub Variables、工作流文件或日志；公开 Fork 中只能使用加密 Secrets。

安全基线

正式开放域名前，至少完成以下收口：

1. 设置管理员用户名和独立强密码，确认未登录请求无法取得管理员会话，也不能调用受保护的管理接口；
2. 只允许 HTTPS，确认反向代理配置正确后启用 Secure Cookie；
3. 设置上传认证码，或为每个上传客户端创建只有 upload 权限且可过期的 Token；
4. 关闭不需要的随机图、公开画廊和 WebDAV，公开功能只暴露计划公开的目录；
5. 设置来源域名、IP 或文件名单作为辅助限制，并用无凭据请求验证接口确实拒绝访问；
6. Cloudflare、S3、Telegram、Discord 和 Hugging Face 凭据进入专用密钥存储，按最小权限发放；
7. 对登录失败、上传失败、异常流量、存储额度和数据库错误建立日志与告警。

内容审查功能可以减少明显违规上传，但第三方审查服务本身会接触待审内容，也可能产生费用、延迟与误判。涉及私密文件时，需要单独评估数据是否会发送给外部服务；白名单和来源域名限制也不能替代访问加密与身份认证。

备份与升级

Docker 部署应把 data/ 视为一个恢复单元。更稳妥的备份顺序是暂停写入或停止容器，复制整个 data/，再恢复到隔离环境，确认后台记录与文件读取都正常。单独复制 database.sqlite 只保留索引和设置，单独复制 r2/ 又会丢失管理元数据。

Cloudflare 部署要分别处理元数据与对象数据。管理端提供元数据备份与恢复能力，但元数据导出不能自动证明 R2、S3 或其他渠道的实际文件已经备份。生产方案应为数据库和每个存储后端建立各自的版本、保留与恢复测试，并记录文件 ID 到对象路径的映射。

升级前固定当前镜像 digest 或源码提交，阅读目标 Release，备份并在副本环境验证数据库迁移、登录、上传、读取、删除和 WebDAV。Docker 不应长期使用 latest；Pages/Workers 的 Fork 也应通过明确提交或受控合并升级，避免上游变化直接进入生产。

适用边界

CloudFlare-ImgBed 适合希望掌握域名与存储去向的个人站点、小团队素材库，以及需要网页、API、上传工具和 WebDAV 共用一个文件入口的场景。已有 Cloudflare 账户时，Pages/Workers 可以减少服务器维护；已有 VPS 或 NAS 时，Docker 提供更直接的本地数据与备份路径。

以下情况需要换一个方向评估：

• 只需要为网站保存静态资源：直接使用 R2/S3、自有域名和一段受控上传服务，组件更少；
• 不希望承担升级、安全、备份和存储渠道故障：选择提供 SLA、账号体系和账单支持的托管媒体服务；
• 需要多人空间、审核流、精细组织权限或完整数字资产管理：选择面向团队协作的文件平台或 DAM；
• 需要视频转码、图片处理流水线和大规模派生资源：选择专门的媒体处理平台，不把文件托管层当成处理引擎。

采用前最有价值的一步，是用计划中的真实存储渠道完成一次小型恢复演练：上传一组不同大小和类型的文件，导出元数据与对象备份，在隔离环境恢复，再逐一验证旧链接、目录、删除和 WebDAV。这个结果比功能列表更能回答 CloudFlare-ImgBed 是否适合长期保存当前资产。

版本与参考

本文基于 CloudFlare-ImgBed v2.7.6 的源码提交 ee8cce3，源码与动态仓库信息核对日期为 2026 年 9 月 1 日。最新 Release v2.7.6 发布于 2026 年 8 月 16 日；仓库采用 MIT 许可证。

研究读取了中文 README、Docker Compose、Docker 服务入口、Workers 配置、管理员登录、数据库初始化以及官方文档。官方文档仓库固定到提交 ac259fa。

本次只做公开资料和固定源码的静态核对，没有安装依赖、构建项目、拉取或运行 Docker 镜像，也没有登录演示站、上传文件、连接真实存储、测试额度、执行恢复演练或验证性能。文中的命令、成功信号和故障分支是可执行检查路径，不是本次环境的亲测结果。