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

Jin's Blog

2019-11-26

工具

doc, docker, node, wiki

很多时候, 我们都需要一个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方案并不那么符合实际需要, 主要有以下明显几个缺陷:

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

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

开始之前,先把准备工作做好, 后文主要是以Linux环境在部署(以Cent为例). MacOS/Win也可以很简单的准备好环境. 因为Wiki.js更新很快, 所以本文写的内容很可能随时过时, 强烈建议大家优先通读官方文档, 更可靠准确

大致步骤如下:

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

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

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

# 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

# 8. 下载官方最新的docker-compose.yml文件, 然后一切就绪 (退出当前bash再进入刷新
wget https://raw.githubusercontent.com/Requarks/wiki/dev/dev/examples/docker-compose.yml

不是, 需要自己去部署后端存储 + 安装最新的Node.js. (步骤略, 但也不麻烦)

访问前端页面 ,进行第一次的初始化操作.
构建你的第一个Wiki页面. 大功告成!

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

0x01. 部署和升级

1. 首次安装

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

version: "3"
services:

  db:
    image: postgres:11-alpine  # 如果初始化一直报错, 请降级11为9版本. (特别注意)
    environment:
      POSTGRES_DB: wiki
      POSTGRES_PASSWORD: wikijsrocks
      POSTGRES_USER: wikijs
    logging:
      driver: "none"
    restart: unless-stopped
    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
    restart: unless-stopped
    ports:
      - "3000:3000" # 这里设置docker内部和外部的端口,比如你改成"80:3000"服务器默认输入ip/域名后就能直接访问了.
      - "443:3443" # 添加默认的https映射

volumes:
  db-data:

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

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

$ 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.下载新的包
docker-compose pull wiki
# 2. 重新创建(-d后台,建议)
docker-compose up --force-recreate -d

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

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

3. 备份

大家使用容器可能会担心数据丢失的问题, 但是 Wiki.js 的备份也做的挺完善, 不仅支持多端备份, 且默认的本地备份也是每天定时的, 你只需要在设置里开启, 然后就有备份文件了, 比如我设置的容器内备份地址是 ./backup, 你还可以crontab定期从容器复制一份到本地

1	docker cp wiki_wiki_1:/wiki/backup ./

当然, 配置好之后还可以对Git仓库/FTP开启同步的备份, 不过Git仓库有一些限制, 所以个人觉得大多时候本地备份就足矣了

0x02. 常用设置

0. Dashboard

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

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

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

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

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

1.发布文章

这里需要注意一下, wiki.js 的文件夹和路径解析和我们传统的树形结构有点区别, 官方文档说的很清楚了, 而为了后续的权限管理和分类, 建议创建新的page时不要放根下, 而是根据不同业务, 使用类别给前缀, 这样权限划分会轻松很多

# 假设根是 --> '/'
# 那么它们的名字建议如下:
# 业务A有三个子页面p1,p2,p3 (仅业务A和管理员可见)
/businessA/p1
/businessA/p2
/businessA/p3

# 业务B有两个子页面p1,p2 (仅业务B和管理员可见)
/businessB/p1
/businessB/p2

# 公共可以访问的区域
/public/p1
/public/p2
....

# 只有管理员可见的区域
/admin/p1
/admin/p2
/admin/p3

注意有些系统关键字和保留字不可用, 这个可能随时更新, 稍微注意下就行. (文档)

2.权限管理

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

简单的例子可以参考我上面发布文章划分的三个板块, 然后每个区域有固定的前缀(start with xx规则)

admin区域: 仅管理员组(administrator)可以访问
public区域: 所有非注册用户, 或默认用户都可以访问/禁止访问的区域, 通过操作Guest用户实现,
personal区域: 各业务自己的用户组, group1/group2对应业务1/业务2, 然后他们各自只拥有自己区域的增删改查权限, 不允许访问admin/其他业务

TODO: 之后等规则模板可以创建再补充, 建议设置一个允许和禁止权限的模板, 这样大部分可以复用, 目前需要一个个用户组去定义. 稍显麻烦.

举个例子. 业务A的权限设置:

允许读取/public开头的所有页面 (应放入模板)
允许增删改查 /businessA 开头的所有页面
不允许读取/admin开头的所有页面 (应放入模板)
不允许读取/businessB 或其他业务的所有页面 (考虑正则? 除businessA外所有business*)

然后Guest(默认)用户, 或者不登录用户的权限:

只允许读取/public开头的所有页面.
其他页面全禁止 (正则? 非public?)

禁止规则和允许规则同时存在时, 目前是禁止覆盖允许, 并且要注意先开全局权限, 再设置页面权限, 否则页面权限不会生效.

3. 安全相关

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

更新: SRI目前默认关闭了, 终于可以开心的自己修改主题了… 不过大家也可以通过注入css或自定义主题的方式(目前好像没开放)去实现, 总之可定制化也很好.

0x03. DIY

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

1. SRI

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

<!--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优秀的模块和复用, 所以实际上基本都是在修改模板文件, 比如我想修改一下默认的标题, 可以这样来操作

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

DIY部分未完待续

0x04. 收尾

整个Wiki项目从文档到社区, 到UI界面, 技术栈和Roadmap , 你都能感受到作者的用心和细致, 并且它还内置了很强大的功能, 以及很易用的可扩展性, 虽然定制化稍微麻烦一些, 但是从官方支持”主题“特性来看, 应该也不是问题.

后续会持续更新, 补充一些官方没有单独说明, 但是比较难理解/修改的地方, 以及补充一下我自己的DIY.