面向 Web 开发者的 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 版 Maxisnap 和 Mac 版 Maxisnap 会通过一次请求把每次上传发送到 Cloudflare 版 Studio，而 Studio 对每个文件最多接受 25 MB。
• Cloudflare 版还提供了用于较大文件的分块上传 API，《Developer guide》中有说明：api/upload/start、part 和 complete。
• 分享页面及其媒体文件使用这些路径；其他所有路径都是内部路径：/<slug> /<slug>.<ext>

以后更新或移除它

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 调用。