运行服务器
存储、备份与限制
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_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 | 把这个提供方给出的每个电子邮箱地址都视为已验证。请先阅读已验证的电子邮箱地址。 | 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_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。请阅读每个账户的限制。 | 无限制,开放注册时为 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。
默认情况下,服务器把所有内容都放在 OLEAFLY_DATA_DIR 中:数据库、人们共享的文件以及项目快照。快照是每个项目的已保存副本,让人们能快速加入并跟上进度。
存储桶中的文件
标题为“存储桶中的文件”的部分服务器可以改为把文件和快照保存在 Amazon S3 中,或保存在其他具有 S3 兼容 API 的存储中,例如 MinIO 或 Cloudflare R2。无论哪种方式,数据库都留在 OLEAFLY_DATA_DIR 中,所以服务器仍然需要它的数据文件夹。
-
创建一个存储桶,并阻止对它的公开访问。
-
创建一个只能对该存储桶读取、写入和删除对象的密钥。在 Amazon S3 上,这意味着对
arn:aws:s3:::lab-bucket/*授予s3:GetObject、s3:PutObject和s3:DeleteObject;如果使用文件夹,则对arn:aws:s3:::lab-bucket/oleafly/*授予。 -
设置这些变量,例如写在
.env中:终端窗口 OLEAFLY_BLOB_STORE=s3://lab-bucket/oleaflyOLEAFLY_S3_REGION=eu-west-1OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-idOLEAFLY_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”的部分所有者或编辑者成功编译共享项目后,他们的应用会把 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 连接被阻止时
标题为“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 会改变什么
标题为“OLEAFLY_BEHIND_PROXY 会改变什么”的部分服务器在两个地方记录客户端地址:安全日志,以及限制同一个地址发起登录或打开实时连接的频率的限制。
不设置它时,服务器使用连到它的那个组件的地址。在代理之后,那永远是代理,所以所有人共用一个限额,安全日志也只显示代理的地址。
设置 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”的部分Caddy 无需额外设置就会转发 WebSocket 连接和 X-Forwarded-For,并且自己获取证书。在前面加上 HTTPS 中有完整的 Caddyfile。
nginx
标题为“nginx”的部分先为域名获取证书,例如用 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
标题为“Apache”的部分你需要 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_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。
cd /opt/oleafly-serversudo docker compose stop oleafly-serversudo 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-serversudo 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-serversudo docker volume create oleafly-restore-drillsudo 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.gzsudo 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-servercurl -fsS https://collab.example.org/.well-known/oleafly-server两次回应中的 server_id 必须一致。演练副本里有一个占位的 GitHub 登录,它无法让任何人登录,也没有开放端口,所以没有人能使用它。完成后把它删除:
sudo docker rm -f oleafly-restore-drillsudo docker volume rm oleafly-restore-drill要用 Docker Compose 进行真正的恢复,请停止服务器,用归档文件替换数据卷的内容,然后再次启动:
cd /opt/oleafly-serversudo docker compose stop oleafly-serversudo 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-serversudo find /var/lib/private/oleafly-server -mindepth 1 -deletesudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gzsudo systemctl start oleafly-server恢复后的服务器缺少备份之后人们所做的更改。每个应用重新连接时(无论一直开着还是之后才打开)都会发现这一点,并重新发送自己缺少的更改。这不需要任何人做什么。如果某个更改建立在别人缺失的更改之上,它要等到那个人打开项目才会生效,因为只有他们的应用才能发送他们的更改。请让故障前后正在编辑的所有人各打开一次项目。
用 Litestream 持续复制
标题为“用 Litestream 持续复制”的部分归档文件只包含你制作它时已有的内容。Litestream (在新标签页中打开) 会在服务器数据库的每个更改发生约一秒后,把它复制到一个 S3 兼容的存储桶中。Compose 文件把它作为可选服务包含在内。
Litestream 只复制数据库。如果文件在存储桶里,那么存储桶已经保存了文件和快照,所以 Litestream 的副本加上存储桶就可以恢复丢失的磁盘。如果文件在磁盘上,请继续同时为数据卷制作归档文件,因为 Litestream 不会复制 blobs 文件夹。
-
创建一个只供这台服务器的 Litestream 使用的存储桶,或存储桶中的一个文件夹。不要与
OLEAFLY_BLOB_STORE共用。给 Litestream 一个可以列出该存储桶、并读取、写入和删除其中对象的密钥。 -
把详细信息添加到
.env:终端窗口 LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-serverLITESTREAM_REGION=eu-west-1LITESTREAM_ACCESS_KEY_ID=your-access-key-idLITESTREAM_SECRET_ACCESS_KEY=your-secret-access-keyCOMPOSE_PROFILES=litestream如果使用 Amazon S3 以外的存储,还要把
LITESTREAM_ENDPOINT设为它的地址,并把LITESTREAM_REGION设为它期望的区域(R2 用auto)。COMPOSE_PROFILES会让每条docker compose命令都包含 Litestream。 -
启动它:
终端窗口 sudo docker compose up -d -
检查它是否复制了数据库。这会输出一行包含
snapshot complete的内容:终端窗口 sudo docker compose logs litestream | grep 'snapshot complete'
Litestream 每天做一次完整复制,并保留一周的副本以及它们之间的更改。这个计划写在 litestream.yml 中。
Litestream 恢复演练
标题为“Litestream 恢复演练”的部分这个演练会把存储桶中的数据库恢复到一个临时数据卷里,在其上启动服务器的第二个副本,并检查两者是同一台服务器。正在运行的服务器不会被动到。
cd /opt/oleafly-serversudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --versionsudo 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.sqlite3sudo 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-servercurl -fsS https://collab.example.org/.well-known/oleafly-server第一条命令会创建临时数据卷,并赋予服务器所需的所有者。最后两次回应中的 server_id 必须一致。完成后删除这个副本:
sudo docker rm -f oleafly-litestream-drillsudo docker volume rm oleafly-litestream-drill从 Litestream 恢复数据库
标题为“从 Litestream 恢复数据库”的部分当数据库文件损坏或丢失,但数据文件夹的其余部分完好时,请停止服务器和 Litestream,删除残留的数据库,恢复它,然后重新启动:
cd /opt/oleafly-serversudo docker compose stop oleafly-server litestreamsudo 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-litestreamsudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3sudo 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 会告诉你哪一个需要更新。