1. 项目概述为什么选择 Wiki.js 来搭建你的知识库在团队协作或者个人知识管理的场景里我们常常需要一个地方来沉淀文档、记录流程、分享经验。你可能试过用共享文档、云笔记甚至是一堆零散的 Markdown 文件。但这些方式要么权限管理麻烦要么搜索困难要么格式不统一时间一长知识就散了。这时候一个自托管的 Wiki 系统就成了刚需。它能把所有知识结构化地集中起来支持多人协作、版本控制、全文搜索还能通过 Web 界面轻松编辑。在众多开源 Wiki 方案中Wiki.js是我近年来用过最顺手的一个。它基于现代化的 Node.js 技术栈界面美观直观支持 Markdown、可视化编辑自带强大的权限管理和统计功能而且对中文搜索的支持相当不错。更重要的是它部署起来并不复杂。很多人一听到“自托管”、“Linux 服务器”就觉得头大其实跟着清晰的步骤走半小时内就能让一个功能完整的 Wiki 跑起来。这篇文章我就以最常用的 Linux 发行版为例手把手带你完成 Wiki.js 的安装、配置到最终上线。无论你是运维工程师、开发者还是想搭建个人知识库的爱好者这份“保姆级”图解指南都能让你一次成功。2. 安装前的环境准备与规划在开始敲命令之前花几分钟做好规划能避免后面很多不必要的麻烦。Wiki.js 的运行依赖几个核心组件我们需要确保服务器环境满足要求。2.1 系统要求与组件选型Wiki.js 官方推荐运行在 Linux 系统上Ubuntu 20.04/22.04 LTS 或 CentOS/Rocky Linux 8 都是很好的选择它们拥有长期支持和完善的软件包生态。对于服务器配置一个拥有 1核 CPU、1GB 内存和 10GB 磁盘空间的虚拟机就足以支撑一个小型团队的 Wiki 了。如果文档量巨大或访问频繁可以适当提升配置。软件栈方面Wiki.js 2.x 版本需要以下组件Node.js: 这是 Wiki.js 的运行环境。官方要求版本在 14.0 以上但为了更好的性能和兼容性我强烈建议安装最新的Node.js 18 LTS版本。它是一个长期支持版稳定性和新特性都有保障。数据库: Wiki.js 支持多种数据库包括 PostgreSQL、MySQL、MariaDB、SQLite 和 MS SQL Server。对于生产环境PostgreSQL是首选它在处理复杂查询和并发读写方面表现更优。如果是个人使用或想快速体验SQLite则是最简单的选择无需单独安装数据库服务。Web 服务器与反向代理: 虽然 Wiki.js 内置了一个 Web 服务器但直接暴露给公网并不安全性能也有限。我们通常会在前面加一个反向代理比如Nginx。它负责处理 SSL 加密HTTPS、静态文件缓存、负载均衡等让 Wiki.js 更安全、更高效地运行。2.2 服务器初始安全设置在安装任何服务之前确保服务器基础安全是第一步。如果你用的是新服务器请务必完成以下操作更新系统:sudo apt update sudo apt upgrade -y(Ubuntu/Debian) 或sudo dnf update -y(CentOS/Rocky)。创建非 root 用户: 避免直接使用 root 操作使用adduser wiki-user命令创建一个新用户并通过usermod -aG sudo wiki-user(Ubuntu) 或usermod -aG wheel wiki-user(CentOS) 赋予其管理员权限。配置 SSH 密钥登录: 禁用密码登录使用密钥对认证大幅提升安全性。配置防火墙: 启用系统的防火墙如ufw或firewalld默认只开放 SSH22端口。我们后续需要开放 HTTP80和 HTTPS443端口。注意本文后续操作如无特别说明均假设你已使用具有sudo权限的非 root 用户登录服务器。3. 核心依赖安装Node.js 与数据库现在我们开始安装 Wiki.js 赖以运行的核心环境。我会以Ubuntu 22.04为例其他系统的命令略有不同但思路一致。3.1 安装 Node.js 18 LTS不推荐使用系统自带的旧版本 Node.js。我们将通过 NodeSource 提供的官方仓库来安装。# 1. 下载并执行 NodeSource 的安装脚本添加 Node.js 18 的仓库源 curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - # 2. 从新添加的源安装 Node.js 和 npmNode.js 的包管理器 sudo apt install -y nodejs # 3. 验证安装是否成功查看版本号 node --version # 应显示 v18.x.x npm --version # 应显示 9.x.x 或更高如果npm版本较旧可以运行sudo npm install -g npmlatest进行升级。3.2 安装与配置 PostgreSQL 数据库如前所述我们选择 PostgreSQL 作为生产数据库。# 1. 安装 PostgreSQL 服务器和客户端 sudo apt install -y postgresql postgresql-contrib # 2. 启动 PostgreSQL 服务并设置开机自启 sudo systemctl start postgresql sudo systemctl enable postgresql # 3. 切换到 PostgreSQL 的默认管理用户 postgres sudo -i -u postgres # 4. 进入 PostgreSQL 交互终端 psql现在你进入了psql命令行。我们需要为 Wiki.js 创建一个专用的数据库、用户并设置密码。-- 1. 创建一个名为 wikijs 的数据库名字可自定义但后续配置需对应 CREATE DATABASE wikijs; -- 2. 创建一个名为 wikijs 的用户名字可自定义 CREATE USER wikijs WITH PASSWORD 你的强密码在这里; -- 3. 将 wikijs 数据库的所有权限授予 wikijs 用户 GRANT ALL PRIVILEGES ON DATABASE wikijs TO wikijs; -- 4. 为了提高连接性能建议修改该用户的连接限制可选 ALTER USER wikijs WITH CONNECTION LIMIT -1; -- -1 表示无限制 -- 5. 退出 psql \q然后我们退出postgres用户回到自己的用户 shell。# 退出 postgres 用户身份 exit实操心得数据库密码务必使用强密码大小写字母、数字、符号组合长度大于12位。你可以使用openssl rand -base64 24命令生成一个随机密码。请务必记下这个密码下一步配置 Wiki.js 时会用到。4. Wiki.js 本体的安装与配置环境准备好后就可以安装 Wiki.js 了。官方提供了几种安装方式我们采用最通用、最可控的“手动安装”。4.1 下载与解压 Wiki.js我们将在/var目录下创建一个专门的服务目录来存放 Wiki.js。# 1. 创建 Wiki.js 的安装目录并进入 sudo mkdir -p /var/wiki sudo chown -R $USER:$USER /var/wiki # 将目录所有权赋予当前用户方便操作 cd /var/wiki # 2. 从 GitHub 发布页获取最新稳定版的下载链接。 # 访问 https://github.com/Requarks/wiki/releases 查看最新版本号例如 2.5.300 # 替换下面命令中的版本号 VERSION2.5.300 wget https://github.com/Requarks/wiki/releases/download/v$VERSION/wiki-js.tar.gz # 3. 解压下载的压缩包 tar -xzf wiki-js.tar.gz # 4. 解压后你会得到一个 wiki 目录里面包含了所有运行文件 ls -la4.2 配置 Wiki.js 连接数据库Wiki.js 的配置主要通过一个名为config.yml的文件完成。我们需要从模板创建它。# 1. 复制配置文件模板 cp config.sample.yml config.yml # 2. 使用文本编辑器如 nano 或 vim编辑配置文件 nano config.yml打开config.yml后找到db配置部分。我们需要将之前设置的数据库信息填写进去。以下是一个针对 PostgreSQL 的配置示例db: type: postgres host: localhost # 数据库服务器地址因为是本机安装所以是 localhost port: 5432 # PostgreSQL 默认端口 user: wikijs # 你创建的数据库用户名 pass: 你的强密码在这里 # 你设置的数据库密码注意用单引号包裹 db: wikijs # 你创建的数据库名 ssl: false # 如果是本地连接通常关闭 SSL。如果数据库在远程且支持 SSL可设为 true # 其他参数保持默认即可另外建议修改bind配置让 Wiki.js 只监听本地回环地址因为我们后面会用 Nginx 做反向代理这样更安全。bind: 127.0.0.1 # 只允许本地访问 port: 3000 # Wiki.js 应用运行的端口默认 3000保存并退出编辑器在 nano 中按CtrlX然后按Y确认再按Enter。4.3 启动 Wiki.js 并完成初始化配置完成后就可以首次启动 Wiki.js 了。它会自动根据配置文件创建数据库表结构。# 1. 启动 Wiki.js 服务 node server # 或者使用 nohup 让它在后台运行按 CtrlC 停止前台进程后使用 # nohup node server wiki.log 21 第一次启动时控制台会输出大量日志显示数据库迁移、初始化等过程。当你看到类似[MASTER] Wiki.js is listening on 127.0.0.1:3000的日志时说明启动成功。现在打开你的浏览器访问http://你的服务器IP地址:3000。你应该会看到 Wiki.js 的初始化设置页面。设置管理员账户输入你的邮箱、密码和站点名称。这个账户将是 Wiki 的超级管理员。完成初始化点击下一步Wiki.js 会进行最后的环境检查并完成设置。登录后台初始化完成后使用你刚设置的管理员邮箱和密码登录。恭喜至此Wiki.js 的核心服务已经安装并运行起来了。但我们现在是通过 IP 和 3000 端口直接访问的这既不安全也不方便记忆。下一步我们将通过 Nginx 和域名让它变成一个标准的网站。5. 使用 Nginx 配置反向代理与 HTTPS让服务通过标准的 80/443 端口并启用 HTTPS是生产环境部署的必备步骤。5.1 安装 Nginxsudo apt install -y nginx sudo systemctl start nginx sudo systemctl enable nginx安装后可以先访问http://你的服务器IP应该能看到 Nginx 的欢迎页面证明 Nginx 已正常运行。5.2 配置 Nginx 反向代理我们需要为 Wiki.js 创建一个独立的 Nginx 站点配置文件。sudo nano /etc/nginx/sites-available/wiki将以下配置粘贴进去。请将wiki.yourdomain.com替换为你自己的域名。server { listen 80; listen [::]:80; server_name wiki.yourdomain.com; # 你的域名 # 将 HTTP 请求重定向到 HTTPS申请证书后生效 # return 301 https://$server_name$request_uri; # Wiki.js 反向代理配置 location / { proxy_pass http://127.0.0.1:3000; # 指向我们本地运行的 Wiki.js proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; # 设置超时时间避免长任务失败 proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; } # 静态资源缓存提升性能 location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ { proxy_pass http://127.0.0.1:3000; expires 30d; add_header Cache-Control public, immutable; proxy_set_header Host $host; } }配置解析proxy_set_header系列指令至关重要它们将客户端的真实 IP、协议等信息传递给后端的 Wiki.js否则 Wiki.js 日志里看到的访问者 IP 都会是127.0.0.1。Upgrade和Connection头是为了支持 WebSocket这是 Wiki.js 实时协作等功能所必需的。保存退出后启用这个站点配置并测试 Nginx 语法。# 创建符号链接到 sites-enabled 目录 sudo ln -s /etc/nginx/sites-available/wiki /etc/nginx/sites-enabled/ # 测试 Nginx 配置是否有语法错误 sudo nginx -t # 如果显示 syntax is ok 和 test is successful则说明配置正确 # 重新加载 Nginx 使配置生效 sudo systemctl reload nginx现在你应该可以通过域名http://wiki.yourdomain.com访问到你的 Wiki.js 站点了如果域名已解析到服务器IP。5.3 使用 Let‘s Encrypt 配置 HTTPS免费的 SSL 证书可以通过 Let‘s Encrypt 的 Certbot 工具轻松获取。# 1. 安装 Certbot 和 Nginx 插件 sudo apt install -y certbot python3-certbot-nginx # 2. 运行 Certbot它会自动读取你的 Nginx 配置并申请证书 sudo certbot --nginx -d wiki.yourdomain.com按照提示操作输入邮箱用于接收安全通知、同意服务条款。Certbot 会自动为你申请证书并修改 Nginx 配置将 HTTP 重定向到 HTTPS。申请成功后它会配置自动续期。完成后再次访问https://wiki.yourdomain.com浏览器地址栏应该显示安全的锁标志。6. 配置系统服务与进程守护目前我们的 Wiki.js 是通过命令行node server运行的一旦关闭终端服务就停止了。我们需要将其配置为系统服务实现开机自启和自动重启。6.1 创建 Systemd 服务单元文件Systemd 是现代 Linux 系统的服务管理器。sudo nano /etc/systemd/system/wiki.service将以下内容粘贴进去[Unit] DescriptionWiki.js Afternetwork.target postgresql.service # 确保在网络和数据库服务启动后再启动 Wantspostgresql.service [Service] Typesimple Userwiki-user # 替换为你的非 root 用户名例如之前创建的 wiki-user WorkingDirectory/var/wiki # Wiki.js 的安装目录 EnvironmentNODE_ENVproduction ExecStart/usr/bin/node server # Node.js 的路径可通过 which node 确认 Restartalways RestartSec10 StandardOutputsyslog StandardErrorsyslog SyslogIdentifierwiki # 安全相关设置限制服务权限 NoNewPrivilegestrue ProtectSystemstrict ReadWritePaths/var/wiki/data # 允许写入数据目录 PrivateTmptrue [Install] WantedBymulti-user.target注意事项User务必修改为你的实际用户名不要用 root。这符合最小权限原则更安全。WorkingDirectory确保路径是 Wiki.js 的实际安装目录。ReadWritePathsWiki.js 需要写入data目录来存储上传的文件、缓存和日志。这里我们只授予它对这个特定目录的写权限。6.2 启动并启用 Wiki.js 服务# 1. 重新加载 systemd 配置使其识别新的服务文件 sudo systemctl daemon-reload # 2. 启动 wiki 服务 sudo systemctl start wiki.service # 3. 设置开机自启 sudo systemctl enable wiki.service # 4. 检查服务状态确认运行正常 sudo systemctl status wiki.service如果状态显示为active (running)并且日志没有报错说明服务已成功在后台运行。现在你可以安全地关闭终端Wiki.js 也会持续运行。6.3 管理服务常用命令sudo systemctl stop wiki停止服务。sudo systemctl restart wiki重启服务修改配置后常用。sudo systemctl status wiki查看服务状态和最新日志。sudo journalctl -u wiki -f实时查看 Wiki.js 的日志输出用于排错。7. 基础优化与安全加固服务跑起来只是第一步做一些简单的优化和安全设置能让你的 Wiki 更稳定、更安全。7.1 配置防火墙确保只开放必要的端口。# 如果使用 ufw (Ubuntu) sudo ufw allow ssh sudo ufw allow Nginx Full # 同时开放 80 和 443 端口 sudo ufw --force enable # 启用防火墙 # 如果使用 firewalld (CentOS/Rocky) sudo firewall-cmd --permanent --add-servicessh sudo firewall-cmd --permanent --add-servicehttp sudo firewall-cmd --permanent --add-servicehttps sudo firewall-cmd --reload7.2 优化 Nginx 配置编辑之前创建的/etc/nginx/sites-available/wiki文件在server块内或全局http块/etc/nginx/nginx.conf中添加一些优化参数。# 在 wiki 配置文件的 server 块内或 nginx.conf 的 http 块内添加 client_max_body_size 100M; # 允许上传最大 100M 的文件根据需求调整 proxy_buffering on; proxy_buffer_size 4k; proxy_buffers 8 16k; proxy_busy_buffers_size 24k;7.3 配置 Wiki.js 后台设置登录 Wiki.js 管理后台 (https://你的域名/management)进行一些重要设置常规设置检查站点 URL 是否正确设置为你的 HTTPS 域名。安全性启用“强制 HTTPS”。设置“登录失败尝试次数”和“账户锁定时间”防止暴力破解。考虑启用双因素认证 (2FA) 以增强管理员账户安全。存储确认“文件存储”位置正确通常使用本地文件系统 (/var/wiki/data)。如果需要可以配置外部存储如 AWS S3。邮件配置 SMTP 邮件服务器用于用户注册、密码重置等通知。这是生产环境必备功能。8. 常见问题与排查技巧实录即使按照步骤操作也可能会遇到一些问题。这里记录了几个我踩过的坑和解决方法。8.1 服务启动失败端口占用或数据库连接错误问题现象执行sudo systemctl status wiki显示failed或inactive查看日志journalctl -u wiki -f发现错误。排查思路端口占用日志可能显示EADDRINUSE。检查 3000 端口是否被其他进程占用sudo lsof -i :3000。如果是可以停止该进程或者修改 Wiki.jsconfig.yml中的port为其他端口记得同步修改 Nginx 的proxy_pass。数据库连接失败日志可能显示password authentication failed或connection refused。检查密码确认config.yml中的密码与创建数据库用户时设置的完全一致注意特殊字符的转义。检查 PostgreSQL 服务确保 PostgreSQL 正在运行sudo systemctl status postgresql。检查连接权限默认情况下PostgreSQL 只允许本地peer或ident认证。我们需要修改为md5密码认证。编辑配置文件sudo nano /etc/postgresql/14/main/pg_hba.conf版本号可能不同。找到类似下面的行# IPv4 local connections: host all all 127.0.0.1/32 scram-sha-256将scram-sha-256改为md5。然后重启 PostgreSQLsudo systemctl restart postgresql。8.2 通过域名访问显示 “502 Bad Gateway”问题现象Nginx 能访问但反向代理到 Wiki.js 时出错。排查思路检查 Wiki.js 服务首先确认 Wiki.js 本身是否在运行sudo systemctl status wiki。检查 Nginx 配置运行sudo nginx -t检查语法。确保proxy_pass的地址和端口与 Wiki.js 监听的地址 (config.yml中的bind和port) 完全一致。如果 Wiki.js 绑定到127.0.0.1:3000那么proxy_pass必须是http://127.0.0.1:3000。检查防火墙虽然 Wiki.js 在本地但确保服务器的防火墙没有阻止本地回环 (lo) 接口的通信。查看 Nginx 错误日志获取更详细的错误信息sudo tail -f /var/log/nginx/error.log。8.3 上传文件大小限制问题现象上传稍大的图片或附件失败。解决方法这是一个常见问题需要同时修改两处配置Nginx如 7.2 节所述在配置文件中增加client_max_body_size 100M;。Wiki.js 后台登录管理后台进入“存储” - “文件存储”设置找到“最大文件大小”并相应调大例如设置为 100 MB。修改后重启 Nginx (sudo systemctl reload nginx) 和 Wiki.js (sudo systemctl restart wiki)。8.4 后台管理界面加载缓慢或部分功能异常问题现象页面可以打开但样式错乱、JS 不加载或操作无响应。排查思路检查静态资源路径确保 Nginx 配置中静态资源缓存部分的proxy_pass指向正确。检查 WebSocketWiki.js 的实时功能依赖 WebSocket。确保 Nginx 配置中包含了proxy_set_header Upgrade和proxy_set_header Connection指令。浏览器开发者工具按 F12 打开控制台查看“网络”(Network) 标签页是否有资源加载失败状态码为 4xx 或 5xx。这能快速定位是哪个文件或接口出了问题。服务器资源使用htop或free -h检查服务器内存和 CPU 使用率。1GB 内存的服务器在初始化或处理大量内容时可能吃紧。安装和配置的过程本质上是在理解一个现代化 Web 应用的标准部署流程准备环境Node.js、数据库、部署应用、配置反向代理Nginx、启用 HTTPS、配置进程守护Systemd、最后进行基础优化。每一步都有其明确的目的遇到问题也大多有清晰的日志可循。当你成功看到自己部署的 Wiki 页面时这套流程和经验完全可以复用到其他类似的自托管服务上这才是比单纯安装一个 Wiki.js 更大的收获。