使用 Docker Compose 部署 SlideStage Pro

这是一份面向操作者的快速部署指南。它帮助你在一台 Linux VPS 上启动 SlideStage Pro，并完成首次管理员登录。

完整运维细节见 docs/DEPLOYMENT.md。本指南只覆盖最小可用路径。

前提条件

服务器需要：

• Linux。
• Docker Engine 24 或更新版本。
• Docker Compose v2。
• 至少 1 vCPU、1 GB RAM。
• 可访问 npm registry，因为构建时会安装 @slidestage/* 包。

默认服务使用 HTTP 80 端口。生产 HTTPS 建议在前面放 Caddy、Traefik、Cloudflare Tunnel 或其他 TLS 终止器。

1. 获取代码

git clone <your-fork-url> slidestage-pro
cd slidestage-pro

2. 配置环境变量

复制模板：

cp .env.example .env

编辑 .env，至少设置：

BETTER_AUTH_SECRET=<openssl rand -base64 32>
BETTER_AUTH_URL=https://decks.example.com
BOOTSTRAP_ADMIN_EMAIL=admin@example.com
BOOTSTRAP_ADMIN_PASSWORD=<strong-password>
BOOTSTRAP_ADMIN_NAME=Admin

关键变量说明：

• BETTER_AUTH_SECRET：Better Auth 会话签名密钥。
• BETTER_AUTH_URL：用户实际访问的公开 URL，必须和浏览器地址一致，否则登录 cookie 可能失效。
• BOOTSTRAP_ADMIN_EMAIL：首次启动时创建的管理员邮箱。
• BOOTSTRAP_ADMIN_PASSWORD：首次管理员密码，登录后建议修改。
• UPLOAD_MAX_BYTES：上传 .stage 的大小限制，默认 100 MiB。
• HTTP_PORT：Compose 暴露的 HTTP 端口，默认 80。

不要提交 .env。

3. 构建并启动

docker compose build
docker compose up -d

查看 API 日志：

docker compose logs -f api

首次启动时，如果数据库中没有用户，API 会创建 bootstrap 管理员。

4. 健康检查

在服务器上运行：

curl http://localhost/api/health

成功时返回类似：

{
  "status": "ok",
  "version": "0.1.0",
  "checks": {
    "db": "ok",
    "storage": "ok"
  }
}

如果返回 503 或 status: degraded，先检查数据库和 /data 持久化卷是否可写。

5. 首次登录

打开：

https://decks.example.com/login

使用 .env 中的 bootstrap 管理员登录。登录后进入设置页，创建邀请链接，再邀请普通用户注册。

SlideStage Pro 默认是关闭开放注册的。没有有效邀请 token 的注册请求会被拒绝。

6. 持久化数据

Compose 使用 slidestage-data volume 保存：

• SQLite 数据库：用户、session、deck 元数据、笔记、批注、邀请。
• .stage 文件：/data/decks/<deckId>/<versionId>.stage。

备份时要同时备份整个 volume，而不是只备份数据库文件。

7. 更新版本

常规更新流程：

git pull
docker compose build
docker compose up -d
curl http://localhost/api/health

容器启动时会自动执行 Prisma migration。迁移文件应随代码提交，不要在生产服务器上手写数据库结构。

故障排查

登录后马上退出

检查 BETTER_AUTH_URL 是否等于用户访问的公开 URL。协议、域名和端口不一致都会影响 cookie。

上传失败

检查：

• .stage 是否能通过 Lite 或 packer 校验。
• 文件是否超过 UPLOAD_MAX_BYTES。
• /data volume 是否可写。

构建失败

确认构建环境能访问 registry.npmjs.org。Pro 通过 semver 安装 Lite 发布的 @slidestage/* 包，不依赖本地 SlideStageLite checkout。