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)建文庫時配置文庫名稱及版本
使用方法
使用方法如下。
安裝 nodejs 及 PM2 管理工具。
-
下載 amWiki-服務器版 并拷貝到服務器(以下示例為放入
/usr/local/src/
目錄,為規(guī)范化 nodejs 模塊考慮,也可以放入 node_modules 目錄),并根據(jù)需要建立軟鏈接,如將程序啟動命令設置為amwiki2
:ln -s /usr/local/src/amWiki/bin/main.js /usr/local/bin/amwiki2
-
在服務器上創(chuàng)建 amWiki 項目目錄:
mkdir /data/wikis
-
切換至 amWiki 項目目錄,初始化目錄:
cd /data/wikis amwiki2 -i 我的 Wiki 文庫
根據(jù)需要配置 wikis.json 配置文件:
-name
- amWiki 項目名稱
-domain
- amWiki 項目服務端域名或地址(不配置則直接展示本地IP) -
創(chuàng)建新 Wiki 文庫:
amwiki2 create 我的知識庫1 amwiki2 create 我的知識庫2 V0.1
根據(jù)需要配置各個文庫的 config.json 配置文件,配置方法參閱config.json 配置。
-
編輯修改新文庫并更新:
amwiki2 update 我的知識庫1 amwiki2 update 我的知識庫2
-
使用 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 分支為例)。
Jenkins 配置
- 指定文庫服務器做構建服務器,并配置 git 倉庫(注意,需要先將構建服務器的公鑰 id_rsa.pub 添加到 git 項目的 key 中);
- 配置構建計劃(這里每5分鐘執(zhí)行一次檢查),并確認構建命令腳本
其中,腳本內容(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
- 本地編輯 wiki 文庫,并提交 git 倉庫,確認 Jenkins 執(zhí)行狀態(tài),如果構建成功刷新瀏覽器即可看到文庫的更新內容。