关于团队知识库的选择
git 笔记 docker Wiki.js
工作 工具
Publish Date:   2025-02-08
Update Date:   2025-02-08
Word Count:   5.2k
Read Times:   19 Min

1 背景与目标

随着高性能计算技术在工业仿真领域的快速发展，团队成员面临着日益复杂的技术挑战。为了提高工作效率、促进知识共享、减少重复劳动和提升技术水平，建立一个高效、易用、全面的团队知识库显得尤为重要。该知识库将成为团队知识积累、经验共享和技术创新的核心平台，确保团队在不断变化的技术环境中保持竞争力。

团队知识库的目标如下：

  • 知识存储与管理：高效存储和管理团队成员在项目中积累的技术知识、经验、解决方案、文档和工具。
  • 信息共享与传递：促进团队成员之间的知识共享，避免信息孤岛，提升团队的整体技术水平。
  • 技术支持与问题解决：提供对常见问题、挑战和技术难题的解决方案和最佳实践。
  • 培训与成长：为新成员提供系统的技术入门资料和学习资源，帮助团队成员快速提升专业能力。
  • 文档化工作流程：记录和规范团队的工作流程、项目管理规范和技术决策，为后续工作提供指导和参考。

2 需求分析

为满足团队的实际工作需求，知识库应具备以下功能：

2.1 核心功能

  • 技术文档管理
    • 版本控制、文档更新日志和权限管理。
    • 确保知识库中的文档和资料及时更新，并且成员可以方便地查看文档的历史版本。

  • 文档搜索与分类

    • 强大的全文搜索功能，能够快速定位到需要的技术文档和解决方案。
    • 分类清晰的目录结构，支持按主题、领域、项目等多维度进行浏览。

  • 权限管理

    • 根据团队成员的角色和权限设置不同的访问权限，保证敏感信息的安全性。
    • 支持不同级别的编辑和评论权限，以便团队成员能够参与到文档的完善和更新中。

  • 集成与兼容性

    • 支持多种格式的文档，如文本(Markdown)、图像、PDF、代码文件等，确保资料的多样性和可读性。

  • 数据备份与恢复

    • 设置定期的数据备份方案，防止数据丢失。
    • 提供应急数据恢复机制，确保系统故障时能够快速恢复。

  • 安全性与隐私保护

    • 数据本地储存
    • 公司内网访问

2.2 可选功能

  • 成员间交互

    • 支持评论、反馈和讨论功能，促进成员间的知识交流。
    • 提供书签、收藏夹等功能，帮助成员保存常用文档和知识点。

  • 数据库与存储

    • 使用高性能的数据库管理系统（如MySQL、PostgreSQL）来管理知识库中的文档数据。

  • 自动化更新与提醒

    • 系统可以自动提醒团队成员参与文档的更新和审阅工作，确保知识库内容的及时更新。
    • 定期发布知识库更新报告，向团队成员推送重要文档和技术内容。

3 几款知名知识库

3.1 Wiki.js

  • 功能特点：
    • 支持Markdown和富文本编辑器。
    • 提供多用户实时协作功能。
    • 支持多种备份存储方式和用户验证方式。
    • 提供灵活的权限管理。
    • 支持国际化和自定义主题。
  • 优点：
    • 开源免费，可自由部署和定制。
    • 界面简洁美观，易于使用。
    • 支持多种编辑器和插件扩展。
  • 缺点：
    • 部署和配置需要一定的技术基础。

3.2 Confluence

  • 功能特点：
    • 提供强大的文档管理和团队协作功能。
    • 支持丰富的插件和自定义功能。
    • 支持文档版本控制和搜索功能。
  • 优点：
    • 界面简洁直观，易于上手。
    • 与Jira等Atlassian产品无缝集成。
    • 功能强大，适合大型企业和复杂项目。
  • 缺点：
    • 价格较高，尤其是用户数量增加时。
    • 不支持私有部署。

3.3 Outline

  • 功能特点：
    • 支持Markdown语法和富文本编辑。
    • 支持团队协作和内容分享。
    • 提供即时搜索功能。
  • 优点：
    • 开源免费，可私有化部署。
    • 界面简洁，学习成本低。
  • 缺点：
    • 功能相对简单，部分高级功能有待完善。

3.4 DocMost

  • 功能特点：
    • 支持实时协作的富文本编辑器。
    • 支持表格、数学公式和注释。
    • 提供完善的权限管理系统。
  • 优点：
    • 开源免费，可自托管。
    • 界面简洁，类似Notion。
    • 支持Docker部署，便于安装。
  • 缺点：
    • 功能相对有限，不如其他软件丰富。
    • 层级目录管理功能缺失。

3.5 PingCode

  • 功能特点：
    • 支持多人实时在线协同编辑，信息实时保存同步。
    • 支持富文本编辑，支持插入图片、表格、思维导图等。
    • 支持页面级权限管控和安全能力。
    • 支持AI智能助手。
  • 优点：
    • 产品开箱即用，简单易上手。
    • 支持私有部署和定制化。
    • 国际信息安全体系认证，安全有保障。
  • 缺点：
    • 商软，且功能比较杂。
    • 用户没有数据的掌控权。

3.6 对比

功能/工具 Wiki.js Confluence Outline DocMost PingCode
开源性 开源免费 非开源，需付费 开源免费 开源免费 非开源，需付费
编辑器 Markdown、富文本 富文本编辑器 Markdown、富文本 富文本、Markdown 富文本、Markdown等
协作功能 多用户实时协作 多人协作编辑和审核 多人协作 多人实时协作 多人实时在线协同编辑
版本控制 支持 支持 不支持 不支持 支持
权限管理 灵活 强大 简单 完善 页面级权限管控
多语言支持 支持多种语言 支持多种语言 支持多种语言 支持多种语言 不支持多语言
集成能力 支持多种插件 与Atlassian生态系统集成 不支持集成 不支持集成 支持多种集成
部署方式 自行部署 云部署或本地部署 自行部署 自行部署 云部署或本地部署
学习曲线 中等 较高 低 低 中等
价格 免费 高 免费 免费 中等

4 总结

建立一个高效、全面的团队知识库将极大提升团队的技术水平和工作效率。通过系统的文档管理、技术分享和问题解决，知识库能够帮助团队成员在复杂的高性能计算和工业仿真项目中快速找到解决方案，减少重复劳动，推动技术创新和协作。

根据需求分析以及各产品的功能调研，最终选择Wiki.js作为使用的团队知识库，它支持上述所有需求且有较高的安全与灵活性，兼顾开源低成本的优势。

5 docker部署Wiki.js流程

  1. 新建文件夹，在其中建立docker-compose.yml文件如下； 
services:
  db:
    image:  abcfy2/zhparser:15-alpine
    environment:
      POSTGRES_DB: wiki
      POSTGRES_PASSWORD: wikijsrocks
      POSTGRES_USER: wikijs
    logging:
      driver: "none"
    restart: unless-stopped
    volumes:
      - ./db-data:/var/lib/postgresql/data

  wiki:
    image: ghcr.io/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
      OFFLINE_ACTIVE: 1
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./sideload:/wiki/data/sideload
      - ./config.yml:/wiki/config.yml

  1. 在文件夹中新建sideload文件夹，将https://github.com/requarks/wiki-localization中的内容下载到sideload文件夹内部；

  2. 在docker-compose.yml同级目录下建立config.yml如下（更多设置项参考官方example)：

port: 3000
bindIP: 0.0.0.0
db:
  type: $(DB_TYPE)
  host: '$(DB_HOST)'
  port: $(DB_PORT)
  user: '$(DB_USER)'
  pass: '$(DB_PASS)'
  db: $(DB_NAME)
  storage: $(DB_FILEPATH)
  ssl: $(DB_SSL)
ssl:
  enabled: $(SSL_ACTIVE)
  port: 3443
  provider: letsencrypt
  domain: $(LETSENCRYPT_DOMAIN)
  subscriberEmail: $(LETSENCRYPT_EMAIL)
logLevel: info
ha: $(HA_ACTIVE)
offline: $(OFFLINE_ACTIVE)

  1. 运行docker-compose up -d；

  2. 打开网页，进行初始化设置；

  3. 配置中文全文检索：

  • 进入db容器的终端，输入psql -U wikijs -d wiki（名字可能不一样）；
  • 输入如下命令： 
CREATE EXTENSION pg_trgm;
CREATE EXTENSION zhparser;
CREATE TEXT SEARCH CONFIGURATION pg_catalog.chinese_zh (PARSER = zhparser);
ALTER TEXT SEARCH CONFIGURATION chinese_zh ADD MAPPING FOR n,v,a,i,e,l WITH simple;
-- 忽略标点影响
ALTER ROLE wikijs SET zhparser.punctuation_ignore = ON;
-- 短词复合
ALTER ROLE wikijs SET zhparser.multi_short = ON;
-- 测试一下
select ts_debug('chinese_zh', '白垩纪是地球上海陆分布和生物界急剧变化、火山活动频繁的时代');

  1. wikijs中增加相应中文搜索选项：在/wiki/server/modules/search/postgres/definition.yml中增加- chinese_zh相应行；

  2. 重启wikijs容器，打开 wiki.js 管理 | 搜索引擎 | Database - PostgreSQL | Dictionary Language 选 chinese_zh，并重建索引。

  3. 关于导航栏中根目录按钮无法正确显示，可在主题中的正文html注入以下代码： 

<script>
const sidebarText = "（根目录）";
(() => {const updateElement = el => {if(el.innerHTML === '/ sidebar.root' || el.innerHTML === '/ (root)'){el.innerHTML = sidebarText; console.log("Element updated to:", el.innerHTML);}}; const checkElement = () => {const targetEl = document.querySelector("#app > div.v-application--wrap > nav > div.v-navigation-drawer__content > div > div > div > div:nth-child(1) > div.v-list.py-2.v-sheet.theme--dark.v-list--dense.primary > div:nth-child(1) > div.v-list-item__title"); if(targetEl){updateElement(targetEl);} requestAnimationFrame(checkElement);}; if(document.readyState === 'loading'){document.addEventListener('DOMContentLoaded', () => requestAnimationFrame(checkElement));} else {requestAnimationFrame(checkElement);})();
</script>}

6 部署注意事项

按照Wiki.js官网给出的docker安装流程(https://docs.requarks.io/install/docker)会出现问题，与上面的配置区别主要体现在offline设置和本地化文件的下载以及中文全文搜索的支持(zhparser是PostgreSQL的中文分词插件，安装后可以使PostgreSQL支持中文的全文检索)上，原配置文件如下： 

version: "3"
services:

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: wiki
      POSTGRES_PASSWORD: wikijsrocks
      POSTGRES_USER: wikijs
    logging:
      driver: "none"
    restart: unless-stopped
    volumes:
      - db-data:/var/lib/postgresql/data

  wiki:
    image: ghcr.io/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
    restart: unless-stopped
    ports:
      - "80:3000"

volumes:
  db-data:

关于问题的具体描述，可参考该讨论贴：https://github.com/requarks/wiki/discussions/5339

7 Wiki.js使用说明

7.1 基础

Wiki.js 是一个现代化的开源知识库系统，用于创建和管理文档、知识库或维基网站。以下是关于 Wiki.js 的界面布局和基本操作的详细介绍。

7.1.1 界面布局

以下是 Wiki.js 界面的主要组成部分：

  • 全局导航栏（Global Navigation）：这是一个持续显示在所有页面上的导航菜单，通常包含重要页面或外部链接。
  • 全局搜索（Global Search）：通过搜索快速找到页面。
  • 新建页面（Create New Page）：用于创建新页面。
  • 用户菜单（User Menu）：用户特定的操作，如查看个人资料、管理界面和注销。
  • 页面操作（Page Actions）：当前页面的操作列表，如编辑、移动、删除、历史记录等。
  • 页面路径（Breadcrumbs）：显示当前页面的完整路径，代表文件夹结构。
  • 目录（Table of Contents）：基于内容中的标题显示当前页面的各个部分。
  • 页面标签（Page Tags）：与当前页面关联的标签，点击标签可以查看相关页面。
  • 作者信息（Author）：显示页面最后修改的作者和日期。
  • 社交链接（Social Links）：用于分享或打印当前页面的链接。
  • 编辑页面 / 页面操作（Edit Page / Page Actions）：快速访问菜单，用于编辑或对当前页面执行其他操作。

7.1.2 基本用法

7.1.2.1 创建新页面

要创建新页面，请点击页面右上角的 新建页面（New Page） 按钮。会弹出对话框：

  1. 选择语言：选择要创建页面的语言（默认选择当前语言）。
  2. 输入页面路径： 路径应包含无空格（使用连字符代替）、无句点，且由 URL 安全字符组成。不要在路径末尾添加斜杠。
  3. 无需手动创建文件夹。只需输入完整的路径，文件夹将自动创建。例如，输入universe/planets/earth，将自动创建 universe 和 planets 子文件夹，earth则作为当前页面的实际文件名（页面的显示名称在后续title中设置）。
  4. 点击“选择”：继续下一步。

7.1.2.2 选择编辑器

创建新页面时，会弹出对话框：

Wiki.js 提供多种编辑器，具体取决于你想要编写的内容类型或个人偏好。开发者通常会选择 Markdown 编辑器，而非技术人员可能更喜欢可视化编辑器（Visual Editor）。

7.1.2.3 填写页面元数据

选择编辑器后，会弹出页面元数据对话框：

  1. 输入页面的 标题、描述 和 标签（路径之前填写过，此处可修改），并点击 “确定” 关闭对话框并开始编写内容。
  2. 之后可以随时通过点击页面右上角的 “页面” 按钮，返回页面元数据对话框。

7.1.2.4 保存页面

页面创建完成之前，你需要点击页面右上角的 “创建” 按钮。页面将被保存并渲染，之后你将自动被重定向到最终结果页面。如果需要继续编辑，只需点击编辑按钮即可。

7.2 文件夹与标签

7.2.1 文件夹结构

Wiki.js 并没有传统意义上的文件夹结构。无需创建文件夹即可创建新页面。相反，你可以直接在你选择的路径上创建页面。
例如，要创建路径为 /universe/planets/earth 的页面，你无需事先创建 universe 和 planets 文件夹。这些文件夹会根据页面路径自动推断。

这种系统提供了更大的灵活性，并减少了页面之间的依赖性。但这并不意味着你不能使用传统的文件夹系统。文件夹结构在创建和移动页面时仍然可用，唯一的区别是你无需手动管理文件夹，它们会根据页面路径自动推断。
每页顶部显示的导航栏也是根据路径自动生成的。

7.2.2 多级页面与引导页

  • 在创建多级页面时，你可能希望为每个虚拟文件夹创建一个引导页。 例如，如果你有一个路径为 /foo/bar 的页面，你应该创建一个路径为 /foo 的新页面。这样可以确保在 /foo/bar 页面上点击foo链接时，能够跳转到 /foo 页面。

  • 站点树导航模式中，每个层级的页面标题将从其对应的页面中获取。
    例如，创建以下页面：

  1. 路径为 /universe 的页面，标题为“The Universe”
  2. 路径为 /universe/planets 的页面，标题为“The Planets”
  3. 路径为 /universe/planets/earth 的页面，标题为“The Blue Marble”

将生成一个站点树，包含以下条目：

  • The Universe
    • The Planets
      • The Blue Marble

在“The Blue Marble”页面上，导航将类似于：

/ universe / planets / earth

每个链接分别对应上面创建的三个页面。

7.2.3 标签

  • 标签是分类页面和快速查找相关内容的绝佳方式。它们是使用复杂文件夹系统分类内容的更轻量级替代方案。标签是附加到页面上的简单标签。
    可以为一个页面添加多个标签。
  • 例如，对于关于城市 Montreal 的页面，你可以添加标签 cities、canada、north-america。这些标签随后可以用来快速找到该页面。通过浏览标签 canada 和 cities，页面 Montreal 将出现在结果中，因为这两个标签都存在于该页面上。
  • 可以随时向页面添加更多标签或从页面中移除标签。
  • 使用按标签浏览链接（位于搜索栏旁边，或在导航菜单中）查看 Wiki 中所有可用的标签列表。
  • 选择一个或多个标签，查看符合选择条件的页面列表。

7.3 页面

7.3.1 创建新页面

在 Wiki.js 中，有多种方法可以创建新页面：

  • 通过“新建页面”按钮：点击页面右上角的“新建页面”按钮。
  • 通过链接指向不存在的页面：点击一个指向不存在页面的链接，系统会提示你创建该页面。
  • 手动输入路径：在浏览器地址栏中直接输入页面路径。

7.3.2 编辑页面

要编辑已存在的页面，可以通过以下方式：

  • 点击页面右下角的 铅笔图标。
  • 使用页面右上角的 页面菜单。
  • 创建页面时选择的编辑器将自动加载。注意：目前一旦页面创建完成，将无法更改编辑器。

7.3.3 页面路径与文件夹结构

  • Wiki.js 不依赖传统的文件夹结构来组织页面，而是使用页面路径来实现。
  • 例如，在传统的系统中，要创建路径为universe/planets/earth 的页面，你需要先创建一个名为 universe 的文件夹，然后在该文件夹中创建一个名为 planets 的子文件夹，最后在子文件夹中创建名为 earth 的页面。
  • 而在 Wiki.js 中，你可以直接创建路径为 universe/planets/earth 的页面。universe 和 planets 文件夹将被自动推断，但它们实际上并不存在于页面路径之外的上下文中。因此，你无需管理文件夹，只需专注于你想要的页面路径即可。
  • 基于这个原因，Wiki.js 没有提供创建文件夹的选项。只需输入完整的路径，文件夹将在创建时自动推断。

7.3.4 保留路径和限制

以下路径被保留用于系统使用，不能用于内容创建：

  • 单字符路径：用于访问 Wiki 的不同部分，例如：

    a：管理区域
c：评论
e：页面编辑器
f：资源管理器
h：页面历史
i：按 ID 浏览页面
p：用户个人资料
s：页面源代码
t：标签
u：上传端点（API）
w：个人 Wiki

  • 语言标签：用于指定使用的语言区域，例如：

    两位语言代码（如 en、fr）
国家特定的语言代码（如 en-us、fr-ca）

  • 其他系统使用的路径：

    _assets
favicon [ .ico ]
graphql
healthz
home（保留用于根主页）
login
logout
register
browserconfig [ .xml ]
css
favicon [ .ico ]
favicons
fonts
graphql
healthz
home（保留用于根主页）
img
js
login
logout
manifest [ .json ]
register
svg

7.3.5 路径命名规则

页面路径不能包含以下字符：

  • 空格（使用连字符代替）
  • 句点（保留用于文件扩展名）
  • 不安全的 URL 字符（如标点符号、引号、数学符号等）

7.4 媒体资源

在 Wiki.js 中，媒体资源（如图片、文档、压缩文件等）可以通过资源管理器进行管理和插入。以下是详细的操作指南。

7.4.1 打开资源管理器

所有编辑器都提供了一个按钮，用于打开资源管理器对话框。具体操作可以参考每种编辑器的文档。

7.4.2 创建文件夹

  • 点击资源管理器对话框顶部的 “New Folder” 按钮。
  • 输入一个符合以下命名规则的新文件夹名称：
    • 禁止使用空格。
    • 禁止使用大写拉丁字母。
    • 禁止使用特殊字符，除了连字符-和下划线_。
    • 文件夹名称至少需要 2 个字符。
    • 不能仅由拉丁字母（A-Z）组成，且不能符合 ZZ 或 ZZ-ZZ 的模式（这些模式被保留用于语言区域）。
    • 不能以特殊字符开头或结尾。

7.4.3 上传资源

  • 支持的文件类型：资源可以是任何类型的文件，包括图片、文档、ZIP 文件等。
  • 图片显示：图片文件会自动以图片形式显示，而其他文件类型则会显示为标准链接。
  • 上传操作：
    • 点击 “Browse…” 按钮，或者点击灰色区域，或者直接将文件拖拽到灰色区域。
    • 准备好后，点击 “Upload” 按钮开始上传所有文件。

7.4.4 插入资源

  • 选择你想要插入的资源，然后点击 “Insert” 按钮。
  • 如果插入的是图片，还可以通过 “Image Alignment” 下拉菜单（位于对话框右侧）设置图片的对齐方式：
    • Left：页面左侧对齐。
    • Centered：页面居中对齐。
    • Right：页面右侧对齐。
    • Absolute Top Right：作为页面右上角的徽标显示。

7.4.5 管理资源

对于已上传的资源，你可以执行以下操作：

  • 重命名、删除 或 编辑 资源。
  • 点击资源列表项右侧的 … 按钮，会出现一个下拉菜单，列出所有可能的操作。
Author: zcp
Link: https://chengpengzhao.com/2025-02-08-guan-yu-tuan-dui-zhi-shi-ku-de-xuan-ze/
Reprint policy: All articles in this blog are used except for special statements CC BY 4.0 reprint polocy. If reproduced, please indicate source zcp !
git 笔记 docker Wiki.js
赏
评论
 Current
关于团队知识库的选择
1 背景与目标随着高性能计算技术在工业仿真领域的快速发展，团队成员面临着日益复杂的技术挑战。为了提高工作效率、促进知识共享、减少重复劳动和提升技术水平，建立一个高效、易用、全面的团队知识库显得尤为重要。该知识库将成为团队知识积累、
2025-02-08 工作 工具
git 笔记 docker Wiki.js
Next 
2024年总结--没想到合适的标题
1 2024年总结依照惯例，看看2024年自己的时间都花在哪了吧： 回顾一下我的时间分类： 睡眠，毕竟人类的一生有$\frac{1}{3}$的时间都在睡觉 消费时间，指我们每天的日常工作（或学业），为了获取报酬所花的时
2025-02-02 生活 杂感
atimelogger
  TOC