部落格圖片作業流水線 — 零成本、零帳單風險的完整方案

每次做靜態站，圖片管理都是讓人頭大的問題。

WordPress 年代有媒體庫，上傳、壓縮、CDN 全部包辦。切換到 Astro 之後，第一個踩到的坑就是：**圖片到底放哪裡？**我們在設計 Agentic Blog 的時候，列出了所有主流方案，逐一測試風險，最後走出一條零成本、零帳單風險的路。這篇文章把完整設計記錄下來。

我們踩過的坑，以及為什麼不用那些方案

在確定現在的架構之前，我們評估了以下選項：

Cloudflare R2 — 看起來免費，實際上有帳單風險。10 GB 免費，但一旦超過，每 GB 收 $0.015。更麻煩的是，R2 的帳單邏輯是「用了才知道」，監控設定繁瑣，對一個小 blog 來說不值得。

Git LFS — 這是社區公認的陷阱，後面會單獨說明。

Google Drive 直連 — 流量稍大就 403 限流。Google Drive 從來不是 CDN，不應該當 CDN 用。

imgix / Bunny CDN — 根本沒有免費 tier，直接排除。

Cloudinary — 有 25 credits 免費限制，小 blog 大概夠用，但既然 Cloudflare Pages 本身就能做到同樣的事，再多一個第三方帳號只是多一個管理負擔。

最後我們的答案是：Cloudflare Pages 的靜態檔案 CDN 就是我們需要的一切。 帶寬無限免費，全球邊緣節點，自動 HTTPS，不需要額外設定一個字。

1. 全局架構

整個圖片 pipeline 分成五層：來源、Google Drive SSoT、本地作業、Astro Build、CF Pages CDN。

flowchart TB
    subgraph 來源["圖片來源"]
        CANVA["Canva Pro 素材庫\n夏哥挑選"]
        GEMINI["Gemini API 生圖\n$0.039/張（備用）"]
        MANUAL["手動上傳\n截圖、照片"]
    end

    subgraph DRIVE["Google Drive SSoT"]
        STOCK["blog-assets/agentic/\nstock-library/\n001.webp ~ 210.webp\n（19.6 MB）"]
    end

    subgraph 本地["本地作業（SS1 Mac）"]
        PULL["rclone pull\n從 Drive 拉素材"]
        LOCAL_STOCK["public/images/\nstock-library/\n（.gitignore 不進 repo）"]
        SCRIPT["generate-cover.py\n--slug 或 --all"]
        MAPPING["cover-mapping.json\n文章↔素材配對表"]
        COVER_OUT["public/images/covers/\nagentic-{slug}-cover.png\n（1200×630）"]
        BODY_IMG["src/content/posts/\nattachments/\n（文內圖）"]
        SATORI["Satori OG Endpoint\nsrc/pages/og/[...slug].png.ts\n（1200×630 自動生成）"]
    end

    subgraph BUILD["Astro Build"]
        SHARP["Sharp 圖片優化\nPNG/JPG → WebP\n7 個響應式尺寸"]
        DIST["dist/\n部署產物"]
    end

    subgraph CDN["Cloudflare Pages CDN"]
        EDGE["全球邊緣節點\n免費無限帶寬\n自動 HTTPS"]
        READER["讀者瀏覽器\n最近節點取圖"]
    end

    CANVA -->|"下載 zip"| STOCK
    GEMINI -->|"API 輸出"| STOCK
    MANUAL -->|"上傳"| STOCK

    STOCK -->|"rclone pull"| PULL
    PULL --> LOCAL_STOCK
    LOCAL_STOCK --> SCRIPT
    MAPPING --> SCRIPT
    SCRIPT -->|"PIL 合成\n素材圖 + 暗色 overlay\n+ 標題 + 分類 pill\n+ 品牌水印"| COVER_OUT

    COVER_OUT -->|"進 repo"| SHARP
    BODY_IMG -->|"進 repo"| SHARP
    SATORI -->|"build-time\n自動生成"| DIST

    SHARP -->|"優化壓縮"| DIST
    DIST -->|"wrangler pages deploy\n或 git push → 自動 build"| EDGE
    EDGE --> READER

關鍵設計決策：素材圖（stock-library）不進 repo，透過 .gitignore 排除，只有最終合成的 cover PNG 才進 repo。這樣 repo 只存放真正需要版本控制的產出物，不會因為原始素材庫膨脹而拖累 git 效能。

2. 三種圖片類型

Agentic Blog 的圖片分三類，各自有不同的存放路徑、生成方式和 CDN 行為：

Cover 圖是唯一需要手動觸發生成的類型。OG 圖由 Satori 在 astro build 時自動生成，完全不需要人工介入。Body 圖直接放進 attachments/ 資料夾，由 Astro 的 Sharp integration 在 build 時優化成 7 個響應式尺寸。

3. Cover 生成流程

封面圖是整個 pipeline 中最有意思的環節。我們不用 AI 生圖（成本和一致性都是問題），而是從 Canva Pro 素材庫挑選 210 張高品質 WebP 作為原料，再用 generate-cover.py 批量合成風格一致的封面。

sequenceDiagram
    participant 夏哥
    participant Canva as Canva Pro
    participant Drive as Google Drive
    participant Agent as 小克 (Agent)
    participant Script as generate-cover.py
    participant Repo as Git Repo
    participant CF as CF Pages CDN

    夏哥->>Canva: 搜尋素材圖
    夏哥->>Canva: 挑選 + 下載 zip
    夏哥->>Drive: 上傳到 blog-assets/agentic/stock-library/

    Note over 夏哥: 以上一次性（已完成 210 張）

    夏哥->>Agent: 寫新文章
    Agent->>Agent: rclone pull Drive → 本地 stock-library/
    Agent->>Agent: 編輯 cover-mapping.json（配對素材編號）
    Agent->>Script: python3 generate-cover.py --slug {slug}

    Script->>Script: 載入素材圖（WebP/PNG）
    Script->>Script: Resize + Center Crop → 1200×630
    Script->>Script: 漸層暗色 Overlay（上淺下深）
    Script->>Script: 4px Terra Cotta 左色條
    Script->>Script: 分類 Pill（專案身份色）
    Script->>Script: 標題文字（PingFang 48px）
    Script->>Script: SUPERPORTIA AGENTIC 水印
    Script-->>Agent: 輸出 PNG → public/images/covers/

    Agent->>Repo: git add + commit
    Repo->>CF: push → 自動 build + deploy
    CF-->>夏哥: 文章上線，封面圖從最近邊緣節點載入

generate-cover.py 做的事情：

1. 從 cover-mapping.json 讀取 slug → 素材編號的配對
2. 用 PIL 把素材圖 resize + center crop 到 1200×630
3. 疊加漸層暗色 overlay（上方較透明、下方較深，讓文字可讀）
4. 在左側畫 4px Terra Cotta 色條（品牌識別）
5. 根據文章分類畫對應身份色的分類 pill
6. 渲染標題文字（PingFang SC，48px）
7. 加上 SUPERPORTIA AGENTIC 品牌水印
8. 輸出到 public/images/covers/agentic-{slug}-cover.png

單次執行指令：

# 生成單篇文章的封面
python3 scripts/generate-cover.py --slug agentic-blog-image-pipeline

# 批量生成所有文章的封面（初次設定或素材更新後）
python3 scripts/generate-cover.py --all

# 從 Drive 拉取最新素材（需先設定 rclone）
rclone copy gdrive:blog-assets/agentic/stock-library/ public/images/stock-library/

命名規則保持一致：

4. 為什麼不用 R2、Git LFS、Google Drive 直連

這是整個設計中最重要的決策之一，值得詳細說明。

CF Pages 靜態檔案 CDN 的優勢在於：超過限制時的行為是「拒絕部署」而不是「繼續服務並收費」。 這是本質上的安全差異。20,000 檔的免費上限到達後，wrangler 會報錯、部署停止，不會悄悄升級你的方案。

5. 費用分析：每個環節都是 $0

目前架構中，每一個超限事件的後果都是「服務停止」而不是「帳單增加」。這是我們選擇這套方案的核心原因：不需要盯著 billing dashboard，也不需要設定帳單警報。

6. 監控清單

雖然不會意外收費，但仍需要定期確認各項指標沒有接近警戒線：

建議每月跑一次以下腳本，輸出簡短的健康報告：

#!/bin/bash
# check-image-health.sh — 每月跑一次
echo "= Agentic Blog 圖片管線健康檢查 ="
echo ""
echo "Repo 大小:"
git count-objects -vH | grep size-pack
echo ""
echo "Cover 圖數量: $(ls public/images/covers/*.png 2>/dev/null | wc -l | tr -d ' ') 張"
echo "Stock 素材數量: $(ls public/images/stock-library/*.webp 2>/dev/null | wc -l | tr -d ' ') 張"
echo "Body 圖數量: $(find src/content/posts/attachments/ -type f 2>/dev/null | wc -l | tr -d ' ') 張"
echo ""
echo "public/images 總大小: $(du -sh public/images/ 2>/dev/null | cut -f1)"
echo ""
echo "最大的 5 張 Cover 圖:"
ls -lhS public/images/covers/*.png 2>/dev/null | head -5 | awk '{print $5, $9}'

7. 容量規劃

根據目前的發文節奏（每週 2-3 篇），我們做了以下估算：

遷移觸發點：repo 超過 500 MB 或源圖超過 200 張時，搬到 CF R2（零出口費）。

CF R2 在遷移發生後依然是安全選項：零出口費意味著圖片被讀取不產生費用，超過 10 GB 免費額度才以 $0.015/GB 計費，而那個時候 blog 應該已經有足夠的商業理由支撐這點小額費用。

8. 我們的觀點

工具清單

相關文件

• Agentic Blog Image Pipeline — 本文對應的 vault spec（完整規格）
• Image Pipeline — Complete Rules & Recommendation — 早期規劃（已被現行設計取代）
• Astro Modular Components — 圖片相關元件（ImageWrapper、ImageGallery、Lightbox）
• Google Drive Image SSoT — Drive 資料夾結構詳細說明
• Agentic — 專案 MOC