本文使用「署名 4.0 国际 (CC BY 4.0)」许可协议，欢迎转载、或重新修改使用，但需要注明来源。 [署名 4.0 国际 (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/deed.zh)

本文作者: 苏洋

创建时间: 2021年09月05日
统计字数: 8223字
阅读时间: 17分钟阅读
本文链接: https://soulteary.com/2021/09/05/opensource-documentation-wiki-software-outline-part-1.html

-----


# 从零开始使用开源文档/Wiki软件 Outline（一）

本篇文章将介绍一款适用于个人或团队场景使用的开源 文档/ Wiki 软件，Outline。

在介绍如何部署使用之前，先聊聊为什么我会选择它。

## 写在前面

作为一个 Confluence 重度用户、前 EverNote 重度用户，我觉得有必要聊一下我对文档、笔记、Wiki 软件的一些看法。如果你仅对部署环境感兴趣，可以直接跳转文章下面的章节。

### 为什么要切换笔记/Wiki 软件

熟悉我的朋友了解我是 Confluence 重度用户，不少个人数据都存放在私有化部署的实例上，之前还额外购置了一台 NUC，用于低成本的跑这个服务，以及折腾过不少公开或还未公开的优化方案，关于部分 Confluence 部署和运维实战相关的文章，如果你感兴趣，可以[翻阅这里](https://soulteary.com/tags/confluence.html)。

然而，在之前官方公布，不再出售授权，仅提供海外的在线 SaaS 服务，虽然我的授权会在 2022 年到期，但是考虑到长久使用，免不了要未雨绸缪，看看有没有更好的替代方案。

![即将过期的 Confluence 授权](https://attachment.soulteary.com/2021/09/05/confluence-license.jpg)

在试过国内外一众 SaaS 方案、以及部分类似 Joplin 支持私有化部署的方案、以及诸如 Obsidian 这类以本地工具为主的方案后，我最终选择了当下名气还不如它们的 Outline。

![Outline 日常使用界面](https://attachment.soulteary.com/2021/09/05/outline-webui.jpg)

### 为什么选择了 Outline

我目前已经使用这款软件两个月有余，在确认选择之前还是比较“折腾”和“犹豫”的。

影响我选择新工具的主要因素有三个：首先是书写体验要能够接近或优于 Confluence，接着是我能够拥有对输入内容的绝对管理权，能够放心的使用工具进行创作和内容管理，最后是使用工具的综合成本要相对低一些。这么组合下来，可供选择的“成品”就少了许多：

- 书写体验主要由工具编辑器的响应交互能力决定，但是不仅仅由这部分决定，想要实现更多的套路，还需要前后结合，Confluence 迭代了十几年之久，在产品体验上确实做的挺全面的，导致切换到新的软件，总能感觉到新软件**哪里缺了一些**。
- 国内外不乏一些工具提供 SaaS 方案，有免费的，也有费用比 Confluence 高一些的，或是从资源配额上进行限制，或是从协作人数上进行限制，在预算之内能够解决问题自然是最好的，但是工具厂商为了“续费”、为了能持续盈利活下去，或者扩大账面上的数字拿更多的投资，很少做到**完全将用户数据处置权完全交给用户**，而且几乎没有能够将**数据完全自托管管理**的，这和 SaaS 生态模式和当前严峻的付费环境有关，软件和用户相互提防，挺没意思的。
- 国内外也有一些开源或闭源的具备自托管能力的工具方案，但是这些方案起步时间比较早，产品策略上多数是对标早些时候类似 EverNote 这类纯粹的笔记软件，产品在内容创作场景和内容管理逻辑上和 Wiki 类产品差别还是有不少的，我比较反感“无效囤积”素材，尤其是软件默认逻辑可能就是如此。“知识库”类的工具光是解决了“书写”和“采集”的需求是不够的，还要解决“用”的问题呀。
- 参考之前流行的 API As Service 方式做产品，参考 Confluence 做一个编辑器和这类 BaaS 服务（许多方案支持私有化部署）进行联动如何呢？之前曾看过 Confluence 迄今为止几个大版本的代码变化，虽然它是基于 tinyMCE 来定制的编辑器，编写门槛虽然不高，但是产品体验相关的细节，从前到后、方方面面的细节还是比较多的，换言之，工作量并不完全在前端，或许未来我会考虑折腾一把，但目前我还是想**把精力尽可能聚焦在内容上**，而不是造轮子。
- 此外，Confluence 之前每年授权费用只有 10 刀，大概60块钱左右，相比较当前各种产品的费用，还是比较低的，如果考虑长期使用，采购一台小主机，容器启动起来就完事了。（相比较云主机同等配置资源要更便宜实惠一些）
- 至于维护成本，Confluence 维护成本其实不算低，只不过在长时间维护过多个实例后，几乎踩遍了各种坑、手熟之后，倒也还好。如果再次选择方案，我会优先选择技术栈简单、代码开放的工具，如果不开放代码，那么在数据存储上需要有明确规范的工具。

在遍寻和尝试了各种软件之后，我将目光聚焦到了 Outline 上，一款目标是成为成长性团队使用的 Wiki 和知识库的软件，它直观的优点有这些：

- Outline 是开源软件，软件由 Node 编写、数据库为 Postgres 9.x +、可以使用 Redis 作为缓存、部分存储使用 S3 兼容的对象存储协议。允许用户随意改动和进行私有化部署，所有数据由用户自己掌控，只要用户改造后不推出和官方一样的云服务进行商业化竞争即可。
- 这款软件的编辑器类似简化版的 Notion，书写使用的快捷键和语法标记几乎和 Confluence 一致，切换使用几乎没有学习成本（除了个别快捷键）。
- 软件界面中提供类似 Obsidian Publish 的悬浮卡片，能够在不切换上下文的情况下，快速了解工具内其他内容的概要，比较节约上下文切换时间。
- 支持团队协作、以及分享功能，但是并不是强制要求使用的，对于个人使用场景、或小团队私密使用的场景，就显得非常友好了。
-  另外，所有的文章数据均允许直接导出（默认格式为 markdown）、同样的，你也可以使用 API 或者编写自己的小工具快速进行整站内容的转换和导入。

当然，软件处于快速迭代期，缺点也有不少。我个人认为之所以有这些原因，主要的原因是 Slack 生态下对于这些问题都有解决和补充，从 Slack 生态剥离，产品逻辑自然需要进行调整，功能也自然就需要进行补充了：

- 软件之前是重度绑定在 Slack 生态下的，很多功能和 Slack 深度绑定，私有化部署一度只支持使用 Slack 、GitHub 三方 OAuth 进行登陆授权。目前维护者正在着手解决身份验证相关的问题 [ISSUE#1945](https://github.com/outline/outline/issues/1945)，应该在接下来几个版本中，我们就能够看到实质的变化（在团队使用场景中）。
- 软件之前对于自托管的支持并不是那么的友好，社区成员曾在 [ISSUE#1881](https://github.com/outline/outline/issues/1881) 下进行了大量讨论，在社区和作者的努力下，目测在下一个版本中，将有质的变化。我已经基于这些改动进行了一个“抢先版”的镜像，所以，你并不需要等待官方发布新版，就能提前进行体验啦。
- 目前还不支持评论功能，官方正在着手解决。[ISSUE#457](https://github.com/outline/outline/issues/457)
- 目前对于附件管理功能也是缺失的，官方计划在未来两个版本中着手解决。[ISSUE#859](https://github.com/outline/outline/issues/859)不过目前其实有挺多解决方案的，后面的文章中我会进行展开，聊聊最简单的方式。
- 等等

虽然问题不少，但是这些问题对于个人和小团队使用来说，或许并不是最主要的问题，而且有非常多低成本解决方案。

接下来，我们来聊聊如何简单快速的私有化部署这套软件吧。

## 使用容器进行私有化部署

早些时候，我在 GitHub 上提交了示例代码：[https://github.com/soulteary/docker-outline](https://github.com/soulteary/docker-outline)，为了降低配置复杂度，在这个例子中同样使用 Traefik 作为服务网关，如果你对 Traefik 还不熟悉，可以翻阅之前的内容进行了解[《更简单的 Traefik 2 使用方式》](https://soulteary.com/2020/12/02/easier-way-to-use-traefik-2.html)，以及一些 [Traefik 实战例子](https://soulteary.com/tags/traefik.html)来加深理解。

在 Traefik 服务就绪的环境下，我们只需要几个步骤就能够将 Outline 跑起来。

### 步骤一：下载示例代码

首先，将示例代码下载到本地。

```bash
git clone https://github.com/soulteary/docker-outline.git
```

如果你在下载过程中遇到了网络问题，可以使用镜像地址：

```bash
git clone https://github.com.cnpmjs.org/soulteary/docker-outline.git
```

### 步骤二：创建你的配置文件

先复制一份配置文件，将新配置文件命名为 `.env`，修改其中你“介意”的地方：

```bash
cp .env.example .env
```

我个人推荐修改以下配置：

所有的**域名相关的配置**，使用你自己的域名进行替换。

```bash
DOCKER_MINIO_HOSTNAME=file.lab.com
DOCKER_MINIO_ADMIN_DOMAIN=file-admin.lab.com
SSO_SERVER_DOMAIN=sso.lab.com
DOCKER_ATTACHMENT_HOSTNAME=attachment.lab.com
DOCKER_OUTLINE_HOSTNAME=docs.lab.com
```

**密钥相关的配置**，你可以参考注释中的链接或生成方法，手动生成一份，如果你是在私有网络运行，不修改问题也不大。

```bash
# Select `Lowercase a-z and numbers` and 16-bit string length https://onlinerandomtools.com/generate-random-string
MINIO_ROOT_USER=6m2lx2ffmbr9ikod
# Select `Lowercase a-z and numbers` and 64-bit string length https://onlinerandomtools.com/generate-random-string
MINIO_ROOT_PASSWORD=2k78fpraq7rs5xlrti5p6cvb767a691h3jqi47ihbu75cx23twkzpok86sf1aw1e
MINIO_REGION_NAME=cn-homelab-1

DOCKER_POSTGRES_PASS=qTj5kwUEetmN

# You can use online tools to regenerate: https://www.uuidgenerator.net/
SSO_CLIENT_ID=b8c40013-cc03-4bc5-b3a5-6a31046fa415
SSO_CLIENT_SECRET=26272010-37d9-4bea-a58e-6b0a382d7626 

# Execute in the CLI `htpasswd -nb user pass`
DOCKER_ATTACHMENT_BASIC_AUTH=user:$apr1$8wC8avYf$Nhn0oTAvNjdw8FPROokGN.

# `openssl rand -hex 32`
OUTLINE_SECRET_KEY=64074328631d7ce618f554694ff7e83e820b9f7e14b13e4317893fed18e0b3c3
OUTLINE_UTILS_SECRET=04d7572e983ee6adfd77f8c77b61be8236a9e459fc9c1b7032ec278345638bcc
```

如果你希望使用你自己的用户名进行登陆，而非使用 SSO 服务默认使用的 `username` 用户进行登陆的话，则需要修改下面的配置，避免登陆被 Outline 拦截。
 
```bash
OIDC_ALLOWED_DOMAINS=company.ltd
```

默认的 SSO 使用的用户账号和邮箱，我在 [soulteary/docker-sso-server](https://github.com/soulteary/docker-sso-server) 这个项目中有提到过，目前项目默认使用的用户配置信息如下：

- 用户: `username`，
- 密码: `password`
- 邮箱：`username@company.ltd`

如果你想定制生成属于你的信息，可以使用 [授权协议在线生成工具](https://readers-lic-gift.suyang.wiki/) ，生成属于你的授权文件。

### 步骤三：启动应用

根据你的实际情况，创建一个属于 Outline 的虚拟网卡，让各种应用之间能够相对独立的进行数据通信，如果你已经创建过了，那么可以跳过这里，继续浏览如何启动应用。

```bash
docker network create outline
```

接着使用 `docker-compose` 选择各种应用配置，一键启动应用所需的各种服务：

```bash
docker-compose -f docker-compose.postgres.yml -f docker-compose.redis.yml -f docker-compose.minio.yml -f docker-compose.attachment.yml -f docker-compose.sso.yml -f docker-compose.outline.yml up -d
```

命令执行后，不出意外，你将会看到类似下面的日志输出：

```bash
Creating outline_minio    ... done
Creating outline-postgres ... done
Creating outline-redis    ... done
Creating linx-server      ... done
Creating outline          ... done
Creating sso-server       ... done
```

但是此刻我们还不能使用 Outline，服务首次启动后需要做一些初始化的操作，但是放心，这些操作都是自动化的。只需要稍等片刻，等待服务启动就绪就可以了。

我们，可以通过下面的命令来检查服务运行状态是否健康。

```bash
docker-compose -f docker-compose.postgres.yml -f docker-compose.redis.yml -f docker-compose.minio.yml -f docker-compose.attachment.yml -f docker-compose.sso.yml -f docker-compose.outline.yml ps   
```

当你看到类似下面的日志内容的时候（服务状态都展示 `healthy`），我们就能在浏览器中访问之前我们在配置中设置的域名，来使用 Outline 了。（本例中我设置的域名是 `docs.lab.com`）

```bash
      Name                    Command                  State        Ports  
---------------------------------------------------------------------------
linx-server        /usr/local/bin/linx-server ...   Up (healthy)   8080/tcp
outline            docker-entrypoint.sh sh -c ...   Up (healthy)   3000/tcp
outline-postgres   docker-entrypoint.sh postgres    Up (healthy)   5432/tcp
outline-redis      docker-entrypoint.sh redis ...   Up (healthy)   6379/tcp
outline_minio      /usr/bin/docker-entrypoint ...   Up (healthy)   9000/tcp
sso-server         docker-entrypoint.sh ./main      Up (healthy)   80/tcp   
```

不出意外，你将看到类似下面的界面。

![Outline 初始界面](https://attachment.soulteary.com/2021/09/05/outline-welcome.png)

因为使用了 SSO 登陆服务，所以我们继续来聊聊 Outline 的初次使用。

## 对 Outline 进行简单使用

在服务正常运行后，在浏览器中打开 Outline，点击使用 MySSO 登陆按钮，页面将会被跳转至本地运行的 SSO 服务。

![默认的 SSO 登陆界面](https://attachment.soulteary.com/2021/09/05/outline-sso-login.png)

在“步骤二：创建你的配置文件”提到过如何自定义用户名和密码，以及默认用户名和密码。我们使用设置好的账号密码登陆，将会被引导到 OTP 工具设置界面。

![设置 OTP 工具](https://attachment.soulteary.com/2021/09/05/outline-sso-otp.jpg)

你可以使用任何你熟悉或者喜欢的工具，扫描二维码或者通过密钥建立完成 OTP 绑定，在今后首次登陆应用时，SSO 服务除了会向你询问账号密码之外，还会和你确认根据时间实时生成的这个 OTP 代码。从而增强你本地账户登陆的安全性和背后的应用数据访问安全。

我这里使用的是谷歌推出身份认证器（Google Authenticator），当然你使用微软、或者三方推出的也没有问题，毕竟是通用协议，用啥解析都行，甚至是“网页”，只要你用起来顺手就成。

配置完毕之后，点击蓝色的“确认”按钮，将会被要求输入第一次 OTP 代码。

![首次确认 OTP 代码](https://attachment.soulteary.com/2021/09/05/outline-sso-otpcode.png)

因为首次使用时间太久，用于认证的参数过期，我们可能会被重新重定向到 Outline 的首页，这时放心的再次点击“使用 MySSO 继续”，稍等片刻就能看到 Outline 的“真身”了。

![默认的 Outline 内容界面](https://attachment.soulteary.com/2021/09/05/outline-inited.png)

软件界面非常简洁，功能分布也比较清晰，相信不用我过多介绍，你就能直接开始探索了，相信没有人能抵抗“开箱”的乐趣，所以基础使用部分，我就先不做展开了，自己探索出来的玩法才是“最香”的嘛。

不过，我猜使用者中一定有“英语苦手”，目前 Outline 中的中文已经是就绪状态，推荐点击左侧侧边栏的 “settings” 链接，进入设置页面，切换语言为中文。两个月前，我曾经对官方翻译进行了一[部分更新](https://github.com/outline/outline/discussions/2305)，目前应该绝大多数内容都是中文了，如果还有漏网之鱼，欢迎联系我。

![调整语言配置](https://attachment.soulteary.com/2021/09/05/outline-change-i18n.png)

此外，如果你对于默认的应用名称“Wiki”也有个性化的需求，可以修改设置界面里的“团队”名称，来完成内容更新。

![更新团队名称](https://attachment.soulteary.com/2021/09/05/outline-team-name.png)

## 最后

这篇关于 Outline 的内容，虽然早在 7月末就在群里和大伙聊过，但是考虑到数据安全、运行稳定一直拖到了现在，在充分使用和验证后，这个坑应该会在本月进行完结。

下篇 Outline 相关的内容，我将展开聊下如何进行更细致的配置。

--EOF