1 前言

Wiki.js 是一个功能强大且现代化的开源 Wiki 平台，基于 Node.js 开发，拥有丰富的功能和简洁的界面。本教程将指导你完成 Wiki.js 的部署安装，帮助你快速搭建属于自己的知识库。

官网：Wiki.js
官方文档：Wiki.js 文档

特点

现代化界面：采用直观、简洁的现代化用户界面设计，操作方便，用户可以轻松上手，快速找到所需功能，提升使用体验。
多语言支持：支持多种语言，能够满足不同地区、不同语言背景用户的需求，方便全球范围内的团队协作和知识共享。
插件系统丰富：拥有丰富的插件生态系统，用户可以根据自身需求轻松扩展功能，如添加代码高亮、数学公式支持、图表绘制等插件，增强维基的实用性。
用户管理灵活：提供灵活的用户管理和权限设置功能，可针对不同用户角色或用户组精细设置访问权限、编辑权限等，确保知识的安全性和保密性。
Markdown 支持：支持 Markdown 语法，用户可以使用简洁的 Markdown 语言进行内容编辑，方便快捷地创建格式丰富的文档，提高编辑效率。
实时协作：支持实时协作编辑，团队成员可以同时对同一篇文档进行编辑，实时看到彼此的修改，提高协作效率，促进知识的快速沉淀和更新。
易于部署：安装和部署过程相对简单，可轻松部署在各种服务器环境中，无论是本地服务器还是云服务器，都能快速搭建起属于自己的维基系统。

2 准备工作

在正式安装之前，你需要准备一台至少为 2C1G 的服务器。

根据官方文档的描述，你可以在任意一台支持 Node.js 的系统上安装，推荐使用 Linux 系统，本文使用 Ubuntu 演示。

2.1 购买服务器

我们需要准备一台云服务器用于部署，如果你没有云服务器，这里推荐使用腾讯云轻量应用服务器，新用户购买低至 68 元/年，点击 https://curl.qcloud.com/wltDVjMI 立即选购。

除了特惠产品外，特别推荐腾讯云新推出拥有高峰值带宽的锐驰型套餐，峰值带宽高达 200Mbps。

2.2 选择安装方式

Wiki.js 安装方式多样，常见的有通过宝塔面板、通过 Docker、通过 1Panel 面板及通过命令行，你可以根据个人情况任选其一。

宝塔面板图形化界面操作，适合新手快速部署，无需记忆命令，但部分高级配置需要通过手动修改文件实现；Docker 容器步骤简单，维护方便，适合环境隔离和快速迁移，但对容器相关知识有一定要求；1Panel 面板操作简单，现代化图形界面操作便捷，无需复杂配置，但可控制性较低；命令行是直接操作服务器，无需安装额外面板或服务，节省服务器资源，但问题排查更依赖人工，容易出错，门槛较高。

如果你选择面板或者 Docker 的方式安装，建议阅读下方文章完成前置条件：

宝塔面板部署、1Panel 面板部署：https://talen.top/posts/6c819fda/
Docker 安装：https://talen.top/posts/869715fc/

3 通过宝塔面板

3.1 安装 Node.js

在宝塔面板侧边栏软件商店中搜索 nodejs，找到 Node.js版本管理器 进行安装。

安装完成后，点击设置按钮，选择任意 LTS 版本 Node.js 进行安装。

3.2 安装 PostgreSQL

在宝塔面板侧边栏软件商店中搜索 postgresql，找到 PostgreSQL管理器 进行安装。

安装完成后，点击设置按钮，选择任意 postgresql 版本（建议版本号小于 15）进行安装。此安装过程较慢，等待的时间可以先去完成下一步。

3.3 获取源代码

在宝塔面板侧边栏文件中的 /www/wwwroot 目录下新建一个文件夹，名称自定义，这里取为 wikijs。

新建完成后进入该文件夹内，将光标放在上传/下载按钮上点击 URL 链接下载，URL 地址填写官方提供的最新压缩包链接。

https://github.com/Requarks/wiki/releases/latest/download/wiki-js.tar.gz

下载较慢可使用国内镜像站：
https://kkgithub.com/Requarks/wiki/releases/latest/download/wiki-js.tar.gz

下载完成后点击该压缩包后方的更多，选择解压，无误后确认解压。

解压完成后，将示例配置文件 config.sample.yml 重命名为 config.yml。

3.4 服务配置

前面安装的 PostgreSQL 现在应该安装完成了，点击侧边栏数据库，选择 PgSQL 添加数据库，自定义填写数据库名、用户名及密码，建议数据库名与用户名一致，并且具有标识性。

记住用户名及密码，回到侧边栏文件中在前面源代码存放的目录中，双击打开 config.yml 配置文件，可参考下图修改。

在侧边栏网站中选择 Node 项目中添加站点，项目目录选择前面源代码存放的目录，其它的内容将自动填充。

创建完成后项目将自动开启，在浏览器访问 IP:3000 即可进入 Wiki.js 配置页。

问题汇总
一、项目启动失败
项目根目录下的压缩包未解压
示例配置文件未重命名为 config.yml
数据库版本大于 15
二、网页无法打开
未在云服务商处放行项目端口
未在宝塔面板防火墙处放行端口

4 通过 Docker

使用 Docker 部署是极为简单的，你的设备上只要安装有 Docker 和 Docker Compose，就可以使用简单的几行命令快速部署。

创建部署目录，新建并编写 docker-compose.yml 文件。

1 2	mkdir ~/wikijs && cd ~/wikijs vim docker-compose.yml

在编辑模式（i）下使用以下配置内容，根据实际情况修改无误后，按 <ESC> 并输入 :wq 保存并退出。

services:
  db:
    image: postgres:15-alpine
    container_name: wikijs-db
    volumes:
      - wikijs-db-data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: wikijs    # 数据库名
      POSTGRES_USER: wikijs    # 数据库用户名
      POSTGRES_PASSWORD: your_db_password    # 数据库密码
    restart: unless-stopped

  wiki:
    image: ghcr.io/requarks/wiki:latest
    container_name: wikijs
    depends_on:
      - db
    ports:
      - "3000:3000"
    volumes:
      - wikijs-data:/var/wiki/data
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs    # 数据库用户名
      DB_PASS: your_db_password    # 数据库密码
      DB_NAME: wikijs    # 数据库名
    restart: unless-stopped

volumes:
  wikijs-db-data:
  wikijs-data:

启动容器，命令需在 docker-compose.yml 文件同级目录下执行。

1	sudo docker-compose up -d

验证容器状态，看到 wikijs 和 wikijs-db 容器状态为 Up，则部署成功。

1	sudo docker ps -a

最后在浏览器访问 IP:3000 即可进入 Wiki.js 配置页。

问题汇总
在启动容器时出现 net/http: request canceled while waiting for connection 错误，是由于网络问题导致，需要更换国内镜像源
网页无法打开，需要检查云服务商处是否放行项目端口

5 通过 1Panel 面板

5.1 安装 PostgreSQL

在 1Panel 面板侧边栏应用商店中搜索 postgre 找到 PostgreSQL 进行安装。

用户名及密码自定义，版本需要选择 15 版本号之前的

5.1 安装 Wiki.js

在 1Panel 面板侧边栏应用商店中搜索 wiki 找到 Wiki.js 进行安装。

数据库选择 PostgreSQL，数据库名、用户名、密码自定义，端口自定义，需要在云服务商处放行端口，最后在高级设置中开启端口外部访问。

最后在浏览器访问 IP:3000 即可进入 Wiki.js 配置页。

问题汇总
网站无法打开，检查云服务商及 1Panel 面板端口外部访问是否放行开启
Wiki.js 启动失败，检查 PostgreSQL 版本号是否小于 15

6 通过命令行

6.1 安装 Node.js

更新系统的软件包列表。

1	sudo apt update

快速安装 nodejs 和 npm。

1	sudo apt install nodejs npm -y

安装完成后，通过版本检查命令验证 Node.js 和 npm 是否安装成功。

1 2	node -v npm -v

6.2 安装 PostgreSQL

安装 postgresql 和 postgresql-contrib，前者是 PostgreSQL 数据库的核心软件包，后者包含了一些额外的工具和扩展，能增强 PostgreSQL 的功能。

1	sudo apt install postgresql postgresql-contrib -y

安装完成后，PostgreSQL 服务通常会自动启动，但为减少不必要的麻烦，可以先检查服务的运行状态，当输入内容中出现 Active: active 即正常。

1	sudo systemctl status postgresql

如果服务没有启动，可以使用以下命令启动 postgresql 服务。

1	sudo systemctl start postgresql

若希望 PostgreSQL 在系统启动时自动启动，避免因重启导致的服务暂停，可以使用以下命令。

1	sudo systemctl enable postgresql

PostgreSQL 安装完成后会创建一个名为 postgres 的操作系统用户和同名的数据库用户。你可以通过切换到 postgres 用户来管理数据库。

1	sudo -u postgres psql

进入 psql 环境后，使用 SQL 命令创建一个用户名为 wikijs、密码为 P@ssw0rd 的新数据库用户。

1	CREATE USER wikijs WITH PASSWORD 'P@ssw0rd';

然后创建一个名为 wiki 的新数据库，并将其所有权赋予给新用户 wikijs，完成操作后，输入 \q 退出 psql 环境。

1	CREATE DATABASE wiki OWNER wikijs;

6.3 安装 Wiki.js

创建并进入一个用于存放 Wiki.js 文件的目录，这里命名为 wikijs。

1	mkdir ~/wikijs && cd ~/wikijs

下载 Wiki.js 的最新版本压缩包，并将其解压到当前目录，此处下载地址使用 Github 国内镜像站。

1 2	wget https://kkgithub.com/Requarks/wiki/releases/latest/download/wiki-js.tar.gz tar xzf wiki-js.tar.gz

将示例配置文件 config.sample.yml 重命名为 config.yml。

1	mv config.sample.yml config.yml

编辑配置文件并填写数据库和端口设置。

1	vim config.yml

根据实际情况和前面的数据库设置，在配置文件中修改部分内容，这里的端口需要在云服务商处放行。

当无误的完成以上操作后，就可以尝试启动 Wiki.js 了。

1	node server

当控制台打印输出内容有类似 HTTP Server: [ RUNNING ] 表明启动成功，在浏览器访问 IP:3000 即可进入 Wiki.js 配置页。

6.4 进程守护

如果是使用命令行部署，服务进程将会因终端关闭而停止，所以需要进程守护来保证服务稳定运行，官方推荐使用 systemd。

首先在 /etc/systemd/system 目录下创建并编辑一个名称为 wiki.service 的新文件。

1	sudo vim /etc/systemd/system/wiki.service

将以下内容粘贴到 wikijs.service 这个新文件中，WorkingDirectory 的值需要根据实际安装位置来修改。

[Unit]
Description=Wiki.js
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node server
Restart=always
User=root
Environment=NODE_ENV=production
WorkingDirectory=/home/ubuntu/wikijs

[Install]
WantedBy=multi-user.target

随后依次进行重新加载 systemd、运行服务并在系统启动时启用该服务等操作。

1
2
3

sudo systemctl daemon-reload
sudo systemctl start wikijs
sudo systemctl enable wikijs

还可以使用 sudo systemctl status wikijs.service 命令查看服务状态，当打印输出内容中出现 Active: active (running) 即成功，然后再次在浏览器访问 IP:3000 即可进入 Wiki.js。

问题汇总
网页无法打开，需要检查云服务商处是否放行项目端口
使用进程守护前访问正常，使用后无法访问，请仔细检查 wikijs.service 文件内容，尤其是 WorkingDirectory 设置的目录值

7 配置 Wiki.js

7.1 初始化

首次打开站点后，自动进入程序配置页，需要设置管理员电子邮箱、密码及站点地址，选择是否开启官方收集程序相关数据权限。

配置完成后程序进入登录页，填写前面设置的管理员电子邮箱及密码进行登录。

登录完成后进入 Wiki.js 主页，主页展示了两个按钮，CREATE HOME PAGE 用于新建主页面，CREATE HOME PAGE 用于进入管理面板。

7.2 切换语言

在管理面板中，进入 Site 分类下的 Locale 设置页，在右侧 Download Locale 中找到 Chinese Simplified 并下载，右侧状态变为绿色对号后再左侧 Locale Settings 中将 Site Locale 配置项切换为中文，最后点击 APPLY 按钮应用设置。

7.3 特色功能

7.3.1 多用户

在后台身份验证设置中，可以添加不同的登录方式，目前几乎集成了市面上各种常见的登录方式，选择某一种登录方式，通过给予开放注册权限，允许他人通过此种方式进行登录。

如果选择 Local Database 方式开放注册，则需要在后台邮件设置中配置发件人信息，主机为 SMTP 服务器，端口根据邮箱厂商设置，用户名为邮箱地址，密码为登录密码或者授权密码，根据邮箱厂商设置，如有疑问可参考这篇文章：https://talen.top/posts/caffd8d6/。

Wiki.js 还拥有强大的权限系统，在后台用户组设置中添加新的用户组，并且可以设置权限和页面规则等配置。

7.3.2 评论

Wiki.js 拥有一套内置的评论系统和多套第三方评论系统，在后台评论设置中可进行相关配置，根据喜好自行选择。

7.3.3 搜索

在后台搜索引擎设置中，可以选择使用不同类型的搜索引擎，可以选择基于本地数据库或者其它第三方搜索引擎，推荐使用 Algolia。

7.3.4 存储

Wiki.js 支持第三方存储库，特别适合大型的 Wiki 站点，减轻服务器负载压力。在后台存储设置中选择需要的第三方存储库，根据官方教程来进一步配置。

7.4 主题修改

7.4.1 导航栏

在后台导航设置中，有四种导航模式可选，分别是站点地图、静态导航、自定义导航（站点地图 + 静态导航）和禁用导航栏，可根据喜欢的样式进行选择展示，标签为展示名称，图标根据在后台主题设置中选择的图标集在相应网站里查找图标名称。

7.4.2 登录背景

登录界面背景图可更换自己想要的图片，在后台安全设置中找到登录配置板块，在登录页处填写背景图片链接或者点击右侧的按钮上传新图像。

7.4.3 网站常规

在后台常规设置中，可对站点图标、站点名称和页脚版权说明等信息进行修改。

7.4.4 目录位置

在后台主题设置中，找到主题设置配置板块，修改目录展示位置，建议设置右侧（Right）。

8 创建首页

在初始化 Wiki.js 并完成登录后的主页面，点击“创建首页（CREATE HOME PAGE）”按钮，选择想要使用的编辑器。

这里选择 Markdown 编辑器，然后编辑页面属性，这里需要重点配置页面标题及路径，完成后点击弹窗右上角“OK”按钮，编辑页面内容。

页面内容编辑完成后，点击“创建”按钮来保存，此后 Wiki.js 站点首页成为默认页面。

9 写在最后

通过本教程，相信你已经掌握了在不同环境下部署 Wiki.js 的核心方法。作为一款集开源、轻量、可扩展于一体的知识管理工具，Wiki.js 凭借其现代化的架构设计和丰富的功能特性，能够完美适配个人知识沉淀、团队协作共享乃至企业级文档中心等场景。无论是通过可视化面板的便捷部署，还是 Docker 容器化的一键启停，亦或是命令行操作的灵活掌控，Wiki.js 都为用户提供了多样化的选择。

在完成基础部署后，建议进一步探索其多语言内容管理、细粒度权限体系、第三方存储集成等进阶功能。通过合理配置用户组规则、评论模块、搜索引擎优化等特性，可打造出高度定制化的知识协作平台。若在部署过程中遇到问题，可参考各章节的"问题汇总"排查，或前往官方文档与社区获取支持。现在就行动起来，构建属于你的智能化知识库吧！