Self-hosted image host: upload, tags, WebP/AVIF variants, expiry, and a public random-image API.

1.0.0 runs the admin UI and the API on one Cloudflare Worker. Open the Worker hostname (workers.dev or a Custom Domain) and the UI is there. There is no Vercel app and no second frontend deploy.

Image files live in R2 and are served from R2_PUBLIC_URL (object CDN and /cdn-cgi/image). That is storage, not a second app.

中文 · Changelog · API · Deploy

Public HTTP routes are unchanged. GET /api/random still returns 302 to an image URL.

flowchart TB
    subgraph Client
        Browser[Browser]
        APIClient[API client]
    end

    subgraph Worker["Cloudflare Worker"]
        Assets["Static Assets<br/>/ and /manage"]
        Hono["Hono /api/*"]
    end

    subgraph CF["Cloudflare"]
        R2[("R2")]
        D1[("D1")]
        KV[("KV")]
        Queue[Queues]
        Images[Images binding]
        Cron[Cron]
    end

    Browser --> Assets
    Browser --> Hono
    APIClient --> Hono
    Hono --> R2
    Hono --> D1
    Hono --> KV
    Hono --> Queue
    Hono --> Images
    Cron --> Hono
    Browser -->|"image bytes"| R2

Static HTML/JS/CSS does not invoke the Worker. assets.run_worker_first is ["/api/*"] only.

GIF is original-only. JPEG/PNG larger than 20MB skip the Images binding; variant URLs may use /cdn-cgi/image. Advertised max upload is 70MB.

• JPEG, PNG, GIF, WebP, AVIF upload
• Stored WebP/AVIF for files within the Images .input() limit (20MB)
• Tags, batch tag edits, expiry
• Public GET /api/random with orientation, tags, exclude, format
• ZIP upload in the browser (extract, then concurrent POST /api/upload/single)
• Dark mode management UI

Configured in wrangler.jsonc:

USE_QUEUE is true: R2 deletes go through the queue. Forks can set it to false for synchronous deletes.

Requires Node.js 24+ and pnpm.

git clone https://github.com/Yuri-NagaSaki/CattoPic.git
cd CattoPic
pnpm install
pnpm dev       # http://localhost:5173  (UI + API)
pnpm build
pnpm run deploy    # vite build && wrangler deploy
pnpm typecheck
pnpm test

pnpm wrangler login
pnpm wrangler d1 migrations apply CattoPic-D1 --remote
pnpm wrangler d1 execute CattoPic-D1 --remote --command "
INSERT OR IGNORE INTO api_keys (key, created_at) VALUES ('your-secure-api-key', datetime('now'));
"
pnpm run deploy

Then open https://cattopic-worker.<subdomain>.workers.dev (or your Custom Domain). Paste the API key in the UI.

curl -I "https://cattopic-worker.<subdomain>.workers.dev/api/random"

Enable public access on the R2 bucket and set vars.R2_PUBLIC_URL in wrangler.jsonc.

Forks: copy wrangler.example.jsonc to wrangler.jsonc and fill D1/KV ids.

GitHub Actions uses CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. Config is the committed wrangler.jsonc.

Full steps: DEPLOYMENT.md.

Public: GET /api/random (302 to an image URL). Query: orientation, tags, exclude, format. Follow redirects with curl -L if you want the file.

Everything else needs Authorization: Bearer <api-key>.

Full reference: docs/API_EN.md / docs/API.md.

GPL-3.0