Wiki.js部署教程

1. Wiki.js 简介

Wiki.js 是一款现代化、功能强大的开源 Wiki 系统，支持多种数据库，界面美观，易于扩展。
官方网址：https://wiki.js.org/
官方文档：https://docs.requarks.io/install/linux

推荐配合官方教程操作，确保获取最新版本。本文档写于 2025/06/10 （Wiki.js 大约发布于当前 3 个月前）。

2. 我的环境信息

• Node.js：22.16.0
• PostgreSQL：17.5
• 操作系统：Linux - Ubuntu (plucky) 25.04 x64
• CPU 核心数：1
• 总内存：955.12 MB

3. 部署准备

3.1 远程连接工具

• 推荐使用 Xshell（免费版），请安装左侧的 Xshell 而不是 Xftp。
• Xshell 8.0 官方直链下载（建议下载最新版）。

3.2 系统更新与基础工具

sudo apt update && sudo apt upgrade
sudo apt install screen ufw

4. Wiki.js 安装包部署（非 Docker）

Docker 方式可能存在兼容性问题，推荐直接使用安装包部署。

4.1 下载并解压

cd /home/
wget https://github.com/Requarks/wiki/releases/latest/download/wiki-js.tar.gz
mkdir wiki
tar xzf wiki-js.tar.gz -C ./wiki
cd ./wiki

4.2 配置文件准备

mv config.sample.yml config.yml

5. config.yml 配置说明

5.1 英文原版示例

#######################################################################
# Wiki.js - CONFIGURATION                                             #
#######################################################################
# Full documentation + examples:
# https://docs.requarks.io/install

# ---------------------------------------------------------------------
# Port the server should listen to
# ---------------------------------------------------------------------

port: 3000

# ---------------------------------------------------------------------
# Database
# ---------------------------------------------------------------------
# Supported Database Engines:
# - postgres = PostgreSQL 9.5 or later
# - mysql = MySQL 8.0 or later (5.7.8 partially supported, refer to docs)
# - mariadb = MariaDB 10.2.7 or later
# - mssql = MS SQL Server 2012 or later
# - sqlite = SQLite 3.9 or later

db:
  type: postgres

  # PostgreSQL / MySQL / MariaDB / MS SQL Server only:
  host: localhost
  port: 5432
  user: wikijs
  pass: wikijsrocks
  db: wiki
  ssl: false

  # Optional - PostgreSQL / MySQL / MariaDB only:
  # -> Uncomment lines you need below and set `auto` to false
  # -> Full list of accepted options: https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options
  sslOptions:
    auto: true
    # rejectUnauthorized: false
    # ca: path/to/ca.crt
    # cert: path/to/cert.crt
    # key: path/to/key.pem
    # pfx: path/to/cert.pfx
    # passphrase: xyz123

  # Optional - PostgreSQL only:
  schema: public

  # SQLite only:
  storage: path/to/database.sqlite

#######################################################################
# ADVANCED OPTIONS                                                    #
#######################################################################
# Do not change unless you know what you are doing!

# ---------------------------------------------------------------------
# SSL/TLS Settings
# ---------------------------------------------------------------------
# Consider using a reverse proxy (e.g. nginx) if you require more
# advanced options than those provided below.

ssl:
  enabled: false
  port: 3443

  # Provider to use, possible values: custom, letsencrypt
  provider: custom

  # ++++++ For custom only ++++++
  # Certificate format, either 'pem' or 'pfx':
  format: pem
  # Using PEM format:
  key: path/to/key.pem
  cert: path/to/cert.pem
  # Using PFX format:
  pfx: path/to/cert.pfx
  # Passphrase when using encrypted PEM / PFX keys (default: null):
  passphrase: null
  # Diffie Hellman parameters, with key length being greater or equal
  # to 1024 bits (default: null):
  dhparam: null

  # ++++++ For letsencrypt only ++++++
  domain: wiki.yourdomain.com
  subscriberEmail: admin@example.com

# ---------------------------------------------------------------------
# Database Pool Options
# ---------------------------------------------------------------------
# Refer to https://github.com/vincit/tarn.js for all possible options

pool:
  # min: 2
  # max: 10

# ---------------------------------------------------------------------
# IP address the server should listen to
# ---------------------------------------------------------------------
# Leave 0.0.0.0 for all interfaces

bindIP: 0.0.0.0

# ---------------------------------------------------------------------
# Log Level
# ---------------------------------------------------------------------
# Possible values: error, warn, info (default), verbose, debug, silly

logLevel: info

# ---------------------------------------------------------------------
# Log Format
# ---------------------------------------------------------------------
# Output format for logging, possible values: default, json

logFormat: default

# ---------------------------------------------------------------------
# Offline Mode
# ---------------------------------------------------------------------
# If your server cannot access the internet. Set to true and manually
# download the offline files for sideloading.

offline: false

# ---------------------------------------------------------------------
# High-Availability
# ---------------------------------------------------------------------
# Set to true if you have multiple concurrent instances running off the
# same DB (e.g. Kubernetes pods / load balanced instances). Leave false
# otherwise. You MUST be using PostgreSQL to use this feature.

ha: false

# ---------------------------------------------------------------------
# Data Path
# ---------------------------------------------------------------------
# Writeable data path used for cache and temporary user uploads.
dataPath: ./data

# ---------------------------------------------------------------------
# Body Parser Limit
# ---------------------------------------------------------------------
# Maximum size of API requests body that can be parsed. Does not affect
# file uploads.

bodyParserLimit: 5mb

5.2 中文注释版示例

#######################################################################
# Wiki.js - CONFIGURATION                                             #
#######################################################################
# 完整文档和示例:
# https://docs.requarks.io/install

# 服务器监听的端口号
port: 3000

# 数据库设置
# 支持的数据库引擎：
# - PostgreSQL 9.5 或更高版本
# - MySQL 8.0 或更高版本（5.7.8 部分支持，参见文档）
# - MariaDB 10.2.7 或更高版本
# - MS SQL Server 2012 或更高版本
# - SQLite 3.9 或更高版本

db:
  type: postgres  # 使用的数据库类型（PostgreSQL）

  # 仅适用于 PostgreSQL / MySQL / MariaDB / MS SQL Server:
  host: localhost  # 数据库主机地址
  port: 5432       # 数据库端口
  user: wikijs     # 数据库用户名
  pass: wikijsrocks  # 数据库密码
  db: wiki         # 数据库名
  ssl: false       # 是否启用 SSL

  # 可选项 - 仅 PostgreSQL / MySQL / MariaDB:
  # -> 取消需要的注释并将 `auto` 设为 false
  # -> 所有可用选项详见： 
  # https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options

  sslOptions:
    auto: true  # 自动启用 SSL（设为 false 可使用手动配置）
    # rejectUnauthorized: false  # 不验证证书
    # ca: path/to/ca.crt         # CA 证书路径
    # cert: path/to/cert.crt     # 公钥证书路径
    # key: path/to/key.pem       # 私钥路径
    # pfx: path/to/cert.pfx      # PFX 格式证书路径
    # passphrase: xyz123         # 私钥密码（如果有）

  # 仅适用于 PostgreSQL:
  schema: public  # 数据库 schema（默认是 public）

  # 仅适用于 SQLite:
  storage: path/to/database.sqlite  # SQLite 数据库文件路径

#######################################################################
# 高级选项                                      #
#######################################################################
# 除非你知道自己在干啥，否则不要改

# SSL/TLS 设置
# 如果你需要更高级的选项，请考虑使用反向代理（例如 nginx）

ssl:
  enabled: false  # 是否启用 SSL
  port: 3443      # SSL 使用的端口号

  # 使用的证书提供方式，可选：custom, letsencrypt
  provider: custom

  # ++++++ 仅 custom 可用 ++++++
  # 证书格式：'pem' 或 'pfx'
  format: pem

  # 使用 PEM 格式：
  key: path/to/key.pem     # 私钥路径
  cert: path/to/cert.pem   # 公钥证书路径

  # 使用 PFX 格式：
  pfx: path/to/cert.pfx    # PFX 文件路径

  # 使用加密的 PEM / PFX 时的密码（默认为 null）：
  passphrase: null

  # Diffie-Hellman 参数，至少 1024 位（默认 null）：
  dhparam: null

  # ++++++ 仅 letsencrypt 可用 ++++++
  domain: wiki.yourdomain.com        # 你的域名
  subscriberEmail: admin@example.com  # 管理员邮箱

# 数据库连接池设置  Database Pool Options
# 所有可用选项参见： https://github.com/vincit/tarn.js
pool:
  # min: 2   # 最小连接数
  # max: 10  # 最大连接数

# 服务器监听的 IP 地址
# 保留 0.0.0.0 表示监听所有接口  
bindIP: 0.0.0.0

# 日志等级
# 可选值：error, warn, info（默认）, verbose, debug, silly  
logLevel: info

# 日志格式
# 可选输出格式：default, json  
logFormat: default

# 离线模式
# 如果服务器无法联网，设置为 true 并手动下载离线资源
offline: false

# 高可用设置
# 如果你有多个实例同时运行（比如 Kubernetes 部署），请设为 true，否则设为 false
# 仅在使用 PostgreSQL 时才能启用  
ha: false

# 数据存储路径
# 用于缓存和用户临时上传内容  
dataPath: ./data

# 请求体解析大小限制
# 可解析的最大 API 请求体大小（不影响文件上传）  
bodyParserLimit: 5mb

5.3 数据库配置建议

强烈建议使用官方推荐的 PostgreSQL 数据库，Wiki.js 3.0 起将不再支持其他数据库。

将如下内容：

user: wikijs     # 数据库用户名
pass: wikijsrocks  # 数据库密码

修改为（密码可自定义，后续数据库设置需一致）：

user: postgres     # 数据库用户名
pass: postgres     # 数据库密码

6. PostgreSQL 数据库安装与配置

• 官网：https://www.postgresql.org/
• 官方安装教程：https://www.postgresql.org/download/linux/ubuntu/

6.1 安装 PostgreSQL

sudo apt install postgresql

6.2 启动与状态检查

sudo systemctl start postgresql
sudo systemctl status postgresql

正常状态应为绿色 Active: active (running)。

6.3 配置数据库登录权限

PostgreSQL 默认仅允许系统同名用户登录。为方便管理，需将 peer 认证方式改为 trust（部署完成后建议改回更安全的方式）。

• 查找配置文件：

  sudo find / -name "pg_hba.conf"
  

  一般路径为 /etc/postgresql/17/main/pg_hba.conf

• 编辑配置文件（将所有 peer 改为 trust）：

  sudo vim /etc/postgresql/17/main/pg_hba.conf
  

  • 按 i 进入编辑模式，修改后按 Esc，输入 :wq 保存退出。

• 重启数据库服务：

  sudo systemctl restart postgresql
  

6.4 创建数据库与设置密码

psql -U postgres
# 在 psql 提示符下执行：
CREATE DATABASE wiki;
ALTER USER postgres WITH PASSWORD 'postgres';  # 如自定义密码请同步修改 config.yml
\l  # 查看所有数据库
\q  # 退出

安全建议：部署完成后，建议将 trust 认证方式改为 scram-sha-256，增强安全性。更改后重启数据库登录 psql -U postgres 时需输入密码。

7. Node.js 安装

• 官网：https://nodejs.org/en

sudo apt install nodejs npm
node -v  # 检查版本，建议 v22.16.0 或更高

8. 防火墙与端口设置

sudo ufw enable
sudo ufw allow 3000    # Wiki.js 默认端口

部分云服务器需在控制台开放端口。
如需将端口改为 80，请在 config.yml 中修改 port 为 80，然后再执行 sudo ufw allow 80。

9. screen 会话教程（后台运行 Wiki.js）

建议使用 screen 工具后台运行 Wiki.js 服务：

screen -S wikijs
node server

• 按 Ctrl+A 然后 D 键退出 screen，会话仍在后台运行。
• 使用 screen -r wikijs 可重新进入会话。
• screen -ls 查看所有会话列表。

10. 访问与初始化

• 访问 http://你的IP:3000（如端口为 80 可省略端口号）。
• 注册管理员账户，完成初始化。

11. 启用 HTTPS 与域名证书

适用于需要加密和域名访问的场景。

• Let’s Encrypt 官网：https://letsencrypt.org/
• Certbot 官方教程：https://certbot.eff.org/instructions?ws=other&os=snap

11.1 申请免费 SSL 证书

1. 停止 Wiki.js 服务（Ctrl+C）。

2. 临时关闭防火墙（如有必要）：

   sudo ufw disable
   

3. 安装 Certbot：

   sudo snap install --classic certbot
   sudo ln -s /snap/bin/certbot /usr/bin/certbot
   

4. 申请证书：

   sudo certbot certonly --standalone
   

   按提示输入域名和邮箱（邮箱仅用于通知，无需验证）。

5. 证书生成路径一般为 /etc/letsencrypt/live/你的域名/，如：

   ls /etc/letsencrypt/live/wiki.parrotstudio.xyz/
   # cert.pem  chain.pem  fullchain.pem  privkey.pem  README
   

11.2 配置 Wiki.js 使用 HTTPS

在 config.yml 中修改如下：

# ...
ssl:
  enabled: true
  port: 3443  # 可以改为443

  # Provider to use, possible values: custom, letsencrypt
  provider: custom

  # ++++++ For custom only ++++++
  # Certificate format, either 'pem' or 'pfx':
  format: pem
  # Using PEM format:
  key: /etc/letsencrypt/live/您的域名/privkey.pem
  cert: /etc/letsencrypt/live/您的域名/fullchain.pem
  # Using PFX format:
  pfx: path/to/cert.pfx
  # Passphrase when using encrypted PEM / PFX keys (default: null):
  passphrase: null
  # Diffie Hellman parameters, with key length being greater or equal
  # to 1024 bits (default: null):
  dhparam: null

  # ++++++ For letsencrypt only ++++++
  domain: 不用管
  subscriberEmail: 不用管

11.3 开放端口并重启服务

sudo ufw allow 3443
sudo ufw allow 80
sudo ufw allow 443
sudo ufw enable
cd /home/wiki
node server

• 访问 https://你的域名:3443 即可通过 HTTPS 加密访问。
• 如需使用 443 端口，可将 port 参数改为 443，浏览器会自动跳转。

12. 常见问题与建议

• 数据库连接失败？
  检查 config.yml 数据库配置、端口、防火墙、数据库服务状态。
• 端口无法访问？
  检查防火墙设置、云服务器安全组。
• 证书申请失败？
  确认 80/443 端口已开放，域名已正确解析到服务器。
• 安全建议
  部署完成后，建议将 PostgreSQL 认证方式改为 scram-sha-256，并设置强密码。

13. 参考链接

• Wiki.js 官网
• Wiki.js 官方文档
• PostgreSQL 官网
• Node.js 官网
• Let’s Encrypt 官网
• Certbot 官方教程
• Xshell 官网

本教程适用于 Ubuntu 25.04 及 Wiki.js 2.5.307 版本，其他系统请参考官方文档调整。