基于Outline构建团队的知识库（上篇）

Outline 是使用 React 和 Node.js 为您的团队构建的快速、协作的知识库。

杨浦老苏

6293人浏览 · 2022-02-28 10:50:44

杨浦老苏 · 2022-02-28 10:50:44 发布

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

什么是 Outline ？

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

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

前言

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

Outline 用 Docker 部署并不难，只是环境变量有点多，仔细一点应该是没问题的，麻烦的是 Outline 不支持本地认证，也就说 Outline 不支持电子邮件 + 密码的身份验证方式，而需要借助第三方认证，比如 Google、Microsoft / Azure、OIDC、Slack 等等，至于LDAP 和 SAML 则只会包含在企业版中，不会包含在开源代码库中。考虑到 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

 # 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

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

微软（失败）

打开网址：portal.azure.com
找到 Azure Active Directory

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

在 注册应用程序 中填入

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

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

点 注册 后，客户获取到 Client ID

这个值对应着 AZURE_CLIENT_ID

左侧菜单 API 权限，选择 + 添加权限

选择 Microsoft Graph

在 委托的权限 --> OpenId 权限 中勾选 email 和 profile，然后点下面的 添加权限 按钮

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

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

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

添加完成，可以获取到 AZURE_CLIENT_SECRET

注意不是 机密 ID，而是前面的 值

左侧菜单 清单，查找 resourceAppId

这个值对应着 AZURE_RESOURCE_APP_ID

Slack（成功）

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

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

填入相关信息，比如 App name、icon、description 等，然后保存

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

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

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

往下找到 Scopes --> User Token Scopes，通过 Add an OAuth Scope 添加

identify.avatar
identify.basic
identify.email
identify.team

左侧菜单中找到 Basic Information，下拉找到 App Credentials，找到 Client ID 和 Client Secret

其中 Client ID 对应 docker.env.txt 中的 SLACK_KEY，Client 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