wiki.js知识库系统搭建和配置总结

wiki.js知识库成熟度很高，官方文档完备，试用这个知识库后比较满意，而且wiki.js对离线环境相对友好，包括创建用户等不需要邮箱认证，比较简单。这里分别从在线环境和离线环境来记录软件的安装和配置。

一、联网环境安装wiki.js

最主要的参考资料还是官方文档，地址https://docs.requarks.io/

wiki.js的运行环境依赖主要是数据库和node.js，如果docker安装，node.js就不用管了，docker再运行一个数据库即可。推荐的数据库是PostgreSQL。

推荐在Linux环境下安装，下面的安装记录都是在Ubuntu 24系统下完成。

1、安装docker-ce

按照文档操作使用官方docker源，大概率会因为网络导致下载失败，所以换成国内源，下面安装步骤阿里云文档提供的 https://developer.aliyun.com/mirror/docker-ce。

复制代码

# step 1: 安装必要的一些系统工具
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg

# step 2: 信任 Docker 的 GPG 公钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Step 3: 写入软件源信息
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 
# Step 4: 安装Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 安装指定版本的Docker-CE:
# Step 1: 查找Docker-CE的版本:
# apt-cache madison docker-ce
#   docker-ce | 17.03.1~ce-0~ubuntu-xenial | https://mirrors.aliyun.com/docker-ce/linux/ubuntu xenial/stable amd64 Packages
#   docker-ce | 17.03.0~ce-0~ubuntu-xenial | https://mirrors.aliyun.com/docker-ce/linux/ubuntu xenial/stable amd64 Packages
# Step 2: 安装指定版本的Docker-CE: (VERSION例如上面的17.03.1~ce-0~ubuntu-xenial)
# sudo apt-get -y install docker-ce=[VERSION]

2、利用docker创建PostgreSQL、wiki.js和wiki.js升级程序的容器

复制代码

# 在本地创建Wiki.js工作目录
mkdir -p /etc/wiki

# 创建数据库用户密码文件，在创建容器时密码文件比用密码更安全
openssl rand -base64 32 > /etc/wiki/.db-secret

# 创建docker network
docker network create wikinet

# Create data volume for PostgreSQL
docker volume create pgdata

# 利用docker create创建容器，这里创建了三个容器，包括db、wiki、wiki-update-companion
# 这里同样可能遇到网络问题，需要docker增加其他镜像源
sudo docker create --name=db -e POSTGRES_DB=wiki -e POSTGRES_USER=wiki -e POSTGRES_PASSWORD_FILE=/etc/wiki/.db-secret -v /etc/wiki/.db-secret:/etc/wiki/.db-secret:ro -v pgdata:/var/lib/postgresql/data --restart=unless-stopped -h db --network=wikinet postgres:17
sudo docker create --name=wiki -e DB_TYPE=postgres -e DB_HOST=db -e DB_PORT=5432 -e DB_PASS_FILE=/etc/wiki/.db-secret -v /etc/wiki/.db-secret:/etc/wiki/.db-secret:ro -e DB_USER=wiki -e DB_NAME=wiki -e UPGRADE_COMPANION=1 --restart=unless-stopped -h wiki --network=wikinet -p 80:3000 -p 443:3443 ghcr.io/requarks/wiki:2
sudo docker create --name=wiki-update-companion -v /var/run/docker.sock:/var/run/docker.sock:ro --restart=unless-stopped -h wiki-update-companion --network=wikinet ghcr.io/requarks/wiki-update-companion:latest

3、启动docker容器

复制代码

# 如果没有防火墙，直接启动容器
# 停止容器的话，把start换成stop即可
sudo docker start db
sudo docker start wiki
sudo docker start wiki-update-companion

# 如果有问题可以用下面命令查看wiki.js日志信息
sudo docker logs wiki

通过安装docker、创建应用容器、启动容器，简单3步即可完成最小化安装。此时，打开浏览器访问服务器ip+端口3000就能打开wiki.js页面了，要使用wiki.js还需要简单初始化配置，也比较简单。进入系统后，可以在设置页面选择中文。

如果希望使用Docker Compose更方便的管理容器，官方文档也提供了参考写法。参考https://docs.requarks.io/install/docker

wiki.js支持多种全文搜索引擎，对比下比较好用的是Elasticsearch，Elasticsearch也可以用docker安装。

二、离线环境安装wiki.js

离线环境安装wiki.js使用docker安装应该是最方便的，利用docker save命令很容易将image保存为tar压缩文件到本地，然后在离线环境中用docker load导入image的tar压缩文件。

1、在线环境docker导出所需image

复制代码

# 离线环境，没法自动升级，所以升级程序就不需要部署了
sudo docker save -o db.tar postgres:17
sudo docker save -o wikijs.tar ghcr.io/requarks/wiki

2、离线环境docker导入image

复制代码

sudo docker load -i db.tar
sudo docker load -i wiki.tar

3、离线环境额外配置wiki.js

wiki.js默认是英语环境，其他语言包并没有包含在镜像中，需要在线额外加载，对于离线环境需要额外配置。首先，是从官方提供的地址https://github.com/Requarks/wiki-localization下载最新的语言包。注意，不能只下载中文(zh.json)，locales.json也是必须的。最好右上角直接下载整个项目文件。

把压缩包传输到离线环境中，解压到/etc/wiki/data/sideload目录下，或其他目录。关于此的参考文档在这里https://docs.requarks.io/install/sideload

在/etc/wiki/下新增一个配置文件config.yml。可以从官网下载wiki.js的压缩包从利明提取config.sample.yml并重命名。或者从docker容器里cp一个。增加offline: true选项，同时会自动开启sideload，sideload加载语言包。

复制代码

# 从在线环境的wiki容器里复制config.yml到本地
sudo docker cp wiki:/wiki/config.yml ./

# 修改配置文件，增加离线模式
vi config.yml

# 这是从容器中提取的配置文件，并增加了离线模式配置
# 可以看到参数都是通过docker环境变量传入
port: 3000
bindIP: 0.0.0.0
db:
  type: $(DB_TYPE)
  host: '$(DB_HOST)'
  port: $(DB_PORT)
  user: '$(DB_USER)'
  pass: '$(DB_PASS)'
  db: $(DB_NAME)
  storage: $(DB_FILEPATH)
  ssl: $(DB_SSL)
ssl:
  enabled: $(SSL_ACTIVE)
  port: 3443
  provider: letsencrypt
  domain: $(LETSENCRYPT_DOMAIN)
  subscriberEmail: $(LETSENCRYPT_EMAIL)
logLevel: $(LOG_LEVEL:info)
logFormat: $(LOG_FORMAT:default)
ha: $(HA_ACTIVE)
offline: true     # 增加配置

docker create部分也需要修改一下，把本地的config.yml和sideload目录映射给wiki容器。wiki容器修改后如下，就是增加了-v参数来映射文件。

复制代码

sudo docker create --name=wiki -e DB_TYPE=postgres -e DB_HOST=db -e DB_PORT=5432 -e DB_PASS_FILE=/etc/wiki/.db-secret -v /etc/wiki/.db-secret:/etc/wiki/.db-secret:ro -v /etc/wiki/data/sideload:/wiki/data/sideload -v /etc/wiki/config.yml:/wiki/config.yml -e DB_USER=wiki -e DB_NAME=wiki -e UPGRADE_COMPANION=1 --restart=unless-stopped -h wiki --network=wikinet -p 80:3000 -p 443:3443 ghcr.io/requarks/wiki:2

修改后启动容器，就可以选择中文语言了。

3、用deb安装Elasticsearch

Elasticsearch没有选择容器安装，而是用的deb，希望这样性能能好些，而且es的安装比较简单，deb安装足够方便。wiki.js最高只支持es 8x版本，安装过程参考官方文档：https://www.elastic.co/guide/en/elasticsearch/reference/8.19/deb.html

从官网下载deb文件。地址：wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-8.19.12-amd64.deb

或者从官方网页下载更多选项，地址：https://www.elastic.co/downloads/past-releases/elasticsearch-8-19-12

复制到离线环境，用dpkg -i 安装。

复制代码

sudo dpkg -i elasticsearch-8.19.12-amd64.deb

# 软件自动安装系统服务，设置服务开机启动
sudo systemctl daemon-reload
sudo systemctl enable elasticsearch.service

# 启动es
sudo systemctl start elasticsearch

# 停止es
sudo systemctl stop elasticsearch

# 查看状态
sudo systemctl status elasticsearch

#  有问题看日志
tail -n 500 /var/log/elasticsearch/

在deb安装Elasticsearch过程中会屏显日志输出默认生成的超级用户elastic随机密码，以及通信使用的tls证书，有2种证书一种用于客户端访问通信，一种用户集群互访。

复制代码

# 生成密码如果找不到，可以用命令重置
elasticsearch-reset-password

程序启动后，可以用curl测试程序是否正常运行，默认Elasticsearch是用户名密码验证。可以验证证书，也可以用-k参数跳过证书验证。正常运行的话会有返回消息。

复制代码

# 测试es是否正确运行
curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic:生成的密码 https://localhost:9200 

# 跳过验证证书
curl -XGET -u elastic:生成的密码 "https://localhost:9200/" -k

4、安装Elasticsearch ik中文分词插件

这个中文分词插件可以更好支持中文，必须安装。项目地址：https://release.infinilabs.com/analysis-ik/stable/

复制代码

# 下载压缩包 https://release.infinilabs.com/analysis-ik/stable/
# 在elastic安装目录的plugins包下创建IK文件夹，将下载好的zip包解压在IK文件夹中，重启elastic
sudo unzip elasticsearch-analysis-ik-8.19.10.zip -d /usr/share/elasticsearch/plugins/ik

5. 修改Elasticsearch配置文件

这里有个坑，我用的Elasticsearch 8.19.12安装包生成的配置文件，有2处重复的cluster.initial_master_nodes，得删除一处，否则后面的覆盖前面的，导致配置异常。另外就是xpack.security.enabled，默认开启，但是配置wiki.js时总是报错，最后还是选择关闭身份认证。

复制代码

# 编辑elasticsearch配置文件
$ vi /etc/elasticsearch/elasticsearch.yml 

# 需要修改内容参考了其他文章
# cluster.name：集群名称，根据自己业务启个合适的名字
# node.name：给节点起个名字，一般使用node-1 、node-2 、...
# path.data：数据存放的位置，比如：/data/elasticsearch/data
# path.logs：日志存放的位置，比如：/data/elasticsearch/logs
# network.host：配置成本机 IP 地址，用于集群机器之间相互通信。
# http.port：ES 服务访问的端口号，比如：9200
# discovery.seed_hosts：配置为 master 候选者节点。如果要与其他节点组成集群，这里必须配置。比如：["10.20.1.29", "10.20.0.91", "10.20.0.93"]
# cluster.initial_master_nodes：首次启动集群时，配置主节点的候选节点，该配置里的节点都是候选节点。比如：["node-1", "node-2", "node-3"]
# xpack.security.enabled: false  是否开启安全性，默认是开启，但是测试wiki.js功能是否发现总有问题，还是关闭了

6、wiki.js修改搜索引擎为Elasticsearch 并支持中文检索

在wiki.js的搜索引擎设置页面，按下图设置。正常host处可以增加用户名和密码，但我测试失败了。

三、遗留问题

wiki.js相对docmost要成熟很多，界面很漂亮。但是，上传附件的好像是存储在数据库中。长期使用，大量附件上传到数据库内是否有些问题？能否附件不存储在数据库中？