Dokuwiki 筆記

為什麼用 Dokuwiki?

(2014 年 3 月重寫)

雲端運算裡面， 一個最重要最簡單的應用就是 wiki。 邁入雲端第一步， 與其詢問 「該採購哪一種雲端產品呢?」 不如 改以 wiki 部份取代 word， 作為雲端版的文書工具。 要用哪一套 wiki 呢? 用 「wiki comparison」 可以搜尋到 WikiMatrix; 不過選擇多到爆... 例如 以太陽花為 logo 的 Mediawiki 大概是最熱門的 (Wikipedia 就是用它架的); 我個人則偏好既精簡又強大的 dokuwiki。 它不需要用到資料庫 (為什麼不用資料庫?) 也因此安裝特別簡單。 整個設計很模組化﹑ 很清爽﹑ 擴充性高 (2014 年 3 月已有一千多個擴充套件)。 也請搜尋 「dokuwiki review」 可看到很多正面評價。

以下是在 Antix 13.1 (Debian 系列) 底下的架站筆記。

安裝與初體驗

剛安裝好的 dokuwiki 畫面 請先以 root 的身份更新套件清單並安裝： apt-get update ; apt-get install dokuwiki 。 安裝過程會被問到要搭配哪個 web server。 如果你感到迷惘， 選預設的 apache2 就對了。 另外也會被問到未來的超級管理員帳號 admin 的密碼。 (回答兩次) 安裝成功之後， 打開瀏覽器， 檢查這個網址： http://localhost/dokuwiki/ 應該就會看到簡單的 [[start]] 畫面。 注意左下角的按鈕顯示 「Show pagesource」， 表示現在尚未登入的你， 只能閱讀頁面原始碼， 沒有足夠的權限可以編寫或建立 (這個其實尚不存在的) 頁面。

點選右下方的 「login」， 用剛才 admin 帳密登入， 就會看到頁面的左下角多了一小排字 「Logged in as: DokuWiki Administrator (admin)」 表示它認出你的身份。 也請注意左下角的按鈕變成 「Create this page」， 表示你有權限可以建立新頁面。 點下去、 在編輯畫面輸入一點歡迎詞、 按左下角的 Save。 你已在你的 wiki 裡建立第一頁， 叫做 「start」 (請看網址) 注意左下角的按鈕變成 「Edit this page」 -- 這個頁面已存在， 但若你高興， 可以繼續修改它。

請把 start 改成 xyz 或是 homework 等等隨便亂取的名字， 按 Enter。 左下角的按鈕再度變成 「Create this page」。 在任何 wiki 裡面， 通常如果你亂打一個不存在的網址， 系統就會跟你講 「This topic does not exist yet」 並且建議你按下 「Create this page」 的按鈕， 建立一個新的頁面。

請在 shell 底下檢視 /var/lib/dokuwiki/data/pages/start.txt 這個檔案的內容 -- 正好就是你剛剛透過 dokuwiki 頁面所建立的內容。 也就是說， 未來所有頁面的資料都會以純文字的方式存放在這個目錄底下。

基本設定

回到瀏覽器， 點一下下面中間的 「Admin」， 開始管理與設定你的 wiki。 (這就是 admin 的宿命啊!) 點一下 「Configuration Settings」。 注意畫面中間出現一片紫色的警告訊息， 大意是說無法更新 (update) 你的設定， 因為你的檔案的權限 (permissions) 設定不正確。

再度回到 shell 底下， ls -l /var/lib/dokuwiki/data/pages/ 看一下 start.txt 的擁有人是誰。 以我的系統而言， 是 www-data。 根據 官方文件 的解釋， 有一個目錄及四個檔案的權限或所有權需要修正一下。 先檢查原來的設定： cd /etc/dokuwiki ; ls -ldL . local.php users.auth.php acl.auth.php plugins.local.php 會看到其中有些目錄或檔案屬於 root， 所以 網頁伺服器 (webserver) apache2 無權更改它。 把它們指派給代表 apache2 的用戶 www-data ： chown www-data . local.php users.auth.php acl.auth.php plugins.local.php

又回到瀏覽器， 重新整理。 紫色的警告訊息不見了。 編輯 /etc/dokuwiki/htaccess 把原先被註解掉的指令全部打開 (刪除最前面的 "#")。

  1. 到 Interface language 欄位點選 zh-tw。
  2. 到 Use nice URLs 欄位點選 「.htaccess」。
  3. 在 Use slash as namespace separator in URLs 欄位旁邊打勾。

最後點下去左下角的 「Save」， 再點左上角的 「顯示頁面」， 不只訊息變成中文， 也請注意網址變乾淨了。

回到 shell 底下， ls -ltr 注意到 local.php 的更改時間就是剛剛。 檢視一下內容， 會看到剛剛的設定。 如果沒有網頁介面可以管理 dokuwiki 的時候， 可以直接編修這個文字檔。 完整的預設選項可以參考 dokuwiki.php 。 網頁介面底下， 每個選項的左上角那一小串英文代號， 就對應到 dokuwiki.php 裡面 conf 陣列的一個元素。

清爽的網址

Dokuwiki 有 "namespace" 的概念， 就是類似子目錄的概念， 方便頁面簡單分類歸檔。 (實際上 /var/lib/dokuwiki/data/pages/ 底下， 就是用目錄來實作 namespace。) 不過預設的路徑名稱有點醜， 長得像這樣: http://localhost/dokuwiki/doku.php?id=playground:abc:xyz 我們希望可以改用更清爽的網址， 像這樣: http://localhost/dokuwiki/playground/abc/xyz。 上一節的 「Use nice URLs」 選用 「Dokuwiki internal」 目的就是要啟動清爽網址的功能。 詳見 URL Rewriting 頁面的 「Apache」 的那一節。 至於上一節的 「Use slash as namespace separator in URLs」， 指的就是用 "/" 取代 ":" 作為子分類與上層分類名稱之間的分隔號。

開放給全世界使用!

到目前為止， 我們都在自己的機器測試。 若是從別的機器連線過來， 有可能會看到 "forbidden" 禁止存取的訊息。 這是因為 debian 系列， 的預設值只允許本他機存取。 所以要先將 /etc/dokuwiki/apache.conf 設定檔內的 "Allow from 127.0.0.0 localhost" 改成 "Allow from All" 並重新啟動網頁伺服器： service apache2 restart 這樣從別的機器才可看見我們的 dokuwiki。

新增用戶

一般公開的 wiki 都是讓用戶自行註冊。 沒有帳戶的訪客按下 「登入」 再按下 「註冊」 並填妥帳號/姓名/E-mail 之後， 就會從 E-mail 收到註冊成功通知及亂數產生的密碼。

但是如果你的機器沒有郵件伺服器 (隨身碟開機的情況下， 多半沒有) 那就只能靠超級管理員 admin 自己以手動的方式新增帳號。 進入 「管理選單」 裡面的 「帳號管理員」。 頁面下方的 「增加帳號」 裡面的前四個欄位 (帳號、 密碼、 真實姓名、 e-mail) 都必須填寫， 新增才會成功。

新增成功之後， 回到 shell 底下， 在 /var/lib/dokuwiki/acl/users.auth.php 裡面會看見多出一列這位新用戶的資料。 當然， 密碼已經被系統採用 one-way-hash 打亂過的， 所以 admin 只能幫忙改密碼， 無法偷窺用戶的真實密碼。 (採用哪個 one-way-hash 則是由管理選單當中 「密碼加密方式 passcrypt」 所指定的。)

萬一要是 admin 的密碼忘記了怎麼辦? 搜尋 「salted md5 linux command」 找到 這一頁。 把那一段 php 程式存檔， 比方叫做 chpwd.php 好了。 把 $password 變數的值改成你要的密碼， 再執行 php chpwd.php 產生 hash 過的密碼， 長得類似這樣： $1$7wtGfwgp$772bEQInetnJKUNtLM0Xt/。 或者也可以先安裝 libcrypt-passwdmd5-perl 套件， 然後下這一串指令 perl -M'Crypt::PasswdMD5 qw(unix_md5_crypt)' -e 'print unix_md5_crypt("Test11", "7wtGfwgp") . "\n"' 也會產生相同的字串。 (請將上面的 Test11 改成你的密碼； 7wtGfwgp 改成隨便的亂數字串。) 最後， 編輯 /etc/dokuwiki/users.auth.php 這個檔案， 找到 admin 那一列， 把第一跟第二個冒號之間的把那一長串 (內含三個 $ 號的) 字串改成上面 php 或 perl 指令所印出來的 (內含三個 $ 號的) 字串。

如果要一次新增很多用戶， 可以修改上述 php 或 perl 程式， 批次建立一個文字檔， 貼到 users.auth.php 裡面去。

權限管理

你的 dokuwiki 一旦開放給全世界使用， 就要開始煩惱： 要允許誰可以對你的 wiki 做哪些事? 通常會對陌生訪客開放 「讀」 的權限； 一般註冊用戶開放 「寫」 及 「新增頁面」 的權限； 然後註冊用戶越來越多、 你事業越做越大忙不過來， 就要開始找其中幾位好友幫你管理， 這時你必須開放許多權限給這些幫手管理團隊。

正好， dokuwiki 有所謂的 @ALL (所有人， 包含未註冊的陌生訪客)、 @user (已註冊的用戶)、 @admin (管理團隊) 等三個預設的群組 (groups)。 你可以在 「帳號管理員」 裡面把某些普通的 user 提升為 admin， 他就可以有很多權限幫忙管理 wiki。

也並不是所有頁面的權限都必須以一致的方式處理。 像我自己架的 wiki， 就會有某些頁面開放給任何陌生訪客隨意填寫。 到底哪些頁面要開放哪些權限給哪些人? 主管理選單裡面的 「管理存取控制表 (ACL)」 可以設定。 設定好之後， 請回 shell 查看一下 /var/lib/dokuwiki/acl/acl.auth.php 這個檔案的內容 -- 它會反應你剛才所做的修改。 第一個欄位指定 「哪些頁面」； 第二個欄位指定 「對誰」； 第三個欄位指定 「開放哪些權限」。 詳見 Access Control Lists。

外掛： 以防止機器人灌水的 Captcha 為例

Dokuwiki 的 CAPTCHA (防灌水/防垃圾留言機制) 開放給全世界註冊/填寫/上傳資料的網站， 一定要有防範灌水、 灌垃圾留言的措施。 這類措施稱為 CAPTCHA。 它主要是防範機器人大量惡意灌水； 如果是人工填寫垃圾留言當然擋不了， 不過至少可以提高垃圾留言者的時間成本， 讓他稍微節制一點。 Dokuwiki 本身並未內建 CAPTCHA； 但是有很多外掛套件 (plugins) 都提供這個功能。

搜尋 「dokuwiki captcha」 找到 CAPTCHA 外掛。 下載、 解壓縮、 把新產生的目錄 (splitbrain-dokuwiki-plugin-captcha-3d316e4/ 之類一長串的名稱) 搬到 /var/lib/dokuwiki/lib/plugins 底下， 同時改名為 captcha/ 。

回到瀏覽器， 重新進入主管理選單底下的 「系統配置設定」， 在這一頁搜尋 「captcha」 就可以開始設定防止機器人灌水的 captcha 。

如果沒有顯示 captcha 圖片， 請檢查 /var/log/apache2/error.log 如果裡面出現 "fatal error ... undefined function imagecreatetruecolor" 那麼請先安裝一個套件： apt-get install php5-gd 之後再重新整理網頁， 應該就 ok 了。

CAPTCHA 只是外掛套件的一個範例。 Dokuwiki 目前有一千多個 plugin。 你想要用， 但是 dokuwiki 所沒有的功能， 大概都可以透過 plugin 來補足。

[注意： chrome 用戶可能無法通過 captcha 認證。 我試過 firefox、 w3m-img、 dillo 都可以。 還沒研究如何解決。]

換裝

如果你只是想更改顏色與字型大小等等， 其實可以直接修改預設的 css 檔。 cd /var/lib/dokuwiki/lib/tpl/default 粗略研讀一下 design.css 發現有一些預設值可以改。 但不建議直接改 design.css ， 而是編輯 style.ini 。 例如請找到 __text__ 跟 __background__ 把它們的值改一下， 再重新整理網頁檢視效果。

如果你希望大幅度改變版面， 可以到 這一頁 下載一些網友做好的樣版。 建議點一下 "Last Update" 或 "Popularity"， 挑那些一兩年內曾修改過 (所以跟得上 dokuwiki 程式碼的變化)、 有一點人氣 (所以可能有中譯) 的樣版。

下載幾個樣版回來之後， cd /var/lib/dokuwiki/lib/tpl/ 然後解壓縮， 會多出幾個目錄。 回到瀏覽器， 重新進入管理畫面， 找到 「template」， 就可以選用新的樣版了。 記得按左下角的 「儲存」 才會生效。

* * * * *

討論本篇講議!