用Wiki.js来优雅的管理文档

很多时候, 我们都需要一个Wiki/文档管理系统. 但是市面上常见的开源方案都没法同时满足标题的需求, 大多是类似GitBook的方案, 依靠git仓库来维护文档的管理, 但是Wiki不同于纯电子书, 有很多在线编辑的场景, 很需要一个在线编辑功能支持的(类似tower/teambition, 但比它们要轻许多).

今天介绍, 并推荐的就是不仅满足上述需求, 技术栈新, UI还挺漂亮的Wiki系统 — Wiki.js, 下面是作者对它的描述:

​ —–*”A modern, lightweight and powerful wiki app built on NodeJS, Git and Markdown”*

0x00. 简介

需求在开头已经简单说过了, 虽然文档管理一个很简单的需求, 但是我找来找去, 发现传统的Wiki方案并不那么符合实际需要, 主要有以下明显几个缺陷:

  1. 不支持Markdown格式 (或支持很差, mathJax/Mermiad图表不支持)
  2. 不支持在线实时修改 , 过于依赖git仓库
  3. 收费闭源, 或很难内部独立部署
  4. 功能太重, 远大于所需 ( 比如国产的禅道 )
  5. UI太复古, 难以直视… (打开有种学校20年前选课系统的感觉 ,糟糕)
  6. 已经多年无人维护, 依赖旧, 安全性差, 升级/修改麻烦等…

然后我调研了多款可能解决了上述问题的方案之后, 最后选择了Wiki.js, 在此对作者表示敬意 (后续如果体验不错, 会Sponsor予以支持~), 希望开源社区能长期发展下去, Wiki界面如图所示:

wikiJS00

开始之前,先把准备工作做好, 后文主要是以Linux环境在部署(以Cent为例). MacOS/Win也可以很简单的准备好环境. 参考文档这不单独说了~ 大致步骤如下:

  1. 检查环境要求 (最低配置-树莓派)

  2. 是否是Docker方式部署 (推荐)

    • 是, 需要准备DockerDocker-compose环境(优先docker-compose管理, 很方便) ,其他方式参考官方文档

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      # 1. 安装预备工具
      sudo yum install -y yum-utils device-mapper-persistent-data lvm2

      # 2. 添加docker官方源,默认cent源太久
      sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

      # 3. 安装最新版,如需指定自行搜一下
      sudo yum install -y docker-ce docker-ce-cli containerd.io

      # 4. 启动docker-client,并设置开机启动
      sudo systemctl start docker && sudo systemctl enable docker

      # 5. 配置当前用户操作docker命令无需sudo (推荐)
      sudo usermod -aG docker $USER

      # 6. 下载Docker-compose对应Linux版本(通用,很贴心)
      sudo curl -L "https://github.com/docker/compose/releases/download/1.24.0/docker-compose-$(uname -s)-$(uname -m)" \
      -o /usr/local/bin/docker-compose

      # 7.赋予执行权限 (大功告成)
      sudo chmod +x /usr/local/bin/docker-compose
    • 不是, 需要自己去部署后端存储 + 安装最新的Node.js. (步骤略, 但也不麻烦)

  3. 访问前端页面 ,进行第一次的初始化操作.

  4. 构建你的第一个Wiki页面. 大功告成!

因为Wiki.js的文档已经写得非常不错了, 有问题也可以在issue区找到大致解决方案, 所以本文主要是给大家简单介绍一个如此nice的开源软件, 也希望擅长前端的小伙伴能支持社区的发展了

0x01. 部署和升级

1. 首次安装

因为Wiki 对依赖的存储PostgreSQL和Node版本要求都很高, 所以为了避免和系统环境产生冲突或者多后端有其他问题, 我们这里优先采用Docker方式来进行部署, 并选择docker-compose 的一键管理方式, 后续升级两步搞定, 也挺稳定的. 以下是官方提供的docker-compose.yml写法 :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
version: "3"
services:

db:
image: postgres:9-alpine
environment:
POSTGRES_DB: wiki
POSTGRES_PASSWORD: wikijsrocks
POSTGRES_USER: wikijs
logging:
driver: "none"
volumes:
- db-data:/var/lib/postgresql/data

wiki:
image: requarks/wiki:2
depends_on:
- db
environment:
DB_TYPE: postgres
DB_HOST: db
DB_PORT: 5432
DB_USER: wikijs
DB_PASS: wikijsrocks
DB_NAME: wiki
ports:
- "3000:3000" # 这里设置docker内部和外部的端口,比如你改成"80:3000"服务器默认输入ip/域名后就能直接访问了.

volumes:
db-data:

然后这里关键要注意的是数据映射的问题, 数据的备份和冗余我觉得是比较重要的, 可以修改映射到自定义目录.

然后建议修改一下3000 端口, 因为容易冲突~ 然后docker-compose up -d 一键启动, docker-compose down 一键关闭, 其他操作直接-h 自己看下, 还是很易用的.

1
2
3
4
5
6
$ docker-compose up -d
#虽然是一键, 但是也要注意观察到底做了哪些事, 你才能知道要删除修改需要哪些操作.为什么删除不掉数据
Creating network "wiki_wikinet" with the default driver
Creating volume "wiki_db-data" with default driver
Creating wiki_db_1 ... done
Creating wiki_wiki_1 ... done

2. 更新

使用docker-compose之后. 你可以很明显的感受到容器化编排带来的极大易用性, 尤其体现在软件升级上, 现在我们只需要简单的两行命令, 就能一键完成所有更新:

1
2
3
4
# 1.下载新的包
docker-compose pull wiki
# 2. 重新创建(-d后台,建议)
docker-compose up --force-recreate -d

如果普通启动, 会输出当前wiki版本, 以及一些关键信息:

wikiJS01

整个安装-升级就这么简单, 而且你也可以自己封装docker镜像, 后续迁移也是一键的事, 容器化在无状态web服务上的优势的确是无可比拟.(docker就不在此细说了)

0x02. 常用设置

0. Dashboard

第一次进入要选择之后的文章类型, 目前是选择之后就无法修改的, 可以看到作者期望支持的模板和格式还是很多的: (这里我们选择md)

wikiPage00

然后注册用户后, 进入后台. 后台的管理面板做的也挺简洁美观, 在这里你可以配置后面绝大部分的功能, 如下图所示:

wikiUI00

页面的分类, 权限的管理控制, 数据的备份都在其中, 初步使用这三个应该是最常用的功能, 分别提供:

  1. 良好的Wiki分类, 比如多种文档如何划分, 而不是只能有一个根.
  2. 良好的权限控制, 这点很不容易, 可以实现如下效果
    • N个业务使用同一个服务, 需要记录每个业务的机器信息, 业务信息等
    • 不同的业务拥有不同的权限, 默认不允许CURD其他业务的, 但是大家都能访问公共的主页说明
    • 特定页面可以隐藏, 也可以仅部分权限可访问
  3. 数据备份提供了多种方式: (全面)
    • 本地机器定时/手动上的备份 (注意容器默认是容器内部, 但是你可以通过存储映射出来)
    • git仓库同步备份
    • 云服务厂商备份(Google/OneDriver/AmazonS3/DO等)
    • SSH方式备份

至于其他提供的模块一般都是类似的, 提供了很多种的选择(搜索引擎/主题/邮件尚未实现的功能等…), 大家自己探索一下就能感受到.

1.发布文章

2.权限管理

首先就是发布文章和权限管理了, 有多个用户, 多个分类, 多篇文章, 大家一起正常协作. 如官方图所示:

wikiLDAP00

这里因为还需要进一步完善, 后续补充实际例子, 稍复杂一点.

3. 安全相关

因为技术栈新以及作者对代码的追求, wiki.js对常见的前端/服务端安全特性支持很齐全, 详情可以参考此博主的前端安全文章

wikiSecurity00

0x03. DIY

官方目前最新版还没有主题可以直接更换, 如果你觉得默认的样式不够好看, 也可以自己修改, 不过官方没有给出这个介绍, 之后我简单说明一下如何修改.

1. SRI

这里关键要先说的是默认开启的SRI(上图所示), 简单理解就是一个完整性检查的安全机制, 在这里主要体现为HTTP的integrity 属性的检查, 例如:

1
2
3
4
5
6
7
8
9
<!--css文件开启SRI后加载-->
<link type="text/css" rel="stylesheet" href="/css/app.56f692dcdb16249c4e25.css"
integrity="sha256-6nOFwGP2Y9xNP8b6i8JzWYYX7Dsdl5qjcOPBXqU+5Co= sha512-xxx"
crossorigin="use-credentials">

<!--js文件开启SRI后加载-->
<script type="text/javascript" src="/js/runtime.1fbb812ea0a6249a72ee.js"
integrity="sha256-me5R5sI1cYB5Gon1l7X1Ytr9EOve/Ht9iA9HRndBjrE= sha512-xxx" crossorigin="use-credentials">
</script>

这样的效果就是, 如果浏览器检测到你访问的资源文件的sha256/512对应的值不符合定义, 则拒绝加载资源(CSS/JS) , 在控制台里你可以看到如下错误提示:

Failed to find a valid digest in the integrity attribute for resource ip/js/theme-page.243ce630c2f2b056cb8b.js with computed SHA-256 integrity ‘xxxxxxxx…xx’. The resource has been blocked.

由于这个属性似乎是14年之后才出, 目前来看, 主流似乎只有Chrome +Firefox 完美支持它, 所以你使用Edge/IE , 大概率还不会受影响. 但是大部分人现在都用的Chrome 或类似内核, 所以我们必须解决这个问题, 才方便去DIY一下各种主题和动画… 不过好在官方直接给出了关闭选项, 如果你不想去重新折腾编译, 可以直接关闭默认的SRI策略. 因为我亲测来看, 修改它的js/css 还是比较麻烦的.

2. 修改页面

假设我希望定制化Wiki系统, 体现在前端页面的也许是html的变化, 但是因为Wiki.js优秀的模块和复用, 所以实际上基本都是在修改模板文件, 比如我想修改一下默认的标题, 可以这样来操作

  1. 进入docker容器, 找到对应的静态文件: docker exec -it wiki_wiki_1 /bin/bash
  2. 使用find搜索相关的关键字, 因为不是前端, 暂时不会去看整个结构了:)
  3. 观察对应的静态文件如何调用的, 然后尝试修改
  4. 保存刷新(必要时重启), 看看效果和预期差别
  5. 反复2~4的步骤, 从而达到简单修改的效果.

DIY部分未完待续

0x04. 末尾

整个Wiki项目从文档到社区, 到UI界面, 技术栈和Roadmap , 你都能感受到作者的用心和细致, 并且它还内置了很强大的功能,


参考文档:
  1. Wiki.js-install=by-docker
  2. SRI增强本地存储的安全