企业官网建设流程全解析

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 版本需要以下组件：

1. Node.js: 这是 Wiki.js 的运行环境。官方要求版本在 14.0 以上，但为了更好的性能和兼容性，我强烈建议安装最新的Node.js 18 LTS版本。它是一个长期支持版，稳定性和新特性都有保障。
2. 数据库: Wiki.js 支持多种数据库，包括 PostgreSQL、MySQL、MariaDB、SQLite 和 MS SQL Server。对于生产环境，PostgreSQL是首选，它在处理复杂查询和并发读写方面表现更优。如果是个人使用或想快速体验，SQLite则是最简单的选择，无需单独安装数据库服务。
3. 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），默认只开放 SSH（22）端口。我们后续需要开放 HTTP（80）和 HTTPS（443）端口。

注意：本文后续操作如无特别说明，均假设你已使用具有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 和 npm（Node.js 的包管理器） sudo apt install -y nodejs # 3. 验证安装是否成功，查看版本号 node --version # 应显示 v18.x.x npm --version # 应显示 9.x.x 或更高

如果npm版本较旧，可以运行sudo npm install -g npm@latest进行升级。

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 # 替换下面命令中的版本号 VERSION=2.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 -la

4.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 中按Ctrl+X，然后按Y确认，再按Enter）。

4.3 启动 Wiki.js 并完成初始化

配置完成后，就可以首次启动 Wiki.js 了。它会自动根据配置文件创建数据库表结构。

# 1. 启动 Wiki.js 服务 node server # 或者使用 nohup 让它在后台运行（按 Ctrl+C 停止前台进程后使用） # nohup node server > wiki.log 2>&1 &

第一次启动时，控制台会输出大量日志，显示数据库迁移、初始化等过程。当你看到类似[MASTER] Wiki.js is listening on 127.0.0.1:3000的日志时，说明启动成功。

现在，打开你的浏览器，访问http://你的服务器IP地址:3000。你应该会看到 Wiki.js 的初始化设置页面。

1. 设置管理员账户：输入你的邮箱、密码和站点名称。这个账户将是 Wiki 的超级管理员。
2. 完成初始化：点击下一步，Wiki.js 会进行最后的环境检查并完成设置。
3. 登录后台：初始化完成后，使用你刚设置的管理员邮箱和密码登录。

恭喜！至此，Wiki.js 的核心服务已经安装并运行起来了。但我们现在是通过 IP 和 3000 端口直接访问的，这既不安全也不方便记忆。下一步，我们将通过 Nginx 和域名，让它变成一个标准的网站。

5. 使用 Nginx 配置反向代理与 HTTPS

让服务通过标准的 80/443 端口，并启用 HTTPS，是生产环境部署的必备步骤。

5.1 安装 Nginx

sudo 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] Description=Wiki.js After=network.target postgresql.service # 确保在网络和数据库服务启动后再启动 Wants=postgresql.service [Service] Type=simple User=wiki-user # 替换为你的非 root 用户名，例如之前创建的 wiki-user WorkingDirectory=/var/wiki # Wiki.js 的安装目录 Environment=NODE_ENV=production ExecStart=/usr/bin/node server # Node.js 的路径，可通过 `which node` 确认 Restart=always RestartSec=10 StandardOutput=syslog StandardError=syslog SyslogIdentifier=wiki # 安全相关设置，限制服务权限 NoNewPrivileges=true ProtectSystem=strict ReadWritePaths=/var/wiki/data # 允许写入数据目录 PrivateTmp=true [Install] WantedBy=multi-user.target

注意事项：

1. User：务必修改为你的实际用户名，不要用 root。这符合最小权限原则，更安全。
2. WorkingDirectory：确保路径是 Wiki.js 的实际安装目录。
3. ReadWritePaths：Wiki.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-service=ssh sudo firewall-cmd --permanent --add-service=http sudo firewall-cmd --permanent --add-service=https sudo firewall-cmd --reload

7.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)，进行一些重要设置：

1. 常规设置：检查站点 URL 是否正确设置为你的 HTTPS 域名。
2. 安全性：
   • 启用“强制 HTTPS”。
   • 设置“登录失败尝试次数”和“账户锁定时间”，防止暴力破解。
   • 考虑启用双因素认证 (2FA) 以增强管理员账户安全。
3. 存储：确认“文件存储”位置正确，通常使用本地文件系统 (/var/wiki/data)。如果需要，可以配置外部存储如 AWS S3。
4. 邮件：配置 SMTP 邮件服务器，用于用户注册、密码重置等通知。这是生产环境必备功能。

8. 常见问题与排查技巧实录

即使按照步骤操作，也可能会遇到一些问题。这里记录了几个我踩过的坑和解决方法。

8.1 服务启动失败：端口占用或数据库连接错误

问题现象：执行sudo systemctl status wiki显示failed或inactive，查看日志journalctl -u wiki -f发现错误。

排查思路：

1. 端口占用：日志可能显示EADDRINUSE。检查 3000 端口是否被其他进程占用：sudo lsof -i :3000。如果是，可以停止该进程，或者修改 Wiki.jsconfig.yml中的port为其他端口（记得同步修改 Nginx 的proxy_pass）。
2. 数据库连接失败：日志可能显示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。然后重启 PostgreSQL：sudo systemctl restart postgresql。

8.2 通过域名访问显示 “502 Bad Gateway”

问题现象：Nginx 能访问，但反向代理到 Wiki.js 时出错。

排查思路：

1. 检查 Wiki.js 服务：首先确认 Wiki.js 本身是否在运行：sudo systemctl status wiki。
2. 检查 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。
3. 检查防火墙：虽然 Wiki.js 在本地，但确保服务器的防火墙没有阻止本地回环 (lo) 接口的通信。
4. 查看 Nginx 错误日志：获取更详细的错误信息：sudo tail -f /var/log/nginx/error.log。

8.3 上传文件大小限制

问题现象：上传稍大的图片或附件失败。

解决方法：这是一个常见问题，需要同时修改两处配置：

1. Nginx：如 7.2 节所述，在配置文件中增加client_max_body_size 100M;。
2. Wiki.js 后台：登录管理后台，进入“存储” -> “文件存储”设置，找到“最大文件大小”并相应调大（例如设置为 100 MB）。
3. 修改后，重启 Nginx (sudo systemctl reload nginx) 和 Wiki.js (sudo systemctl restart wiki)。

8.4 后台管理界面加载缓慢或部分功能异常

问题现象：页面可以打开，但样式错乱、JS 不加载或操作无响应。

排查思路：

1. 检查静态资源路径：确保 Nginx 配置中静态资源缓存部分的proxy_pass指向正确。
2. 检查 WebSocket：Wiki.js 的实时功能依赖 WebSocket。确保 Nginx 配置中包含了proxy_set_header Upgrade和proxy_set_header Connection指令。
3. 浏览器开发者工具：按 F12 打开控制台，查看“网络”(Network) 标签页，是否有资源加载失败（状态码为 4xx 或 5xx）。这能快速定位是哪个文件或接口出了问题。
4. 服务器资源：使用htop或free -h检查服务器内存和 CPU 使用率。1GB 内存的服务器在初始化或处理大量内容时可能吃紧。

安装和配置的过程，本质上是在理解一个现代化 Web 应用的标准部署流程：准备环境（Node.js、数据库）、部署应用、配置反向代理（Nginx）、启用 HTTPS、配置进程守护（Systemd）、最后进行基础优化。每一步都有其明确的目的，遇到问题也大多有清晰的日志可循。当你成功看到自己部署的 Wiki 页面时，这套流程和经验完全可以复用到其他类似的自托管服务上，这才是比单纯安装一个 Wiki.js 更大的收获。