[开源] PicHost - 自托管个人轻量图床

项目是怎么长出来的#

市面上那些「花花绿绿」的图床依然很好，只是诉求不同：我要的是轻量、和 Firefly + Twikoo 咬得上，而不是天天跟 Cloudflare Dashboard 较劲。

为什么从 Cloudflare 版推倒重来#

CF 版并非不能用，对个人博客量级也够用。让我下决心重写的是这几件事叠在一起：

双域拆分维护成本高。 管理后台在 pic 域，出图在 img 域，环境变量、IMAGE_BASE_URL、Worker 路由、R2 binding 要同时对齐。改一处漏一处，返回的 Markdown 链接就和防盗链规则对不上。

deploy 会「悄悄改配置」。 最大的坑是 ALLOWED_REFERER_HOSTS 写进 wrangler.jsonc 的 vars——每次 CI deploy 都会用仓库里的值覆盖 Dashboard 手工加的博客域名，全站插图 403。根治办法是从 wrangler 删掉 vars，但这类细节要踩过才知道。

数据不在一个「我能直接摸到」的地方。 R2 桶里的对象好备份，但用户、设置、会话散落在 CF 各处的配置里；想迁到 NAS 或家里小主机，得重新拼一套。

v1.0 的选择很直接：单进程、单域、单数据目录。Nuxt 4 管界面，Nitro 管 API 和出图，Referer 防盗链还在，Twikoo 兼容接口还在，架构变成「能 docker run 就跑、能 tar /data 就迁」。后来的 v1.1 又把对象存储和双域名接回来了，但都在同一个 Docker 实例里完成，不再绑死在 CF Dashboard。

界面长什么样#

v1.2 后台基于 Nuxt UI，默认暗黑主题，中英文可切换。登录页加了滑动拼图验证；上传偏好藏在卡片背面，翻转可调客户端预压缩、自动复制链接、按用户自动删除。下面按我用到的页面过一遍——截图来自 仓库，与当前 v1.2.2 一致。

上传#

主界面就是上传区：拖拽、点击、Ctrl+V 粘贴都行。上传完一键复制直链 / Markdown / HTML，写博客时基本不用切窗口。

存储管理#

可以挂多个 S3 兼容后端（R2、COS、OSS、AWS S3），在 存储 页添加实例、设默认写入后端，直链可选 PicHost 代理或 302 到 CDN。

图库与统计#

图库分页浏览、按文件名搜索、批量删除；管理员能看到每张图的上传者标签，还能按存储后端筛选。统计页看上传/删除趋势和目录分布，偶尔清图库时有个数。

设置#

Referer 白名单、公网域名、全局上传 Token 都在这里配；支持单域或 双域名分离（SITE_BASE_URL + IMAGE_BASE_URL），还能切换按年/月分组或扁平保存路径。v1.2.2 修了双域名保存时误清空管理域、未知 Host 绕过隔离等问题。

相比 CF 版，Docker 版多出来的、我自己用得上的几块：

• 多用户：账号密码登录（滑动验证），管理员可开放注册；普通用户只看到自己的图。以前 CF 版是单人密钥，没法给朋友开个上传账号。
• 多后端存储：本地盘和云桶可以混用，新上传走默认后端，老图按索引路由，不必为了 R2 再维护一套 CF Worker。
• 双域名分离：管理域和图片域拆开，中间件自动隔离——网站域访问不了后台，图片域访问不了非图片路径。
• 操作日志：上传/删除有记录，管理员可按用户筛选，偶尔查「谁删了这张图」有用。
• 上传偏好：卡片翻转设置里可调客户端预压缩、上传后自动复制链接、按用户自动删除——写博客时少点几下。
• 统计页：上传/删除趋势、目录分布，管理员还能看到注册用户数。个人图床不至于天天看，但偶尔清图库有个数。
• 服务端 WebP：sharp 在入库前转码，比纯浏览器端压缩稳，大图体积也能压下来。
• 文档站：o96u.github.io/PicHost 中英文指南，环境变量、API、双域名、Twikoo、迁移与更新日志都集中在这里，README 只留产品宣传。

复制直链 / Markdown / HTML、拖拽粘贴上传、图库搜索批量删——这些基础能力保留着，没为了「重写」而砍掉。

---

我怎么部署的#

我现在用 Docker，核心就这一条：

1
docker run -d \
2
  --name pichost \
3
  -p 6892:6892 \
4
  -v ./data:/data \
5
  --restart unless-stopped \
6
  muxui/pichost:latest

浏览器打开 http://<主机IP>:6892，首次访问走 Web 引导创建管理员，不用预先写 ADMIN_SECRET——这是和 CF 版体验差别最大的一点。以前要在 Dashboard 配一串 Secret，配错就登录不了；现在容器起来就能用。

前面挂了 Nginx 反代，HTTPS 终止在反代层，client_max_body_size 我设了 12m。公网访问记得配 IMAGE_BASE_URL（单域）或 SITE_BASE_URL + IMAGE_BASE_URL（双域分离），否则 API 返回的 Markdown 链接会带内网地址，粘贴到文章里读者打不开。双域 Nginx 示例见文档站 双域名分离。

1
# 预览，生成 data/mapping.json（旧 key → 新 key）
2
docker exec pichost migrate
3

4
# 确认后搬文件
5
docker exec pichost migrate --apply
6

7
# 拉新镜像并重启；启动日志会打印索引同步

1
/data
2
├── pichost.db          # 用户、会话、设置、storage_backends、images 索引
3
└── images/             # 全部图片（本地后端时）
4
    ├── blog/           # 我自定义的博文目录（迁移后）
5
    ├── twikoo/         # 评论配图（迁移后）
6
    └── 2026/08/…       # 或扁平保存：images/随机ID.webp

Twikoo 评论配图怎么接#

这条链路从 CF 版沿用下来，配置没变多少：

评论发图走 POST /api/index.php，表单里 token + image；展示时图片 URL 是 /images/... 直链（开启隐藏前缀时也可能是 /xxx.webp 短链）。

Referer 白名单仍然要配。 和 CF 版一样，把博客域名（muxui.com 和 www.muxui.com 要分别加）写进 ALLOWED_REFERER_HOSTS，否则读者在评论区看到的图会 403，自己后台预览却正常——这种「只有我电脑能看」的错觉，我踩过不止一次。双域名模式下，网站域与图片域主机名会自动放行。

正文配图我习惯在后台上传到 blog/ 目录，评论图自动进 twikoo/；v1.2 起它们都在 images/blog/、images/twikoo/ 下，删图库时好区分来源。若从旧版升级，记得跑一遍 migrate 并对照 mapping.json 替换文章里的旧外链。

版本更新#

写在最后#

回头看，PicHost 的演进路径很清晰：先为博客配图（自持、尽量不删即长期在），再为 Twikoo 评论配图（自己适配 EasyImage 接口），最后把运维成本打下来（Docker、本地盘、单域），v1.1 接回对象存储与双域，v1.2 把目录模型收拢到 images/ 并补上独立文档站。

CF 版教会我 Referer 防盗链和双 Token 分离；Docker 版教会我图床不必绑在某家云上——NAS、VPS、家里小主机，能跑 Docker、能挂卷，就能把图床和数据一起带走。

仓库：github.com/O96u/PicHost（GPL-3.0）· 文档：o96u.github.io/PicHost。部署细节、API、cURL 示例以文档站为准；这篇只是我自己的改版记录。若你也在 Firefly + Twikoo 这条路上，对接有问题欢迎 Issue 或评论区聊。