方舟 · Ark

Appearance

Wiki.js 轻量级知识库部署指南 ​

1. 简介 ​

Wiki.js 是一款基于 Node.js、Vue.js 构架的现代化开源 Wiki 软件。它以界面美观、性能优异和强大的扩展性著称。

主要特点：

  • 现代化 UI：默认主题简洁美观，响应式设计，阅读体验极佳。
  • 多种编辑器：支持 Markdown, Visual Editor (所见即所得), Raw HTML 等多种编辑模式。
  • 存储灵活性：除了数据库，支持将内容双向同步到 Git 仓库 (GitHub/GitLab)，这是其最独特的功能之一。
  • 权限管理：细粒度的用户权限控制，支持 OAuth2/OIDC 登录集成。

2. 安装部署 ​

Wiki.js 官方强烈推荐使用 PostgreSQL 作为数据库（虽然支持 MySQL/SQLite，但 PostgreSQL 对新特性支持最好）。

2.1 Docker Compose 部署配置 ​

yaml
version: "3"
services:
  db:
    image: postgres:11-alpine
    environment:
      POSTGRES_DB: wiki
      POSTGRES_PASSWORD: wikijsrocks
      POSTGRES_USER: wikijs
    volumes:
      - db-data:/var/lib/postgresql/data
    restart: unless-stopped

  wiki:
    image: requarks/wiki:2
    depends_on:
      - db
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: wikijsrocks
      DB_NAME: wiki
    ports:
      - "3000:3000"
    restart: unless-stopped

volumes:
  db-data:

2.2 启动流程 ​

  1. 保存为 docker-compose.yml。
  2. 执行 docker-compose up -d。
  3. 访问 http://localhost:3000。
  4. 按照向导完成管理员账户设置。

3. 核心功能配置 ​

3.1 Git 存储同步 (Git Storage) ​

在后台 Storage 模块中，可以配置 Git 仓库同步。这是 Wiki.js 最强大的功能。

  • 双向同步：
    • Backup: Wiki 修改 -> Commit & Push 到 Git。
    • Restore/Sync: Git 修改 -> Pull & Update 到 Wiki。
  • 配置步骤：
    1. Target 选择 Git。
    2. Git Url: 仓库地址 (SSH 或 HTTPS)。
    3. Authentication: 推荐使用 SSH Private Key。将生成的公钥添加到 GitHub/GitLab 的 Deploy Keys 中。
    4. Branch: 指定分支 (如 main)。
    5. Sync Direction: 建议选择 Bidirectional (双向)。
    6. Sync Schedule: 设置自动同步间隔 (如 5m)。

3.2 搜索引擎 (Search Engine) ​

Wiki.js 支持多种搜索引擎，可在 Search 模块配置：

  • DB Search (默认)：基于数据库的基础搜索，中文支持一般，适合小规模使用。
  • Elasticsearch: 适合海量文档，支持全文检索和分词。
  • Algolia: 云端搜索服务，体验极佳，但需要注册账号和 API Key。

3.3 邮件服务 (Mail) ​

配置 SMTP 是找回密码和接收通知的前提。

  • 在 Mail 模块配置 SMTP Server (Host, Port, User, Pass)。
  • 如果是 Gmail/Outlook，可能需要生成应用专用密码。
  • 配置完成后，点击 Send Test Email 验证。

4. 权限与界面定制 ​

4.1 用户与权限 (Users & Groups) ​

Wiki.js 采用基于组 (Group) 的权限管理。

  1. 创建组：如 Editors, Viewers。
  2. 分配权限：
    • Page Rules: 控制哪些路径下的页面可以被读取、编辑、删除。例如允许 Editors 编辑 dev/* 下的所有文档。
    • System Permissions: 控制后台管理功能的访问权限。
  3. 分配用户：将用户添加到对应的组。

4.2 界面定制 (Theme) ​

在 Theme 模块中，可以：

  • Code Injection: 注入自定义 CSS 或 JS。
    • 例如：修改字体、隐藏特定元素、添加统计代码。
    • CSS 示例 (修改正文字体)：
      css
      body {
    font-family: "Segoe UI", "Microsoft YaHei", sans-serif !important;
}
  • Navigation: 自定义顶部导航栏和侧边栏链接。

5. 高级配置与性能优化 ​

5.1 性能调优 ​

随着文档数量增加，Wiki.js 可能需要更多资源。

  • Node.js 内存限制：在 Docker Compose 中设置 NODE_OPTIONS。
    yaml
    environment:
  - NODE_OPTIONS=--max-old-space-size=2048
  • 数据库连接池：如果并发高，适当增加 PostgreSQL 的 max_connections。

5.2 安全性增强 (Security) ​

  • 强制 HTTPS：在 SSL 模块中配置，或通过前置 Nginx 代理处理 HTTPS。
  • 私有 Wiki 模式：在 Guest 组中移除所有权限，强制用户登录后才能查看任何内容。
  • 2FA：建议管理员开启双因素认证。

6. 维护与故障排除 ​

6.1 Git 同步失败 ​

如果 Git 同步报错，通常是因为：

  1. SSH Key 权限问题：检查 Deploy Key 是否有 Write 权限。
  2. 冲突：Git 仓库中有非 Wiki.js 生成的冲突文件。
    • 解决：在 Storage 设置中点击 "Force Sync" (谨慎使用，可能会覆盖本地修改)，或者进入容器手动处理 git 仓库。

6.2 忘记管理员密码 ​

如果无法通过邮件找回，可以通过数据库重置。

  1. 进入数据库容器：
    bash
    docker exec -it wiki_db_1 psql -U wikijs wiki
  2. 将密码重置为 admin123 (Bcrypt Hash):
    sql
    UPDATE "users" SET "password" = '$2a$10$1.1.1.1.1.1.1.1.1.1.1.u1.1.1.1.1.1.1.1.1.1.1.1' WHERE "email" = 'admin@example.com';
    (注意：请替换为有效的 Bcrypt 哈希值)

6.3 备份策略 ​

虽然有了 Git 同步，但数据库备份依然重要（包含用户、配置、评论等非 Markdown 数据）。

  • 数据库备份：
    bash
    docker exec -t wiki_db_1 pg_dumpall -c -U wikijs > dump_`date +%d-%m-%Y"_"%H_%M_%S`.sql
  • 完整恢复：
    1. 恢复数据库 SQL。
    2. 重新拉取 Docker 容器。
    3. Git 内容会自动同步。

参考资料 ​

方舟 · Ark

Copyright © 2026-present WhatHappenin