Wiki.js 完整使用手册

一、平台介绍

Wiki.js 是基于 Node.js 开发、开源免费的现代化知识库/Wiki 系统，采用AGPL-v3 开源协议。官网地址为 https://js.wiki/，是目前全球主流自建文档知识库工具。GitHub 粉丝超 28400+，累计下载超 1 亿次。

1. 基础架构

• 开发架构：后端基于 Node.js，前端采用现代化 UI 设计。
• 部署环境：支持 Windows Server、macOS、Linux、K8s 及 Docker 多环境部署。
• 硬件兼容性：兼容树莓派小主机到云服务器全规格硬件。

2. 数据库兼容

系统支持五种主流数据库，用户可按需选型：

1. PostgreSQL
2. MySQL/MariaDB
3. SQL Server
4. SQLite
5. Microsoft Access

3. 产品定位

旨在替代传统 MediaWiki 或 Confluence，适用于：

• 企业知识库
• 项目文档
• 个人笔记
• 产品手册
• 轻量化私有化部署

二、核心主要功能

1. 多类型文档编辑器（内容创作）

Wiki.js 提供多种编辑器以适应不同场景：

• Markdown 编辑器适用场景：开发技术文档
• 特点：实时预览、快捷键支持、代码高亮，是主流开发者的首选。
• 可视化富文本（WYSIWYG）适用场景：非技术人员文案写作
• 特点：零代码操作，类 Word 拖拽编辑体验。
• 原生 HTML 编辑器适用场景：导入外部网页或存量 HTML 文档
• 特点：直接编写 HTML，适配现有网页内容。
• WikiText（待上线）适用场景：MediaWiki 系统迁移
• 特点：快速从维基系统迁移存量内容。
• API/表格编辑器（待上线）适用场景：接口文档、数据表编写
• 特点：类似 Excel 的表格编辑、REST/GraphQL 接口编写。

附加内容能力：

• 代码块语法高亮及行号显示。
• UML、流程图、时序图绘图功能。
• TeX 数学公式渲染支持。
• 音视频嵌入（支持 Youtube、asciinema 等）。
• 版本全追踪：页面修改留痕、版本对比、回滚历史版本、删除页面恢复、单页导出及基于旧版本新建页面。

2. 多渠道登录认证（权限管控）

系统提供完善的登录认证体系：

• 本地账号：支持内置注册、找回密码功能。
• 第三方社交登录：支持 GitHub、微软、谷歌、Facebook、Discord、Slack 等 OAuth 登录。
• 企业级登录：支持 LDAP、SAML、CAS、Azure AD、Okta、Auth0、通用 OIDC/OAuth2。
• 安全加固：所有登录方式均支持 2FA 双因素认证。

3. 精细化权限&分组管理

• 用户分组：支持批量分组管控权限，避免单用户逐个配置。
• 细粒度权限：控制页面编辑、附件上传、后台管理、页面访问等分级权限。
• 页面规则：通过路径前缀、后缀或正则表达式批量配置页面访问权限。
• 站点模式：支持全站公开、全私密、部分页面公开混合三种模式。

4. 多方式内容存储&备份

• Git 同步（核心）：文档自动同步/备份至 GitHub、GitLab、Bitbucket、Azure DevOps，依托 Git 进行版本兜底。
• 企业云盘：支持 AWS S3、Azure Blob、谷歌云存储。
• 个人云盘（待上线）：支持 OneDrive、Dropbox、谷歌网盘。
• 本地存储：支持本机磁盘、局域网共享盘、SSH 远程服务器备份。

5. 全文检索系统

• 内置数据库检索：开箱即用，适合小型站点。
• 外接搜索引擎：支持 Elasticsearch、Algolia 云搜、Azure 搜索、Solr、Manticore 等（适合中大型知识库）。

6. 国际化与页面多语言

• 系统界面：支持全球 40+ 语言，包括阿拉伯语等 RTL 从右向左排版语种。
• 文档多语种：单页面支持做多语言版本，一键切换同文档不同语种内容。

7. 自定义美化

• 主题模式：提供深浅两套主题（深色/浅色模式）。
• 自定义样式：后台可直接注入自定义 CSS、JS，自定义页面样式。
• 开发支持：支持开发自定义主题（功能后续完善）、自定义导航样式。

8. 资源资产管理

• 内置素材库：文件夹分类管理图片/附件。
• 引用追踪：查看素材被哪些页面引用。
• 编辑器功能：自带图片裁剪、调色编辑器（即将上线）。

三、适用人群&使用场景

1. 企业团队（最主流）

• 研发团队：编写接口文档、技术规范、运维手册、项目迭代文档。
• 行政/人事：管理公司制度、员工手册、规章制度、培训资料。
• 产品团队：撰写产品需求文档、版本说明、运营 SOP。
• 价值：替代付费 Confluence，低成本搭建内部知识库。

2. 开发者/个人用户

• 程序员自建：个人知识库、学习笔记、踩坑文档。
• 开源项目：用于开源项目官方文档站（大量开源项目使用 Wiki.js 做官网文档）。
• 极客玩家：树莓派本地自建私人知识库。

3. 社团/培训机构

• 管理机构课件库、社团规章、课程资料、学员手册。
• 服务于小众社群公开知识库。

4. 自媒体/内容创作者

• 搭建独立百科站点。
• 创建专栏知识库。

四、免费&付费详情

1. 开源授权规则（核心）

Wiki.js 主体永久免费开源，遵循 AGPL-v3 开源协议：

• 个人/非商用/内部自用：100% 完全免费。无功能阉割、无用户数限制、无页面上限。全部官方内置功能（权限、搜索、Git 备份、多登录、编辑器）免费开放。
• 商用二次修改分发：遵循 AGPLv3 协议。修改源码并对外提供服务时，需要开源修改后的代码。
• 官方无强制付费：无软件订阅费、无授权费。

2. 付费仅两种可选（非强制）

• 云托管服务：官方合作云厂商（DigitalOcean 等）提供一键托管部署，费用为云服务器租赁费，非 Wiki.js 软件费用。
• 商业技术支持：如需官方定制开发、7×24 运维服务、企业专属技术顾问，联系开发团队付费购买技术服务（可选，不用可不花钱）。
• 注意：模块、插件、主题全部官方原生免费，无付费功能锁。

五、快速使用（安装+上手步骤）

方式 1：Docker 一键部署（推荐新手，5 分钟启动）

1. 确保服务器预装 Docker 和 Docker Compose。
2. 拉取 Wiki.js 镜像 + 配套数据库（SQLite 最简单，无需额外安装数据库）。
3. bash

docker run -d -p 8080:3000 --name=wiki -e "DB_TYPE=sqlite" requarks/wiki:2
docker run -d -p 8080:3000 --name=wiki -e "DB_TYPE=sqlite" requarks/wiki:2

1. 浏览器访问 服务器 IP:8080，按初始化向导设置管理员账号、站点名称，完成安装。

方式 2：一键云主机（DigitalOcean marketplace）

• 在 DigitalOcean 云市场一键创建实例，系统自动装好 Wiki.js，开箱即用，仅付云服务器租金。

方式 3：原生手动部署（Linux/macOS）

1. 安装 Node.js 环境 + 对应数据库。
2. 下载 Wiki.js 源码，配置数据库连接配置文件。
3. 启动服务，浏览器初始化配置。

基础上手使用流程

1. 管理员初始化：登录后台→【设置 - 本地化】切换中文界面。
2. 配置登录：【模块 - 认证】开启本地/第三方登录（如 GitHub 快捷登录）。
3. 创建分组与权限：【用户&分组】新建用户组，配置页面读写权限。
4. 新建文档：首页创建页面，选择 Markdown/富文本编辑器编写内容。
5. 配置备份：【模块 - 存储】开启 Git 自动备份至 Github 仓库。
6. 开启搜索：小型站点用内置搜索，海量文档对接 Elasticsearch。

六、部署&日常使用避坑指南

（一）部署避坑

• 数据库选型踩坑10 人以内小团队：优先 SQLite，零配置。
• 50 人以上团队禁止 SQLite，并发访问会卡死，改用 PostgreSQL（官方推荐）或 MySQL。
• MySQL 需开启 InnoDB 引擎，避免 MyISAM 出现版本存储异常。
• 端口&防火墙默认端口 3000，服务器防火墙/安全组需放行对应端口。
• 反向代理 Nginx 后注意配置 websocket，否则后台实时预览失效。
• Docker 升级坑Docker 部署不要直接删除容器升级。
• 升级前需备份数据库 + Git 同步全量文档，新版本镜像数据库结构可能变动。

（二）功能配置避坑

• Git 自动备份配置使用 Git 存储时，仓库权限需配置成读写权限。
• 只读仓库无法自动提交文档，会导致备份失败。
• 定期核对仓库提交记录。
• 权限配置误区不要直接给普通用户管理员权限，优先分组配置。
• 页面正则规则慎用全匹配 /*，容易误锁全站。
• 第三方登录OAuth/GitHub 登录需在对应平台创建应用。
• 填写正确回调域名，域名错误无法跳转登录。

（三）日常运维避坑

• 素材存储大量图片附件不要全存在本地磁盘。
• 开启 S3/Git 附件存储，防止服务器磁盘爆满丢失素材。
• 版本丢失重要知识库务必开启 Git 双备份（本地 + 云端 Git 仓库），避免服务器硬盘损坏文档全丢。
• 搜索引擎文档超万页后停用内置数据库检索，改用 Elasticsearch，否则搜索卡顿超时。
• 升级系统大版本升级前（如 v2.x→v3）先全量备份数据库。
• 官方大版本偶尔存在配置不兼容问题。

（四）协议合规避坑

• 企业仅内部部署自用、不对外分发修改后的程序，不受 AGPLv3 开源约束。
• 若修改源码并对外提供 SaaS 服务，必须开源修改代码，避免版权纠纷。

七、补充拓展

1. 中文支持

• 系统内置简体中文。
• 后台 Locales 一键切换，无需额外汉化包。

2. 插件生态

• 原生 50+ 集成模块（登录/存储/搜索/编辑器）。
• 全部免费开关，按需启用。