基于Outline构建团队的知识库(上篇)

本文是网友要求写的,文章有点长,为了便于阅读分成了上、下两篇,上篇主要是一些前期的准备工作,下篇才是正式的安装

什么是 Outline ?

Outline 是使用 ReactNode.js 构建的开放、可扩展的 wiki,美观,功能丰富,并兼容 Markdown,是适用于成长型团队的最快 wiki 和知识库。

如果你不想自己部署,可以去官网:https://www.getoutline.com/ 看看

前言

最早折腾 Outline 是去年 11 月,当时遇到了认证的问题给搁置了,直到最近有网友问起,才又捡起来研究。

OutlineDocker 部署并不难,只是环境变量有点多,仔细一点应该是没问题的,麻烦的是 Outline 不支持本地认证,也就说 Outline 不支持电子邮件 + 密码的身份验证方式,而需要借助第三方认证,比如 GoogleMicrosoft / AzureOIDCSlack 等等,至于 LDAPSAML 则只会包含在企业版中,不会包含在开源代码库中。考虑到 Google 在国内访问的麻烦,老苏第一次选了 Microsoft ,结果反而还遇到了问题(具体的问题后面有描述)。

这回老苏改换用 Slack 做第三方认证,总算顺利的搞定了。

部署的方式用的是 docker-compose命令行,没有用 portainer 的原因是因为用到了环境变量文件,而 portainer 并不支持搜索主机的绝对路径,变通的办法是给 portainer 映射卷,然后把环境变量文件放到映射的卷里

能不能用群晖的 docker 管理器?老苏觉得应该可以,只是容器多,环境变量多,调试的时候很不方便,现在也懒得再去重新改了,最近工作比较忙,这么多图弄起来也是不小的工作量。

安装

下载镜像

开始是打算过用 portainer 安装的,考虑到 deploy the stack 的时候看不到镜像的下载进度,所以老苏把要用到镜像都先下载了

Outline 依赖下面这 3 个软件,所以一共要下载四个镜像:

  • PostgreSQL (v12+)
  • Redis (v4+)
  • Minio, S3, or S3 兼容对象存储服务

在注册表中搜索 postgres ,选择第一个 postgres,版本选择 latest

在注册表中搜索 redis ,选择第一个 redis,版本选择 latest

在注册表中搜索 minio ,选择第一个 minio/minio,版本选择 latest

关于 minio 可以看老苏之前写的:『 拥有自己的MinIO对象存储服务器 』,原本开始准备用 Fake S3 的,因为不熟悉所以改了。

在注册表中搜索 outline ,选择第一个 outlinewiki/outline,版本选择 latest

准备域名

用第三方认证涉及到回调地址,所以需要有可以访问的域名,老苏准备了两个

域名 局域网地址 备注
https://ot.laosu.ml http://192.168.0.197:6070 Outline 的访问地址
https://s3.laosu.ml http://192.168.0.197:9100 minio api 的访问地址

分别用 Nginx Proxy Manager 做了反代处理

其中:

  • 192.168.0.197 为群晖的 IP
  • 6070 是准备分配给 Outline 的端口

SSL 设置里全部勾选了

另一个地址 https://s3.laosu.ml

  • 9100 是准备分配给 Outline API 的端口
  • 9101 是准备分配给 Outline Console 的端口,出于安全性考虑,并没有将 9101 映射到公网,所以不能通过 Web 从公网来访问 Console,只能在局域网中通过 http://192.168.0.197:9101 访问

SSL 设置里全部勾选了

还需要在 Advanced –> Custom Nginx Configuration 中填入👇下面的内容

参考:https://docs.min.io/docs/setup-nginx-proxy-with-minio.html

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Proxy requests to the bucket "outline" to MinIO server running on port 9100
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;

proxy_connect_timeout 300;
# Default is HTTP/1, keepalive is only enabled in HTTP/1.1
proxy_http_version 1.1;
proxy_set_header Connection "";
chunked_transfer_encoding off;

proxy_pass http://192.168.0.197:9100;
}

其中 proxy_pass http://192.168.0.197:9100; 要改为你自己的局域网 IP + 端口

获取认证信息

关于第三方认证,参考的是官方的文档:https://app.getoutline.com/share/770a97da-13e5-401e-9f8a-37949c19f97e/doc/authentication-7ViKRmRY5o

微软认证虽然失败了,但还是记录了过程,方便后续发现问题,如果你们看出来,请一定告诉我,当局者总是迷的

微软(失败)

  1. 打开网址:portal.azure.com
  2. 找到 Azure Active Directory

左侧菜单中找到 应用注册,选择 + 新注册

  1. 注册应用程序 中填入
  • 应用的名称
  • 账户类型选择 仅此组织目录中的账号
  • 重定向 URI 中选择 Web,后面的地址填入
    https://域名/auth/azure.callback,也就是 https://ot.laosu.ml/auth/azure.callback

实际上老苏因为没有备案的缘故,域名后是带端口的,但在不影响理解的情况下老苏的描述一般会忽略端口的存在;

  1. 注册 后,客户获取到 Client ID

这个值对应着 AZURE_CLIENT_ID

  1. 左侧菜单 API 权限,选择 + 添加权限

选择 Microsoft Graph

委托的权限 –> OpenId 权限 中勾选 emailprofile,然后点下面的 添加权限 按钮

添加完成后可以在列表中找到

  1. 左侧菜单 证书和密码,选择 + 新客户端密码

用了默认的截止期限,可以自定义

添加完成,可以获取到 AZURE_CLIENT_SECRET

注意不是 机密 ID,而是前面的

  1. 左侧菜单 清单,查找 resourceAppId

这个值对应着 AZURE_RESOURCE_APP_ID

Slack(成功)

  1. 打开网址:https://api.slack.com/apps,登录后点 Create an App 创建一个新应用

如果还没有账号,需要先注册一个

填入相关信息,比如 App nameicondescription 等,然后保存

老苏懒得改,都用的默认值,反正就是测试而已

  1. 左侧菜单中找到 OAuth & Permissions,在 Redirect URLs 的地址填入
    https://域名/auth/slack.callback,也就是 https://ot.laosu.ml/auth/slack.callback,点后面的Add 按钮之后,别忘记还要点 Save URLs 按钮

和前面一样,老苏忽略了端口,真实的域名实际上是带端口的

  1. 往下找到 Scopes –> User Token Scopes,通过 Add an OAuth Scope 添加
  • identify.avatar
  • identify.basic
  • identify.email
  • identify.team

  1. 左侧菜单中找到 Basic Information,下拉找到 App Credentials,找到 Client IDClient Secret

其中 Client ID 对应 docker.env.txt 中的 SLACK_KEYClient Secret 则对应着 SLACK_SECRET

到这里,前期的准备工作就差不多了,下篇开始正式进入安装环节

参考文档

outline/outline: The fastest wiki and knowledge base for growing teams. Beautiful, feature rich, and markdown compatible.
地址:https://github.com/outline/outline

Outline – Team knowledge base & wiki
地址:https://www.getoutline.com/

Use Fake S3 to simulate and test APIs of Amazon S3 in a sandbox environment | Devforgalaxy
地址:https://zeckli.github.io/en/2017/02/14/use-fake-s3-to-test-aws-s3-api-en.html