詳解如何搭建一套知識管理工具

閱讀目錄

1、用互聯網思惟來看知識管理工具

2、工具選型

3、開始搭建這套工具

4、如何編譯運行

5、如何部署到服務器

6、如何自動部署到雲服務器

Github連接：

https://github.com/Jackson0714/BirdDoc   記得點個Star

1、用互聯網思惟來看知識管理工具

1.1 用戶故事

我是一名開發人員，常常會迷失在尋找團隊內的各類開發文檔中，我指望有一個網站，全部文檔都集中在這個網站中，我能夠進行根據目錄瀏覽，最好能支持搜索，並且我貢獻的文檔別人不知道，會再跑過來問我。

1.2 用戶痛點

（1）文檔存放位置雜亂

（2）搜索文檔困難

（3）文檔沒有目錄

（4）文檔普及度不高

1.3 產品團隊深挖用戶痛點

根據用戶的痛點，產品團隊設計了一個模型

（1）左側具備菜單導航欄

（2）頂部具備搜索欄

（3）能夠經過網站的形式訪問，方便用戶訪問

2、工具選型

這種團隊管理工具備不少，不少大廠出了軟件專門來作知識管理：

好比xx筆記企業版

這些大廠的軟件必須購買企業版才能在團隊內共享，且筆記很雜，不利於管理。並且根本就沒有解決用戶痛點。

最後選擇了vuePress來作，它的好處是能夠用markdown語言來作筆記，讓你專一於寫做，還能夠將筆記提交到gitlab進行管理，還有變動記錄，並且高度支持自定義主題等等。

因而咱們選擇了vuepress。官網連接：https://v0.vuepress.vuejs.org/zh/

官網也是用VuePress作的哦。但這個開源工具不是下載下來就能夠直接用的，還有些開發工做須要作。

另外有人提出怎麼不用GitBook ？

 GitBook 最大的問題在於當文件不少時，每次編輯後的從新加載時間長得使人沒法忍受。它的默認主題導航結構也比較有限制性，而且，主題系統也不是 Vue 驅動的。GitBook 背後的團隊現在也更專一於將其打造爲一個商業產品而不是開源工具。 -- 來源vuepress

3、開始搭建這套工具

3.1 方案一 按照官網搭建

快速上手

注意

請確保你的 Node.js 版本 >= 8。

全局安裝

若是你只是想嘗試一下 VuePress，你能夠全局安裝它：

# 安裝 yarn global add vuepress # 或者：npm install -g vuepress # 新建一個 markdown 文件 echo '# Hello VuePress!' > README.md # 開始寫做 vuepress dev . # 構建靜態文件 vuepress build . 

現有項目

若是你想在一個現有項目中使用 VuePress，同時想要在該項目中管理文檔，則應該將 VuePress 安裝爲本地依賴。做爲本地依賴安裝讓你可使用持續集成工具，或者一些其餘服務（好比 Netlify）來幫助你在每次提交代碼時自動部署。

# 將 VuePress 做爲一個本地依賴安裝 yarn add -D vuepress # 或者：npm install -D vuepress # 新建一個 docs 文件夾 mkdir docs # 新建一個 markdown 文件 echo '# Hello VuePress!' > docs/README.md # 開始寫做 npx vuepress dev docs 

WARNING

若是你的現有項目依賴了 webpack 3.x，推薦使用 Yarn 而不是 npm 來安裝 VuePress。由於在這種情形下，npm 會生成錯誤的依賴樹。

接着，在 package.json 里加一些腳本:

{    "scripts" : {      "docs:dev" :  "vuepress dev docs" ,      "docs:build" :  "vuepress build docs"    } }

而後就能夠開始寫做了:

yarn docs:dev # 或者：npm run docs:dev 

要生成靜態的 HTML 文件，運行：

yarn docs:build # 或者：npm run docs:build 

默認狀況下，文件將會被生成在 .vuepress/dist，固然，你也能夠經過 .vuepress/config.js 中的 dest 字段來修改，生成的文件能夠部署到任意的靜態文件服務器上，參考 部署 來了解更多。

這些步驟執行完後，只能看到搜索欄和標題，是沒有菜單的，須要本身建立菜單。

3.2 方案2、用個人demo搭建

3.2.2 如何建立菜單

上面只有搜索功能，沒有菜單功能。修改config文件定義菜單，而後加上菜單對應的文件夾。

3.2.2 下載demo

我已經有一份作好的demo供你們使用，該demo的功能：展現接口文檔，供第三方使用。功能以下圖。

github路徑：https://github.com/Jackson0714/BirdDoc

 

3.3.3 如何編寫文檔

好比想增長一個刪除優惠券的接口，能夠在coupon目錄下面建立一個delete.md文件

而後在config.js 文件配置菜單

4、如何編譯運行

若是已經安裝了node.js和npm，則在根目錄執行這條命令就能夠運行起來了

1

npm start

 這條命令其實就是執行npm vuepress dev來進行實時編譯

 編譯完成後，會提示監聽8080端口，能夠打開http://localhost:8080查看效果

 

5、如何部署到服務器

5.1 打包成靜態文件

npm run build

5.2 配置nginx和hosts

我是部署到ubuntu上的，須要建立nginx 配置文件

// 建立nginx配置文件<br>sudo vim /etc/nginx/conf.d/interface.conf // interface.conf server {      listen       8002;      server_name  birddoc.com;        location / {          root   /home/user/project/github/BirdDoc/public;          index  index.html index.htm;          try_files $uri $uri/ =404;      } } // 重啓nginx服務 sudo service nginx restart // 配置hosts文件，映射網站域名 sudo vim /etc/hosts localhost birddoc.com

5.3 打開站點

http://birddoc.com:8002/

6、如何自動部署到雲服務器

6.1 拉取代碼

git clone git@github.com:Jackson0714/BirdDoc.git

6.2 打包鏡像文件

npm run build<br><br>> kidsplace- interface @1.0.0 build /home/workspace/BirdDoc/BirdDoc > vuepress build       WAIT  Extracting site metadata... [9:59:39 AM] Compiling Client [9:59:39 AM] Compiling Server [9:59:45 AM] Compiled Server  in  6s [9:59:51 AM] Compiled Client  in  13s   WAIT  Rendering  static  HTML...     DONE  Success! Generated  static  files  in  public.<br><br>

生成靜態文件，路徑爲 /home/workspace/BirdDoc/BirdDoc/public

6.3 添加域名解析

在雲服務器控制檯 添加 birddoc.jay.club的域名解析，網站jay.club是我本身備案的網站。

等待10分鐘就生效了。

6.4 修改nginx配置文件

監聽經過birddoc.jay.club發來的請求，路由到靜態文件目錄 /home/workspace/BirdDoc/BirdDoc/public

server {      listen       80;      server_name  birddoc.jayh.club;        location / {          root   /home/workspace/BirdDoc/BirdDoc/public;          index  index.html index.htm;          try_files $uri $uri/ =404;      } }

 6.5 打開網站

http://birddoc.jayh.club

 

（臨時網站，後面可能會停掉。）

 6.6 如何用jenkins部署

參考我以前寫的文章：1. 容器化部署一套雲服務 第一講 Jenkins（Docker + Jenkins + Yii2 + 雲服務器)）

最後部署成功，控制檯輸出以下圖：

 

 

查看public目錄下這些文件

 6.7 如何自動部署

自動部署的方式不少

6.7.1 Jenkins 定時構建

6.7.2 Crontab定時構建

注意：該腳本還有些編譯問題未解決，僅供參考。

/home/job/build.sh   #!/bin/bash cd /home/workspace/BirdDoc/BirdDoc /usr/bin/git pull /usr/local/n/versions/node/10.15.3/bin/npm run build currentTime=$(date) echo $currentTime >> /home/job/build.log   crontab -e * * * * * sleep 0; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 5; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 10; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 15; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 20; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 25; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 30; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 35; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 40; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 45; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 55; /home/job/build.sh >> /home/job/cron.log 2>&1 &

6.7.3 Jenkins經過git提交代碼觸發構建

我配置了GitHub hook trigger for GITScm polling，但仍是沒有自動觸發。

後續再用docker run起來。

本文分享自微信公衆號 - 悟空聊架構（PassJava666）。
若有侵權，請聯繫 support@oschina.cn 刪除。
本文參與「OSC源創計劃」，歡迎正在閱讀的你也加入，一塊兒分享。