roim-picx 安裝與舊版升級：Cloudflare R2、D1 設定教學

圖片資源留在自己的 Cloudflare 帳號#

Pages、R2、D1 與 KV 都由自己建立。即使 roim-picx 是第三方開源專案，實際圖片與資料庫仍放在自己的 Cloudflare 資源中，也能自行決定網域、Token 與存取設定。

這不等於資料會自動備份或永遠免費。R2 容量、操作次數與其他 Cloudflare 服務仍要依帳號用量計算，正式使用前應先了解Cloudflare R2 的免費額度與請求成本。

不需要另外維護一台圖床伺服器#

整套應用使用 Pages 與 Pages Functions 執行，不需要為了圖片管理介面另外準備 VPS、作業系統與常駐 Node.js 程序。需要維護的重點會轉成 Cloudflare Bindings、環境變數、D1 migration 與專案版本。

比直接操作 R2 多一層日常管理介面#

R2 適合保存 object，但原生 Dashboard 不是為日常圖床工作流程設計。roim-picx 把上傳、搜尋、相簿、分享、權限與統計集中在同一個網頁介面，對經常管理文章圖片或專案素材的人會比較順手。

舊版圖片可以原地納入新系統#

升級時不需要重新下載再上傳圖片。專案內建同步 API，會掃描原本的 R2 object，再把 key、大小、格式、資料夾與建立時間等 metadata 寫入 D1。圖片檔仍留在原 bucket，降低搬移時改壞既有圖片網址的風險。

API 上傳後可以直接取得圖片 URL#

我不只想在瀏覽器上傳圖片，也希望讓圖片生成或排程產文流程直接呼叫 API，拿到 URL 後寫進 Astro Markdown。新版 roim-picx 已有獨立 API Key，不需要把管理員 Token 放進自動化腳本；API Key 的權限也限制在上傳、列表與刪除。

這項功能讓 roim-picx 不只是圖片後台，也能當成自動化流程中的圖片儲存端。後面會提供可直接測試的 curl 與 Node.js 範例。

目前沒有正式 GitHub Releases#

截至 2026-07-15，專案 GitHub 頁面仍顯示沒有正式 Releases。若 Cloudflare Pages 直接追蹤上游 main，一次更新可能同時帶入新功能、migration、環境變數或不相容調整。

比較保守的做法是：

1. Fork 到自己的 GitHub 帳號。
2. 保留目前已驗證可運作的 commit。
3. 不要自動把上游 main 直接推進正式環境。
4. 更新前先檢查 migrations/、.env.example、README 與程式差異。
5. 重要更新前備份 D1，並確認 R2 圖片有可恢復來源。

架構已經不只是簡單圖床#

新版需要 R2、D1、KV、Pages Functions 與登入設定。D1 平常不需要反覆建立，但每次更新只要出現新的 migration，就要先判斷執行順序與正式資料庫狀態，再重新部署驗證。

文件可能落後目前程式碼#

這次實際版本已有 0001 到 0011，但專案內仍可看到只執行 0001_init.sql 的舊說明。這也是本文選擇直接檢查 migration 目錄與程式碼，而不是完全照著單一 README 指令操作的原因。

Step 1：Fork 專案並建立 Cloudflare Pages#

先 Fork roimdev/roim-picx，再把自己的 Fork clone 到電腦：

1
git clone https://github.com/<你的 GitHub 帳號>/roim-picx.git
2
cd roim-picx
3
npm install

到 Cloudflare Dashboard 建立 Pages 專案，連接剛才的 GitHub repository。建置設定可使用：

1
Build command: npm run build
2
Build output directory: dist

先讓 Pages 完成第一次建置。資源 Binding 與環境變數可以在專案建立後補上。

Step 2：建立 KV、R2 與 D1#

在 Cloudflare Dashboard 建立：

1. 一個 KV namespace，保存工作階段等鍵值資料。
2. 一個 R2 bucket，保存實際圖片檔案。
3. 一個 D1 database，保存圖片 metadata 與其他結構化資料。

名稱可以自行決定。本文後續以這組名稱示範：

1
KV namespace: imgs
2
R2 bucket: media
3
D1 database: roim-picx

Step 3：設定 Production Bindings#

回到 Pages 專案，進入 Settings → Bindings。有些 Dashboard 版本會把入口放在 Settings → Functions。

新增三個 Production Binding：

1
KV namespace binding
2
Variable name: XK
3
KV namespace: imgs
4

5
R2 bucket binding
6
Variable name: PICX
7
R2 bucket: media
8

9
D1 database binding
10
Variable name: DB
11
D1 database: roim-picx

如果 D1 資料庫就叫 roim-picx，Variable name 仍然要填 DB，不能也填成 roim-picx。Cloudflare 的 Binding 是 Pages Functions 存取資源時使用的程式介面。

Step 4：加入最小環境變數#

只使用 Token 登入與 R2 儲存時，先設定以下 Production 變數：

PICX_AUTH_TOKEN 應存成 Cloudflare Secret，不要寫進 Git、Wrangler 設定檔或文章。GitHub、Google、Steam OAuth 與 Hugging Face 儲存都是選配，先完成基本部署再加比較容易排錯。

Step 5：建立本機 Wrangler 設定#

這次直接在沒有 Wrangler 設定檔的專案執行 migration 時，Wrangler 4.110.0 回傳：

1
No configuration file found. Create a wrangler.jsonc file to define your D1 database.

先登入 Cloudflare 並查出 D1 的 database ID：

1
npx wrangler login
2
npx wrangler whoami
3
npx wrangler d1 list

在專案根目錄新增 wrangler.local.jsonc：

1
{
2
  "$schema": "node_modules/wrangler/config-schema.json",
3
  "name": "roim-picx",
4
  "compatibility_date": "2026-07-15",
5
  "d1_databases": [
6
    {
7
      "binding": "DB",
8
      "database_name": "roim-picx",
9
      "database_id": "填入 d1 list 顯示的實際 ID",
10
      "migrations_dir": "migrations"
11
    }
12
  ]
13
}

這份檔案只用來讓本機 Wrangler 找到正式 D1，不需要放 Token 或 OAuth Secret。若不打算提交它，可以加入本機 repository 的 exclude：

1
echo 'wrangler.local.jsonc' >> .git/info/exclude

Step 6：一次套用所有 D1 migrations#

目前專案有 0001 到 0011 共 11 個 migration。不要只執行 0001_init.sql，否則相簿、系統設定、NSFW、API Key 等後續資料結構不會建立。

請在專案根目錄執行：

1
npx wrangler d1 migrations apply roim-picx \
2
  --remote \
3
  --config wrangler.local.jsonc

--remote 不能省略。Cloudflare 現行 Wrangler 的 D1 指令預設使用本機資料庫，沒有加上 --remote 不會初始化 Pages 正式環境使用的 D1。

完成後檢查是否還有未套用的 migration：

1
npx wrangler d1 migrations list roim-picx \
2
  --remote \
3
  --config wrangler.local.jsonc

正常應顯示沒有 migration 等待執行。也可以查詢遠端資料表：

1
npx wrangler d1 execute roim-picx \
2
  --remote \
3
  --config wrangler.local.jsonc \
4
  --command="SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;"

Step 7：重新部署並驗證#

新增 Binding 或修改環境變數後，舊 deployment 不會自動取得新設定。到 Pages 的 Deployments 對最新 Production 執行 Retry deployment，或推送一個新 commit 觸發部署。

部署列表出現新的 Production deployment 後，再測試：

1. 使用 PICX_AUTH_TOKEN 登入。
2. 上傳一張測試圖片。
3. 重新整理圖片列表。
4. 確認管理頁能讀取統計資料。

第一次安裝到這裡就完成，不需要執行歷史圖片同步。

Step 1：保留舊 R2 與 KV#

不要刪除或重建原本的 R2 bucket。舊圖片檔仍然保存在裡面，升級只是在既有架構旁新增 D1。

先把 Fork 或本機部署分支更新到新版，再確認 Cloudflare 仍綁定原有資源：

1
KV：XK → 原本的 KV namespace
2
R2：PICX → 原本的 R2 bucket

接著建立新的 D1 database，並補上：

1
D1：DB → roim-picx

Step 2：初始化 D1 並重新部署#

照前一節建立 wrangler.local.jsonc，再對遠端 D1 套用全部 migration：

1
npx wrangler d1 migrations apply roim-picx \
2
  --remote \
3
  --config wrangler.local.jsonc

確認 migration 已全部套用後，回到 Pages 重新部署 Production。這一步不能省略，因為已經在執行的舊 deployment 不會自動取得剛新增的 DB Binding。

Step 3：遇到 Token login failed 先檢查 D1#

這次升級時，登入畫面一直顯示 Token login failed，但 Token 本身沒有填錯。從專案程式碼來看，流程是先確認 Token 與 PICX_AUTH_TOKEN 相符，再檢查 ALLOW_TOKEN_LOGIN，接著才讀寫 D1、建立 system 使用者並簽發 JWT。

因此三種訊息要分開判斷：

本次真正的原因是 Production 仍在執行兩個月前的舊 deployment，新增的 D1 Binding 還沒進入正式環境。重新部署後即可登入，不需要重設 Token。這個現象也與專案的 Issue #30 相符。

Step 4：確認新版 D1 還沒有舊圖資料#

登入成功但舊圖片沒出現時，先查 images 筆數：

1
npx wrangler d1 execute roim-picx \
2
  --remote \
3
  --config wrangler.local.jsonc \
4
  --command="SELECT COUNT(*) AS image_count FROM images;"

如果 R2 有圖片、結果卻是 0，代表圖片檔仍在 R2，只是尚未把 metadata 寫入 D1，不是前端顯示錯誤。

Step 5：先 dry run R2 到 D1 同步#

不要把 Token 直接貼進 shell history。先暫存在目前終端機工作階段：

1
read -s "PICX_TOKEN?請輸入登入 Token："
2
echo

先執行 dry run，不寫入 D1：

1
curl -sS \
2
  -H "Authorization: Bearer $PICX_TOKEN" \
3
  -H "Content-Type: application/json" \
4
  -d '{"limit":100,"dryRun":true}' \
5
  "https://你的圖床網域/rest/admin/sync-r2-to-d1"

確認回傳 code: 200 後，再正式同步第一批：

1
curl -sS \
2
  -H "Authorization: Bearer $PICX_TOKEN" \
3
  -H "Content-Type: application/json" \
4
  -d '{"limit":100}' \
5
  "https://你的圖床網域/rest/admin/sync-r2-to-d1"

Step 6：依 nextCursor 同步所有批次#

每次最多處理指定的 limit。回傳內容要看兩個欄位：

1
{
2
  "nextCursor": "實際回傳的一長串 cursor",
3
  "hasMore": true
4
}

只要 hasMore 是 true，就把實際的 nextCursor 放進下一次請求：

1
curl -sS \
2
  -H "Authorization: Bearer $PICX_TOKEN" \
3
  -H "Content-Type: application/json" \
4
  -d '{"limit":100,"cursor":"貼入實際 nextCursor"}' \
5
  "https://你的圖床網域/rest/admin/sync-r2-to-d1"

不要把 貼入實際 nextCursor 這類範例文字直接送出。那不是合法的 R2 continuation token，會收到：

1
Continuation token is not valid. (10023)

如果已經找不到上一個 cursor，可以重新執行第一批請求。同步 API 會用圖片 key 檢查 D1，已經存在的圖片會計入 skipped，不會重複新增，並會再次提供下一個 cursor。

重複執行到回傳：

1
{
2
  "hasMore": false,
3
  "errors": 0
4
}

最後清除目前 shell 暫存的 Token：

1
unset PICX_TOKEN

unset 只會清除目前終端機的環境變數，不會刪除 Cloudflare Secret、D1、R2 或剛完成的同步資料。

建立 API Key#

登入 roim-picx 後，到管理頁的 API Keys 區塊建立新 Key，例如命名為：

1
Astro uploader

完整 Key 只在建立時回傳一次，格式如下：

1
px_前綴.秘密字串

請立即存進密碼管理器或自動化平台的 Secret。D1 的 api_keys 表只保存秘密字串的 SHA-256 hash，之後無法從資料庫還原完整 Key。

如果目前介面暫時找不到 API Keys 頁面，也可以先登入取得 JWT，再呼叫建立 API：

1
curl -sS -X POST \
2
  "https://你的圖床網域/rest/api-keys" \
3
  -H "Authorization: Bearer $ROIM_LOGIN_JWT" \
4
  -H "Content-Type: application/json" \
5
  -d '{"name":"Astro uploader"}'

也可以設定 ISO 8601 格式的到期時間：

1
{
2
  "name": "Astro uploader",
3
  "expires_at": "2027-01-01T00:00:00.000Z"
4
}

API Key 只會完整顯示一次

不要把 API Key 寫進 Git、Markdown 或公開的 shell 指令。請用環境變數或 Secret 管理；如果遺失，就撤銷舊 Key 並重新建立。

用 curl 上傳一張圖片#

先把 API Key 暫存在目前終端機：

1
read -s "ROIM_PICX_API_KEY?請輸入 roim-picx API Key："
2
echo

接著上傳圖片：

1
curl -sS -X POST \
2
  "https://你的圖床網域/rest/upload" \
3
  -H "X-API-Key: $ROIM_PICX_API_KEY" \
4
  -F "files=@./image.webp"

上傳 API 使用 multipart/form-data，檔案欄位名稱一定要是：

1
files

不是常見的 file 或 image。批次上傳時，重複提供多個 files：

1
curl -sS -X POST \
2
  "https://你的圖床網域/rest/upload" \
3
  -H "X-API-Key: $ROIM_PICX_API_KEY" \
4
  -F "files=@./cover.webp" \
5
  -F "files=@./content-01.png"

可傳入的 FormData 欄位#

例如上傳到文章封面目錄、保留原始檔名並加入標籤：

1
curl -sS -X POST \
2
  "https://你的圖床網域/rest/upload" \
3
  -H "X-API-Key: $ROIM_PICX_API_KEY" \
4
  -F "files=@./文章封面.webp" \
5
  -F "path=blog/covers" \
6
  -F "keepName=true" \
7
  -F "tags=blog,cover"

path 不需要自己補齊前後斜線，後端會移除開頭的 /，並在結尾補上 /。啟用 keepName 時，英文、數字、中文以及 .、_、- 可以保留，其他不支援的字元會被替換成底線。

從回傳資料取得 URL#

上傳成功後，回應中的 data 是圖片陣列：

1
{
2
  "code": 200,
3
  "msg": "",
4
  "data": [
5
    {
6
      "key": "blog/covers/example.webp",
7
      "size": 123456,
8
      "url": "https://你的圖床網域/blog/covers/example.webp",
9
      "filename": "example.webp",
10
      "delToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
11
      "storageType": "R2",
12
      "nsfw": false,
13
      "nsfwScore": 0
14
    }
15
  ]
16
}

單張上傳的圖片網址位於：

1
data[0].url

取得這個值後，就能直接寫入 Astro 文章的 image frontmatter，或插入 Markdown 圖片語法。

Node.js／TypeScript 串接範例#

以下函式會上傳本機 WebP，並直接回傳圖片 URL：

1
import { readFile } from "node:fs/promises";
2
import { basename } from "node:path";
3

4
interface UploadResponse {
5
  code: number;
6
  msg: string;
7
  data?: Array<{ url?: string }>;
8
}
9

10
export async function uploadImage(filePath: string): Promise<string> {
11
  const fileBuffer = await readFile(filePath);
12
  const formData = new FormData();
13

14
  formData.append(
15
    "files",
16
    new Blob([new Uint8Array(fileBuffer)], { type: "image/webp" }),
17
    basename(filePath),
18
  );
19
  formData.append("path", "blog/covers");
20
  formData.append("keepName", "true");
21

22
  const apiKey = process.env.ROIM_PICX_API_KEY;
23
  if (!apiKey) {
24
    throw new Error("ROIM_PICX_API_KEY is not configured");
25
  }
26

27
  const response = await fetch("https://你的圖床網域/rest/upload", {
28
    method: "POST",
29
    headers: {
30
      "X-API-Key": apiKey,
31
    },
32
    body: formData,
33
  });
34

35
  const result = (await response.json()) as UploadResponse;
36
  if (!response.ok || result.code !== 200) {
37
    throw new Error(`Upload failed: ${response.status} ${result.msg}`);
38
  }
39

40
  const url = result.data?.[0]?.url;
41
  if (!url) {
42
    throw new Error(`Upload succeeded but URL was missing: ${JSON.stringify(result)}`);
43
  }
44

45
  return url;
46
}

執行完測試後，清除目前 shell 的 API Key：

1
unset ROIM_PICX_API_KEY

API Key 出現 no such table 時怎麼處理？#

若建立或驗證 API Key 時出現：

1
no such table: api_keys

代表 D1 還沒有套用建立 api_keys 表的後續 migration。請回到前面的 D1 步驟，執行所有尚未套用的 migration：

1
npx wrangler d1 migrations apply roim-picx \
2
  --remote \
3
  --config wrangler.local.jsonc

這也是不能只執行 0001_init.sql 的另一個實際原因。

Q: roim-picx 的 D1 database 一定要叫 picx-db 嗎？#

A: 不需要。D1 資料庫可以叫 roim-picx、picx-db 或其他名稱；真正固定的是 Pages Functions 的 Variable name 必須是 DB。Wrangler 指令中的資料庫名稱也要改成你實際建立的名稱。

Q: 為什麼不能只執行 0001_init.sql？#

A: 0001_init.sql 只建立初始結構。目前實測版本還有 0002 到 0011，包含後續登入方式、儲存類型、系統設定、相簿、NSFW、效能索引與 API Key 等變更。使用 wrangler d1 migrations apply 才會依序套用並記錄所有 migration。

Q: Token login failed 是否代表 PICX_AUTH_TOKEN 填錯？#

A: 不一定。程式在 Token 已匹配、且 ALLOW_TOKEN_LOGIN 開啟後，仍要讀寫 D1；這段發生例外也會顯示 Token login failed。新版剛升級時，應先檢查 D1 是否完成 migration、Production 是否綁定 DB，以及修改 Binding 後是否真的重新部署。

Q: 同步舊圖會把 R2 圖片搬進 D1 嗎？#

A: 不會。R2 繼續保存圖片檔，D1 只新增圖片 key、大小、類型、資料夾、上傳者與建立時間等 metadata。同步完成後，新版才能從 D1 列出與管理原本的 R2 圖片。

Q: roim-picx 可以用 API 上傳圖片並直接取得網址嗎？#

A: 可以。建立 px_ 開頭的 API Key 後，使用 X-API-Key Header 呼叫 POST /rest/upload，並以 multipart/form-data 的 files 欄位上傳圖片。成功後可從回應的 data[0].url 取得公開網址，適合接圖片生成、排程產文或 Astro frontmatter 更新流程。

Q: roim-picx 和 CloudFlare-ImgBed 應該選哪一個？#

A: 如果需求集中在自用圖床、R2 圖片、網頁管理、相簿與 API 上傳，roim-picx 的範圍比較接近這篇的使用情境。若還需要一般檔案、WebDAV、多種儲存後端或個人雲端硬碟功能，則可以評估 CloudFlare-ImgBed。真正的差異是需求範圍，不是單看哪個功能數量更多。

參考資料：

roimdev/roim-picx GitHub repository

MarSeventh/CloudFlare-ImgBed GitHub repository

Cloudflare D1 Migrations

Cloudflare Wrangler D1 Commands

Cloudflare Pages Functions Bindings

roim-picx Issue #30：Token 登入失敗