Wiki.js 知识管理平台部署教程

Wiki.js 是一款功能全面的开源 Wiki 引擎，基于 Node.js 构建。它支持 Markdown、可视化编辑器和 HTML 三种编辑模式，内置 Git 同步、全文搜索、多语言、访问控制等丰富功能。Wiki.js 的安装和配置相比 Outline 更加简单，是个人和团队搭建知识库的优秀选择。本文将介绍如何在搬瓦工 VPS 上使用 Docker 部署 Wiki.js。部署前请确保已安装好 Docker 和 Docker Compose。

一、系统要求

操作系统：Ubuntu 20.04+ 或 Debian 11+。
内存：至少 1GB，建议 2GB。
磁盘：至少 5GB 可用空间。
域名：建议绑定域名并配置 SSL。

二、Docker Compose 部署

mkdir -p /opt/wikijs
cd /opt/wikijs

cat > /opt/wikijs/docker-compose.yml <<'EOF'
version: '3.8'

services:
  db:
    image: postgres:15-alpine
    restart: always
    environment:
      POSTGRES_DB: wikijs
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: your_db_password
    volumes:
      - postgres_data:/var/lib/postgresql/data

  wikijs:
    image: ghcr.io/requarks/wiki:2
    restart: always
    depends_on:
      - db
    ports:
      - "3000:3000"
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: your_db_password
      DB_NAME: wikijs

volumes:
  postgres_data:
EOF

docker compose up -d

三、配置 Nginx 反向代理

cat > /etc/nginx/sites-available/wikijs <<'EOF'
server {
    listen 80;
    server_name wiki.yourdomain.com;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
EOF

ln -s /etc/nginx/sites-available/wikijs /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d wiki.yourdomain.com

四、初始化设置

访问 https://wiki.yourdomain.com，首次访问进入设置向导：

管理员邮箱：设置管理员邮箱地址。
管理员密码：设置管理员密码。
站点 URL：填入 https://wiki.yourdomain.com。

完成向导后自动登录管理面板。

五、编辑器选择

Wiki.js 提供三种编辑器，创建页面时可以选择：

Markdown：使用 Markdown 语法编辑，适合开发者和技术人员。支持 GFM 扩展、数学公式、Mermaid 流程图等。
可视化编辑器：所见即所得的富文本编辑器，适合不熟悉 Markdown 的用户。
HTML：直接编写 HTML 代码，提供最大的灵活性。

六、配置搜索引擎

在管理面板 > Search Engines 中配置全文搜索。Wiki.js 支持多种搜索后端：

Database：使用 PostgreSQL 的全文搜索功能，无需额外服务，适合中小规模。
Elasticsearch：适合大规模部署，搜索性能更好。

对于大多数场景，Database 搜索引擎已经足够。

七、Git 同步

Wiki.js 支持将所有页面内容同步到 Git 仓库，实现版本控制和异地备份。在管理面板 > Storage 中配置 Git 同步：

选择 "Git" 存储模块。
填入 Git 仓库 URL、分支名和认证信息。
设置同步间隔（默认 5 分钟）。
选择同步方向（双向、仅推送或仅拉取）。

八、用户认证

Wiki.js 支持多种认证方式，在管理面板 > Authentication 中配置：

本地认证：邮箱密码登录（默认启用）。
OAuth 2.0：GitHub、Google、GitLab 等。
LDAP：企业级目录服务集成。
SAML 2.0：企业单点登录。

九、权限管理

Wiki.js 提供细粒度的权限控制。在管理面板 > Groups 中创建用户组并分配权限：

按页面路径设置读写权限。
控制页面的创建、编辑、删除、发布操作。
设置 Guest（访客）组权限来控制公开内容。

十、主题与自定义

在管理面板 > Theme 中可以自定义 Wiki 的外观：

切换亮色/暗色主题。
自定义 CSS 样式。
添加自定义 JavaScript。
修改导航栏和侧边栏配置。

十一、数据备份

# 备份数据库
docker exec wikijs-db-1 pg_dump -U wikijs wikijs > /opt/wikijs/backup_$(date +%Y%m%d).sql

# 如果配置了 Git 同步，页面内容已自动备份到 Git 仓库

十二、常见问题

中文搜索不准确

PostgreSQL 的默认分词器对中文支持有限。可以安装 zhparser 扩展改善中文搜索效果，或使用 Elasticsearch 作为搜索后端。

上传文件大小限制

检查 Nginx 的 client_max_body_size 配置是否满足需求。

总结

Wiki.js 是一款部署简单、功能全面的知识管理平台，支持多种编辑模式和丰富的集成选项。相比 Outline 的配置复杂度更低，因为它支持本地用户认证，无需额外的 SSO 服务。更多知识管理工具请参考：BookStack 部署、Memos 笔记部署、Docker 安装教程。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的循环折扣。