跳转到内容
Oleaflyv0.4.12

运行服务器

Oleafly Server 存储什么、需要什么,以及如何用一条命令安装它,或用 Docker Compose、Coolify、Render、Railway 或普通的 Linux 服务来运行它,然后成为它的第一位管理员。

Oleafly Server 是实时协作背后的协作服务器。你的实验室、院系或机构在自己的机器上,或在自己的云账户中运行它。人们在 Oleafly 中添加它,并用已有的账户登录,比如 GitHub 或学校的登录。有人在服务器上共享项目时,被他们添加的人会得到一份完整的副本,编辑时保持同步。开启浏览器访问后,他们还可以在网页浏览器中打开它。

本指南面向为实验室、课程或合作作者小组运行服务器的人。你应当熟悉终端。有些部署方式还需要你编辑配置文件。你不需要编写代码。

做安全评估时,请阅读服务器安全。它涵盖自托管、登录、设备密钥、签名的更改、安全日志和访问日志,以及容器镜像及其软件物料清单。

服务器把所有内容都保存在一个数据文件夹中,由 OLEAFLY_DATA_DIR 指定:

  • 账户:每位成员的显示名称、头像地址、已验证的电子邮箱地址,以及他们在登录提供方处的用户 ID 和登录名。服务器从不查看或存储密码。
  • 设备:每台登录过的电脑,包括它的名称、操作系统、公钥和上次出现的时间。登录令牌只以哈希形式存储。
  • 安全日志:登录和被拒绝的登录、添加和退出登录的设备、成员、角色和设置的更改、共享、归档和恢复的项目、谁能打开项目的更改,以及访客邀请。每条记录都有时间和 IP 地址。
  • 管理员在 Oleafly 中更改的服务器设置。
  • 项目访问日志,针对所有者开启了它的项目:谁打开过项目、加入过项目或下载过副本,包括设备名称和时间。只有项目的所有者能阅读它。
  • 访客邀请:被邀请的电子邮箱地址、项目、角色以及发送者。
  • 共享项目:每个文件和完整的更改历史,以及属于它们的评论、建议、聊天和版本名称。
  • 编译出的 PDF:对每个共享项目,保存所有者或编辑者的应用在成功编译后发来的最新 PDF 及其 SyncTeX 文件,并记录编译者和编译时间。

安全日志和访问日志中的记录,以及已答复或已过期的访客邀请,会在 OLEAFLY_SECURITY_LOG_DAYS 天后删除,默认为 365 天。项目不再使用的文件,比如被替换的图片的旧副本,会在项目最后一次使用它们的 30 天后删除。每个编译出的 PDF 都会替换上一个。所有者停止共享某个项目后,服务器会让它以只读方式保留 OLEAFLY_ARCHIVE_DAYS 天(默认 30 天),然后删除它。在此期间,只有所有者和项目中的管理员可以下载它。

项目在服务器上不加密。任何能读取数据文件夹、机器磁盘或你的备份的人,都能读取其中存放的每个项目。这包括运行这台机器的人,以及托管它的公司。

在 Oleafly 内部,规则更严格。没有任何服务器角色(包括管理员)可以打开项目,除非项目的所有者添加了他们。如果某个项目必须对运行服务器的人保密,请为它单独运行一台服务器。

每位成员的电脑上也会保存与他们共享的每个项目的完整副本。请让成员开启磁盘加密,比如 macOS 上的 FileVault、Windows 上的 BitLocker 或 Linux 上的 LUKS。

  • 一台保持开机的机器。 任何 Linux 机器都行,或者在 Render 或 Railway 等托管服务上开一个账户。一台小型虚拟机就足以起步。随着项目增多,留意它的内存和磁盘。服务器可运行在 x86-64 和 ARM 上。
  • 服务器的域名,例如 collab.example.org,并有一条 DNS 记录指向这台机器。如果你没有域名,Render 和 Railway 会给你一个地址。如果这台机器没有公网地址,请阅读没有公网地址时。
  • 让人们登录的方式:至少一个登录提供方,比如 GitHub OAuth 应用或你所在机构的登录。没有它服务器无法启动。服务器可以用来发信的电子邮件账户是可选的。有了它,管理员还可以让人们用邮件里的链接登录。请阅读登录与访问。

每个版本都作为容器镜像 ghcr.io/oleafly/oleafly-server 发布。安装脚本及其 Compose 文件在 Oleafly Server 发布页 (在新标签页中打开)上。单个 Linux 程序形式的服务器在 Oleafly 发布页 (在新标签页中打开)上。

方案何时使用
一条命令一台由你维护的 Linux 机器。安装脚本会配置 Docker、Caddy 和 HTTPS,并问几个问题。不确定时从这里开始。
手动使用 Docker Compose你更愿意自己放置和编辑每个文件。
Coolify你已经在运行一台 Coolify 服务器。
Render 或 Railway你更愿意付费使用托管服务,而不是自己维护机器。
不用 Docker 的 Linux无法使用 Docker 的学校虚拟机。

服务器从环境变量读取设置。存储、备份与限制列出了其中每一个。

在一台由你自己维护的 Linux 机器上,安装脚本会完成所有设置,只问它需要知道的内容。

安装程序做什么安装程序按顺序执行六个步骤。它先检查机器运行的是 x86-64 或 ARM 架构的 Linux,且 80 和 443 端口空闲。如果缺少 Docker,它会先询问再安装。它下载该版本的文件,并对照 SHA256SUMS 逐个检查。它会询问域名、服务器名称、用户如何登录,以及(可选的)电子邮件。它把设置写入 .env,并在 /opt/oleafly-server 中连同 Caddy 一起启动服务器。服务器通过 HTTPS 响应后,它会打印出第一位管理员使用的设置代码。检查机器Linux,x86-64 或 ARM80 和 443 端口空闲Docker缺少时安装,安装前会询问你下载并校验该版本的文件,用 SHA256SUMS 检查几个问题域名、服务器名称、登录方式、电子邮件启动服务器和 Caddy位于 /opt/oleafly-server设置代码服务器响应后打印出来安装程序做什么安装程序按顺序执行六个步骤。它先检查机器运行的是 x86-64 或 ARM 架构的 Linux,且 80 和 443 端口空闲。如果缺少 Docker,它会先询问再安装。它下载该版本的文件,并对照 SHA256SUMS 逐个检查。它会询问域名、服务器名称、用户如何登录,以及(可选的)电子邮件。它把设置写入 .env,并在 /opt/oleafly-server 中连同 Caddy 一起启动服务器。服务器通过 HTTPS 响应后,它会打印出第一位管理员使用的设置代码。检查机器Linux,x86-64 或 ARM80 和 443 端口空闲Docker缺少时安装,安装前会询问你下载并校验该版本的文件,用 SHA256SUMS 检查几个问题域名、服务器名称、登录方式、电子邮件启动服务器和 Caddy位于 /opt/oleafly-server设置代码服务器响应后打印出来
一条命令:检查、Docker、下载并校验、几个问题、启动,最后得到设置代码。

运行之前,请确认:

  • 机器运行的是 x86-64 或 ARM 上的 Linux,比如 Ubuntu 24.04 或 Debian 13,并且你可以在上面使用 sudo。
  • 机器上没有其他程序占用 80 和 443 端口。请在它前面的任何防火墙中开放 TCP 的 80 和 443 端口以及 UDP 的 443 端口。
  • 你域名的 DNS 记录指向这台机器。如果还没有,安装仍会完成,Caddy 会不断尝试获取证书,直到记录生效。
  • 你有至少一个登录提供方的详细信息,比如 GitHub OAuth 应用的客户端 ID 和密钥。对于 GitHub,回调地址是 https:// 加上你的域名,再接 /auth/callback/github。

然后运行:

终端窗口
curl -fsSL https://oleafly.com/server/install.sh | sudo sh

安装脚本会:

  1. 检查机器,以及 80 和 443 端口是否空闲。
  2. 检查是否有 Docker。如果没有,安装脚本会先询问,然后用 Docker 自己的脚本安装它。
  3. 从 Oleafly Server 发布页 (在新标签页中打开)下载最新版本的文件,并用该版本的 SHA256SUMS 逐个检查。如果有文件不匹配,它会停止,不做任何更改。
  4. 询问你的域名、服务器名称以及人们如何登录。它还会提供设置电子邮件和把文件保存在 S3 存储桶的选项。这两项都是可选的。
  5. 显示摘要,并在做任何更改之前询问。然后把它的文件写入 /opt/oleafly-server,你的设置放在只有 root 能读取的 .env 中。
  6. 启动前面带有 Caddy 的服务器,等到你的域名通过 HTTPS 应答,然后输出地址和设置码。

然后成为第一位管理员。

你可以随时再次运行安装脚本。当它在 /opt/oleafly-server 中发现一台服务器时,会保持 .env 不变,放回其他文件并重启服务器。这能修复大多数损坏的部署。

你的数据存放在 Docker 数据卷 oleafly-server_oleafly-data 中。要安装到 /opt/oleafly-server 以外的位置,请设置 OLEAFLY_DIR,例如 curl -fsSL https://oleafly.com/server/install.sh | sudo OLEAFLY_DIR=/srv/oleafly sh,并在下面的命令中使用那个文件夹。

如果你所在的机构不允许把脚本通过管道交给 shell 执行,请把 install.sh 和 SHA256SUMS 从最新版本 (在新标签页中打开)下载到同一个文件夹中。检查脚本、阅读它,然后运行:

终端窗口
sha256sum --check --ignore-missing SHA256SUMS
sudo sh install.sh

对于脚本或部署工具,请加上 --yes,并把答案作为环境变量传入。OLEAFLY_INSTALL_DOCKER=yes 让安装脚本在缺少 Docker 时自行添加。

终端窗口
curl -fsSL https://oleafly.com/server/install.sh | sudo \
OLEAFLY_DOMAIN=collab.example.org \
OLEAFLY_SERVER_NAME='Smith Lab' \
OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId \
OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret \
OLEAFLY_INSTALL_DOCKER=yes \
sh -s -- --yes

无论是否加 --yes,安装脚本都会直接使用它在环境中找到的任何设置,不再询问。sudo sh /opt/oleafly-server/install.sh --help 会列出全部设置,包括 OpenID Connect、电子邮件和 S3。在命令行中输入的值可能会留在你的 shell 历史记录里,所以部署工具应当从它自己的密钥存储中传入密钥。

  • 状态:sudo sh /opt/oleafly-server/install.sh status 会显示服务器是否在运行,以及你的域名是否通过 HTTPS 应答并带有有效的证书。

  • 更新:先按更新所述备份。然后运行下面的命令。它会下载最新版本的文件和镜像,保留 .env,重启服务器并等到它应答。已连接的人会自动重新连接。安装脚本从不会把服务器退回到较旧的版本。

    终端窗口
    curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update
  • 卸载:sudo sh /opt/oleafly-server/install.sh uninstall 会停止并移除容器。除非你在它询问时输入 delete,否则你的数据和 .env 会保留。删除它们会移除服务器上的每个共享项目、每个账户和安全日志。人们在自己电脑上保留着项目的副本。

如果安装脚本因为你无法解决的问题而停止,请报告问题 (在新标签页中打开),并附上它输出的内容。

这种方式运行两个容器。oleafly-server 是服务器,只有其他容器能访问它。caddy 从 Let’s Encrypt 获取证书,在 80 和 443 端口提供 HTTPS,并把请求转交给服务器,包括实时连接。

Docker Compose 部署每台电脑上的 Oleafly 通过 HTTPS 连接到你机器上的 Caddy。Caddy 持有证书,并通过普通 HTTP 把请求转发给 oleafly-server 容器。服务器把数据库和文件保存在 Docker 数据卷中,也可以改为把文件保存在 S3 存储桶中。你的机器(使用 Docker Compose)Oleafly在每台电脑上CaddyHTTPS证书oleafly-server.env 中的设置数据卷数据库、文件S3 存储桶可选Docker Compose 部署每台电脑上的 Oleafly 通过 HTTPS 连接到你机器上的 Caddy。Caddy 持有证书,并通过普通 HTTP 把请求转发给 oleafly-server 容器。服务器把数据库和文件保存在 Docker 数据卷中,也可以改为把文件保存在 S3 存储桶中。你的机器(使用 Docker Compose)Oleafly在每台电脑上CaddyHTTPS 证书oleafly-server.env 中的设置数据卷数据库、文件S3 存储桶可选,用于文件HTTPSHTTP
Docker Compose:Caddy 在服务器前处理 HTTPS,数据卷保存数据库和文件。
  1. 按照 Docker 的说明 (在新标签页中打开)安装 Docker Engine 和 Compose 插件。

  2. 把你域名的 DNS 记录指向这台机器。在它前面的任何防火墙中开放 TCP 的 80 和 443 端口以及 UDP 的 443 端口。Caddy 需要 80 端口来获取证书。

  3. 为服务器创建一个文件夹,把最新版本的文件下载到其中,检查它们,并创建你的设置文件:

    终端窗口
    sudo mkdir -p /opt/oleafly-server && cd /opt/oleafly-server
    base=https://github.com/Oleafly/oleafly-server/releases/latest/download
    for f in docker-compose.yml Caddyfile env.example litestream.yml SHA256SUMS; do sudo curl -fsSLO "$base/$f"; done
    sha256sum --check --ignore-missing SHA256SUMS
    sudo install -m 600 env.example .env
  4. 用 sudoedit .env 编辑 .env。把 OLEAFLY_DOMAIN 设为你的域名(不带 https://),设置 OLEAFLY_SERVER_NAME,并至少填写一个登录提供方。不用的提供方那几行请留空。如果值包含 $ 或 #,请用单引号括起来。

  5. 启动它。首次启动会下载该版本对应的服务器镜像 ghcr.io/oleafly/oleafly-server。

    终端窗口
    sudo docker compose up -d
  6. 检查它是否应答。这会输出 200:

    终端窗口
    curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz
  7. 成为第一位管理员。设置码在日志里:

    终端窗口
    sudo docker compose logs oleafly-server | grep 'Setup code'

你的数据存放在 Docker 数据卷 oleafly-server_oleafly-data 中。Caddy 把它的证书保存在 oleafly-server_caddy-data 中。

即使开启了 ufw 这样的主机防火墙,Docker 也会自己打开 80 和 443 端口。这正是 Caddy 所需要的。不要给 oleafly-server 服务添加 ports: 条目。如果要从这台机器本身访问服务器,请把它发布为 127.0.0.1:8080:8080,这样它就不会暴露到网络上。

如果你修改了 Caddyfile,请运行 sudo docker compose up -d --force-recreate caddy。以后要更新,请用同样的方法下载新版本的文件,然后再次运行 sudo docker compose up -d。

有七项设置可以保存密钥:OLEAFLY_SETUP_CODE、OLEAFLY_GITHUB_CLIENT_SECRET、OLEAFLY_OIDC_<NAME>_CLIENT_SECRET、OLEAFLY_SMTP_URL、OLEAFLY_BLOB_STORE、OLEAFLY_S3_ACCESS_KEY_ID 和 OLEAFLY_S3_SECRET_ACCESS_KEY。每一项还有一个 _FILE 版本,用来指定保存该值的文件。两者设置其一即可,不要同时设置。

例如,要把 GitHub 客户端密钥作为 Docker secret 传入,请把它保存在 docker-compose.yml 旁边的 secrets/github_client_secret 中,让服务器的用户(ID 为 10001)可以读取它,并删除 .env 中的 OLEAFLY_GITHUB_CLIENT_SECRET 这一行:

终端窗口
sudo chown 10001:10001 secrets/github_client_secret
sudo chmod 400 secrets/github_client_secret

然后在 docker-compose.yml 旁边创建 docker-compose.override.yml。Compose 会自动读取它,安装脚本更新其他文件时也不会动它。

services:
oleafly-server:
environment:
OLEAFLY_GITHUB_CLIENT_SECRET_FILE: /run/secrets/github_client_secret
secrets:
- github_client_secret
secrets:
github_client_secret:
file: ./secrets/github_client_secret

再次运行 sudo docker compose up -d。

Coolify 会把它自己的代理放在服务器前面并获取证书,所以这种方式不需要 Caddy。Coolify 可以从 Oleafly 仓库构建服务器,也可以运行已发布的镜像,这样就省去了构建。

Coolify 部署每台电脑上的 Oleafly 连接到 Coolify 的代理(可选择经过 Cloudflare),由代理处理 HTTPS 并把请求转发给 oleafly-server。服务器把数据保存在 Docker 卷中。当 Cloudflare 位于 Coolify 的代理之前时,每个请求都会经过两层代理,因此要把 OLEAFLY_PROXY_HOPS 设为 2。Oleafly在每台电脑上Cloudflare可选Coolify 的代理HTTPSoleafly-server在你的 Coolify服务器上数据卷两者都在前面时,设置OLEAFLY_PROXY_HOPS=2Coolify 部署每台电脑上的 Oleafly 连接到 Coolify 的代理(可选择经过 Cloudflare),由代理处理 HTTPS 并把请求转发给 oleafly-server。服务器把数据保存在 Docker 卷中。当 Cloudflare 位于 Coolify 的代理之前时,每个请求都会经过两层代理,因此要把 OLEAFLY_PROXY_HOPS 设为 2。Oleafly在每台电脑上Cloudflare可选Coolify 的代理HTTPSoleafly-server在你的 Coolify 服务器上数据卷两者都在前面时,设置OLEAFLY_PROXY_HOPS=2
Coolify:它的代理处理 HTTPS。如果前面还有 Cloudflare,请设置 OLEAFLY_PROXY_HOPS=2。

开始之前,请把你域名的 DNS 记录(比如 collab.example.org)指向 Coolify 服务器。然后按照 GitHub 中的说明创建 GitHub OAuth 应用,回调地址为 https://collab.example.org/auth/callback/github。把它的客户端 ID 和密钥放在手边。

  1. 在你的 Coolify 项目中,点击 + New,然后点击 Public Repository,并输入 https://github.com/Oleafly/Oleafly。分支保持 main。
  2. 把 Build Pack 设为 Docker Compose,Base Directory 设为 /,Docker Compose Location 设为 /deploy/server/docker-compose.coolify.yml,然后点击 Continue。
  3. 在 Advanced › Build 下,把 Build arguments 设为 Managed manually in Dockerfile。服务器的镜像不需要构建参数。保持自动时,Coolify 会把每个变量(包括密钥)都写入镜像的构建历史。
  4. 在 General 下,把 oleafly-server 的域名设为 https://collab.example.org:8080 并保存。:8080 告诉 Coolify 的代理服务器监听哪个端口。人们仍然使用常规的 HTTPS 端口连接,Coolify 会替你把 OLEAFLY_PUBLIC_URL 设为 https://collab.example.org。
  5. 在 Environment Variables 下,填写 Coolify 标为必填的 OLEAFLY_SERVER_NAME,然后填写 OLEAFLY_GITHUB_CLIENT_ID 和 OLEAFLY_GITHUB_CLIENT_SECRET。不用的变量请留空。
  6. 点击 Deploy。首次构建会编译服务器,需要几分钟。完成后,Coolify 会显示该资源正在运行且状态健康。
  7. 在浏览器中打开 https://collab.example.org/healthz。它会显示 {"status":"ok"}。
  8. 打开 Logs,选择 oleafly-server 容器,并从以 Setup code: 开头的最新一行复制代码。
  9. 用这个代码成为第一位管理员。

如果服务器无法启动,它的日志会指出无法使用的那项设置。当日志说 OLEAFLY_PUBLIC_URL 未设置时,说明缺了第 4 步。以 http:// 开头的域名会被拒绝,因为服务器需要 HTTPS。

如果 Cloudflare 位于 Coolify 前面,也就是你的 DNS 记录经过 Cloudflare 的代理,或者有一条隧道通向 Coolify 的代理,请把 OLEAFLY_PROXY_HOPS 设为 2。不设置的话,安全日志会为所有人显示代理的地址,他们也会共用同一个登录限额。

Coolify 文件里为 GitHub 和一个名为 UNIVERSITY 的 OpenID Connect 提供方留了位置。请把 OLEAFLY_OIDC_UNIVERSITY_LABEL 设为人们应当看到的文字,比如 GitLab。它的回调地址以 /auth/callback/university 结尾。如需更多提供方,请从你自己的分叉部署,并使用你自己的文件副本。

数据存放在名称以 oleafly-data 结尾的 Docker 数据卷中。用 docker volume ls --filter name=oleafly-data 找到它。镜像里没有 shell,所以 Coolify 的 Terminal 无法在服务器的容器中打开一个。日志和健康检查照常可用。

运行已发布的镜像可以省去构建,适合较小的 Coolify 服务器。按照上面的步骤操作,但有两处改动。在第 2 步中,把 Docker Compose Location 设为 /deploy/server/docker-compose.coolify-image.yml。跳过第 3 步,因为没有东西需要构建。这个文件跟随一个版本系列,所以每次 Redeploy 都会拉取该系列中的最新版本。

Deploy to Render (在新标签页中打开) 会读取 Oleafly 仓库中的 Blueprint。它用已发布的镜像创建一个 Web 服务,并配有一块 1 GB 的磁盘用于数据文件夹。Render 只给付费实例类型挂载磁盘,所以该服务从最小的付费实例开始,位于 Render 的 Oregon 区域。如需其他区域,请从分叉部署,并在 render.yaml 中设置 region。

  1. 打开链接并登录 Render。
  2. Render 会询问 OLEAFLY_SERVER_NAME 以及 GitHub 客户端 ID 和密钥。填写名称,GitHub 的几项先留空。它们的回调地址取决于服务的地址,而你现在还没有这个地址。
  3. 点击 Deploy Blueprint。服务上线后,它的页面会显示它的地址,比如 https://oleafly-server.onrender.com。Blueprint 会把 OLEAFLY_PUBLIC_URL 设为这个地址。
  4. 按照 GitHub 中的说明创建 GitHub OAuth 应用,以该地址后接 /auth/callback/github 作为回调地址。在服务的 Environment 下添加客户端 ID 和密钥。Render 会带着它们重启服务器。
  5. 在服务的 Logs 中找到最新的 Setup code: 行,然后成为第一位管理员。

如果你给服务绑定了自己的域名,请在 Environment 下把 OLEAFLY_PUBLIC_URL 设为该域名,并在 GitHub 上相应修改回调地址。

由于有磁盘,Render 会先停止正在运行的服务器,再启动新的,所以每次部署都会让服务器中断几秒钟。Oleafly 会自动重新连接。

Railway 运行已发布的镜像,并为数据文件夹配一个数据卷。

  1. 在 Railway 项目中,点击 + New,然后点击 Docker Image,并输入 ghcr.io/oleafly/oleafly-server:latest。如果想自己选择何时升级,请改用发布页 (在新标签页中打开)上某个版本自己的标签。Railway 可能会立即开始第一次部署。它会以 OLEAFLY_PUBLIC_URL is not set 停止,这在此时是预期的。

  2. 打开该服务。在 Settings › Networking 下,点击 Generate Domain 并输入端口 8080。Railway 会显示地址,比如 oleafly-server-production.up.railway.app。

  3. 在 Settings › Deploy 下,把 Healthcheck Path 设为 /readyz。

  4. 右键点击项目画布,添加一个数据卷,把它挂到服务器的服务上,并把挂载路径设为 /data。

  5. 在 Variables 下,打开 Raw Editor,粘贴下面这几行,并填入你自己的服务器名称。GitHub 的值请按照 GitHub 获取。回调地址是第 2 步中的地址,前面加上 https://,后面加上 /auth/callback/github。

    OLEAFLY_PUBLIC_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}
    OLEAFLY_BIND=0.0.0.0:8080
    OLEAFLY_DATA_DIR=/data
    OLEAFLY_BEHIND_PROXY=true
    OLEAFLY_SERVER_NAME=Smith Lab
    OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
    OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
    PORT=8080
    RAILWAY_RUN_UID=0

    Railway 以 root 身份挂载数据卷。RAILWAY_RUN_UID=0 让服务器以 root 身份运行,这样它才能写入数据卷。

  6. 部署这些更改。在服务的 Deploy Logs 中找到最新的 Setup code: 行,然后成为第一位管理员。

在没有 Docker 的机器上,服务器作为单个程序在 systemd 下运行,前面用 Caddy 提供 HTTPS。

不使用 Docker 的 Linux 部署每台电脑上的 Oleafly 通过 HTTPS 连接到你的 Linux 机器上的 Caddy。Caddy 把请求转发给 oleafly-server,后者作为 systemd 服务运行,监听 127.0.0.1 的 8080 端口,并把数据保存在 /var/lib/oleafly-server。你的 Linux 机器Oleafly在每台电脑上CaddyHTTPS证书oleafly-serversystemd 服务数据文件夹/var/lib/oleafly-server不使用 Docker 的 Linux 部署每台电脑上的 Oleafly 通过 HTTPS 连接到你的 Linux 机器上的 Caddy。Caddy 把请求转发给 oleafly-server,后者作为 systemd 服务运行,监听 127.0.0.1 的 8080 端口,并把数据保存在 /var/lib/oleafly-server。你的 Linux 机器Oleafly在每台电脑上CaddyHTTPS 证书oleafly-serversystemd 服务数据文件夹/var/lib/oleafly-serverHTTPSHTTP
不使用 Docker 的 Linux:由 systemd 运行服务器,前面的 Caddy 处理 HTTPS。

发布页 (在新标签页中打开)上的每个服务器版本都有适用于 x86-64 和 ARM 的预先构建好的程序,以及用来校验它的 SHA256SUMS 文件。该程序不需要安装任何其他东西。

请把适合你机器的压缩包(文件名以 x86_64-unknown-linux-musl.tar.gz 或 aarch64-unknown-linux-musl.tar.gz 结尾)和 SHA256SUMS 下载到同一个文件夹中。然后校验并安装。在 ARM 机器上,请用 aarch64 代替 x86_64:

终端窗口
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf oleafly-server-*-x86_64-unknown-linux-musl.tar.gz
sudo install -m 0755 oleafly-server-*-x86_64-unknown-linux-musl/oleafly-server /usr/local/bin/oleafly-server
oleafly-server --version

如果装有 GitHub CLI,gh attestation verify oleafly-server-*-x86_64-unknown-linux-musl.tar.gz --repo Oleafly/Oleafly 还会检查该压缩包是由 GitHub 从 Oleafly 仓库构建的。压缩包中包含 systemd 单元 oleafly-server.service。

如果你想自己构建这个程序,请在任何装有 Docker 的电脑上,在 Oleafly 仓库的克隆中运行下面的命令。ARM 服务器请使用 --platform linux/arm64。

终端窗口
docker buildx build --platform linux/amd64 --target binary --output type=local,dest=dist -f crates/oleafly-server/Dockerfile .

这会写出 dist/oleafly-server。把它复制到服务器上的 /usr/local/bin/oleafly-server,并设为可执行。

  1. 创建设置文件。只有 root 能读取它:

    终端窗口
    sudo install -d -m 0755 /etc/oleafly-server
    sudo install -m 0600 /dev/null /etc/oleafly-server/oleafly-server.env
    sudoedit /etc/oleafly-server/oleafly-server.env

    每行写一项设置。OLEAFLY_BIND=127.0.0.1:8080 让服务器不暴露到网络上,只有 Caddy 能访问它。不要设置 OLEAFLY_DATA_DIR,因为单元会设置它。

    OLEAFLY_PUBLIC_URL=https://collab.example.org
    OLEAFLY_BIND=127.0.0.1:8080
    OLEAFLY_BEHIND_PROXY=true
    OLEAFLY_SERVER_NAME=Smith Lab
    OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
    OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
  2. 从解压后的压缩包,或从仓库克隆中的 deploy/server 安装并启动这个单元。然后找到设置码:

    终端窗口
    sudo install -m 0644 oleafly-server.service /etc/systemd/system/oleafly-server.service
    sudo systemctl daemon-reload
    sudo systemctl enable --now oleafly-server
    sudo journalctl -u oleafly-server | grep 'Setup code'

这个单元以 systemd 为它创建的用户来运行服务器,对系统其余部分只有只读视图。它唯一能写入的位置是 /var/lib/oleafly-server,它的数据就保存在那里。在磁盘上,这个文件夹是 /var/lib/private/oleafly-server。

要让客户端密钥不出现在设置文件里,请使用 systemd 凭据。把密钥保存在 /etc/oleafly-server/github-client-secret 中,权限设为 600,从设置文件中删除 OLEAFLY_GITHUB_CLIENT_SECRET 这一行,运行 sudo systemctl edit oleafly-server,并添加:

[Service]
LoadCredential=github-client-secret:/etc/oleafly-server/github-client-secret
Environment=OLEAFLY_GITHUB_CLIENT_SECRET_FILE=%d/github-client-secret

然后运行 sudo systemctl restart oleafly-server。

按照适用于你所用发行版的说明 (在新标签页中打开)安装 Caddy。用下面几行替换 /etc/caddy/Caddyfile,然后运行 sudo systemctl reload caddy。Caddy 会获取证书,并转发实时连接。

collab.example.org {
reverse_proxy 127.0.0.1:8080
}

如果使用 nginx 或 Apache,或你的学校已在运行的 Web 服务器,请阅读反向代理之后。

如果机器没有公网地址,例如学校防火墙后面你实验室里的一台电脑,可以用 Cloudflare Tunnel 让它可以被访问。你需要一个添加了你的域名的 Cloudflare 账户。Cloudflare 负责该主机名的 HTTPS,所以请求在到达你的机器之前,会在 Cloudflare 的网络上被解密。请把 Cloudflare 算作能够读取你服务器流量的一方。

Cloudflare Tunnel 部署每台电脑上的 Oleafly 通过 HTTPS 连接到 Cloudflare。你机器上的 cloudflared 容器向外建立一条通往 Cloudflare 的隧道,所以这台机器不需要公网地址。请求经隧道到达 cloudflared,再由它转发给 oleafly-server。你的机器(无公网地址)Oleafly在每台电脑上CloudflareHTTPScloudflared建立隧道oleafly-server数据卷Cloudflare Tunnel 部署每台电脑上的 Oleafly 通过 HTTPS 连接到 Cloudflare。你机器上的 cloudflared 容器向外建立一条通往 Cloudflare 的隧道,所以这台机器不需要公网地址。请求经隧道到达 cloudflared,再由它转发给 oleafly-server。你的机器(无公网地址)Oleafly在每台电脑上CloudflareHTTPScloudflared建立隧道oleafly-server数据卷隧道
Cloudflare Tunnel:由你的机器自己建立隧道,所以不需要公网地址。
  1. 按照手动使用 Docker Compose的步骤做到编辑 .env 为止。把 OLEAFLY_DOMAIN 设为你要使用的主机名,比如 collab.example.org。一条命令的安装脚本不适合这里,因为它会启动 Caddy。

  2. 只启动服务器。这里不需要 Caddy:

    终端窗口
    sudo docker compose up -d oleafly-server
  3. 在 Cloudflare 控制台中,进入 Networking › Tunnels,点击 Create Tunnel,给它起个名字,然后再次点击 Create Tunnel。从它显示的安装命令中复制令牌。

  4. 在服务器旁边启动隧道。read 命令会等你粘贴令牌,并且不显示它:

    终端窗口
    read -rs TUNNEL_TOKEN && export TUNNEL_TOKEN
    sudo --preserve-env=TUNNEL_TOKEN docker run -d --name oleafly-tunnel --restart unless-stopped --network oleafly-server_default -e TUNNEL_TOKEN cloudflare/cloudflared:2026.10.0 tunnel --no-autoupdate run
  5. 回到控制台,打开这条隧道。在 Routes 下,点击 Add route,然后点击 Published application。在 Hostname 下输入子域名并选择你的域名。把 Service URL 设为 http://oleafly-server:8080,然后点击 Add route。

  6. 检查它是否在 https://collab.example.org/healthz 应答,然后成为第一位管理员。

在没有 Docker 的机器上,请从 Cloudflare 的软件包仓库 (在新标签页中打开)安装 cloudflared,运行 sudo cloudflared service install 并接上令牌,然后把 Service URL 设为 http://127.0.0.1:8080。

Cloudflare 会转发实时连接,并把访问者的地址放在 X-Forwarded-For 的最后,所以请保持 OLEAFLY_BEHIND_PROXY=true。当隧道通向的是另一个代理(比如 Coolify 的)而不是直接通向服务器时,还要设置 OLEAFLY_PROXY_HOPS=2。Cloudflare 在其 Free 和 Pro 套餐中会拒绝大于 100 MB 的请求,所以请把 OLEAFLY_MAX_PROJECT_MB 设为 100 或更小,否则大项目会上传失败。不要在服务器前面放 Cloudflare Access,因为 Oleafly 无法越过它的登录页面。

以后更新服务器时,请下载新版本的文件,并指定服务名,这样 Caddy 就不会被启动:sudo docker compose up -d oleafly-server。

新服务器没有管理员。在有人完成设置之前,服务器每次启动都会生成一个新的一次性设置码,并把它写入日志。

  1. 在日志中找到以 Setup code: 开头的最新一行:
    • 一条命令安装:安装脚本在结束时会输出它。要再次查看,请运行 cd /opt/oleafly-server && sudo docker compose logs oleafly-server | grep 'Setup code'
    • 手动使用 Docker Compose:在服务器的文件夹中运行 sudo docker compose logs oleafly-server | grep 'Setup code'
    • Coolify:oleafly-server 服务的日志
    • systemd:sudo journalctl -u oleafly-server | grep 'Setup code'
  2. 在 Oleafly 中打开设置 → 协作,点击添加服务器,并输入你的服务器地址。Oleafly 发现服务器需要设置,会要求输入设置码。
  3. 输入代码,并用你配置的任一提供方登录。你就成为这台服务器的管理员,代码随即失效。

在你使用它之前,任何拿到这个代码的人都可以让自己成为管理员,所以只能把它粘贴到 Oleafly 中。

你也可以用 OLEAFLY_SETUP_CODE 自己选择代码:至少 12 个字母或数字,愿意的话可以加连字符或空格。这样服务器就永远不会打印它。日志里只会写 Setup code: set by OLEAFLY_SETUP_CODE,你输入自己设置的值即可。设置完成后,请把它从你的设置中删除。

接下来,让人们进来。登录与访问解释了怎么做。

  • 使用一条命令安装时,sudo sh /opt/oleafly-server/install.sh status 会一次检查容器和 HTTPS。
  • 只要服务器进程在运行,https://collab.example.org/healthz 就会应答 200。
  • 只有当服务器能写入它的数据库和数据文件夹时,/readyz 才会应答 200。不能写入时,例如磁盘已满,它会应答 503,并指出失败的是什么,database 或 storage。
  • Docker 镜像会自行检查 /readyz,所以 docker ps 和 Coolify 会显示服务器不健康,而不是显示一个在运行却什么都保存不了的服务器。
  • 在 Oleafly 中,设置 → 协作下的测试连接会检查地址、HTTPS、版本、实时连接、登录方式和服务器的时钟。管理控制台中的连接检查运行同样的检查。
图片预览

无法加载 AI 回答

请重试,或搜索文档。