跳转到内容
Oleaflyv0.4.12

运行服务器

存储、备份与限制

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

本页介绍 Oleafly 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_URLGitHub Enterprise Server 的地址。https://github.com
OLEAFLY_GITHUB_API_URLGitHub API 地址,适用于你的地址不寻常的情况。https://api.github.com,或 OLEAFLY_GITHUB_URL 下的 /api/v3
OLEAFLY_GITHUB_LABELGitHub 登录按钮上的文字。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把这个提供方给出的每个电子邮箱地址都视为已验证。请先阅读已验证的电子邮箱地址。false
OLEAFLY_SMTP_URL、OLEAFLY_MAIL_FROM电子邮件。请阅读电子邮件。关闭
OLEAFLY_OPEN_SIGNUP让任何用你的某个提供方登录的人都得到一个成员账户。请阅读开放注册。false
OLEAFLY_WEB开启浏览器访问。请阅读浏览器访问。false
OLEAFLY_BLOB_STORE图片和 PDF 等文件的存放位置。fs 把它们放在 OLEAFLY_DATA_DIR 中。像 s3://lab-bucket 或 s3://lab-bucket/oleafly 这样的地址会把它们放在存储桶中。fs
OLEAFLY_S3_ENDPOINTAmazon 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。请阅读每个账户的限制。无限制,开放注册时为 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_IP15 分钟内,服务器向同一个网络地址下的人最多发送多少封登录邮件。100
OLEAFLY_EMAIL_LINKS_PER_ADDRESS15 分钟内,同一个电子邮箱地址最多可以收到多少封登录邮件。它不能超过 OLEAFLY_EMAIL_LINKS_PER_IP。3
OLEAFLY_DEVICE_CODES_PER_IP10 分钟内,同一个网络地址下的人最多可以请求多少个登录码。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。

默认情况下,服务器把所有内容都放在 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 中:

    终端窗口
    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 发送到服务器,如果有 SyncTeX 文件,也会一并发送。每个项目每分钟最多发送一次。服务器为每个项目保留一个 PDF 和一个 SyncTeX 文件,并记录主文件的名称、编译者和编译时间。浏览器访问会把这个 PDF 显示给项目中的人。

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

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

服务器说的是普通 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 连接,常见于带有过滤代理的学校或公司网络。实时编辑在那里仍然可用,只是更慢。当服务器仍能通过 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=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 无需额外设置就会转发 WebSocket 连接和 X-Forwarded-For,并且自己获取证书。在前面加上 HTTPS 中有完整的 Caddyfile。

先为域名获取证书,例如用 certbot。然后把下面的内容保存为 /etc/nginx/conf.d/oleafly.conf,并运行 sudo nginx -t && sudo systemctl reload 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 2.4.47 或更新版本,Debian 12 以及 Ubuntu 22.04 及更新版本都带有。启用这些模块:

终端窗口
sudo a2enmod proxy proxy_http ssl

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

<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 地址算作一个地址。只有当服务器看到每个人的真实地址时,这些限制才会按人起作用,所以请正确设置你的代理。

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

项目限制对所有人适用:整个项目用 OLEAFLY_MAX_PROJECT_MB(默认 200 MB),单个文件用 OLEAFLY_MAX_FILE_MB(50 MB),一个项目的人数用 OLEAFLY_MAX_MEMBERS_PER_PROJECT(20)。管理控制台的概览会显示当前的限制。

有三项限制适用于每个账户。在你设置之前它们是关闭的,除非开启了开放注册,那时它们会以下列默认值开启:

限制设置开放注册时
账户拥有的项目的存储空间OLEAFLY_ACCOUNT_STORAGE_MB100 MB
账户拥有的共享项目OLEAFLY_MAX_PROJECTS_PER_ACCOUNT50
账户在一小时内的上传次数OLEAFLY_UPLOADS_PER_HOUR300

你设置的值始终优先于默认值。每个值都必须是不小于 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,默认):数据库、文件和快照都在数据文件夹里。备份整个文件夹。
  • 存储桶中的文件:数据文件夹里有数据库,存储桶里有文件和快照。数据库的一份副本加上存储桶,就是完整备份。请为存储桶开启版本控制,这样被误删的对象还能找回来。
服务器把数据保存在哪里,以及要备份什么文件存放在磁盘上(默认)时,数据文件夹中有数据库,以及存放文件和快照的 blobs 文件夹,所以要备份整个文件夹。文件存放在存储桶中时,数据文件夹中有数据库,而 S3 存储桶中存放文件和快照,所以要备份数据库和存储桶。文件在磁盘上(默认)文件在存储桶中oleafly-server数据文件夹数据库:账户、设置、日志blobs:文件和快照备份整个文件夹oleafly-server数据文件夹数据库S3 存储桶文件和快照备份数据库和存储桶服务器把数据保存在哪里,以及要备份什么文件存放在磁盘上(默认)时,数据文件夹中有数据库,以及存放文件和快照的 blobs 文件夹,所以要备份整个文件夹。文件存放在存储桶中时,数据文件夹中有数据库,而 S3 存储桶中存放文件和快照,所以要备份数据库和存储桶。文件在磁盘上(默认)文件在存储桶中oleafly-server数据文件夹数据库和 blobs(文件、快照)备份整个文件夹oleafly-server数据文件夹数据库S3 存储桶文件和快照备份数据库和存储桶
完整备份需要什么,取决于文件存放在哪里。

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

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

终端窗口
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 时:

终端窗口
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。

终端窗口
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 登录,它无法让任何人登录,也没有开放端口,所以没有人能使用它。完成后把它删除:

终端窗口
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill

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

终端窗口
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 时:

终端窗口
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 (在新标签页中打开) 会在服务器数据库的每个更改发生约一秒后,把它复制到一个 S3 兼容的存储桶中。Compose 文件把它作为可选服务包含在内。

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

  1. 创建一个只供这台服务器的 Litestream 使用的存储桶,或存储桶中的一个文件夹。不要与 OLEAFLY_BLOB_STORE 共用。给 Litestream 一个可以列出该存储桶、并读取、写入和删除其中对象的密钥。

  2. 把详细信息添加到 .env:

    终端窗口
    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. 启动它:

    终端窗口
    sudo docker compose up -d
  4. 检查它是否复制了数据库。这会输出一行包含 snapshot complete 的内容:

    终端窗口
    sudo docker compose logs litestream | grep 'snapshot complete'

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

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

终端窗口
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 必须一致。完成后删除这个副本:

终端窗口
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill

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

终端窗口
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 中保留相同的存储桶设置。每个项目都会连同它的文件和快照一起回来。

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

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

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

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

图片预览

无法加载 AI 回答

请重试,或搜索文档。