本页内容

  • 前提条件
  • 第 1 步 - 配置防火墙
  • 第 2 步 - 安装 Docker
  • 第 3 步 - 安装 Docker Compose
  • 第 4 步 - 为 Docker 创建环境文件 配置 Slack 身份验证 配置 Slack 集成 创建 S3 凭证 创建密钥 创建并编辑环境文件
  • 第 5 步 - 为 Outline 创建 Docker Compose 文件
  • 第 6 步 - 安装 Outline
  • 第 7 步 - 安装 SSL
  • 第 8 步 - 安装 Nginx
  • 第 9 步 - 配置 Nginx
  • 第 10 步 - 访问 Outline
  • 第 11 步 - 更新 Outline
  • 结论
  • 配置 Slack 身份验证
  • 配置 Slack 集成
  • 创建 S3 凭证
  • 创建密钥
  • 创建并编辑环境文件

Outline 是一款开源、协作式的知识库软件。你可以用它来托管文档和粉丝页面,甚至用于笔记分享。它包含一个 markdown 编辑器,并集成了多种服务,例如 Slack、Figma、Airtable、Google Docs、Trello、Zapier、Codepen、Spotify、Youtube 等。它具有安全功能,比如具有独立读写权限的用户组,允许公开分享,并支持 RTL 及 13 种语言的翻译。它使用 React 和 Node.js 构建。使用 Outline 有两种方式。一种是使用他们云托管的版本,或者你可以将其托管在自己的服务器上。

本教程将教你如何使用 Docker 在基于 Ubuntu 的服务器上安装 Outline Wiki。

前提条件

  • 一台运行 Ubuntu 20.04、至少 1GB 内存的服务器。
  • 一个具有 sudo 权限的非 root 用户。
  • 一个指向该服务器的域名。本教程中我们将使用 https://outline.example.com。
  • 开始之前需要安装几个必备应用。$ sudo apt install nano curl wget unzip gnupg

一台运行 Ubuntu 20.04、至少 1GB 内存的服务器。

一个具有 sudo 权限的非 root 用户。

一个指向该服务器的域名。本教程中我们将使用 https://outline.example.com。

开始之前需要安装几个必备应用。

$ sudo apt install nano curl wget unzip gnupg

第 1 步 - 配置防火墙

第一步是配置防火墙。Ubuntu 默认自带 ufw(Uncomplicated Firewall)。

检查防火墙是否正在运行。

$ sudo ufw status

你应该会得到以下输出。

Status: inactive

允许 SSH 端口,以便启用防火墙时不会中断当前连接。

$ sudo ufw allow OpenSSH

同时允许 HTTP 和 HTTPS 端口。

$ sudo ufw allow 80
$ sudo ufw allow 443

启用防火墙。

$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

再次检查防火墙的状态。

$ sudo ufw status

你应该会看到类似的输出。

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80                         ALLOW       Anywhere
443                        ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80 (v6)                    ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)

第 2 步 - 安装 Docker

我们将需要使用其官方仓库来安装 Docker。添加 Docker 的官方 GPG 密钥。

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

将 Docker 仓库添加到系统。

$ echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

更新 APT 仓库列表并安装 Docker。

$ sudo apt update
$ sudo apt install docker-ce

验证 Docker 引擎是否已正确安装。

$ docker --version
Docker version 20.10.14, build a224086

执行以下命令,这样运行 Docker 命令时就不需要使用 sudo。

$ sudo usermod -aG docker ${USER}
$ su - ${USER}

第 3 步 - 安装 Docker Compose

运行以下命令来安装 Docker compose。Docker Compose 最近更新到了 v2.0,引入了许多破坏性变更。我们将使用其 Github releases 页面提供的最新 1.x 版本。

$ sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

为 Docker compose 二进制文件添加可执行权限。

$ sudo chmod +x /usr/local/bin/docker-compose

验证 Docker Compose 是否已正确安装。

$ docker-compose --version
docker-compose version 1.29.2, build 5becea4c

为 Docker compose 安装命令补全。

$ sudo curl \
	-L https://raw.githubusercontent.com/docker/compose/1.29.2/contrib/completion/bash/docker-compose \
    -o /etc/bash_completion.d/docker-compose
$ source ~/.bashrc

本教程的 Docker 和 Docker compose 安装部分到此结束。

第 4 步 - 为 Docker 创建环境文件

配置 Slack 身份验证

Outline 要求你配置一个身份验证提供方。在本教程中,我们将配置基于 Slack 的登录。

使用你的 Slack 账户登录并访问 Slack 的 API Apps 页面。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

点击 Create an App 按钮继续。点击 From Scratch 链接来创建应用。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

为你的应用选择一个名称,并选择你希望应用出现在哪个工作区。如果你不想将应用与现有工作区关联,可以创建另一个工作区,然后回到这一步。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

完成后点击 Create App 按钮。接下来,向下滚动到页面底部,为你的应用添加描述、图标和背景颜色。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

完成后点击 Save Changes 按钮。从左侧边栏选择 OAuth and Permissions 选项。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

在提供的框中添加重定向 URL https://outline.example.com/auth/slack.callback,然后点击 Add 按钮。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

点击 Save URLs 按钮继续。向下滚动到页面的 User Token Scopes 部分,并从下拉菜单中选择以下 scopes。

  • identity.avatar
  • identity.basic
  • identity.email
  • identity.team

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

从左侧边栏返回 Basic Information 页面。复制 App Credentials 下对应框中的 Client ID 和 Client Secret 值。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

配置 Slack 集成

从左侧边栏访问 Slash Commands 选项。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

在出现的页面中点击 New Command 按钮。输入 /outline 作为命令。输入 https://outline.example.com/api/hooks.slack 作为 Request URL。为你的命令输入描述,并输入一个词作为提示。完成后点击底部的 Save 按钮。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

从左侧边栏打开 Features >> Interactivity and Shortcuts 菜单。通过切换开关按钮启用 Interactivity,并粘贴 https://outline.example.com/api/hooks.interactive 作为 Request URL。点击 Save Changes 按钮完成。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

从左侧边栏打开 Settings >> Install App 页面,点击 Install to WorkSpace 按钮,为你的 Slack 工作区安装该应用。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

从左侧边栏访问 Basic Information 页面,并复制 App ID 和 Verification Token 值,用于 slack 应用集成。

创建 S3 凭证

在 AWS 或任何兼容 S3 的服务上为你的 Outline 安装创建一个 S3 存储桶。创建存储桶后,添加以下策略 JSON 来配置跨域资源共享(CORS)。将 AllowedOrigins 的值替换为你的 Outline URL。

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "PUT",
            "POST"
        ],
        "AllowedOrigins": [
            "https://docs.mycompany.com"
        ],
        "ExposeHeaders": []
    },
    {
        "AllowedHeaders": [],
        "AllowedMethods": [
            "GET"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": []
    }
]

使用以下策略创建一个 IAM 用户。将 my-bucket-name 替换为你的 Outline S3 存储桶的实际名称。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor",
            "Effect": "Allow",
            "Action": [
                "s3:GetObjectAcl",
                "s3:DeleteObject",
                "s3:PutObject",
                "s3:GetObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::my-bucket-name/*"
        }
    ]
}

现在你已经创建了 IAM 用户,为你的存储桶用户生成 access key 和 secret。

创建密钥

环境文件需要一个 secret key 和一个 utility secret。运行以下命令两次以生成这两个密钥。

$ openssl rand -hex 32

复制并保存这些值。

创建并编辑环境文件

为 Outline 的 docker 设置创建一个目录。

$ mkdir ~/outline

切换到该目录。

$ cd ~/outline

创建 docker.env 文件并打开进行编辑。该文件将存储安装所需的所有环境变量。

$ nano docker.env

将以下代码粘贴进去。输入之前创建的 secret key 和 utils secret。复制之前为身份验证和应用集成创建的 Slack 凭证。按照下面的说明输入你的 Amazon S3 凭证。

如果你想使用 Google Analytics 来跟踪 Outline 应用的统计数据,请在下面的字段中输入你的 Analytics ID。目前 Outline 不支持 GA4 标签,因此你必须输入旧的跟踪 ID。

对于 WEB_CONCURRENCY 变量,将你的系统内存除以 512 并输入近似值。由于我们使用 Nginx 作为代理服务器,FORCE_HTTPS 变量设置为 false。

# –––––––––––––––– REQUIRED ––––––––––––––––
SECRET_KEY=generate_a_new_key
UTILS_SECRET=generate_a_new_key

POSTGRES_USER=outlinepg
POSTGRES_PASSWORD=yourpassword
POSTGRES_DB=outline
DATABASE_URL=postgres://outlinepg:yourpassword@localhost:5432/outline
DATABASE_URL_TEST=postgres://outlinepg:yourpassword@localhost:5432/outline-test
PGSSLMODE=disable
REDIS_URL=redis://localhost:6379

URL=https://docs.example.com
PORT=3000

AWS_ACCESS_KEY_ID=get_a_key_from_aws
AWS_SECRET_ACCESS_KEY=get_the_secret_of_above_key
AWS_REGION=us-east-2
AWS_S3_UPLOAD_BUCKET_URL=https://my-bucket-name.s3.us-east-2.amazonaws.com
AWS_S3_UPLOAD_BUCKET_NAME=my-bucket-name
AWS_S3_UPLOAD_MAX_SIZE=26214400
AWS_S3_FORCE_PATH_STYLE=true

# –––––––––––––– AUTHENTICATION ––––––––––––––
SLACK_KEY=<slackclientid>
SLACK_SECRET=<slackclientsecret>

# –––––––––––––––– OPTIONAL ––––––––––––––––
GOOGLE_ANALYTICS_ID=UA-XXXXXXX-1

SLACK_VERIFICATION_TOKEN=your_token
SLACK_APP_ID=A0XXXXXXX
SLACK_MESSAGE_ACTIONS=true

FORCE_HTTPS=false
ENABLE_UPDATES=true
WEB_CONCURRENCY=2

上述文件基于 Outline 的 Github 仓库中的示例文件。如果你需要配置任何其他设置,可以从该示例文件复制到你的文件中。

按 Ctrl + X 并在提示时输入 Y 来保存文件。

第 5 步 - 为 Outline 创建 Docker Compose 文件

创建 docker-compose.yml 文件并打开进行编辑。

$ nano docker-compose.yml

将以下代码粘贴进去。

version: "3"
services:

  outline:
    image: outlinewiki/outline:latest
    restart: always
    command: sh -c "yarn sequelize:migrate --env=production-ssl-disabled && yarn start --env=production-ssl-disabled"
    env_file: ./docker.env
    ports:
      - "3000:3000"
    depends_on:
      - postgres
      - redis

  redis:
    image: redis
    restart: always
    env_file: ./docker.env
    ports:
      - "6379:6379"
    volumes:
      - ./redis.conf:/redis.conf
    command: ["redis-server", "/redis.conf"]

  postgres:
    image: postgres
    restart: always
    env_file: ./docker.env
    ports:
      - "5432:5432"
    volumes:
      - database-data:/var/lib/postgresql/data

volumes:
  database-data:

按 Ctrl + X 并在提示时输入 Y 来保存文件。

第 6 步 - 安装 Outline

通过启动容器来安装 Outline。

$ docker-compose up -d

检查容器的状态。

$ docker ps

第 7 步 - 安装 SSL

要使用 Let's Encrypt 安装 SSL 证书,我们需要下载 Certbot 工具。为此我们将使用 Snapd 包安装程序。

安装 Snap 安装程序。

$ sudo apt install snapd

确保你的 Snapd 版本是最新的。

$ sudo snap install core && sudo snap refresh core

安装 Certbot。

$ sudo snap install --classic certbot

使用以下命令,通过创建到 /usr/bin 目录的符号链接来确保可以运行 Certbot 命令。

$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

生成 SSL 证书。

$ sudo certbot certonly --standalone --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m 
[email protected]
 -d outline.example.com

上述命令会将证书下载到服务器上 /etc/letsencrypt/live/outline.example.com 目录。

生成 Diffie-Hellman 组证书。

$ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

为 Let's Encrypt 自动续期创建一个 challenge webroot 目录。

$ sudo mkdir -p /var/lib/letsencrypt

创建一个 Cron 任务来续期 SSL。它将每天运行以检查证书,并在需要时续期。为此,首先创建文件 /etc/cron.daily/certbot-renew 并打开进行编辑。

$ sudo nano /etc/cron.daily/certbot-renew

粘贴以下代码。

#!/bin/sh
certbot renew --cert-name outline.example.com --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"

按 Ctrl + X 并在提示时输入 Y 来保存文件。

更改任务文件的权限使其可执行。

$ sudo chmod +x /etc/cron.daily/certbot-renew

第 8 步 - 安装 Nginx

Ubuntu 自带的是较旧版本的 Nginx。你需要下载官方 Nginx 仓库来安装最新版本。

导入 Nginx 的签名密钥。

$ curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
	| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

添加 Nginx 稳定版的仓库。

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

更新系统仓库。

$ sudo apt update

安装 Nginx。

$ sudo apt install nginx

验证安装。

$ nginx -v
nginx version: nginx/1.20.2

启用 Nginx 服务。

$ sudo systemctl enable nginx

第 9 步 - 配置 Nginx

到目前为止,Shlink 一直通过端口 8080 在本地系统上运行。我们将使用 Nginx 作为反向代理,使其在自己的域名上运行。

在 /etc/nginx/conf.d 目录中为 Shlink 服务器创建一个配置文件。

$ sudo nano /etc/nginx/conf.d/outline.conf

将以下代码粘贴进去。

server {
        server_name outline.example.com;

        listen 443 ssl http2;
        listen [::]:443 ssl http2;

        access_log /var/log/nginx/outline.access.log;
        error_log /var/log/nginx/outline.error.log;

        ssl_certificate /etc/letsencrypt/live/outline.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/outline.example.com/privkey.pem;
        ssl_trusted_certificate /etc/letsencrypt/live/outline.example.com/chain.pem;
        ssl_session_timeout 1d;
        ssl_session_cache shared:MozSSL:10m;
        ssl_session_tickets off;

        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

        ssl_stapling on;
        ssl_stapling_verify on;
        ssl_dhparam /etc/ssl/certs/dhparam.pem;
 
        location / {
                proxy_pass http://localhost:3000;
                
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "Upgrade";
                proxy_set_header Host $host;
        
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header Host $host;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Scheme $scheme;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_redirect off;
        }
}

## HTTPS Redirect
server {
        listen 80; 
        listen [::]:80;
        server_name outline.example.com;
        return 301 https://$host$request_uri;
}

完成后,按 Ctrl + X 并在提示时输入 Y 来保存文件。

打开文件 /etc/nginx/nginx.conf 进行编辑。

$ sudo nano /etc/nginx/nginx.conf

在 include /etc/nginx/conf.d/*.conf; 这一行之前添加以下行。

server_names_hash_bucket_size  64;

按 Ctrl + X 并在提示时输入 Y 来保存文件。再次验证 Nginx。

验证 Nginx 配置文件的语法。

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

启动 Nginx 服务器。

$ sudo systemctl start nginx

第 10 步 - 访问 Outline

在浏览器中打开域名 https://outline.example.com,你将看到以下页面。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

点击 Continue with Slack 按钮,使用 Slack 登录并连接你的工作区。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

登录后,Outline 主页将打开,你就可以开始使用了。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

Outline 的 Slack 应用允许你在工作区内搜索并粘贴任意文档的链接。为此,打开你的 slack 工作区,在消息中输入 /outline 并发送。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

它将自动定位与搜索词相关的文档,并将其发布到你的消息中。

在 Ubuntu 20.04 上安装部署 Outline 知识库 Wiki 系统完整教程

第 11 步 - 更新 Outline

要更新 Outline wiki,请运行以下命令。第一条命令会关闭并移除容器。第二条命令会拉取 Outline 及其他工具的最新版本 Docker 镜像。如果你需要对 Docker compose 文件或环境文件做任何更改,也可以运行相同的命令。

$ docker-compose down --remove-orphans
$ docker-compose pull 

运行以下命令来升级数据库。

$ docker-compose run --rm outline yarn db:migrate --env=production-ssl-disabled

在保持数据完整的前提下,使用全新镜像启动新容器。

$ docker-compose up -d

结论

关于使用 Docker 在 Ubuntu 20.04 服务器上安装 Outline Knowledgebase Wiki 的教程到此结束。如果你想了解更多关于 Outline 的内容,可以查阅其官方文档。如果有任何问题,请在下方评论区留言。