roim-picx Cloudflare page 部署教程

Saitenasuk Lv1
  2026-02-05 15:13:24 2026-02-05 15:13:24 创建   2026-02-26 00:25:13 2026-02-26 00:25:13 更新    1.6k 字  5 分钟  

📋 前置条件

  1. 一个 GitHub 账号
  2. 一个 Cloudflare 账号
  3. 本地已安装 Node.js（v18+）和 pnpm

第一步：Fork 项目到你的 GitHub

  1. 访问项目仓库：https://github.com/roimdev/roim-picx
  2. 点击右上角的 Fork 按钮
  3. 将项目 Fork 到你自己的 GitHub 账户

第二步：注册并登录 Cloudflare

  1. 访问 Cloudflare Dashboard
  2. 如果没有账号，点击注册并完成邮箱验证
  3. 登录你的 Cloudflare 账户

第三步：创建 R2 存储桶

R2 用于存储上传的图片文件。

步骤：

  1. 在 Cloudflare Dashboard 左侧菜单，找到 R2 对象存储
  2. 如果是首次使用，需要先 开通 R2 服务（免费套餐包含 10GB 存储）
  3. 点击 创建存储桶
  4. 输入存储桶名称，例如：picx-imgs
  5. 选择区域（选择离你最近的区域）
  6. 默认存储类：标准
  7. 点击 创建存储桶

第四步：创建 KV 命名空间

KV 用于会话管理和临时数据存储。

步骤：

  1. 在 Cloudflare Dashboard 左侧菜单，找到 存储和数据库 → Workers KV
  2. 点击 创建命名空间
  3. 输入命名空间名称，例如：picx-kv
  4. 点击 添加

第五步：创建 D1 数据库

D1 用于存储用户信息、图片元数据、统计信息等结构化数据。

步骤：

  1. 在 Cloudflare Dashboard 左侧菜单，找到 存储和数据库 → D1 SQL 数据库
  2. 点击 创建数据库
  3. 输入数据库名称，例如：picx-db
  4. 数据位置：（选择离你最近的区域或自动）
  5. 点击 创建

    [!IMPORTANT]
    记住你的数据库名称和 Database ID，后面需要用到

第六步：创建 Pages 项目

步骤：

  1. 在 Cloudflare Dashboard 左侧菜单，找到 计算和AI → Workers & Pages
  2. 点击 创建应用程序 → 想要部署 Pages？开始使用 点击开始使用
  3. 选择 导入现有 Git 存储库
  4. 授权 Cloudflare 访问你的 GitHub
  5. 选择你 Fork 的 roim-picx 仓库 → 点击开始设置

第七步：配置构建设置

在创建 Pages 项目时，需要配置构建命令和输出目录：

配置项值
框架预设选择 Vue
构建命令npm run build
构建输出目录dist
根目录留空

第八步：配置环境变量

在 Pages 项目的 设置 → 变量和机密 中添加以下变量：

[!TIP]
变量类型都为文本

如果只是个人使用，可以先只配置 ALLOW_TOKEN_LOGIN=true，使用 Token 登录即可

必填变量

变量名示例值说明
BASE_URLhttps://your-project.pages.dev你的 Pages 访问域名或你自己的域名
PICX_AUTH_TOKEN随机生成一个强密码管理员 Token，用于 API 认证

可选变量（Token 登录）

变量名示例值说明
ALLOW_TOKEN_LOGINtrue是否允许使用 Token 直接登录
STORAGE_TYPER2R2 或 HF（默认值R2）

可选变量（GitHub OAuth 登录）

变量名示例值说明
GITHUB_CLIENT_ID你的 GitHub App Client IDGitHub OAuth 客户端 ID
GITHUB_CLIENT_SECRET你的 GitHub App Client SecretGitHub OAuth 客户端密钥
VITE_GITHUB_CLIENT_ID同上，用于前端与 GITHUB_CLIENT_ID 相同
GITHUB_OWNER*允许登录的用户，* 表示所有人
ADMIN_USERSyourname管理员用户名，逗号分隔

第九步：绑定 R2、KV、D1 服务

步骤：

  1. 进入你的 Pages 项目
  2. 点击 设置 → 绑定
  3. 分别添加以下绑定：

R2 绑定

设置项值
变量名PICX
R2 存储桶选择你创建的存储桶

KV 绑定

设置项值
变量名XK
KV 命名空间选择你创建的命名空间

D1 绑定

设置项值
变量名DB
D1 数据库选择你创建的数据库

[!CAUTION]
变量名必须完全匹配！

  • R2 绑定变量名必须是 PICX
  • KV 绑定变量名必须是 XK
  • D1 绑定变量名必须是 DB

如果变量名不匹配，项目将无法正常工作！除非你修改了项目代码中的变量名

第十步：初始化 D1 数据库

需要在本地执行数据库迁移脚本来创建表结构。

步骤：

  1. 克隆你 Fork 的项目到本地：
1
2
git clone https://github.com/你的用户名/roim-picx.git
cd roim-picx
  1. 安装依赖：
1
pnpm install
  1. 登录 Cloudflare CLI：
1
npx wrangler login

这会打开浏览器让你授权。

  1. 复制项目根目录下的文件wrangler.toml.example重命名为wrangler.toml
1
2
3
4
[[d1_databases]]
binding = "DB"
database_name = "picx-db"
database_id = "xxx"

只留下d1_databases部分其余删除，并将database_id与database_name的值替换为你刚刚创建D1数据库的名称与ID

  1. 执行数据库迁移（将 picx-db 替换为你的数据库名）：
1
npx wrangler d1 migrations apply picx-db --remote
namestatus
0001_init.sql✅
0002_steam_login.sql✅
0003_google_login.sql✅
0004_add_storage_type.sql✅
0005_add_email.sql✅
0006_system_settings.sql✅
0007_add_albums.sql✅
0008_add_nsfw.sql✅
0009_optimize_performance.sql✅
0010_api_keys.sql✅

观察日志输出，是否成功迁移

第十一步：触发部署

  1. 回到 Cloudflare Pages 项目页面
  2. 点击 部署
  3. 在所有部署中的最新一条部署的末尾点击 重新部署

等待构建完成后，你就可以通过 https://你的项目名.pages.dev 访问了！

第十二步：验证部署

  1. 访问你的 Pages 地址
  2. 使用你设置的 PICX_AUTH_TOKEN 登录
  3. 尝试上传一张图片
  4. 确认图片可以正常显示和管理

    [!TIP]
    如果你的环境变量BASE_URL与cloudflare提供的域名一致，那么图片可以显示

    如果BASE_URL为你的自己的域名，需要前往 自定义域 设置你自己的域名，设置完后等待DNS同步，图片就可以正常显示

可选配置：自定义域名

  1. 在 Pages 项目中点击 自定义域
  2. 添加你的自定义域名
  3. 按照提示配置 DNS 记录
  4. 更新 BASE_URL 环境变量为你的自定义域名

可选配置：GitHub OAuth 登录

如果你想启用 GitHub 登录功能：

1. 创建 GitHub OAuth App

  1. 访问 GitHub Developer Settings
  2. 点击 OAuth Apps → New OAuth App
  3. 填写信息：
    • Application name: roim-picx
    • Homepage URL: https://你的域名
    • Authorization callback URL: https://你的域名/auth
  4. 点击 Register application
  5. 记录 Client ID
  6. 点击 Generate a new client secret 记录 Client secret

2. 配置环境变量

在 Cloudflare Pages 添加：

变量名示例值说明
GITHUB_CLIENT_ID你的 GitHub App Client IDGitHub OAuth 客户端 ID
GITHUB_CLIENT_SECRET你的 GitHub App Client SecretGitHub OAuth 客户端密钥
VITE_GITHUB_CLIENT_ID同上，用于前端与 GITHUB_CLIENT_ID 相同
GITHUB_OWNER*允许登录的用户，* 表示所有人
ADMIN_USERSyourname （Github名称）管理员用户名，逗号分隔

添加后需重新部署

目录
roim-picx Cloudflare page 部署教程
  1. 📋 前置条件
  2. 第一步：Fork 项目到你的 GitHub
  3. 第二步：注册并登录 Cloudflare
  4. 第三步：创建 R2 存储桶
    1. 步骤：
  5. 第四步：创建 KV 命名空间
    1. 步骤：
  6. 第五步：创建 D1 数据库
    1. 步骤：
  7. 第六步：创建 Pages 项目
    1. 步骤：
  8. 第七步：配置构建设置
  9. 第八步：配置环境变量
    1. 必填变量
    2. 可选变量（Token 登录）
    3. 可选变量（GitHub OAuth 登录）
  10. 第九步：绑定 R2、KV、D1 服务
    1. 步骤：
    2. R2 绑定
    3. KV 绑定
    4. D1 绑定
  11. 第十步：初始化 D1 数据库
    1. 步骤：
  12. 第十一步：触发部署
  13. 第十二步：验证部署
  14. 可选配置：自定义域名
  15. 可选配置：GitHub OAuth 登录
    1. 1. 创建 GitHub OAuth App
    2. 2. 配置环境变量