# 登录与访问

为 Oleafly Server 设置登录提供方和电子邮件，用访问规则、开放注册、角色和访客决定谁能进入，开启浏览器访问，并在管理控制台中运行服务器。

人们通过你配置的提供方登录 Oleafly Server，所以服务器从不处理密码。你用访问规则决定谁能进入。其余事务由管理员在 Oleafly 的管理控制台中处理。

## 登录提供方

至少配置一个提供方。没有提供方时服务器无法启动，其日志会写明要添加哪些设置。第一位管理员用它登录，因为[通过电子邮件链接登录](#sign-in-by-email-link)在管理员开启之前一直是关闭的。每个提供方都会把人们送回你服务器上的一个回调地址：

`https://collab.example.org/auth/callback/<provider>`

如果 `OLEAFLY_PUBLIC_URL` 带有路径，回调地址也会带上这个路径，例如 `https://www.cs.example.edu/oleafly/auth/callback/github`。

### GitHub

1. 在 GitHub 上，点击你的头像，然后依次进入 **Settings › Developer settings › OAuth apps**，点击 **New OAuth App**。如果应用归某个组织所有，请改用该组织设置中的 **Developer settings**。
2. 填写 **Application name**（例如 `Smith Lab Oleafly`）、**Homepage URL**（`https://collab.example.org`）和 **Authorization callback URL**（`https://collab.example.org/auth/callback/github`）。不要开启 **Enable Device Flow**。
3. 点击 **Register application**。复制 **Client ID**，然后点击 **Generate a new client secret** 并复制密钥。
4. 设置 `OLEAFLY_GITHUB_CLIENT_ID` 和 `OLEAFLY_GITHUB_CLIENT_SECRET`，然后重启服务器。

服务器只向 GitHub 请求用户的个人资料和电子邮箱地址（`read:user` 和 `user:email`）。`OLEAFLY_GITHUB_LABEL` 可以更改登录按钮上的文字。

如果使用 GitHub Enterprise Server，请在那里注册应用，并把 `OLEAFLY_GITHUB_URL` 也设为它的地址，例如 `https://github.example.edu`。只有当你的 API 地址不寻常时，才需要设置 `OLEAFLY_GITHUB_API_URL`。

### OpenID Connect

OpenID Connect 支持 GitLab、Google、Microsoft Entra ID、Keycloak、Authentik、Okta 以及大多数高校的单点登录系统。如果你的学校只提供 SAML，请在中间加一层 Keycloak 或 Dex。

1. 选一个由字母和数字组成的短名称，例如 `GITLAB`。它会成为变量名的一部分，小写后会成为回调地址的一部分。在 Compose 的 `.env` 里，可以改写 `UNIVERSITY` 那几行，或者再加一组。
2. 在你的提供方处注册一个应用。选择机密应用或 Web 应用，把重定向 URI 设为 `https://collab.example.org/auth/callback/gitlab`，并允许 `openid`、`email` 和 `profile` 这几个范围。
3. 添加提供方的详细信息：

   ```ini
   OLEAFLY_OIDC_GITLAB_ISSUER=https://gitlab.com
   OLEAFLY_OIDC_GITLAB_CLIENT_ID=example-client-id
   OLEAFLY_OIDC_GITLAB_CLIENT_SECRET=example-client-secret
   OLEAFLY_OIDC_GITLAB_LABEL=GitLab
   ```

4. 重启服务器。

标签是登录按钮上的文字，例如 `University login`。颁发者（issuer）是提供方发布 `/.well-known/openid-configuration` 的地址。常见的几个如下：

| 提供方 | 颁发者 |
| --- | --- |
| GitLab.com | `https://gitlab.com` |
| 自行部署的 GitLab | 你的 GitLab 地址，例如 `https://gitlab.example.edu` |
| Google | `https://accounts.google.com` |
| Microsoft Entra ID | `https://login.microsoftonline.com/`，后接你的租户 ID 和 `/v2.0` |
| Keycloak | `https://sso.example.edu/realms/`，后接 realm 名称 |

### 已验证的电子邮箱地址

允许名单条目和域名规则只匹配已验证的电子邮箱地址。只有提供方明确表示地址已验证时，服务器才把它当作已验证：GitHub 标记为已验证，或者 OpenID Connect 的 `email_verified` 声明为 `true`。

有些机构的提供方不提供这个声明。如果你的提供方不提供，而且它只发放本机构控制的地址，请设置 `OLEAFLY_OIDC_<NAME>_TRUST_EMAIL=true`。对于任何人都能随意填写电子邮箱地址的提供方，千万不要设置它。否则任何人都能冒充你允许名单上的人登录。

### 学校自签的证书

如果你的学校为代理或登录服务使用自行签发的证书，服务器必须信任那家证书颁发机构。每台运行 Oleafly 的电脑也一样。

不使用 Docker 时，把证书加入操作系统。在 Debian 和 Ubuntu 上，把它复制到 `/usr/local/share/ca-certificates/`，文件名以 `.crt` 结尾，然后运行 `sudo update-ca-certificates`。

Docker 镜像里没有包管理器，所以要给它一份包含你的证书的证书列表。在 `docker-compose.yml` 旁边，于 Debian 或 Ubuntu 机器上运行：

```sh
cat /etc/ssl/certs/ca-certificates.crt university-ca.pem > ca-bundle.pem
chmod 644 ca-bundle.pem
```

然后在 `docker-compose.override.yml` 中把这个文件加到服务器上，并再次运行 `docker compose up -d`：

```yaml
services:
  oleafly-server:
    volumes:
      - ./ca-bundle.pem:/etc/ssl/certs/ca-certificates.crt:ro
```

## 电子邮件

电子邮件是可选的，没有它其他功能都能正常使用。没有电子邮件时，你需要自己把服务器地址发给大家，Oleafly 会在**与你共享的项目**中列出与每个人共享的项目。

要设置它，请给服务器一个 SMTP 账户：

```ini
OLEAFLY_SMTP_URL=smtps://oleafly%40example.org:example-app-password@smtp.example.org:465
OLEAFLY_MAIL_FROM=Smith Lab <oleafly@example.org>
```

两行要么都设置，要么都不设置。用户名和密码中的特殊字符要写成 URL 形式，例如用 `%40` 表示 `@`。

- `smtps://` 从一开始就使用 TLS，除非你指定其他端口，否则使用 465 端口。
- `smtp://` 除非你指定其他端口，否则使用 587 端口，随后用 STARTTLS 切换到 TLS。如果邮件服务器不支持 STARTTLS，服务器就不会发送。
- 同一台机器上的邮件中继是例外：`smtp://localhost`、`smtp://127.0.0.1` 和 `smtp://[::1]` 不使用 TLS 发送。
- 同一个私有网络上的中继可以在加上 `?tls=none` 后跳过 TLS，例如 `smtp://mailpit:1025?tls=none`。此时地址里不能带用户名或密码，因为它们会不加密地在网络上传输。只有在其他人都无法访问那个网络时才使用它。

服务器会用系统信任的证书来检查邮件服务器的证书。

### 服务器会发送什么

邮件共有六种。发给已有账户的人的邮件只会发到他们已验证的地址，GitHub 的 noreply 地址一律跳过。

| 邮件 | 何时发出 |
| --- | --- |
| 已添加到服务器 | 管理员按电子邮箱地址把某人加入允许名单。邮件包含服务器名称、一个 **Add to Oleafly** 链接和服务器地址。按 GitHub 用户名添加某人，或通过域名规则添加，都不会发送邮件，因为服务器还没有他们的地址。 |
| 项目已共享 | 项目所有者把某人加入项目。邮件包含项目标题、共享者、对方的角色和一个打开项目的链接，另附项目的网页，用于链接打不开应用的情况。之后更改角色不会发送邮件。每个人都可以在**设置 → 协作**中该服务器的卡片上关闭这类邮件。 |
| 新设备 | 账户在另一台设备上登录。邮件包含设备名称、它的系统和以服务器时区表示的时间，并提醒你，如果不是本人操作，请让该设备退出登录。新账户的第一台设备不会收到邮件。设置 `TZ`（例如 `TZ=Europe/Berlin`）可以选择时区。 |
| 访客邀请 | 项目所有者邀请一位访客。邮件包含项目标题、邀请人、一个 **Add to Oleafly** 链接，以及用于登录的地址。开启审批时，邀请获批后才会发出。 |
| 提及 | 有人在评论或回复中提到某位成员。邮件会写明是谁提到了他们、项目和文件、评论所针对的文本以及评论本身，并附一个在 Oleafly 中打开该评论的链接。它在评论到达服务器约一分钟后发出，同一个人在这一分钟内被提到多次，会合并成一封邮件。没有人会收到自己评论的提及邮件，也不会收到自己无法打开的项目的提及邮件，编辑评论也不会重复发送同一条提及。每个人都可以在**设置 → 协作**中该服务器的卡片上用**有人在评论中提到我时给我发邮件**关闭这类邮件。 |
| 登录链接 | 有人在服务器的登录页上请求一个。 |

管理员可以在服务器设置中用**电子邮件通知**停止除登录链接以外的所有邮件。登录链接始终会发出，因为没有它们人们就无法登录。

### 测试一下

在[管理控制台](#admin-console)中打开**电子邮件**。它会显示电子邮件是否已开启以及发件人地址，从不显示密码。管理员可以点击**发送测试邮件**，向自己已验证的地址发一封。页面随后会告诉你邮件是否已发出，或者邮件服务器是怎么回复的。

电子邮件关闭时，该页面会显示 **Add to Oleafly** 链接和服务器地址，方便你自己发给大家。

### 邮件服务器宕机时

发送邮件从不会拖住它背后的操作。服务器把邮件放在内存中的队列里，并在 30 秒、2 分钟、10 分钟、30 分钟和 2 小时后各重试一次。每次失败的尝试都会在服务器日志中记为一条警告，**电子邮件**页面会显示最近一次失败。如果最后一次尝试也失败，服务器会记录一条错误并丢弃这封邮件。服务器重启时仍在等待发送的邮件会丢失。

## 通过电子邮件链接登录

人们也可以用服务器发到邮箱的链接登录，因此不需要 GitHub 或 OpenID Connect 账户。这需要[电子邮件](#email)。然后由管理员在服务器设置中开启**通过电子邮件登录**。它默认是关闭的。

用户在 Oleafly 中点击**使用电子邮件继续**，在浏览器中输入自己的地址，然后点击**发送链接到我的邮箱**。这个链接只能使用一次，有效期 15 分钟，并且只能在请求它的那台电脑上使用。打开链接会显示一个带有**登录**按钮的页面。只是打开链接并不会用掉它，所以会跟随链接的邮件扫描器无法把它用掉。

你的访问规则仍然决定谁能进入：该电子邮箱地址在允许名单中的条目、域名规则或访客邀请。按 GitHub 用户名添加的允许名单条目不会匹配电子邮件链接。无论服务器是否放这个地址进入，页面显示的内容都一样，所以没有人能借此查出谁有账户。

开启它也会让现有账户可以通过电子邮件链接登录。链接会登录到已把该地址作为已验证地址的那个账户。服务器会保留提供方为一个账户报告过的每个已验证地址，而不只是主地址，并且即使用户后来在提供方处删除了某个地址，服务器仍会保留它。例如，GitHub 会报告 GitHub 账户上的每个已验证地址。所以，任何能读取其中一个地址的邮件的人，都可以通过电子邮件登录那个账户。开启之前，请确认大家仍然控制着自己账户上的每个地址。

如果一个地址属于多个账户，这个链接不会登录其中任何一个。如果拥有该地址的唯一账户已被停用或移除，链接会被拒绝，直到你让那个人重新进入。

服务器对同一个电子邮箱地址最多发送 3 个链接，对同一个 IP 地址在 15 分钟内最多发送 100 个链接，所以同一个地址下 50 人的班级可以全部登录。`OLEAFLY_EMAIL_LINKS_PER_ADDRESS` 和 `OLEAFLY_EMAIL_LINKS_PER_IP` 可以更改这两个数字。同一个 `/64` 网络中的所有 IPv6 地址算作一个地址。关闭**通过电子邮件登录**后，已经发出的链接也会失效。

## 用登录码登录

如果登录后浏览器无法返回 Oleafly，例如在受到严格限制的电脑上，人们可以用登录码登录。它不需要任何设置，并且适用于服务器的所有登录方式。

Oleafly 会显示你的服务器地址，后接 `/auth/device`，以及一个由八个字母组成的登录码。用户在任意手机或电脑上打开该地址，输入登录码，核对页面显示的电脑名称，然后登录。登录必须在他们输入登录码的那个浏览器里完成，所以别人以链接形式发来的登录页不会让任何人登录。

登录码只能使用一次，10 分钟后失效，并且只有请求它的那份 Oleafly 才能完成登录。点击**停止，这不是我**可以取消它。同一个 IP 地址在 10 分钟内可以请求 100 个登录码，并输错 10 次登录码。这足够 50 人的班级共用一个地址，`OLEAFLY_DEVICE_CODES_PER_IP` 可以更改这个数字。

## 访问规则

登录并不等于能进入。必须有一条访问规则放这个人进入。在管理控制台的**访问规则**下管理它们：

- **允许的人员**：按电子邮箱地址或 GitHub 用户名添加某人，并指定他们得到的角色。用户名只适用于 GitHub，因为其他提供方允许用户自己选择或更改用户名。如果服务器会发送邮件，按电子邮箱地址添加某人会把服务器地址和一个 **Add to Oleafly** 链接发给他们。
- **域名**：让在某个域名（例如 `cs.example.edu`）下拥有已验证电子邮箱地址的所有人，以你选择的角色登录。

添加好人员后，他们就可以在 Oleafly 中添加这台服务器并登录。

在**人员**下，你可以更改某人的角色、停用或重新启用他们、移除他们，以及让他们的设备退出登录。被停用的人保留账户，但在你重新启用之前无法同步。他们的更改会保留在他们的电脑上。

被你移除的人会一直被挡在外面，即使域名规则涵盖了他们的地址，或者项目所有者把他们邀请为访客。要让他们回来，请再次按电子邮箱地址或用户名添加他们。他们会拿回原来的账户，以及他们原有的所有项目。

### 开放注册

如果服务器允许任何人使用，请设置 `OLEAFLY_OPEN_SIGNUP=true` 并重启服务器。之后，任何用你的某个提供方登录的人都会得到一个成员角色的账户，不需要允许名单条目或域名规则。开启**通过电子邮件登录**时，电子邮件链接也是如此。

开放注册仍会把你移除或停用的人挡在外面，已验证地址属于某个已移除账户的人也一样。允许访客时，持有访客邀请的人登录后会成为成员，并且仍会得到受邀加入的项目。

它还会开启[每个账户的限制](/docs/collaboration/server-operations/#limits-per-account)：除非你设置了其他值，否则每个账户最多可以存储 100 MB、拥有 50 个共享项目，每小时最多上传 300 次。

管理控制台不会显示开放注册是否开启。服务器每次启动时都会在日志中写明：“Open sign-up is on, so anyone who signs in gets an account as a member.”成员在共享项目时可以互相查找，所以在开放的服务器上，可以考虑在服务器设置中关闭**成员目录**。

## 角色与权限

每个人有一个服务器角色，由管理员和维护者授予。在他们被加入的每个项目中，他们还有一个项目角色，由该项目的所有者授予。[角色](/docs/collaboration/sharing/#roles)列出了项目角色：所有者、编辑者、审阅者、评论者和查看者。

没有任何服务器角色能自行打开项目。项目访问权限只来自项目所有者。

| 操作 | 管理员 | 维护者 | 成员 | 访客 |
| --- | --- | --- | --- | --- |
| 在 Oleafly 中添加服务器 | 是 | 是 | 是 | 是 |
| 查看成员列表 | 是 | 是 | 是，除非管理员将其隐藏 | 否 |
| 共享项目 | 是 | 是 | 是 | 否 |
| 查看安全日志 | 是 | 是 | 否 | 否 |
| 向服务器添加成员 | 是 | 是 | 否 | 否 |
| 任命维护者 | 是 | 否 | 否 | 否 |
| 更改服务器设置 | 是 | 否 | 否 | 否 |
| 删除项目以释放存储空间 | 是 | 否 | 否 | 否 |
| 让某人的设备退出登录 | 是 | 是，但不包括其他管理员和维护者的设备 | 仅限自己的设备 | 仅限自己的设备 |
| 通过直接访问服务器读取已存储的项目 | 应用内不行 | 应用内不行 | 应用内不行 | 应用内不行 |

最后一行最重要。项目在服务器上不加密，所以无论角色是什么，运行这台机器的人都能读取每个已存储的项目。Oleafly 不给任何角色（包括管理员）提供在应用里做到这一点的途径。管理员为释放存储空间删除项目时，项目的所有者和成员会收到通知，他们自己的副本仍保留在各自的电脑上。

## 访客

访客是服务器之外的人，例如另一所大学的合作作者，由项目所有者邀请加入某个项目。访客只能看到自己受邀的项目。

### 开启访客

新服务器上访客是关闭的。管理员在服务器设置中用**允许访客**开启它。**访客需先审批**默认开启，所以每个邀请都要先经管理员或维护者批准才生效。关闭它可以让邀请立即生效。管理员或维护者发出的邀请会立即获批。

如果之后你关闭**允许访客**，所有者就不能再发送新邀请，未使用的邀请也会失效。已经登录过的访客保留自己的项目，直到所有者将其移除，或者你在**人员**下将其移除。

### 邀请

只有项目的所有者才能邀请访客加入该项目，操作在项目的**共享**对话框中。

- 一份邀请对应一个地址和一个项目，14 天后失效。
- 一个人每小时最多可以发送 20 份邀请。
- 开启审批时，邀请会在**人员**顶部的**待处理的访客**下等待。管理员和维护者在那里批准、拒绝或撤回邀请。所有者也可以撤回。
- 如果服务器会发送邮件，且**电子邮件通知**已开启，访客会收到一封邀请邮件。否则，Oleafly 会给所有者一个 **Add to Oleafly** 链接，由所有者自己发送。
- 如果项目已经达到服务器允许的人数上限，邀请会等待，并在有人离开后，该用户下一次登录时生效。

访客添加服务器，并用任何能让服务器得到受邀地址作为已验证地址的方式登录：GitHub、OpenID Connect 提供方或电子邮件链接。未验证的地址不算数。首次登录会创建访客账户，并打开该地址受邀的所有项目。

### 访客能做什么

访客可以打开并编译自己受邀加入的项目，在角色允许时编辑它们，并让自己的设备退出登录。他们看不到成员目录或任何人的电子邮箱地址，不能共享项目，不能邀请其他人，也不能通过项目的链接加入项目。要让访客加入另一个项目，由那个项目的所有者邀请同一个地址。

访客被移出最后一个项目，或自己离开它时，服务器会终止其访问权限：移除账户，并让每台设备退出登录。新的邀请会恢复同一个账户。如果访客仍有项目时你在**人员**下移除了他，新的邀请不会把他带回来。

### 移除后不会自行恢复

所有者把某人从项目中移除后，无论是不是访客，这个人都不能再通过项目的链接回来，即使链接共享是开启的。每次尝试都会记入安全日志。要让他们回来，所有者需要重新添加他们，如果是访客，则重新发送邀请。自己离开项目的人仍然可以通过项目的链接重新加入。

## 浏览器访问

开启浏览器访问后，人们无需安装 Oleafly，就可以在网页浏览器中打开与他们共享的项目。他们可以编辑、建议更改、评论、聊天，并阅读最近一次编译出的 PDF。[在浏览器中工作](/docs/collaboration/browser/)介绍了他们会看到什么。

设置 `OLEAFLY_WEB=true` 并重启服务器。发布的容器镜像包含浏览器应用。不含浏览器应用的构建会在日志中写入“OLEAFLY_WEB is true, but this build of Oleafly Server has no browser app, so browser access stays off.”

开启之后：

- 浏览器应用位于你的服务器地址后接 `/web/`，例如 `https://collab.example.org/web/`。每个项目在 `/p/` 下的页面也会多出一个**在浏览器中打开**链接。
- 人们在 `/web/sign-in` 登录，可用的提供方和电子邮件链接与 Oleafly 中相同，也由相同的访问规则决定谁能进入。浏览器会保持登录 30 天。
- 每个浏览器都算作该账户的一台设备，名称类似“Safari on macOS”。它会显示在此人的设备列表和安全日志中，让它退出登录会结束该浏览器的会话。
- 浏览器通过 WebSocket 连接到 `/web/ws`，没有更慢的备用路径，所以你的代理必须在那里放行 WebSocket 升级。Caddy 以及[反向代理之后](/docs/collaboration/server-operations/#behind-a-reverse-proxy)中的 nginx 和 Apache 示例已经这样做了。
- 人们阅读的 PDF 是所有者或编辑者在 Oleafly 中最近一次编译出的 PDF。[编译出的 PDF](/docs/collaboration/server-operations/#compiled-pdfs)说明了它是如何到达服务器的。

浏览器应用无法嵌入其他网站的框架中显示。除了加载人们的头像图片，它只连接你的服务器。

## 管理控制台

管理控制台是一个在 Oleafly 中运行单台服务器的窗口。管理员和维护者可以打开它。在**设置 → 协作**中，点击该服务器卡片上的**打开管理控制台**，或者在**管理服务器**顶部点击它。每台服务器有自己的窗口。

| 栏目 | 显示和执行的内容 |
| --- | --- |
| **概览** | 服务器是否运行正常，有多少人、设备和项目，谁在线，占用了多少存储空间，它的电子邮件和登录方式，以及一览式的设置。服务器没有任何登录方式时会警告**无人可以登录**，数据文件夹无法写入时会警告**服务器无法保存文件**。 |
| **人员** | 所有登录过的人。更改角色，停用或移除人员，让他们的设备退出登录。等待审批的访客邀请显示在顶部。 |
| **访问规则** | 允许的人员列表和域名规则。 |
| **项目** | 服务器上共享的每个项目，包括所有者、人数、大小和最近活动。可按标题或所有者搜索，只显示已共享、已归档或正在上传的项目，并可归档或恢复项目。 |
| **服务器设置** | [服务器设置](#server-settings)。 |
| **电子邮件** | 是否已设置电子邮件、发件人地址和最近一次失败。可以在这里发送测试邮件。 |
| **安全日志** | 登录和被拒绝的登录、设备、人员、设置、项目和访客。每条记录都写明是谁、何时、从哪个 IP 地址操作的，并附有项目、所用登录方式或登录被拒原因等详情。 |
| **连接检查** | 与**测试连接**相同的检查，从你的电脑运行到服务器。 |

维护者可以使用所有栏目，但他们不能让任何人成为管理员或维护者，不能查看或让其他管理员或维护者的设备退出登录，不能查看存储用量，不能归档或恢复项目，不能更改服务器设置，也不能发送测试邮件。管理员可以做所有这些事。

归档项目会对所有人停止共享。人们会停止同步它，并保留各自的副本，服务器会在 `OLEAFLY_ARCHIVE_DAYS` 天后删除它，除非管理员在此之前恢复它。恢复后会重新与原来的人共享。从未完成首次上传的项目无法恢复。两种操作都会记入安全日志。

控制台从不打开项目。它显示标题、所有者和大小，不显示项目内部的任何内容。

### 服务器设置

这些设置适用于服务器上的所有人。只有管理员可以更改。

| 设置 | 作用 |
| --- | --- |
| **允许访客** | 成员可以邀请服务器外部的人加入自己拥有的项目。 |
| **访客需先审批** | 每个访客邀请都要先由维护者或管理员批准才生效。 |
| **成员目录** | 成员在共享项目时可以按姓名查找彼此。 |
| **在目录中显示电子邮箱地址** | 成员查找某人时可以看到彼此的电子邮箱地址。 |
| **允许链接共享** | 项目所有者可以让任何成员通过链接打开项目。 |
| **允许笔记公开链接** | 成员可以把笔记的只读副本发布到一个链接上，任何人无需登录即可打开。默认关闭。关闭它会让所有已发布的链接失效，直到你重新开启。参见[发布只读副本](/docs/notes/projects-and-sharing/#publish-a-read-only-copy)。 |
| **允许项目访问日志** | 项目所有者可以记录谁打开过他们的项目。 |
| **允许评论** | 共享项目中的成员可以对文本发表评论并回复。关闭后会在所有地方隐藏评论，但仍会保存它们。 |
| **电子邮件通知** | 关闭后，服务器停止为所有人发送邮件，登录链接除外。 |
| **通过电子邮件登录** | 人们可以用发到自己电子邮箱的链接登录。这需要服务器的电子邮件设置。 |
