給網頁開發人員的 Studio 設定

取得 Studio 下載檔

使用擁有 Studio 的帳戶登入 Maxisnap，然後：

• 在 Windows 上：在 Maxisnap 中開啟「設定 → 帳戶 → Maxisnap Studio 設定精靈」，按一下「開始使用」，再按一下「下載儀表板」。Maxisnap 會把 Studio ZIP 檔儲存到你的「下載」資料夾，並開啟該資料夾。
• 在 Mac 上：在 Maxisnap 中開啟「Settings → Welcome & Help → Studio Setup Guide」，按一下「Get Started」，再按一下「Download Dashboard」。Maxisnap 會把 Studio ZIP 檔儲存到你的「下載項目」資料夾。

解壓縮 ZIP 檔。在 Windows 上，請以滑鼠右鍵按一下該檔案，選擇「全部解壓縮」。在 Mac 上，按兩下即可。

Maxisnap-Studio-v<version>/
  Maxisnap Studio - Start Here.html   guided setup (branding + every route)
  snaps/                              PHP edition: upload this folder to a web host
  cloudflare/                         Cloudflare Workers edition (Worker + R2 + D1)
    deploy/cli.mjs                    deploys it through the Cloudflare API (Node 20+)
  docs/Developer guide.html           architecture, upload API, security, updates
  docs/Cloudflare setup - technical brief.html
  AGENTS.md                           instructions for AI coding assistants

完整的「Developer guide」涵蓋架構、上傳 API、金鑰與角色、安全模型，以及疑難排解。它在下載檔中的位置是 docs/Developer guide.html。

PHP 版：上傳並完成設定

1. 把 snaps 資料夾上傳到網站根目錄，並包含其中隱藏的 .htaccess 檔案，使最終路徑為 public_html/snaps/index.php。Start Here 頁面產生的品牌化 snaps.zip 做法相同：直接在原處解壓縮，不要變成 snaps/snaps 這樣的巢狀資料夾。
2. 請先開啟 https://yourcompany.com/snaps/ 一次。設定頁面會檢查 PHP 和資料夾權限，並建議一組 40 個字元的管理員金鑰；金鑰至少需要 16 個字元。複製它，然後按一下「Create my dashboard」。
3. 在 nginx 上，請依照 snaps/.htaccess 建立相同的路由與拒絕規則。uploads、data 和 branding 請維持不公開。

設定頁面會寫入 your-settings.php，更新時會保留它：

'dashboard_key' => '…',          // the Admin key; the setup page writes it
'base_url'      => 'https://yourcompany.com/snaps',  // the address setup was opened at; fix it here if share links come out wrong
'max_upload_mb' => 500,          // your host's PHP limits still apply

Cloudflare 版：從終端機部署

隨附的 CLI 會先讀取帳戶，顯示一份計畫，說明它會建立什麼、不會動到什麼，並拒絕已被使用的名稱。如果部署中途停止，再執行一次相同的指令，就會接著進行，不會重複建立任何東西。

cd cloudflare
# Option 1: the bundled CLI (Node 20+; plan first, then --yes). PowerShell:
$env:CLOUDFLARE_API_TOKEN = "<token: Account Settings Read; Workers Scripts, R2 and D1 Edit;
                              for --zone/--hostname also Zone Read, DNS Read, Workers Routes Read>"
node deploy/cli.mjs whoami
node deploy/cli.mjs plan --account <account id> --name snaps
#   no workers.dev name on the account yet? The plan asks you to "Choose your free
#   workers.dev name": add --subdomain <your-company> to both commands (account-wide).
#   A subdomain of your domain as well: add --zone <zone id> --hostname snaps.example.com
node deploy/cli.mjs deploy --account <account id> --name snaps --yes
#   prints the Studio address and the Admin key once, and writes deployment.json here

# Option 2: plain Wrangler (create the bucket and database, set their ids in wrangler.jsonc)
npm install
npx wrangler r2 bucket create maxisnap-studio-media
npx wrangler d1 create maxisnap-studio
npx wrangler secret put ADMIN_KEY
npm run sync
npx wrangler deploy

部署作業只會顯示一次 Studio 網址和管理員金鑰，並在執行它的資料夾中寫入 deployment.json。請保留該檔案：update 和 remove 會用到它。

確認它能正常運作

curl.exe -s -H "X-Dashboard-Key: <Admin key>" https://<studio address>/api/health.php
# {"ok":true,"app":"Maxisnap Studio","version":"…"}   the Cloudflare edition adds "edition":"cloudflare"

接著在瀏覽器中開啟 Studio 網址，並使用管理員金鑰登入。401 表示金鑰錯誤；404 表示網址或資料夾錯誤。

連接 Maxisnap

• Windows 版 Maxisnap：開啟「設定 → 帳戶 → Maxisnap Studio 設定精靈」，按一下「開始使用」，然後一直按「下一步」，直到第 4 步「連接 Maxisnap」。貼上 Studio 網址和金鑰，按一下「測試連線」，再按「下一步」，到最後一頁時按一下「完成並儲存」。設定時取得的管理員金鑰可以使用，儀表板「People & access」中的上傳代碼也可以。
• Mac 版 Maxisnap：開啟「Settings → Welcome & Help → Studio Setup Guide」，選擇「I already have a dashboard」。貼上 Studio 網址和金鑰，按一下「Test Connection」，再按「Next」，最後按一下「Finish & Save」。

了解上傳 API

• Maxisnap 應用程式會透過 X-Dashboard-Key 標頭上傳到 api/upload.php。系統接受圖片（PNG、JPG、GIF 和 WebP）與影片（MP4、WebM 和 MOV）。
• Windows 版和 Mac 版 Maxisnap 會以單一請求把每次上傳送到 Cloudflare 版 Studio，而它每個檔案最大可接受 25 MB。
• Cloudflare 版還提供適用於較大檔案的分段上傳 API，「Developer guide」中有說明：api/upload/start、part 和 complete。
• 分享頁面及其媒體檔案使用下列路徑；其他所有路徑都是內部使用的：/<slug> /<slug>.<ext>

日後更新或移除 Studio

PHP：只替換 snaps/How to update.txt 中列出的檔案，然後清除主機和 CDN 的快取。擷取內容、成員、品牌設定和各項設定都會保留。

Cloudflare：請在較新套件的 cloudflare 資料夾中執行下列指令，並先把舊的 deployment.json 複製進去。

# Update: from a newer package's cloudflare folder, with the old deployment.json copied in
node deploy/cli.mjs update --record deployment.json --yes
# New Admin key (shown once):
node deploy/cli.mjs update --record deployment.json --yes --new-admin-key
# Remove the custom domain and the Worker; the bucket and database (the captures) stay
node deploy/cli.mjs remove --record deployment.json --yes
# Also delete every capture: cannot be undone
node deploy/cli.mjs remove --record deployment.json --yes --delete-data

閱讀 Cloudflare 技術簡介：每一項資源、權限和 API 呼叫。