运行服务器
运行协作服务器
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,比如 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安装脚本会:
- 检查机器,以及 80 和 443 端口是否空闲。
- 检查是否有 Docker。如果没有,安装脚本会先询问,然后用 Docker 自己的脚本安装它。
- 从 Oleafly Server 发布页 (在新标签页中打开)下载最新版本的文件,并用该版本的
SHA256SUMS逐个检查。如果有文件不匹配,它会停止,不做任何更改。 - 询问你的域名、服务器名称以及人们如何登录。它还会提供设置电子邮件和把文件保存在 S3 存储桶的选项。这两项都是可选的。
- 显示摘要,并在做任何更改之前询问。然后把它的文件写入
/opt/oleafly-server,你的设置放在只有 root 能读取的.env中。 - 启动前面带有 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 SHA256SUMSsudo 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会保留。删除它们会移除服务器上的每个共享项目、每个账户和安全日志。人们在自己电脑上保留着项目的副本。
如果安装脚本因为你无法解决的问题而停止,请报告问题 (在新标签页中打开),并附上它输出的内容。
手动使用 Docker Compose
标题为“手动使用 Docker Compose”的部分这种方式运行两个容器。oleafly-server 是服务器,只有其他容器能访问它。caddy 从 Let’s Encrypt 获取证书,在 80 和 443 端口提供 HTTPS,并把请求转交给服务器,包括实时连接。
-
按照 Docker 的说明 (在新标签页中打开)安装 Docker Engine 和 Compose 插件。
-
把你域名的 DNS 记录指向这台机器。在它前面的任何防火墙中开放 TCP 的 80 和 443 端口以及 UDP 的 443 端口。Caddy 需要 80 端口来获取证书。
-
为服务器创建一个文件夹,把最新版本的文件下载到其中,检查它们,并创建你的设置文件:
终端窗口 sudo mkdir -p /opt/oleafly-server && cd /opt/oleafly-serverbase=https://github.com/Oleafly/oleafly-server/releases/latest/downloadfor f in docker-compose.yml Caddyfile env.example litestream.yml SHA256SUMS; do sudo curl -fsSLO "$base/$f"; donesha256sum --check --ignore-missing SHA256SUMSsudo install -m 600 env.example .env -
用
sudoedit .env编辑.env。把OLEAFLY_DOMAIN设为你的域名(不带https://),设置OLEAFLY_SERVER_NAME,并至少填写一个登录提供方。不用的提供方那几行请留空。如果值包含$或#,请用单引号括起来。 -
启动它。首次启动会下载该版本对应的服务器镜像
ghcr.io/oleafly/oleafly-server。终端窗口 sudo docker compose up -d -
检查它是否应答。这会输出
200:终端窗口 curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz -
成为第一位管理员。设置码在日志里:
终端窗口 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。
不要把密钥放进 .env
标题为“不要把密钥放进 .env”的部分有七项设置可以保存密钥: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_secretsudo 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
标题为“Coolify”的部分Coolify 会把它自己的代理放在服务器前面并获取证书,所以这种方式不需要 Caddy。Coolify 可以从 Oleafly 仓库构建服务器,也可以运行已发布的镜像,这样就省去了构建。
开始之前,请把你域名的 DNS 记录(比如 collab.example.org)指向 Coolify 服务器。然后按照 GitHub 中的说明创建 GitHub OAuth 应用,回调地址为 https://collab.example.org/auth/callback/github。把它的客户端 ID 和密钥放在手边。
从仓库构建
标题为“从仓库构建”的部分- 在你的 Coolify 项目中,点击 + New,然后点击 Public Repository,并输入
https://github.com/Oleafly/Oleafly。分支保持main。 - 把 Build Pack 设为 Docker Compose,Base Directory 设为
/,Docker Compose Location 设为/deploy/server/docker-compose.coolify.yml,然后点击 Continue。 - 在 Advanced › Build 下,把 Build arguments 设为 Managed manually in Dockerfile。服务器的镜像不需要构建参数。保持自动时,Coolify 会把每个变量(包括密钥)都写入镜像的构建历史。
- 在 General 下,把
oleafly-server的域名设为https://collab.example.org:8080并保存。:8080告诉 Coolify 的代理服务器监听哪个端口。人们仍然使用常规的 HTTPS 端口连接,Coolify 会替你把OLEAFLY_PUBLIC_URL设为https://collab.example.org。 - 在 Environment Variables 下,填写 Coolify 标为必填的
OLEAFLY_SERVER_NAME,然后填写OLEAFLY_GITHUB_CLIENT_ID和OLEAFLY_GITHUB_CLIENT_SECRET。不用的变量请留空。 - 点击 Deploy。首次构建会编译服务器,需要几分钟。完成后,Coolify 会显示该资源正在运行且状态健康。
- 在浏览器中打开
https://collab.example.org/healthz。它会显示{"status":"ok"}。 - 打开 Logs,选择
oleafly-server容器,并从以Setup code:开头的最新一行复制代码。 - 用这个代码成为第一位管理员。
如果服务器无法启动,它的日志会指出无法使用的那项设置。当日志说 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 都会拉取该系列中的最新版本。
Render
标题为“Render”的部分Deploy to Render (在新标签页中打开) 会读取 Oleafly 仓库中的 Blueprint。它用已发布的镜像创建一个 Web 服务,并配有一块 1 GB 的磁盘用于数据文件夹。Render 只给付费实例类型挂载磁盘,所以该服务从最小的付费实例开始,位于 Render 的 Oregon 区域。如需其他区域,请从分叉部署,并在 render.yaml 中设置 region。
- 打开链接并登录 Render。
- Render 会询问
OLEAFLY_SERVER_NAME以及 GitHub 客户端 ID 和密钥。填写名称,GitHub 的几项先留空。它们的回调地址取决于服务的地址,而你现在还没有这个地址。 - 点击 Deploy Blueprint。服务上线后,它的页面会显示它的地址,比如
https://oleafly-server.onrender.com。Blueprint 会把OLEAFLY_PUBLIC_URL设为这个地址。 - 按照 GitHub 中的说明创建 GitHub OAuth 应用,以该地址后接
/auth/callback/github作为回调地址。在服务的 Environment 下添加客户端 ID 和密钥。Render 会带着它们重启服务器。 - 在服务的 Logs 中找到最新的
Setup code:行,然后成为第一位管理员。
如果你给服务绑定了自己的域名,请在 Environment 下把 OLEAFLY_PUBLIC_URL 设为该域名,并在 GitHub 上相应修改回调地址。
由于有磁盘,Render 会先停止正在运行的服务器,再启动新的,所以每次部署都会让服务器中断几秒钟。Oleafly 会自动重新连接。
Railway
标题为“Railway”的部分Railway 运行已发布的镜像,并为数据文件夹配一个数据卷。
-
在 Railway 项目中,点击 + New,然后点击 Docker Image,并输入
ghcr.io/oleafly/oleafly-server:latest。如果想自己选择何时升级,请改用发布页 (在新标签页中打开)上某个版本自己的标签。Railway 可能会立即开始第一次部署。它会以OLEAFLY_PUBLIC_URL is not set停止,这在此时是预期的。 -
打开该服务。在 Settings › Networking 下,点击 Generate Domain 并输入端口
8080。Railway 会显示地址,比如oleafly-server-production.up.railway.app。 -
在 Settings › Deploy 下,把 Healthcheck Path 设为
/readyz。 -
右键点击项目画布,添加一个数据卷,把它挂到服务器的服务上,并把挂载路径设为
/data。 -
在 Variables 下,打开 Raw Editor,粘贴下面这几行,并填入你自己的服务器名称。GitHub 的值请按照 GitHub 获取。回调地址是第 2 步中的地址,前面加上
https://,后面加上/auth/callback/github。OLEAFLY_PUBLIC_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}OLEAFLY_BIND=0.0.0.0:8080OLEAFLY_DATA_DIR=/dataOLEAFLY_BEHIND_PROXY=trueOLEAFLY_SERVER_NAME=Smith LabOLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientIdOLEAFLY_GITHUB_CLIENT_SECRET=example-client-secretPORT=8080RAILWAY_RUN_UID=0Railway 以 root 身份挂载数据卷。
RAILWAY_RUN_UID=0让服务器以 root 身份运行,这样它才能写入数据卷。 -
部署这些更改。在服务的 Deploy Logs 中找到最新的
Setup code:行,然后成为第一位管理员。
不用 Docker 的 Linux
标题为“不用 Docker 的 Linux”的部分在没有 Docker 的机器上,服务器作为单个程序在 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 SHA256SUMStar -xzf oleafly-server-*-x86_64-unknown-linux-musl.tar.gzsudo install -m 0755 oleafly-server-*-x86_64-unknown-linux-musl/oleafly-server /usr/local/bin/oleafly-serveroleafly-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,并设为可执行。
用 systemd 运行
标题为“用 systemd 运行”的部分-
创建设置文件。只有 root 能读取它:
终端窗口 sudo install -d -m 0755 /etc/oleafly-serversudo install -m 0600 /dev/null /etc/oleafly-server/oleafly-server.envsudoedit /etc/oleafly-server/oleafly-server.env每行写一项设置。
OLEAFLY_BIND=127.0.0.1:8080让服务器不暴露到网络上,只有 Caddy 能访问它。不要设置OLEAFLY_DATA_DIR,因为单元会设置它。OLEAFLY_PUBLIC_URL=https://collab.example.orgOLEAFLY_BIND=127.0.0.1:8080OLEAFLY_BEHIND_PROXY=trueOLEAFLY_SERVER_NAME=Smith LabOLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientIdOLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret -
从解压后的压缩包,或从仓库克隆中的
deploy/server安装并启动这个单元。然后找到设置码:终端窗口 sudo install -m 0644 oleafly-server.service /etc/systemd/system/oleafly-server.servicesudo systemctl daemon-reloadsudo systemctl enable --now oleafly-serversudo 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-secretEnvironment=OLEAFLY_GITHUB_CLIENT_SECRET_FILE=%d/github-client-secret然后运行 sudo systemctl restart oleafly-server。
在前面加上 HTTPS
标题为“在前面加上 HTTPS”的部分按照适用于你所用发行版的说明 (在新标签页中打开)安装 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 算作能够读取你服务器流量的一方。
-
按照手动使用 Docker Compose的步骤做到编辑
.env为止。把OLEAFLY_DOMAIN设为你要使用的主机名,比如collab.example.org。一条命令的安装脚本不适合这里,因为它会启动 Caddy。 -
只启动服务器。这里不需要 Caddy:
终端窗口 sudo docker compose up -d oleafly-server -
在 Cloudflare 控制台中,进入 Networking › Tunnels,点击 Create Tunnel,给它起个名字,然后再次点击 Create Tunnel。从它显示的安装命令中复制令牌。
-
在服务器旁边启动隧道。
read命令会等你粘贴令牌,并且不显示它:终端窗口 read -rs TUNNEL_TOKEN && export TUNNEL_TOKENsudo --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 -
回到控制台,打开这条隧道。在 Routes 下,点击 Add route,然后点击 Published application。在 Hostname 下输入子域名并选择你的域名。把 Service URL 设为
http://oleafly-server:8080,然后点击 Add route。 -
检查它是否在
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。
成为第一位管理员
标题为“成为第一位管理员”的部分新服务器没有管理员。在有人完成设置之前,服务器每次启动都会生成一个新的一次性设置码,并把它写入日志。
- 在日志中找到以
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'
- 一条命令安装:安装脚本在结束时会输出它。要再次查看,请运行
- 在 Oleafly 中打开设置 → 协作,点击添加服务器,并输入你的服务器地址。Oleafly 发现服务器需要设置,会要求输入设置码。
- 输入代码,并用你配置的任一提供方登录。你就成为这台服务器的管理员,代码随即失效。
在你使用它之前,任何拿到这个代码的人都可以让自己成为管理员,所以只能把它粘贴到 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、版本、实时连接、登录方式和服务器的时钟。管理控制台中的连接检查运行同样的检查。