# 存储、备份与限制

Oleafly Server 的全部设置、把文件存放在磁盘或 S3 存储桶中、编译出的 PDF、在代理后运行、同一网络下班级的限制和每个账户的限制、日志、备份、恢复与更新。

本页介绍 Oleafly Server 的日常运行。要安装它，请从[运行协作服务器](/docs/collaboration/server/)开始。

## 设置

服务器从环境变量读取设置。已设置但为空的变量视为未设置。如果某项设置缺失或格式有误，服务器不会启动，其日志会说明是哪一项。

| 变量 | 作用 | 默认值 |
| --- | --- | --- |
| `OLEAFLY_PUBLIC_URL` | 人们在 Oleafly 中输入的 HTTPS 地址。它可以包含路径，例如 `https://www.cs.example.edu/oleafly`。必填。Compose 和 Coolify 文件会替你设置它。 | 无 |
| `OLEAFLY_BIND` | 服务器监听的地址和端口。 | `0.0.0.0:8080` |
| `OLEAFLY_DATA_DIR` | 存放数据库和已存储文件的文件夹。 | `/data` |
| `OLEAFLY_SERVER_NAME` | 人们在 Oleafly 中看到的名称，例如 `Smith Lab`。 | `Oleafly Server` |
| `OLEAFLY_SERVER_ICON_URL` | 显示在名称旁边的方形图片的 HTTPS 地址。 | 无 |
| `OLEAFLY_SETUP_CODE` | 你自己的一次性设置码：至少 12 个字母或数字，愿意的话可以加连字符或空格。不设置时，服务器会自己生成一个。 | 自动生成 |
| `OLEAFLY_GITHUB_CLIENT_ID`、`OLEAFLY_GITHUB_CLIENT_SECRET` | 开启 GitHub 登录。 | 关闭 |
| `OLEAFLY_GITHUB_URL` | GitHub Enterprise Server 的地址。 | `https://github.com` |
| `OLEAFLY_GITHUB_API_URL` | GitHub API 地址，适用于你的地址不寻常的情况。 | `https://api.github.com`，或 `OLEAFLY_GITHUB_URL` 下的 `/api/v3` |
| `OLEAFLY_GITHUB_LABEL` | GitHub 登录按钮上的文字。 | `GitHub` |
| `OLEAFLY_OIDC_<NAME>_ISSUER`、`OLEAFLY_OIDC_<NAME>_CLIENT_ID`、`OLEAFLY_OIDC_<NAME>_CLIENT_SECRET` | 开启名为 `<NAME>` 的 OpenID Connect 提供方。 | 关闭 |
| `OLEAFLY_OIDC_<NAME>_LABEL` | 它的登录按钮上的文字，例如 `University login`。 | `<NAME>` |
| `OLEAFLY_OIDC_<NAME>_TRUST_EMAIL` | 把这个提供方给出的每个电子邮箱地址都视为已验证。请先阅读[已验证的电子邮箱地址](/docs/collaboration/server-access/#verified-email-addresses)。 | `false` |
| `OLEAFLY_SMTP_URL`、`OLEAFLY_MAIL_FROM` | 电子邮件。请阅读[电子邮件](/docs/collaboration/server-access/#email)。 | 关闭 |
| `OLEAFLY_OPEN_SIGNUP` | 让任何用你的某个提供方登录的人都得到一个成员账户。请阅读[开放注册](/docs/collaboration/server-access/#open-sign-up)。 | `false` |
| `OLEAFLY_WEB` | 开启浏览器访问。请阅读[浏览器访问](/docs/collaboration/server-access/#browser-access)。 | `false` |
| `OLEAFLY_BLOB_STORE` | 图片和 PDF 等文件的存放位置。`fs` 把它们放在 `OLEAFLY_DATA_DIR` 中。像 `s3://lab-bucket` 或 `s3://lab-bucket/oleafly` 这样的地址会把它们放在存储桶中。 | `fs` |
| `OLEAFLY_S3_ENDPOINT` | Amazon S3 以外的 S3 兼容存储的地址，例如 MinIO 或 Cloudflare R2。使用 Amazon S3 时请留空。 | Amazon S3 |
| `OLEAFLY_S3_REGION` | 存储桶所在的区域。 | `us-east-1` |
| `OLEAFLY_S3_ACCESS_KEY_ID`、`OLEAFLY_S3_SECRET_ACCESS_KEY` | 服务器访问存储桶所用的密钥。使用 `s3://` 地址时必填。 | 无 |
| `OLEAFLY_MAX_PROJECT_MB` | 服务器接受的最大项目，单位为 MB。 | `200` |
| `OLEAFLY_MAX_FILE_MB` | 单个文件的最大大小，单位为 MB。 | `50` |
| `OLEAFLY_MAX_MEMBERS_PER_PROJECT` | 一个项目最多可以有多少人。 | `20` |
| `OLEAFLY_ACCOUNT_STORAGE_MB` | 一个账户拥有的所有项目最多可以存储多少数据，单位为 MB。请阅读[每个账户的限制](#limits-per-account)。 | 无限制，开放注册时为 `100` |
| `OLEAFLY_MAX_PROJECTS_PER_ACCOUNT` | 一个账户最多可以拥有多少个共享项目。 | 无限制，开放注册时为 `50` |
| `OLEAFLY_UPLOADS_PER_HOUR` | 一个账户在一小时内最多可以上传多少次文件和快照。 | 无限制，开放注册时为 `300` |
| `OLEAFLY_SIGN_IN_BURST` | 同一个网络地址在一次突发中最多可以发出多少个登录请求。一次登录大约需要六个请求，所以默认值足以让同一个地址下的 50 人同时登录。 | `300` |
| `OLEAFLY_SIGN_IN_PER_MINUTE` | 突发用完后，同一个网络地址每分钟恢复多少个登录请求的额度。 | `120` |
| `OLEAFLY_EMAIL_LINKS_PER_IP` | 15 分钟内，服务器向同一个网络地址下的人最多发送多少封登录邮件。 | `100` |
| `OLEAFLY_EMAIL_LINKS_PER_ADDRESS` | 15 分钟内，同一个电子邮箱地址最多可以收到多少封登录邮件。它不能超过 `OLEAFLY_EMAIL_LINKS_PER_IP`。 | `3` |
| `OLEAFLY_DEVICE_CODES_PER_IP` | 10 分钟内，同一个网络地址下的人最多可以请求多少个登录码。 | `100` |
| `OLEAFLY_SNAPSHOT_MEMORY_MB` | 服务器构建项目快照时最多可以使用多少内存，单位为 MB。 | 容器内存上限的一半，没有上限时为 `1024` |
| `OLEAFLY_BEHIND_PROXY` | 从你的代理添加的 `X-Forwarded-For` 头中获取每个人的地址。Compose、Coolify 和 Render 的文件会开启它。 | `false` |
| `OLEAFLY_PROXY_HOPS` | 每个请求到达服务器之前要经过多少个代理。它需要 `OLEAFLY_BEHIND_PROXY=true`。 | `1` |
| `OLEAFLY_LOG_LEVEL` | 服务器记录多少日志：`error`、`warn`、`info`、`debug` 或 `trace`。除非选择 `debug` 或 `trace`，服务器使用的库只记录警告。 | `info` |
| `OLEAFLY_SECURITY_LOG_DAYS` | 安全日志条目、项目访问日志条目以及已答复或已过期的访客邀请保留多少天。 | `365` |
| `OLEAFLY_ARCHIVE_DAYS` | 项目所有者停止共享后，项目保留多少天。 | `30` |
| `OLEAFLY_POLL_HOLD_SECONDS` | 没有待处理的编辑时，服务器让一个长轮询请求保持打开多长时间，取值为 1 到 40 秒。请把它设得比服务器前面任何代理的空闲超时短几秒。 | `25` |

在 Compose 的 `.env` 文件中，如果值包含 `$` 或 `#`，请用单引号括起来。保存密钥的设置也可以从文件中读取。请阅读[不要把密钥放进 .env](/docs/collaboration/server/#keep-secrets-out-of-env)。

## 存储

默认情况下，服务器把所有内容都放在 `OLEAFLY_DATA_DIR` 中：数据库、人们共享的文件以及项目快照。快照是每个项目的已保存副本，让人们能快速加入并跟上进度。

### 存储桶中的文件

服务器可以改为把文件和快照保存在 Amazon S3 中，或保存在其他具有 S3 兼容 API 的存储中，例如 MinIO 或 Cloudflare R2。无论哪种方式，数据库都留在 `OLEAFLY_DATA_DIR` 中，所以服务器仍然需要它的数据文件夹。

1. 创建一个存储桶，并阻止对它的公开访问。
2. 创建一个只能对该存储桶读取、写入和删除对象的密钥。在 Amazon S3 上，这意味着对 `arn:aws:s3:::lab-bucket/*` 授予 `s3:GetObject`、`s3:PutObject` 和 `s3:DeleteObject`；如果使用文件夹，则对 `arn:aws:s3:::lab-bucket/oleafly/*` 授予。
3. 设置这些变量，例如写在 `.env` 中：

   ```sh
   OLEAFLY_BLOB_STORE=s3://lab-bucket/oleafly
   OLEAFLY_S3_REGION=eu-west-1
   OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-id
   OLEAFLY_S3_SECRET_ACCESS_KEY=your-secret-access-key
   ```

如果使用 Amazon S3 以外的存储，还要把 `OLEAFLY_S3_ENDPOINT` 设为它的地址，例如 `https://minio.example.org:9000` 或 `https://<account-id>.r2.cloudflarestorage.com`，并把 `OLEAFLY_S3_REGION` 设为它期望的区域（R2 用 `auto`）。普通的 `http://` 也行，但只在存储与服务器位于同一个私有网络时才用。

存储桶名称后面的部分是可选的文件夹。每个文件以其 SHA-256 哈希命名，并放在该哈希前两个字符对应的文件夹下，所以哈希以 `3f9a` 开头的文件存为 `oleafly/3f/3f9a...`。快照有自己的 `snapshots` 文件夹，其中每个项目一个文件夹。服务器读回文件或快照时，会用哈希检查其字节，并拒绝不匹配的内容。不使用存储桶时，同样的布局位于 `OLEAFLY_DATA_DIR` 内的 `blobs` 文件夹中。

如果存储桶拒绝某个请求，该次上传或下载就会失败，服务器日志会显示存储桶的回复，例如 `403 Forbidden (AccessDenied)`。服务器错误、超时或连接中断则不同：服务器最多重试三次，每次之间有短暂的随机停顿。如果无法删除某个对象，服务器会记下这件事，并在每次维护（每 6 小时一次）时再试，所以一次故障不会留下遗留对象。

### 快照与内存

项目共享时，所有者的应用会上传第一份快照，并用该设备的密钥对其签名。从那以后，服务器自己构建每一份快照，依据是上一份快照以及此后人们发来的更改。项目在上一份快照之后累积 1,000 个更改时，会构建一份新快照。服务器始终至少保留最近的 2,000 个更改，所以短暂离开的设备可以靠这些更改跟上进度，而不必重新下载整个项目。

构建一份快照所需的内存约为上一份快照大小的十倍，再加上此后的更改。服务器只会启动能放进 `OLEAFLY_SNAPSHOT_MEMORY_MB` 的构建，同时运行的构建共享这个额度。如果某次构建放不下，服务器会跳过它，记录它需要多少内存，并保留该项目的所有更改。设备随后会从这些更改中一次几 MB 地跟上进度。调高这项设置，下一份快照就会被构建。服务器不会存储大于 `OLEAFLY_MAX_PROJECT_MB` 的快照。

### 编译出的 PDF

所有者或编辑者成功编译共享项目后，他们的应用会把 PDF 发送到服务器，如果有 SyncTeX 文件，也会一并发送。每个项目每分钟最多发送一次。服务器为每个项目保留一个 PDF 和一个 SyncTeX 文件，并记录主文件的名称、编译者和编译时间。[浏览器访问](/docs/collaboration/server-access/#browser-access)会把这个 PDF 显示给项目中的人。

每次上传都会替换上一次的文件，旧文件在不再被使用后会被删除。编译出的文件与其他文件存放在一起，位于磁盘或存储桶中，并随所属项目一起删除。一个编译出的文件最大可以达到 `OLEAFLY_MAX_FILE_MB`。它计入所有者的[账户存储空间](#limits-per-account)，但不计入每小时上传次数。

项目的每位成员都可以读取它的编译文件。只有所有者和编辑者可以替换它们。

## 反向代理之后

服务器说的是普通 HTTP，所以要由它前面的某个组件处理 HTTPS：Compose 方案中的 Caddy、Coolify 的代理，或者你已有的 Web 服务器，比如学校的。无论放在前面的是什么，都必须：

- 接受不超过 `OLEAFLY_MAX_PROJECT_MB` 大小的请求
- 把客户端地址加到 `X-Forwarded-For` 中

它还应当把 WebSocket 升级请求转发到 `/ws`，并让这些连接至少保持打开一小时。实时编辑在可能时会使用它们。开启浏览器访问时，它还必须把这些请求转发到 `/web/ws`，因为浏览器应用没有更慢的备用方式。

请让服务器运行在只有代理能访问到的地方。在同一台机器上，设置 `OLEAFLY_BIND=127.0.0.1:8080`。然后设置 `OLEAFLY_BEHIND_PROXY=true`。

### WebSocket 连接被阻止时

有些网络会阻止 WebSocket 连接，常见于带有过滤代理的学校或公司网络。实时编辑在那里仍然可用，只是更慢。当服务器仍能通过 HTTPS 响应，而连续两次 WebSocket 尝试都失败时，Oleafly 会切换到 HTTP 长轮询。它把编辑发送到 `/api/v1/projects/<project>/frames`，并在 `/api/v1/projects/<project>/poll` 上等待其他人的编辑，每个请求最长保持打开 `OLEAFLY_POLL_HOLD_SECONDS`。每一个编辑仍然会送达。Oleafly 每分钟再尝试一次 WebSocket，一旦连上就立即切换回去。

出现这种情况时，Oleafly 中的**测试连接**和管理控制台中的**连接检查**会提示：“此网络屏蔽了常规通道，所以实时编辑改走较慢的通道。编辑仍会送达。”

如果由你运行服务器前面的代理，还是请转发 WebSocket 升级请求。长轮询可以工作，但每批编辑要多花一次请求，延迟也会稍多一点。

有些代理会关闭安静时间不到 30 秒的请求，例如把 `proxy_read_timeout` 设得很短的 nginx。它们会用 502 或 504 错误回应长轮询请求，编辑也会延迟到达。请把 `OLEAFLY_POLL_HOLD_SECONDS` 设得比该超时短几秒，例如超时为 10 秒时设为 `8`。

### OLEAFLY_BEHIND_PROXY 会改变什么

服务器在两个地方记录客户端地址：安全日志，以及限制同一个地址发起登录或打开实时连接的频率的[限制](#limits-for-a-class-on-one-network)。

不设置它时，服务器使用连到它的那个组件的地址。在代理之后，那永远是代理，所以所有人共用一个限额，安全日志也只显示代理的地址。

设置 `OLEAFLY_BEHIND_PROXY=true` 后，服务器会读取 `X-Forwarded-For` 头，并使用其中最后一个地址，也就是你的代理添加的那个。如果这个头缺失，或者里面没有有效地址，服务器会退回到连接它的地址。其他一切不变。服务器会忽略 `X-Forwarded-Proto`、`X-Forwarded-Host` 和 `Forwarded`，它发出的每个地址都依据 `OLEAFLY_PUBLIC_URL` 生成。

只有当每个请求都经过你的代理时才开启它。如果人们也能直接访问服务器，任何人都可以发送编造的 `X-Forwarded-For`，在安全日志中写入任意地址，并绕过登录限制。

如果连续有两层代理，例如 Cloudflare 位于 Coolify 的代理前面，请设置 `OLEAFLY_PROXY_HOPS=2`。服务器随后会取倒数第二个地址。只计入每个请求都会经过的代理。直接通向服务器的 Cloudflare Tunnel 算作一层。

要检查这个数字，请从你自己的电脑登录，然后在管理控制台中打开**安全日志**。最新的记录应当显示你的公网地址，也就是 `ifconfig.me` 之类的网站报告的那个。如果它显示的是私有地址或 Cloudflare 的地址，请把 `OLEAFLY_PROXY_HOPS` 加一。

### Caddy

Caddy 无需额外设置就会转发 WebSocket 连接和 `X-Forwarded-For`，并且自己获取证书。[在前面加上 HTTPS](/docs/collaboration/server/#put-https-in-front) 中有完整的 `Caddyfile`。

### nginx

先为域名获取证书，例如用 certbot。然后把下面的内容保存为 `/etc/nginx/conf.d/oleafly.conf`，并运行 `sudo nginx -t && sudo systemctl reload nginx`：

```nginx
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name collab.example.org;
    ssl_certificate /etc/letsencrypt/live/collab.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/collab.example.org/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_read_timeout 1h;
        proxy_send_timeout 1h;
        client_max_body_size 200m;
    }
}
```

`client_max_body_size` 与 `OLEAFLY_MAX_PROJECT_MB` 的默认值 200 相对应。调高其中一个时，另一个也要调高。

### Apache

你需要 Apache 2.4.47 或更新版本，Debian 12 以及 Ubuntu 22.04 及更新版本都带有。启用这些模块：

```sh
sudo a2enmod proxy proxy_http ssl
```

把下面的内容保存为 `/etc/apache2/sites-available/oleafly.conf`，然后运行 `sudo a2ensite oleafly && sudo systemctl reload apache2`：

```apache
<VirtualHost *:443>
    ServerName collab.example.org
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/collab.example.org/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/collab.example.org/privkey.pem

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:8080/ upgrade=websocket timeout=3600
    ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>
```

`upgrade=websocket` 转发 WebSocket 连接，`timeout=3600` 让它们保持打开一小时。Apache 会自动把客户端地址加到 `X-Forwarded-For` 中。

### 放在某个路径下

如果服务器位于某个路径下，请把这个路径写进 `OLEAFLY_PUBLIC_URL`，例如 `https://www.cs.example.edu/oleafly`，也写进你向登录提供方注册的回调地址中。服务器带这个路径和不带这个路径都会响应，所以你的代理可以保留它，也可以去掉它。使用 nginx 时，请用 `location /oleafly/ {`，里面的行相同，并保持 `proxy_pass http://127.0.0.1:8080;` 不带路径，这样 nginx 会把路径原样传下去。

## 同一网络下班级的限制

整个班级常常从同一个网络地址登录，比如学校的 NAT。默认值就是为此设定的：

- **登录**：同一个地址可以突发 300 个登录请求，之后每秒两个。一次登录大约需要六个请求，所以 50 人可以同时登录。用 `OLEAFLY_SIGN_IN_BURST` 和 `OLEAFLY_SIGN_IN_PER_MINUTE` 来更改。
- **电子邮件链接**：15 分钟内，同一个地址 100 个，同一个电子邮箱地址 3 个。用 `OLEAFLY_EMAIL_LINKS_PER_IP` 和 `OLEAFLY_EMAIL_LINKS_PER_ADDRESS` 来更改。
- **登录码**：10 分钟内，同一个地址 100 个登录码和 10 次错误的登录码。用 `OLEAFLY_DEVICE_CODES_PER_IP` 来更改。
- **实时连接**有自己的、更宽松的限制，这样同一个地址后面的整个班级在服务器重启后可以同时重新连接。只有无法证明自己会话的连接才会用掉它：突发 300 个，之后每秒十个。能证明自己会话的连接则计入它自己设备的限额，该设备可以突发重连 60 次，之后每秒一次。

同一个 `/64` 网络中的所有 IPv6 地址算作一个地址。只有当服务器看到每个人的真实地址时，这些限制才会按人起作用，所以请[正确设置你的代理](#what-oleafly_behind_proxy-changes)。

服务器每 30 秒对每个实时连接发一次 ping。连续 90 秒不回应这些 ping 的连接，以及不再读取服务器所发数据的连接，都会被它关闭。

项目限制对所有人适用：整个项目用 `OLEAFLY_MAX_PROJECT_MB`（默认 200 MB），单个文件用 `OLEAFLY_MAX_FILE_MB`（50 MB），一个项目的人数用 `OLEAFLY_MAX_MEMBERS_PER_PROJECT`（20）。管理控制台的**概览**会显示当前的限制。

## 每个账户的限制

有三项限制适用于每个账户。在你设置之前它们是关闭的，除非开启了[开放注册](/docs/collaboration/server-access/#open-sign-up)，那时它们会以下列默认值开启：

| 限制 | 设置 | 开放注册时 |
| --- | --- | --- |
| 账户拥有的项目的存储空间 | `OLEAFLY_ACCOUNT_STORAGE_MB` | 100 MB |
| 账户拥有的共享项目 | `OLEAFLY_MAX_PROJECTS_PER_ACCOUNT` | 50 |
| 账户在一小时内的上传次数 | `OLEAFLY_UPLOADS_PER_HOUR` | 300 |

你设置的值始终优先于默认值。每个值都必须是不小于 1 的整数。

- **存储空间**会累加该账户拥有的每个项目（包括已归档的项目）的文件和更改历史，以及它们编译出的 PDF。快照不计入。任何人添加到项目中的文件都计入项目所有者的额度。所有者的账户存满后，服务器会拒绝其项目中的新文件和编译出的 PDF，所有者也不能再共享其他项目。被拒绝的文件会留在添加它的人的电脑上。人们输入的文本仍会同步。
- **共享项目**统计该账户共享的项目，包括仍在上传的项目。已归档的项目不计入，所以停止共享一个项目就能腾出名额。
- **上传**统计一小时窗口内的每一次文件和快照上传。编译出的 PDF 不计入。被拒绝的文件，Oleafly 稍后会自动重新发送。

管理控制台的**概览**不显示这些限制。开启开放注册时，服务器每次启动都会在日志中列出它们。

## 日志

- **服务器日志**就是 `docker compose logs oleafly-server`、Coolify 的 **Logs** 或 `journalctl -u oleafly-server` 所显示的内容。`OLEAFLY_LOG_LEVEL` 决定它记录多少。
- **安全日志**记录登录和被拒绝的登录、设备、人员、角色、设置、项目和访客，每条都带有时间和 IP 地址。管理员和维护者在管理控制台的**安全日志**下阅读它。早于 `OLEAFLY_SECURITY_LOG_DAYS` 天的记录会被删除。
- **项目访问日志**记录谁打开过项目、加入过项目或下载过副本，包括设备名称和时间。在**允许项目访问日志**开启时，由项目的所有者开启它，也只有该所有者能阅读它。保留期规则相同。

## 备份

完整备份需要什么，取决于文件存放在哪里：

- **磁盘上的文件**（`OLEAFLY_BLOB_STORE=fs`，默认）：数据库、文件和快照都在数据文件夹里。备份整个文件夹。
- **存储桶中的文件**：数据文件夹里有数据库，存储桶里有文件和快照。数据库的一份副本加上存储桶，就是完整备份。请为存储桶开启版本控制，这样被误删的对象还能找回来。

请定期备份，并保管好这些副本，因为它们包含每一个项目。你的设置（例如 `.env`）不在数据文件夹里，所以也要保留一份副本。

使用 Docker 时，复制数据卷期间服务器会停止几秒钟。Oleafly 会自动重新连接。请在服务器的文件夹中运行这些命令，如果你用了安装脚本，就是 `/opt/oleafly-server`。

```sh
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data:ro -v "$PWD":/backup debian:13.7-slim tar -C /data -czf /backup/oleafly-data-$(date +%F).tar.gz .
sudo docker compose start oleafly-server
```

使用 systemd 时：

```sh
sudo systemctl stop oleafly-server
sudo tar -C /var/lib/private/oleafly-server -czf /root/oleafly-data-$(date +%F).tar.gz .
sudo systemctl start oleafly-server
```

把归档文件复制到另一台机器上。

在 Coolify 上，数据卷的名称以资源的 ID 开头。用 `docker volume ls --filter name=oleafly-data` 找到它，用它替换 `oleafly-server_oleafly-data`，并在 Coolify 的控制台中停止和启动服务器，而不是使用 `docker compose`。

### 恢复演练

从未恢复过的备份只是一种希望。这个演练会用一份备份启动服务器的第二个副本，不去动正在运行的那个，并检查两者是同一台服务器。请用你自己归档文件的日期替换 `2026-10-11`。

```sh
cd /opt/oleafly-server
sudo docker volume create oleafly-restore-drill
sudo docker run --rm -v oleafly-restore-drill:/data -v "$PWD":/backup:ro debian:13.7-slim tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz
sudo docker run -d --name oleafly-restore-drill -v oleafly-restore-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-restore-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server
```

两次回应中的 `server_id` 必须一致。演练副本里有一个占位的 GitHub 登录，它无法让任何人登录，也没有开放端口，所以没有人能使用它。完成后把它删除：

```sh
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill
```

### 恢复

要用 Docker Compose 进行真正的恢复，请停止服务器，用归档文件替换数据卷的内容，然后再次启动：

```sh
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data -v "$PWD":/backup:ro debian:13.7-slim sh -c 'find /data -mindepth 1 -delete && tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz'
sudo docker compose start oleafly-server
```

使用 systemd 时：

```sh
sudo systemctl stop oleafly-server
sudo find /var/lib/private/oleafly-server -mindepth 1 -delete
sudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gz
sudo systemctl start oleafly-server
```

恢复后的服务器缺少备份之后人们所做的更改。每个应用重新连接时（无论一直开着还是之后才打开）都会发现这一点，并重新发送自己缺少的更改。这不需要任何人做什么。如果某个更改建立在别人缺失的更改之上，它要等到那个人打开项目才会生效，因为只有他们的应用才能发送他们的更改。请让故障前后正在编辑的所有人各打开一次项目。

### 用 Litestream 持续复制

归档文件只包含你制作它时已有的内容。[Litestream](https://litestream.io) 会在服务器数据库的每个更改发生约一秒后，把它复制到一个 S3 兼容的存储桶中。Compose 文件把它作为可选服务包含在内。

Litestream 只复制数据库。如果文件在存储桶里，那么存储桶已经保存了文件和快照，所以 Litestream 的副本加上存储桶就可以恢复丢失的磁盘。如果文件在磁盘上，请继续同时为数据卷制作归档文件，因为 Litestream 不会复制 `blobs` 文件夹。

1. 创建一个只供这台服务器的 Litestream 使用的存储桶，或存储桶中的一个文件夹。不要与 `OLEAFLY_BLOB_STORE` 共用。给 Litestream 一个可以列出该存储桶、并读取、写入和删除其中对象的密钥。
2. 把详细信息添加到 `.env`：

   ```sh
   LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-server
   LITESTREAM_REGION=eu-west-1
   LITESTREAM_ACCESS_KEY_ID=your-access-key-id
   LITESTREAM_SECRET_ACCESS_KEY=your-secret-access-key
   COMPOSE_PROFILES=litestream
   ```

   如果使用 Amazon S3 以外的存储，还要把 `LITESTREAM_ENDPOINT` 设为它的地址，并把 `LITESTREAM_REGION` 设为它期望的区域（R2 用 `auto`）。`COMPOSE_PROFILES` 会让每条 `docker compose` 命令都包含 Litestream。
3. 启动它：

   ```sh
   sudo docker compose up -d
   ```

4. 检查它是否复制了数据库。这会输出一行包含 `snapshot complete` 的内容：

   ```sh
   sudo docker compose logs litestream | grep 'snapshot complete'
   ```

Litestream 每天做一次完整复制，并保留一周的副本以及它们之间的更改。这个计划写在 `litestream.yml` 中。

#### Litestream 恢复演练

这个演练会把存储桶中的数据库恢复到一个临时数据卷里，在其上启动服务器的第二个副本，并检查两者是同一台服务器。正在运行的服务器不会被动到。

```sh
cd /opt/oleafly-server
sudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --version
sudo docker compose run --rm --no-deps -v oleafly-litestream-drill:/restore litestream restore -config /etc/litestream.yml -o /restore/oleafly-server.sqlite3 /data/oleafly-server.sqlite3
sudo docker run -d --name oleafly-litestream-drill -v oleafly-litestream-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-litestream-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server
```

第一条命令会创建临时数据卷，并赋予服务器所需的所有者。最后两次回应中的 `server_id` 必须一致。完成后删除这个副本：

```sh
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill
```

#### 从 Litestream 恢复数据库

当数据库文件损坏或丢失，但数据文件夹的其余部分完好时，请停止服务器和 Litestream，删除残留的数据库，恢复它，然后重新启动：

```sh
cd /opt/oleafly-server
sudo docker compose stop oleafly-server litestream
sudo docker run --rm -v oleafly-server_oleafly-data:/data debian:13.7-slim rm -rf /data/oleafly-server.sqlite3 /data/oleafly-server.sqlite3-wal /data/oleafly-server.sqlite3-shm /data/.oleafly-server.sqlite3-litestream
sudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3
sudo docker compose up -d
```

磁盘丢失而文件存放在存储桶中时，请在新的空数据卷上运行上面的命令，并在 `.env` 中保留相同的存储桶设置。每个项目都会连同它的文件和快照一起回来。

磁盘丢失而文件存放在磁盘上时，请[恢复](#restore)你最新的归档文件，到此为止。不要把 Litestream 中较新的数据库覆盖到较旧的归档文件之上。数据库会指向归档文件里没有的文件和快照，这些项目将无法打开。

## 更新

先备份。服务器在新版本首次启动时会更新它的数据库，所以回到旧版本就意味着恢复你更新前所做的备份。

- **一键安装**：运行 `curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update`。它会保留 `.env`，获取新版本的文件和镜像，并重启服务器。
- **手动使用 Docker Compose**：按照[手动使用 Docker Compose](/docs/collaboration/server/#docker-compose-by-hand)把新版本的文件下载到服务器的文件夹中，然后运行 `sudo docker compose up -d`。
- **Coolify**：点击 **Redeploy**。使用已发布的镜像时，它会拉取该镜像标签下的最新版本。
- **Render**：打开该服务并手动开始一次部署，这会再次拉取镜像。
- **Railway**：从服务的菜单中再次部署它。Railway 也可以自动更新来自 GitHub 镜像仓库的镜像。
- **systemd**：按照[下载服务器](/docs/collaboration/server/#download-the-server)安装新版本，然后运行 `sudo systemctl restart oleafly-server`。

Oleafly 每次连接时都会检查服务器的版本。如果应用和服务器无法协同工作，Oleafly 会告诉你哪一个需要更新。
