使用 amWiki 搭建自動構建的輕量級知識庫平臺

Posted by WeYo. 轉載請注明出處:http://weyo.me/pages/techs/wikis-by-amwiki/

關于 amWiki

很早就想搭建一個足夠輕量方便易用的Wiki平臺用于個人和團隊的知識交互,由于預算有限,商業(yè)化的confluence只能暫時放棄,另外也不想花費太大精力去維護這個平臺,其他的各類開源免費的Wiki技術(比如mediawiki,dokuwiki 等等)也就不考慮了。尋覓良久,終于發(fā)現(xiàn)了一個有意思的項目:amWiki。

根據(jù)官網介紹,amWiki的優(yōu)點在于:

  • 文檔系統(tǒng)采用 markdown 語法
  • 不用數(shù)據(jù)庫,文檔使用 .md 格式保存本地文件
  • 無需服務端開發(fā),只需支持 http 靜態(tài)訪問網頁空間
  • 一鍵創(chuàng)建新的文庫
  • 自動更新文庫導航目錄
  • 支持多級目錄
  • 支持截圖直接粘帖為本地 png 并插入當前 markdown
  • 文檔web端自適應顯示,適合所有平臺
  • 支持接口文檔自動抓取內容生成簡單的ajax測試
  • 無需服務端的全文庫內容搜索與計分排序

以上加粗字體的內容是我最喜歡amWiki的特性。出于易維護性(i.e. lazy)的需要,不用維護數(shù)據(jù)庫直接使用md文件真的是碼農的福音。

定制 amWiki

特性

不過可惜的是,不知道是不是跟Github逐漸放棄Atom有關,原作者在發(fā)布1.2.1版本之后就不再更新了,我也不希望只在本地使用wiki,希望能發(fā)布成對外的服務,于是就自己搗鼓了幾天 nodejs 折騰出了服務器版本的amWiki(Github:https://github.com/weyo/amWiki)。

這個版本的amWiki支持這些特性:

  • 在服務器端直接發(fā)布 Wiki 服務,并可以通過PM2進行管理
  • 支持同時發(fā)布多個 Wiki 文庫(在首頁顯示列表)
  • 支持自定義配置服務器域名(或地址),以便在云計算平臺(以及需要映射實際地址的網絡場景)部署服務
  • 支持使用命令初始化 Wiki 文庫項目并自定義項目名稱
  • 支持創(chuàng)建文庫時配置文庫名稱及版本

使用方法

使用方法如下。

  1. 安裝 nodejs 及 PM2 管理工具。

  2. 下載 amWiki-服務器版 并拷貝到服務器(以下示例為放入 /usr/local/src/ 目錄,為規(guī)范化 nodejs 模塊考慮,也可以放入 node_modules 目錄),并根據(jù)需要建立軟鏈接,如將程序啟動命令設置為 amwiki2

    ln -s /usr/local/src/amWiki/bin/main.js /usr/local/bin/amwiki2
    
  3. 在服務器上創(chuàng)建 amWiki 項目目錄:

    mkdir /data/wikis
    
  4. 切換至 amWiki 項目目錄,初始化目錄:

    cd /data/wikis
    amwiki2 -i 我的 Wiki 文庫
    

    根據(jù)需要配置 wikis.json 配置文件:
    - name - amWiki 項目名稱
    - domain - amWiki 項目服務端域名或地址(不配置則直接展示本地IP)

  5. 創(chuàng)建新 Wiki 文庫:

    amwiki2 create 我的知識庫1
    amwiki2 create 我的知識庫2 V0.1
    

    根據(jù)需要配置各個文庫的 config.json 配置文件,配置方法參閱config.json 配置。

  6. 編輯修改新文庫并更新:

    amwiki2 update 我的知識庫1
    amwiki2 update 我的知識庫2
    
  7. 使用 PM2 啟動 amWiki 服務:

    pm2 start 'amwiki2 -s'
    

隨后,即可在瀏覽器中訪問文庫:http://<服務器IP>:5171/(端口可根據(jù)需要在步驟 7 中調整)。

最終形成的服務器端 amWiki 文庫目錄結構如下:

/data
├── jenkins
│   ├── scripts
│   │   ├── wikis_master.log
│   │   ├── wikis_master.sh
│   │   ├── wikis_branch1.log
│   │   └── wikis_branch1.sh
│   ├── slave.jar
│   └── workspace
│       ├── wikis-master
│       └── wikis-branch1
├── wikis
│   ├── README.md
│   ├── wikis.json
│   ├── 我的知識庫1
│   │   ├── amWiki
│   │   ├── config.json
│   │   ├── index.html
│   │   └── library
│   └── 我的知識庫2
│       ├── amWiki
│       ├── config.json
│       ├── index.html
│       └── library
└── wikis_bak
    ├── README.md
    ├── wikis.json
    ├── 我的知識庫1
    │   ├── amWiki
    │   ├── config.json
    │   ├── index.html
    │   └── library
    └── 我的知識庫2
        ├── amWiki
        ├── config.json
        ├── index.html
        └── library

配置 Jenkins 自動發(fā)布

為了便于 wiki 的更新維護,使用 git 和 jenkins 搭建了一套自動發(fā)布環(huán)境,通過 git 倉庫管理 md 格式的 wiki 文庫,可以在提交更新后自動在服務器端進行發(fā)布。

Git 倉庫管理模式

為了支持不同項目組維護不同的 wiki 文庫,有兩種方式,第一種方式是每一個 wiki 文庫分別建立不同的 git 倉庫,每個 git 倉庫對應一個 jenkins 任務;第二種方式是建立一個 git 倉庫,然后在不同的 git 分支分別管理不同的 wiki 文庫,并針對每一個分支分別建立獨立的 jenkins 任務,兩種方式各有優(yōu)劣,可根據(jù)需要選擇。

本地 Wiki 項目目錄

以下是一個建立好的 git 倉庫本地 wiki 目錄結構圖(本文均以 master 分支為例)。

本地 Wiki 目錄結構

Jenkins 配置

  1. 指定文庫服務器做構建服務器,并配置 git 倉庫(注意,需要先將構建服務器的公鑰 id_rsa.pub 添加到 git 項目的 key 中);
Jenkins配置1
  1. 配置構建計劃(這里每5分鐘執(zhí)行一次檢查),并確認構建命令腳本
Jenkins配置2

其中,腳本內容(wikis_master.sh)如下,供參考:

#! /bin/bash
rm -rf /data/wikis_bak/WeYo的知識庫/{library,config.json}
mv /data/wikis/WeYo的知識庫/{library,config.json} /data/wikis_bak/WeYo的知識庫
mv /data/wikis/wikis.json /data/wikis_bak
cp -r ./WeYo的知識庫/{library,config.json} /data/wikis/WeYo的知識庫
cp ./wikis.json /data/wikis
cd /data/wikis
# 防止windows gbk編碼與amwiki要求的utf-8編碼不同,需要做編碼轉換
convmv -f gbk -t utf8 -r --notest ./
amwiki2 -u WeYo的知識庫
exit 0
# END
  1. 本地編輯 wiki 文庫,并提交 git 倉庫,確認 Jenkins 執(zhí)行狀態(tài),如果構建成功刷新瀏覽器即可看到文庫的更新內容。
?著作權歸作者所有,轉載或內容合作請聯(lián)系作者
平臺聲明:文章內容(如有圖片或視頻亦包括在內)由作者上傳并發(fā)布,文章內容僅代表作者本人觀點,簡書系信息發(fā)布平臺,僅提供信息存儲服務。

推薦閱讀更多精彩內容