# 使用 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. 获取代码

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

## 2. 配置环境变量

复制模板：

```bash
cp .env.example .env
```

编辑 `.env`，至少设置：

```dotenv
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. 构建并启动

```bash
docker compose build
docker compose up -d
```

查看 API 日志：

```bash
docker compose logs -f api
```

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

## 4. 健康检查

在服务器上运行：

```bash
curl http://localhost/api/health
```

成功时返回类似：

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

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

## 5. 首次登录

打开：

```text
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. 更新版本

常规更新流程：

```bash
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。