# 运行协作服务器

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

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

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

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

## 服务器保存什么

服务器把所有内容都保存在一个数据文件夹中，由 `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 会给你一个地址。如果这台机器没有公网地址，请阅读[没有公网地址时](#without-a-public-address)。
- **让人们登录的方式**：至少一个登录提供方，比如 GitHub OAuth 应用或你所在机构的登录。没有它服务器无法启动。服务器可以用来发信的电子邮件账户是可选的。有了它，管理员还可以让人们用邮件里的链接登录。请阅读[登录与访问](/docs/collaboration/server-access/)。

每个版本都作为容器镜像 `ghcr.io/oleafly/oleafly-server` 发布。安装脚本及其 Compose 文件在 [Oleafly Server 发布页](https://github.com/Oleafly/oleafly-server/releases)上。单个 Linux 程序形式的服务器在 [Oleafly 发布页](https://github.com/Oleafly/Oleafly/releases)上。

## 选择运行方式

| 方案 | 何时使用 |
| --- | --- |
| [一条命令](#install-with-one-command) | 一台由你维护的 Linux 机器。安装脚本会配置 Docker、Caddy 和 HTTPS，并问几个问题。不确定时从这里开始。 |
| [手动使用 Docker Compose](#docker-compose-by-hand) | 你更愿意自己放置和编辑每个文件。 |
| [Coolify](#coolify) | 你已经在运行一台 Coolify 服务器。 |
| [Render](#render) 或 [Railway](#railway) | 你更愿意付费使用托管服务，而不是自己维护机器。 |
| [不用 Docker 的 Linux](#linux-without-docker) | 无法使用 Docker 的学校虚拟机。 |

服务器从环境变量读取设置。[存储、备份与限制](/docs/collaboration/server-operations/#settings)列出了其中每一个。

## 用一条命令安装

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

运行之前，请确认：

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

:::note[公测期间]
请安装候选版本 Oleafly Server 0.1.1-rc，这样服务器才能与 Oleafly 0.4.7-rc 匹配：

```sh
curl -fsSL https://github.com/Oleafly/oleafly-server/releases/download/server-v0.1.1-rc/install.sh | sudo sh
```

下面的命令安装的是更旧的 0.1.0。如果你用其他方式运行镜像，比如 Compose、Coolify、Render 或 Railway，请使用 `ghcr.io/oleafly/oleafly-server:0.1.1-rc`。
:::

然后运行：

```sh
curl -fsSL https://oleafly.com/server/install.sh | sudo sh
```

安装脚本会：

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

然后[成为第一位管理员](#become-the-first-admin)。

你可以随时再次运行安装脚本。当它在 `/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` 从[最新版本](https://github.com/Oleafly/oleafly-server/releases/latest)下载到同一个文件夹中。检查脚本、阅读它，然后运行：

```sh
sha256sum --check --ignore-missing SHA256SUMS
sudo sh install.sh
```

### 不经询问地安装

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

```sh
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 应答并带有有效的证书。
- **更新**：先按[更新](/docs/collaboration/server-operations/#updating)所述备份。然后运行下面的命令。它会下载最新版本的文件和镜像，保留 `.env`，重启服务器并等到它应答。已连接的人会自动重新连接。安装脚本从不会把服务器退回到较旧的版本。

  ```sh
  curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update
  ```

- **卸载**：`sudo sh /opt/oleafly-server/install.sh uninstall` 会停止并移除容器。除非你在它询问时输入 `delete`，否则你的数据和 `.env` 会保留。删除它们会移除服务器上的每个共享项目、每个账户和安全日志。人们在自己电脑上保留着项目的副本。

如果安装脚本因为你无法解决的问题而停止，请[报告问题](https://github.com/Oleafly/oleafly-server/issues/new/choose)，并附上它输出的内容。

## 手动使用 Docker Compose

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

1. 按照 [Docker 的说明](https://docs.docker.com/engine/install/)安装 Docker Engine 和 Compose 插件。
2. 把你域名的 DNS 记录指向这台机器。在它前面的任何防火墙中开放 TCP 的 80 和 443 端口以及 UDP 的 443 端口。Caddy 需要 80 端口来获取证书。
3. 为服务器创建一个文件夹，把最新版本的文件下载到其中，检查它们，并创建你的设置文件：

   ```sh
   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`，并至少填写一个[登录提供方](/docs/collaboration/server-access/#sign-in-providers)。不用的提供方那几行请留空。如果值包含 `$` 或 `#`，请用单引号括起来。
5. 启动它。首次启动会下载该版本对应的服务器镜像 `ghcr.io/oleafly/oleafly-server`。

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

6. 检查它是否应答。这会输出 `200`：

   ```sh
   curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz
   ```

7. [成为第一位管理员](#become-the-first-admin)。设置码在日志里：

   ```sh
   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

有七项设置可以保存密钥：`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` 这一行：

```sh
sudo chown 10001:10001 secrets/github_client_secret
sudo chmod 400 secrets/github_client_secret
```

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

```yaml
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 会把它自己的代理放在服务器前面并获取证书，所以这种方式不需要 Caddy。Coolify 可以从 Oleafly 仓库构建服务器，也可以运行[已发布的镜像](#deploy-the-published-image)，这样就省去了构建。

开始之前，请把你域名的 DNS 记录（比如 `collab.example.org`）指向 Coolify 服务器。然后按照 [GitHub](/docs/collaboration/server-access/#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. 用这个代码[成为第一位管理员](#become-the-first-admin)。

如果服务器无法启动，它的日志会指出无法使用的那项设置。当日志说 `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

[Deploy to Render](https://render.com/deploy?repo=https://github.com/Oleafly/Oleafly) 会读取 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](/docs/collaboration/server-access/#github) 中的说明创建 GitHub OAuth 应用，以该地址后接 `/auth/callback/github` 作为回调地址。在服务的 **Environment** 下添加客户端 ID 和密钥。Render 会带着它们重启服务器。
5. 在服务的 **Logs** 中找到最新的 `Setup code:` 行，然后[成为第一位管理员](#become-the-first-admin)。

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

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

## Railway

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

1. 在 Railway 项目中，点击 **+ New**，然后点击 **Docker Image**，并输入 `ghcr.io/oleafly/oleafly-server:latest`。如果想自己选择何时升级，请改用[发布页](https://github.com/Oleafly/Oleafly/releases)上某个版本自己的标签。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](/docs/collaboration/server-access/#github) 获取。回调地址是第 2 步中的地址，前面加上 `https://`，后面加上 `/auth/callback/github`。

   ```ini
   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:` 行，然后[成为第一位管理员](#become-the-first-admin)。

## 不用 Docker 的 Linux

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

### 下载服务器

[发布页](https://github.com/Oleafly/Oleafly/releases)上的每个服务器版本都有适用于 x86-64 和 ARM 的预先构建好的程序，以及用来校验它的 `SHA256SUMS` 文件。该程序不需要安装任何其他东西。

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

```sh
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`。

```sh
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 运行

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

   ```sh
   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`，因为单元会设置它。

   ```ini
   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` 安装并启动这个单元。然后找到设置码：

   ```sh
   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`，并添加：

```ini
[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`。

### 在前面加上 HTTPS

按照[适用于你所用发行版的说明](https://caddyserver.com/docs/install)安装 Caddy。用下面几行替换 `/etc/caddy/Caddyfile`，然后运行 `sudo systemctl reload caddy`。Caddy 会获取证书，并转发实时连接。

```
collab.example.org {
	reverse_proxy 127.0.0.1:8080
}
```

如果使用 nginx 或 Apache，或你的学校已在运行的 Web 服务器，请阅读[反向代理之后](/docs/collaboration/server-operations/#behind-a-reverse-proxy)。

## 没有公网地址时

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

1. 按照[手动使用 Docker Compose](#docker-compose-by-hand)的步骤做到编辑 `.env` 为止。把 `OLEAFLY_DOMAIN` 设为你要使用的主机名，比如 `collab.example.org`。一条命令的安装脚本不适合这里，因为它会启动 Caddy。
2. 只启动服务器。这里不需要 Caddy：

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

3. 在 Cloudflare 控制台中，进入 **Networking › Tunnels**，点击 **Create Tunnel**，给它起个名字，然后再次点击 **Create Tunnel**。从它显示的安装命令中复制令牌。
4. 在服务器旁边启动隧道。`read` 命令会等你粘贴令牌，并且不显示它：

   ```sh
   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` 应答，然后[成为第一位管理员](#become-the-first-admin)。

在没有 Docker 的机器上，请从 [Cloudflare 的软件包仓库](https://pkg.cloudflare.com/)安装 `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`，你输入自己设置的值即可。设置完成后，请把它从你的设置中删除。

接下来，让人们进来。[登录与访问](/docs/collaboration/server-access/#access-rules)解释了怎么做。

## 检查服务器

- 使用一条命令安装时，`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、版本、实时连接、登录方式和服务器的时钟。[管理控制台](/docs/collaboration/server-access/#admin-console)中的**连接检查**运行同样的检查。
