lewazo/boreale

Boréale

Boréale是一个小巧简单的自托管服务，用于处理https://github.com/containous/traefik%E5%90%8E%E7%AB%AF%E6%9C%8D%E5%8A%A1%E7%9A%84%E8%BD%AC%E5%8F%91%E8%AE%A4%E8%AF%81%E3%80%82

核心功能和特性

• 非常轻量级，小于60 MB
• 支持自定义登录页面
• 所有子域名的单点登录(SSO)
• 无外部依赖
• 通过Boréale CLI轻松管理
• 安全加密的cookie
• 易于部署

为什么选择Boréale？

Traefik目前支持基本认证和摘要认证等方案。虽然这些方案工作良好，但它们非常有限，不可定制，并且每次重启浏览器都需要重新登录。

存在许多与Boréale类似的服务，但它们要么依赖Google OAuth、LDAP、Keycloak等外部服务，要么包含许多更适合大型组织的功能。

Boréale的主要目标是提供一个小型的独立解决方案，更适合家庭服务器使用。

替代方案

• https://github.com/clems4ever/authelia - 如果你正在寻找适合组织的完整解决方案
• https://github.com/thomseddon/traefik-forward-auth - 如果你正在寻找基于Google OAuth的认证

使用场景和适用范围

Boréale特别适合以下场景：

• 家庭服务器或个人自托管环境
• 需要简单但安全的认证机制的场景
• 希望为多个子域名服务提供统一认证的环境
• 不需要复杂组织功能的小型部署

使用方法和配置说明

OTP发布版

Boréale使用Elixir编写，并通过Distillery编译。这允许生成自包含的可执行文件（称为OTP发布版），可以在任何地方运行，无需依赖Elixir和Erlang环境。

因此，你可以直接从https://github.com/lewazo/boreale/releases%E4%B8%8B%E8%BD%BD%E5%8F%91%E5%B8%83%E7%89%88%E5%B9%B6%E7%9B%B4%E6%8E%A5%E8%BF%90%E8%A1%8C%E3%80%82

启动命令：./bin/boreale foreground

后台运行：./bin/boreale start

注意：启动应用前请确保所有必需的环境变量已设置。你可以在环境变量部分查看所有变量列表。环境变量的设置方式完全由你决定。

Docker部署

虽然OTP发布版很好用且易于使用，但它的缺点是需要在与目标环境相似的环境中编译。目前，仅提供在Ubuntu 18.04和MacOS Mojave上编译的二进制文件。

因此，推荐的部署方法是通过Docker。提供的Docker镜像内部仍然使用OTP发布版，但该发布版实际上是在镜像构建过程中编译的。这样做的好处是运行和编译发布版的环境相同。总体大小仍然很小，目前为58 MB。

docker-compose

使用Docker发布版的最简单方法是使用docker-compose。首先，创建一个目录用于存放Boréale配置。它可以位于任何位置。由于我使用unRAID系统，我将其放在其他docker应用程序所在的/mnt/user/appdata目录中。

在/mnt/user/appdata/boreale目录中，放置示例中的.env和docker-compose.yml文件，并进行相应编辑。避免在.env中留下空变量。查看环境变量部分了解哪些是必需的，哪些是可选的。

在上述目录中创建一个data目录作为docker卷。对我来说，路径是/mnt/user/appdata/boreale/data。你可以随意命名，只要在docker-compose.yml文件中设置正确的名称即可。

运行docker-compose up启动Boréale。

docker CLI

当然，使用docker-compose是可选的。你可以使用任何容器管理器。以下是直接使用docker CLI运行的示例。有关.env文件和data/目录的更多信息，请查看docker-compose部分。

docker run \
  --name=boreale \
  --env-file <path docker.xuanyuan.run/to .env file> \
  -p 5252:4000 \
  -v <path docker.xuanyuan.run/to data/ dir>:/opt/app/data \
  lewazo/boreale

unRAID

虽然Boréale在Community Applications插件中不可用，但你仍然可以通过使用https://github.com/lewazo/unraid-docker-templates%E6%9D%A5%E5%AE%89%E8%A3%85%E5%92%8C%E4%BD%BF%E7%94%A8%E5%AE%83%EF%BC%8C%E5%B0%B1%E5%83%8F%E4%BD%BF%E7%94%A8CA%E5%AE%89%E8%A3%85%E7%9A%84%E4%BB%BB%E4%BD%95%E5%85%B6%E4%BB%96Docker%E5%AE%B9%E5%99%A8%E4%B8%80%E6%A0%B7%E3%80%82

配置

Boréale的大部分配置是通过其CLI完成的。根据你的环境，按照以下说明使用CLI。

OTP发布版

使用OTP发布版时，只需运行./bin/boreale cli即可访问CLI。

docker-compose

使用docker-compose时，只需在docker-compose.yml文件所在的目录中运行docker-compose exec boreale bin/boreale cli。

Docker CLI

使用Docker CLI时，首先需要获取容器ID。运行docker ps并找到具有lewazo/boreale镜像的容器。然后，运行docker exec -it <CONTAINER ID> bin/boreale cli。

开发环境

在开发环境中，可以使用mix命令，如mix cli ...

Traefik配置

为了让Traefik将认证转发到Boréale，需要进行一些配置。

在以下代码片段中，将127.0.0.1替换为运行Boréale的主机IP。端口与docker-compose.yml或等效文件中定义的端口匹配。

我们使用insecureSkipVerify = true，以便Traefik可以信任我们的自签名证书。有关更多信息，请参见TLS部分。

Traefik 2.0以下版本

在traefik.toml中，在[entryPoints.https.tls]下添加以下行：

[entryPoints.https.auth.forward]
    address = "https://127.0.0.1:5252"
    [entryPoints.https.auth.forward.tls]
      insecureSkipVerify = true

Traefik 2.0及以上版本

在动态配置文件中，为Boréale定义如下中间件：

注意：Traefik v2.0现在允许使用YAML文件格式。以下配置使用YAML格式，因为在我看来它比TOML更容易使用。你仍然可以使用TOML。

http:
  middlewares:
    boreale:
      forwardAuth:
        address: "https://127.0.0.1:5252"
        tls:
          insecureSkipVerify: true

然后将中间件添加到所有希望使用Boréale保护的路由器。如果使用带标签的配置，只需将此标签添加到路由器："traefik.http.routers.<router name>.middlewares=boreale@file"。

SSO配置

SSO（单点登录）可以使用domain cookie属性实现。如果你的服务按子域设置，如service1.domain.tld、service2.domain.tld，则可以使用SSO功能。如果你使用完全不同的域，如service1-domain.tld和service2-domain.tld，则由于"同源"策略，这将不起作用。

要启用SSO，将SSO_DOMAIN_NAME环境变量设置为你的根域，例如domain.tld。这将使所有*.domain.tld和domain.tld请求共享相同的cookie。因此，用户只需登录一个服务，然后就可以在所有其他服务上进行身份验证。

不设置此变量将禁用SSO。

授权用户管理

授权用户是允许登录并访问Traefik后面所有Web服务的用户。

• 列出所有授权用户：使用CLI的users命令
• 添加新用户：使用CLI的users add命令
• 删除用户：使用CLI的users remove命令

公共域管理

注意：从Traefik v2.0开始，不再需要添加公共域，因为我们可以通过向路由器添加或不添加中间件来选择哪些路由器将认证转发到Boréale。对于Traefik v1.x，这是不可能的，因为配置是全局的；所有请求都转发到Boréale。公共域是这些版本中实现"白名单"的唯一方式。

公共域是用于访问公共服务器的FQDN，即访问此域时不应要求用户进行身份验证。这充当域的一种白名单。

• 列出所有公共域：使用CLI的domains命令
• 添加新公共域：使用CLI的domains add命令
• 删除公共域：使用CLI的domains remove命令

环境变量

以下是应在.env文件中设置或在环境中设置的环境变量。

自定义

Boréale附带默认登录表单，但使用你自己的登录表单非常简单。

只需在data/目录中添加login.html和login.css，它们将被自动使用。唯一的约束是要有username和password输入以及id为form的表单。查看示例了解默认登录表单的代码。

以下截图显示了默认登录表单： !Boréale

安全性

TLS

Boréale旨在通过转发认证直接访问。因此，你不应将其作为Traefik中的后端添加，即不应有boreale.yourdomain.tld或类似的设置。

基于这个前提，Boréale自动创建自签名证书，以提供Traefik和Boréale之间的完整HTTPS连接。这允许服务器在浏览器上设置secure cookie。

由于Boréale仅通过Traefik的认证访问，如果你信任你的私有网络，使用自签名证书是完全没问题的。

HSTS

为了保护你的服务免受cookie劫持和协议降级***，你应该启用HSTS。由于Traefik是终止连接的一方，HSTS应该在Traefik上启用，而不是在Boréale上。

开发环境设置

要开始使用此仓库，不需要任何配置（除非你想要）。你只需要运行make目标make dev，就可以在本地端口4000上运行本地Boreale环境。

注意：服务器仅监听https，证书和密钥会自动生成，因此请确保通过https方案访问端点（https://localhost:4000）。

许可证

Boréale的源代码和二进制文件受MIT许可证约束。

上述徽标由perdanakun制作，可在此处获取，并受https://creativecommons.org/licenses/by/3.0/%E8%AE%B8%E5%8F%AF%E8%AF%81%E7%BA%A6%E6%9D%9F%E3%80%82