roimdev/roim-picx：一款基于 Cloudflare Worker、R2、Page

roimdev

297

315 6

Apache License 2.0

项目介绍

roimdev/roim-picx 是一个托管在 GitHub 上的开源项目，主要使用 Vue 编写，采用 Apache License 2.0 许可证，目前获得 297 个 Star、315 次 Fork。

仓库全名: roimdev/roim-picx
开源许可证: Apache License 2.0
Star 数: 297
Fork 数: 315
未关闭 Issue: 6

README 摘要

roim-picx 🖼️ 一款基于 Cloudflare 的 Worker、R2、Pages、D1 实现的免费图床应用 🌐 在线预览 • ✨ 功能特性 • 🚀 部署教程 • 📸 界面截图 📢 预览说明 [!WARNING] 在线预览地址仅作演示使用，每天有使用限额，请勿大量上传图片。请勿将预览图床地址用于生产环境，数据会定期清理。预览 Token： 4xVSYkCKw2ExbPNEaMPjCnaaOowU9sTf 💡 为什么选择 roim-picx？特性 | 说明 | :---:|:---| 💾 免费存储 | 10GB 的免费存储空间 | 🚀 高速访问 | 每月 300W 次不计流量的图片访问（每天 10W 次限制） | 📤 上传无忧 | 每月 100W 次的图片上传次数 | 🆓 零成本部署 | 无需购买服务器，克隆代码后部署 Cloudflare 即可使用 | 🔒 数据安全 | 独立部署…

完整内容见 GitHub 原始 README 或本页。

常见问题

roim-picx 用什么语言开发？

主要使用 Vue 编写，采用 Apache License 2.0 许可证，目前有 297 个 Star。

roim-picx 可以免费商用吗？

如何获取 roim-picx 的源码？

可以直接克隆仓库：git clone https://github.com/roimdev/roim-picx.git，默认分支为 main；安装与运行步骤见仓库 README。

roim-picx 最近还在维护吗？

仓库最近一次更新为 3月16日，当前有 6 个未关闭 Issue；Star 数为 297，可作为社区活跃度的参考。

关于

GitHub 原始描述（英文）

A free image hosting application based on Cloudflare's Worker, R2, Pages, and D1 architectures.一款基于 Cloudflare 的 Worker、R2、Pages、D1 实现的免费图床应用

描述取自 GitHub 官方 API，保持仓库作者书写的原文。

简要分析

热度分

928

价值分

272

活跃状态

活跃

cloudflare d1 hono pages r2

GitHub

语言占比

CSS

HTML

JavaScript

TypeScript

Vue

贡献者

roimdev

bestzyq

README

roim-picx

🖼️ 一款基于 Cloudflare 的 Worker、R2、Pages、D1 实现的免费图床应用

🌐 在线预览 • ✨ 功能特性 • 🚀 部署教程 • 📸 界面截图

📢 预览说明

[!WARNING] 在线预览地址仅作演示使用，每天有使用限额，请勿大量上传图片。
请勿将预览图床地址用于生产环境，数据会定期清理。

预览 Token： 4xVSYkCKw2ExbPNEaMPjCnaaOowU9sTf

💡 为什么选择 roim-picx？

特性	说明
💾 免费存储	10GB 的免费存储空间
🚀 高速访问	每月 300W 次不计流量的图片访问（每天 10W 次限制）
📤 上传无忧	每月 100W 次的图片上传次数
🆓 零成本部署	无需购买服务器，克隆代码后部署 Cloudflare 即可使用
🔒 数据安全	独立部署，无需担心第三方删除数据

✨ 功能特性

[√] 📦 图片批量上传
[√] 📋 图片列表查询
[√] 🗑️ 图片删除
[√] 📁 目录创建
[√] 🔍 按目录查询
[√] 📎 链接地址点击复制
[√] 🔐 简单的身份认证功能
[√] 🔗 提供删除图片的访问链接
[√] 📂 上传图片时支持选择目录
[√] 📄 管理页面支持分页加载
[√] ✏️ 图片重命名
[√] 🔑 多平台登录授权[Github/Google/Steam]
[√] ⏰ 文件过期自动删除
[√] 🔎 文件前缀搜索
[√] 👤 上传图片关联登录用户信息
[√] 📊 访问统计与热度分析
[√] 💾 D1 数据库持久化存储元数据
[√] 🔄 历史 R2 数据一键同步到 D1
[√] 📱 移动端自适应优化
[√] 🖼️ 相册管理 (创建、编辑、公开/加密分享)
[√] 📤 进阶上传 (保留原名、自定义过期时间)
[√] 👀 我的分享管理 (查看状态、复制链接、删除)
[√] 支持NSFW内容检测
[√] Hugging Face 存储
[√] 支持添加文本水印

🏗️ 技术架构

架构概览

前端技术栈

技术	版本	说明
Vue 3	^3.5	渐进式 JavaScript 框架，使用 Composition API
Vue Router	^4.6	官方路由管理器
Element Plus	^2.13	基于 Vue 3 的组件库
Tailwind CSS	^4.1	原子化 CSS 框架
Vite	^7.3	下一代前端构建工具
TypeScript	^5.9	JavaScript 超集，提供类型安全
Font Awesome	^7.1	图标库
Axios	^1.13	HTTP 客户端

后端技术栈

技术	说明
Cloudflare Pages	静态网站托管平台，支持全球 CDN 加速
Pages Functions	基于 Cloudflare Workers 的 Serverless 函数
Hono	轻量级、高性能的 Web 框架，运行在 Edge Runtime
R2	S3 兼容的对象存储服务，用于存储图片文件
D1	Cloudflare 的原生 SQL 数据库，用于存储结构化元数据和统计信息
KV	分布式键值存储，用于会话管理和元数据存储

项目结构

roim-picx/
├── 📁 src/                    # 前端源码
│   ├── 📁 components/         # Vue 组件
│   ├── 📁 views/              # 页面视图
│   ├── 📁 utils/              # 工具函数
│   ├── 📁 plugins/            # 插件配置
│   └── 📄 App.vue             # 根组件
├── 📁 functions/              # Cloudflare Pages Functions
│   └── 📁 rest/               # RESTful API 路由
│       └── 📄 [[route]].ts    # 动态路由处理
├── 📁 public/                 # 静态资源
├── 📁 docs/                   # 文档资源
├── 📁 migrations/             # D1 数据库迁移文件
├── 📄 package.json            # 项目依赖配置
├── 📄 vite.config.ts          # Vite 构建配置
├── 📄 tailwind.config.js      # Tailwind CSS 配置
└── 📄 tsconfig.json           # TypeScript 配置

数据流程

sequenceDiagram participant U as 用户 participant F as 前端 (Vue) participant A as API (Hono) participant R as R2 存储 participant D as D1 数据库 participant K as KV 存储 U->>F: 选择图片上传 F->>A: POST /rest/upload A->>K: 验证 Token/Session K-->>A: 验证结果 A->>R: 存储图片文件 R-->>A: 返回存储路径 A->>D: 存储图片元数据 A-->>F: 返回图片 URL F-->>U: 显示上传结果

🚀 部署教程

1️⃣ Fork 项目

将本项目 Fork 到自己的 GitHub 账户

2️⃣ 注册 Cloudflare 并开通 R2 服务

开通 R2 服务

3️⃣ 创建 Pages 项目

找到 Pages 选项并创建项目

创建项目

4️⃣ 链接代码仓库

连接 GitHub 或 GitLab 并选择需要构建的项目

链接仓库

5️⃣ 设置环境变量

设置环境变量

6️⃣ 绑定 R2 和 KV 服务

在项目创建后，设置项目的函数信息绑定 R2 和 KV 服务

绑定服务

7️⃣ 构建项目

构建项目，提示成功即可访问

构建成功

[!NOTE] Pages 的函数变量名称需要与项目的变量名称一致。
如需修改 functions 里面的 Env 命名空间，对应的文件是 [[route]].ts

8️⃣ 数据库迁移

在本地环境执行以下命令将初始表结构导入到 D1：

npx wrangler d1 execute <YOUR_DATABASE_NAME> --remote --file=./migrations/0001_init.sql

首次升级可以使用命令进行数据库初始化

```bash
wrangler d1 migrations apply <YOUR_DATABASE_NAME> --remote

在部署 Cloudflare Pages 时，需要在 Settings -> Variables and Secrets 中配置以下环境变量：

核心配置

变量名	必填	示例值	说明
`BASE_URL`	是	`https://picx.your-domain.com`	应用的根域名地址，用于生成完整链接
`PICX_AUTH_TOKEN`	是	`your-secret-token`	管理员 Token，用于管理接口认证
`ALLOW_TOKEN_LOGIN`	否	`true`	是否允许使用管理 Token 直接登录后台
`STORAGE_TYPE`	否	`R2`	默认存储类型，可选 `R2` 或 `HF` (Hugging Face)

GitHub OAuth 登录(可选)

变量名	必填	说明
`GITHUB_CLIENT_ID`	是	GitHub OAuth App 的 Client ID
`GITHUB_CLIENT_SECRET`	是	GitHub OAuth App 的 Client Secret
`VITE_GITHUB_CLIENT_ID`	是	同 `GITHUB_CLIENT_ID`，用于前端调用
`GITHUB_OWNER`	是	允许登录的 GitHub 用户名，`*` 表示允许所有人
`ADMIN_USERS`	否	超级管理员用户名列表，逗号分隔 (例: `user1,user2`)

Google & Steam 登录(可选)

变量名	必填	说明
`STEAM_LOGIN_ENABLED`	否	是否启用 Steam 登录 (`true`/`false`)
`STEAM_API_KEY`	否	Steam Web API Key
`GOOGLE_LOGIN_ENABLED`	否	是否启用 Google 登录 (`true`/`false`)
`GOOGLE_CLIENT_ID`	否	Google OAuth Client ID
`GOOGLE_CLIENT_SECRET`	否	Google OAuth Client Secret

Hugging Face 存储 (可选)

变量名	必填	说明
`HF_TOKEN`	否	Hugging Face Access Token (需要有写权限)
`HF_REPO`	否	Hugging Face 数据集仓库名 (例: `username/dataset`)

🔄 历史数据同步

如果你之前已经有一些图片存储在 R2 中但还没同步到 D1 数据库，可以使用内置的同步 API：

获取你的管理员 Token (PICX_AUTH_TOKEN)。

调用同步接口：

curl -X POST -H "Authorization: <YOUR_ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}' \
  "https://your-domain.com/rest/admin/sync-r2-to-d1"

如果返回数据中 hasMore 为 true，请将返回的 nextCursor 放入下一次调用的 cursor 参数中：

curl -X POST -H "Authorization: <YOUR_ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100, "cursor": "YOUR_NEXT_CURSOR_HERE"}' \
  "https://your-domain.com/rest/admin/sync-r2-to-d1"

📸 界面截图

_{🔐 登录页面}	_{📋 管理页面}
_{📤 上传页面}	_{📂 选择上传}
_{✅ 上传结果}	_{🗑️ 删除页面}
_{图片分享1}	_图片分享
_系统管理	_相册管理