运行服务器
登录与访问
为 Oleafly Server 设置登录提供方和电子邮件,用访问规则、开放注册、角色和访客决定谁能进入,开启浏览器访问,并在管理控制台中运行服务器。
人们通过你配置的提供方登录 Oleafly Server,所以服务器从不处理密码。你用访问规则决定谁能进入。其余事务由管理员在 Oleafly 的管理控制台中处理。
登录提供方
标题为“登录提供方”的部分至少配置一个提供方。没有提供方时服务器无法启动,其日志会写明要添加哪些设置。第一位管理员用它登录,因为通过电子邮件链接登录在管理员开启之前一直是关闭的。每个提供方都会把人们送回你服务器上的一个回调地址:
https://collab.example.org/auth/callback/<provider>
如果 OLEAFLY_PUBLIC_URL 带有路径,回调地址也会带上这个路径,例如 https://www.cs.example.edu/oleafly/auth/callback/github。
GitHub
标题为“GitHub”的部分- 在 GitHub 上,点击你的头像,然后依次进入 Settings › Developer settings › OAuth apps,点击 New OAuth App。如果应用归某个组织所有,请改用该组织设置中的 Developer settings。
- 填写 Application name(例如
Smith Lab Oleafly)、Homepage URL(https://collab.example.org)和 Authorization callback URL(https://collab.example.org/auth/callback/github)。不要开启 Enable Device Flow。 - 点击 Register application。复制 Client ID,然后点击 Generate a new client secret 并复制密钥。
- 设置
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”的部分OpenID Connect 支持 GitLab、Google、Microsoft Entra ID、Keycloak、Authentik、Okta 以及大多数高校的单点登录系统。如果你的学校只提供 SAML,请在中间加一层 Keycloak 或 Dex。
-
选一个由字母和数字组成的短名称,例如
GITLAB。它会成为变量名的一部分,小写后会成为回调地址的一部分。在 Compose 的.env里,可以改写UNIVERSITY那几行,或者再加一组。 -
在你的提供方处注册一个应用。选择机密应用或 Web 应用,把重定向 URI 设为
https://collab.example.org/auth/callback/gitlab,并允许openid、email和profile这几个范围。 -
添加提供方的详细信息:
OLEAFLY_OIDC_GITLAB_ISSUER=https://gitlab.comOLEAFLY_OIDC_GITLAB_CLIENT_ID=example-client-idOLEAFLY_OIDC_GITLAB_CLIENT_SECRET=example-client-secretOLEAFLY_OIDC_GITLAB_LABEL=GitLab -
重启服务器。
标签是登录按钮上的文字,例如 University login。颁发者(issuer)是提供方发布 /.well-known/openid-configuration 的地址。常见的几个如下:
| 提供方 | 颁发者 |
|---|---|
| GitLab.com | https://gitlab.com |
| 自行部署的 GitLab | 你的 GitLab 地址,例如 https://gitlab.example.edu |
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 机器上运行:
cat /etc/ssl/certs/ca-certificates.crt university-ca.pem > ca-bundle.pemchmod 644 ca-bundle.pem然后在 docker-compose.override.yml 中把这个文件加到服务器上,并再次运行 docker compose up -d:
services: oleafly-server: volumes: - ./ca-bundle.pem:/etc/ssl/certs/ca-certificates.crt:ro电子邮件
标题为“电子邮件”的部分电子邮件是可选的,没有它其他功能都能正常使用。没有电子邮件时,你需要自己把服务器地址发给大家,Oleafly 会在与你共享的项目中列出与每个人共享的项目。
要设置它,请给服务器一个 SMTP 账户:
OLEAFLY_SMTP_URL=smtps://oleafly%40example.org:example-app-password@smtp.example.org:465OLEAFLY_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 中打开该评论的链接。它在评论到达服务器约一分钟后发出,同一个人在这一分钟内被提到多次,会合并成一封邮件。没有人会收到自己评论的提及邮件,也不会收到自己无法打开的项目的提及邮件,编辑评论也不会重复发送同一条提及。每个人都可以在设置 → 协作中该服务器的卡片上用有人在评论中提到我时给我发邮件关闭这类邮件。 |
| 登录链接 | 有人在服务器的登录页上请求一个。 |
管理员可以在服务器设置中用电子邮件通知停止除登录链接以外的所有邮件。登录链接始终会发出,因为没有它们人们就无法登录。
测试一下
标题为“测试一下”的部分在管理控制台中打开电子邮件。它会显示电子邮件是否已开启以及发件人地址,从不显示密码。管理员可以点击发送测试邮件,向自己已验证的地址发一封。页面随后会告诉你邮件是否已发出,或者邮件服务器是怎么回复的。
电子邮件关闭时,该页面会显示 Add to Oleafly 链接和服务器地址,方便你自己发给大家。
邮件服务器宕机时
标题为“邮件服务器宕机时”的部分发送邮件从不会拖住它背后的操作。服务器把邮件放在内存中的队列里,并在 30 秒、2 分钟、10 分钟、30 分钟和 2 小时后各重试一次。每次失败的尝试都会在服务器日志中记为一条警告,电子邮件页面会显示最近一次失败。如果最后一次尝试也失败,服务器会记录一条错误并丢弃这封邮件。服务器重启时仍在等待发送的邮件会丢失。
通过电子邮件链接登录
标题为“通过电子邮件链接登录”的部分人们也可以用服务器发到邮箱的链接登录,因此不需要 GitHub 或 OpenID Connect 账户。这需要电子邮件。然后由管理员在服务器设置中开启通过电子邮件登录。它默认是关闭的。
用户在 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 并重启服务器。之后,任何用你的某个提供方登录的人都会得到一个成员角色的账户,不需要允许名单条目或域名规则。开启通过电子邮件登录时,电子邮件链接也是如此。
开放注册仍会把你移除或停用的人挡在外面,已验证地址属于某个已移除账户的人也一样。允许访客时,持有访客邀请的人登录后会成为成员,并且仍会得到受邀加入的项目。
它还会开启每个账户的限制:除非你设置了其他值,否则每个账户最多可以存储 100 MB、拥有 50 个共享项目,每小时最多上传 300 次。
管理控制台不会显示开放注册是否开启。服务器每次启动时都会在日志中写明:“Open sign-up is on, so anyone who signs in gets an account as a member.”成员在共享项目时可以互相查找,所以在开放的服务器上,可以考虑在服务器设置中关闭成员目录。
角色与权限
标题为“角色与权限”的部分每个人有一个服务器角色,由管理员和维护者授予。在他们被加入的每个项目中,他们还有一个项目角色,由该项目的所有者授予。角色列出了项目角色:所有者、编辑者、审阅者、评论者和查看者。
没有任何服务器角色能自行打开项目。项目访问权限只来自项目所有者。
| 操作 | 管理员 | 维护者 | 成员 | 访客 |
|---|---|---|---|---|
| 在 Oleafly 中添加服务器 | 是 | 是 | 是 | 是 |
| 查看成员列表 | 是 | 是 | 是,除非管理员将其隐藏 | 否 |
| 共享项目 | 是 | 是 | 是 | 否 |
| 查看安全日志 | 是 | 是 | 否 | 否 |
| 向服务器添加成员 | 是 | 是 | 否 | 否 |
| 任命维护者 | 是 | 否 | 否 | 否 |
| 更改服务器设置 | 是 | 否 | 否 | 否 |
| 删除项目以释放存储空间 | 是 | 否 | 否 | 否 |
| 让某人的设备退出登录 | 是 | 是,但不包括其他管理员和维护者的设备 | 仅限自己的设备 | 仅限自己的设备 |
| 通过直接访问服务器读取已存储的项目 | 应用内不行 | 应用内不行 | 应用内不行 | 应用内不行 |
最后一行最重要。项目在服务器上不加密,所以无论角色是什么,运行这台机器的人都能读取每个已存储的项目。Oleafly 不给任何角色(包括管理员)提供在应用里做到这一点的途径。管理员为释放存储空间删除项目时,项目的所有者和成员会收到通知,他们自己的副本仍保留在各自的电脑上。
访客是服务器之外的人,例如另一所大学的合作作者,由项目所有者邀请加入某个项目。访客只能看到自己受邀的项目。
开启访客
标题为“开启访客”的部分新服务器上访客是关闭的。管理员在服务器设置中用允许访客开启它。访客需先审批默认开启,所以每个邀请都要先经管理员或维护者批准才生效。关闭它可以让邀请立即生效。管理员或维护者发出的邀请会立即获批。
如果之后你关闭允许访客,所有者就不能再发送新邀请,未使用的邀请也会失效。已经登录过的访客保留自己的项目,直到所有者将其移除,或者你在人员下将其移除。
只有项目的所有者才能邀请访客加入该项目,操作在项目的共享对话框中。
- 一份邀请对应一个地址和一个项目,14 天后失效。
- 一个人每小时最多可以发送 20 份邀请。
- 开启审批时,邀请会在人员顶部的待处理的访客下等待。管理员和维护者在那里批准、拒绝或撤回邀请。所有者也可以撤回。
- 如果服务器会发送邮件,且电子邮件通知已开启,访客会收到一封邀请邮件。否则,Oleafly 会给所有者一个 Add to Oleafly 链接,由所有者自己发送。
- 如果项目已经达到服务器允许的人数上限,邀请会等待,并在有人离开后,该用户下一次登录时生效。
访客添加服务器,并用任何能让服务器得到受邀地址作为已验证地址的方式登录:GitHub、OpenID Connect 提供方或电子邮件链接。未验证的地址不算数。首次登录会创建访客账户,并打开该地址受邀的所有项目。
访客能做什么
标题为“访客能做什么”的部分访客可以打开并编译自己受邀加入的项目,在角色允许时编辑它们,并让自己的设备退出登录。他们看不到成员目录或任何人的电子邮箱地址,不能共享项目,不能邀请其他人,也不能通过项目的链接加入项目。要让访客加入另一个项目,由那个项目的所有者邀请同一个地址。
访客被移出最后一个项目,或自己离开它时,服务器会终止其访问权限:移除账户,并让每台设备退出登录。新的邀请会恢复同一个账户。如果访客仍有项目时你在人员下移除了他,新的邀请不会把他带回来。
移除后不会自行恢复
标题为“移除后不会自行恢复”的部分所有者把某人从项目中移除后,无论是不是访客,这个人都不能再通过项目的链接回来,即使链接共享是开启的。每次尝试都会记入安全日志。要让他们回来,所有者需要重新添加他们,如果是访客,则重新发送邀请。自己离开项目的人仍然可以通过项目的链接重新加入。
浏览器访问
标题为“浏览器访问”的部分开启浏览器访问后,人们无需安装 Oleafly,就可以在网页浏览器中打开与他们共享的项目。他们可以编辑、建议更改、评论、聊天,并阅读最近一次编译出的 PDF。在浏览器中工作介绍了他们会看到什么。
设置 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 以及反向代理之后中的 nginx 和 Apache 示例已经这样做了。 - 人们阅读的 PDF 是所有者或编辑者在 Oleafly 中最近一次编译出的 PDF。编译出的 PDF说明了它是如何到达服务器的。
浏览器应用无法嵌入其他网站的框架中显示。除了加载人们的头像图片,它只连接你的服务器。
管理控制台
标题为“管理控制台”的部分管理控制台是一个在 Oleafly 中运行单台服务器的窗口。管理员和维护者可以打开它。在设置 → 协作中,点击该服务器卡片上的打开管理控制台,或者在管理服务器顶部点击它。每台服务器有自己的窗口。
| 栏目 | 显示和执行的内容 |
|---|---|
| 概览 | 服务器是否运行正常,有多少人、设备和项目,谁在线,占用了多少存储空间,它的电子邮件和登录方式,以及一览式的设置。服务器没有任何登录方式时会警告无人可以登录,数据文件夹无法写入时会警告服务器无法保存文件。 |
| 人员 | 所有登录过的人。更改角色,停用或移除人员,让他们的设备退出登录。等待审批的访客邀请显示在顶部。 |
| 访问规则 | 允许的人员列表和域名规则。 |
| 项目 | 服务器上共享的每个项目,包括所有者、人数、大小和最近活动。可按标题或所有者搜索,只显示已共享、已归档或正在上传的项目,并可归档或恢复项目。 |
| 服务器设置 | 服务器设置。 |
| 电子邮件 | 是否已设置电子邮件、发件人地址和最近一次失败。可以在这里发送测试邮件。 |
| 安全日志 | 登录和被拒绝的登录、设备、人员、设置、项目和访客。每条记录都写明是谁、何时、从哪个 IP 地址操作的,并附有项目、所用登录方式或登录被拒原因等详情。 |
| 连接检查 | 与测试连接相同的检查,从你的电脑运行到服务器。 |
维护者可以使用所有栏目,但他们不能让任何人成为管理员或维护者,不能查看或让其他管理员或维护者的设备退出登录,不能查看存储用量,不能归档或恢复项目,不能更改服务器设置,也不能发送测试邮件。管理员可以做所有这些事。
归档项目会对所有人停止共享。人们会停止同步它,并保留各自的副本,服务器会在 OLEAFLY_ARCHIVE_DAYS 天后删除它,除非管理员在此之前恢复它。恢复后会重新与原来的人共享。从未完成首次上传的项目无法恢复。两种操作都会记入安全日志。
控制台从不打开项目。它显示标题、所有者和大小,不显示项目内部的任何内容。
服务器设置
标题为“服务器设置”的部分这些设置适用于服务器上的所有人。只有管理员可以更改。
| 设置 | 作用 |
|---|---|
| 允许访客 | 成员可以邀请服务器外部的人加入自己拥有的项目。 |
| 访客需先审批 | 每个访客邀请都要先由维护者或管理员批准才生效。 |
| 成员目录 | 成员在共享项目时可以按姓名查找彼此。 |
| 在目录中显示电子邮箱地址 | 成员查找某人时可以看到彼此的电子邮箱地址。 |
| 允许链接共享 | 项目所有者可以让任何成员通过链接打开项目。 |
| 允许笔记公开链接 | 成员可以把笔记的只读副本发布到一个链接上,任何人无需登录即可打开。默认关闭。关闭它会让所有已发布的链接失效,直到你重新开启。参见发布只读副本。 |
| 允许项目访问日志 | 项目所有者可以记录谁打开过他们的项目。 |
| 允许评论 | 共享项目中的成员可以对文本发表评论并回复。关闭后会在所有地方隐藏评论,但仍会保存它们。 |
| 电子邮件通知 | 关闭后,服务器停止为所有人发送邮件,登录链接除外。 |
| 通过电子邮件登录 | 人们可以用发到自己电子邮箱的链接登录。这需要服务器的电子邮件设置。 |