推薦個開源在線文檔，助道友領悟 Django 之 “道”

本文面向有手（需要一點點 Python Django 基礎）的小夥伴，急需文檔管理者食用最佳。

作者：HelloGitHub - 吱吱

嗷嗷待哺的小白：“今天又是沉迷花裏胡哨博客的一天，我希望歸檔一類知識或者是連載一些教程，而博客都是一篇篇散落的，沒有連貫性，閱讀體驗不太良好，怎麼辦呢？”

HelloGitHub：“那你可是問對人了，這期 《講解開源項目》 系列的新項目：MrDoc 覓道文檔，將會解決你的煩惱。”

小白：“這又是什麼神奇的開源工具。”

HelloGitHub：“這是一個基於 Django 開發的在線文檔系統，適合作爲個人和小型團隊的私有云文檔、雲筆記和知識管理工具。你看它界面簡潔，功能俱全，部署簡單。話不多說，直接開始實踐檢驗真理！”

一、簡單測試

HelloGitHub：“嘿嘿，先彆着急，我們先在本地平臺運行，測試測試功能，瞭解這個項目的基本使用，再一步步往前走。”

僅需 6 步你就可以從零運行起來這個項目！

1、我們本地的實驗環境是：

2、我們需要將開源項目克隆到本地，使用如下命令：

git clone https://github.com/zmister2016/MrDoc

3、爲 MrDoc 安裝好所需的第三方庫：進入 Mrdoc/ 目錄，運行如下命令：

4、初始化數據庫，該項目默認使用 sqlite 數據庫。在命令行下執行：

5、創建管理員賬戶，來管理整個 MrDoc 應用。注意用戶名和電子郵箱地址在整個 MrDoc 應用中是唯一的。

6、本地上線測試：在測試環境中，可以使用 Django 自帶的服務器運行 MrDoc。

二、食用說明

小白搓搓手，期待：“我也在本地測試成功了，是不是可以探索一番裏面的彩蛋呢？”

HelloGitHub：“好嘞，項目主打的關鍵字就是：個人團隊協作和文檔管理，讓我現在來給你展現一下五臟俱全的 MrDoc。”

2.1 註冊登錄

HelloGitHub：“當我們訪問網站的時候，以遊客身份進行的。假如我們需要註冊一個普通用戶的帳號，則需要填寫相應的表單信息，註冊完畢後會自動跳轉到已登錄界面。”

小白：“補充：其實如果遊客想點擊 新建 → 新建文檔，也是需要登錄操作的喲。”

2.2 文集文檔

HelloGitHub：“當我們登錄以後，可以在 新建 → 新建文集 中創建一個文集。”

小白：“我發現了，可以點擊首頁的文集，進入到文集的瀏覽閱讀頁面，還可以用 添加 新建一個文檔。在進入文檔編輯器頁面，我們可以 點擊文檔樹 選擇當前文檔對應的上級或者 取消上級，以及通過輸入 文檔排序值，來給不同文檔排序。”

HelloGitHub：“嗯吶，現在我們就不用擔心教程學習類的文章不連續啦，因爲他們都有層次順序的分佈在我們的文集中。不過因爲目前 MrDoc 最多支持 3 級的文檔，可別讓自己的文檔樹太大鴨。”

HelloGitHub：“非常重要的一點是團隊的共享和協作。我們普通用戶可以對自己的文集進行管理，點擊 個人中心 → 我的文集 → 文集管理 → 文集成員 處的 協作管理 小圖標，可以添加協作人。

而且在 文集管理 → 操作 → 文集設置 小圖標可以修改 基礎信息、權限配置 和 管理控制。當權限設置爲公開時，則當以遊客身份訪問網頁的時候能夠看到該文集；當權限設置爲私密，則只有自己能看到。當然也可以給固定的人看，這也就能實現了小團隊的共享。”

2.3 文檔編輯

HelloGitHub：“現在我們把目光投向 MrDoc 的文檔編輯和修改模塊，它支持以 Markdown 和富文本兩種方式進行文檔編寫，給我們提供了 3 種編輯器使用。它能支持插入數學公式、流程圖、序列圖、腦圖、Echarts 圖形圖表和時間線，能夠添加音視頻鏈接和圖片附件等，能夠創建文檔模板，總之是概括不完了，圖也上不完了，需要在使用過程中慢慢的熟練。”

小白：“我現在也看得懂了，在 個人中心 → 我的文檔 → 文檔管理 中可以統一管理創建的所有文檔，還可以看到 歷史版本管理 信息呢，方便了用戶進行對比，也方便了團隊協作的管理。”

2.4 後臺管理【管理員】

HelloGitHub：“大 boss 的權限必然是很高的，一切都收之眼底，包括用戶的文集、文檔、文檔模塊，還可以進行用戶管理和站點設置。”

小白：“那我就做自己的主宰好了。”

三、上線部署

HelloGitHub：“已經瞭解了一些功能了，但是隻在本地跑會不會太拉垮了，是不是得考慮將這個項目部署到我們的雲服務器上，讓自己的小團隊實現高大上的知識協作管理呀。”

小白：“可以和組裏的小夥伴多了一個摸魚工具，想想就很開心~”

HelloGitHub：“先部署好吧，誰知道過程中會出現一堆坑呢。爲了比較順利的進行，我們這次的方法就選用官方提供的比較完整的教程：使用 Nginx + uWSGI 部署 MrDoc。”

1、我們雲主機的環境是：

2、安裝 uWSGI 和 Nginx：

sudo apt-get install uwsgi
sudo apt install uwsgi-plugin-python3
sudo apt-get install nginx

3、將 MrDoc 的源碼拉取至本地（用之前的命令），但是爲了不對服務器上現存的環境造成影響，我們這次需要用到虛擬環境：

4、進入 MrDoc 文件夾，重複簡單測試的 3、4、5 步驟，分別實現依賴庫的安裝、初始化數據庫以及創建管理員賬號（略）。

5、我們在 ~ 目錄下新建一個名爲 mrdoc_deploy 的文件夾，命令如下所示，用於存放部署的相關文件。

mkdir /home/purple/mrdoc_deploy

(1) uWSGI 配置文件：

在 mrdoc_deploy 目錄下新建一個名爲 uwsgi_params 的文件，用 vim uwsgi_params 命令進行寫入：

uwsgi_param  QUERY_STRING       $query_string;
uwsgi_param  REQUEST_METHOD     $request_method;
uwsgi_param  CONTENT_TYPE       $content_type;
uwsgi_param  CONTENT_LENGTH     $content_length;
uwsgi_param  REQUEST_URI        $request_uri;
uwsgi_param  PATH_INFO          $document_uri;
uwsgi_param  DOCUMENT_ROOT      $document_root;
uwsgi_param  SERVER_PROTOCOL    $server_protocol;
uwsgi_param  REQUEST_SCHEME     $scheme;
uwsgi_param  HTTPS              $https if_not_empty;
uwsgi_param  REMOTE_ADDR        $remote_addr;
uwsgi_param  REMOTE_PORT        $remote_port;
uwsgi_param  SERVER_PORT        $server_port;
uwsgi_param  SERVER_NAME        $server_name;

在 mrdoc_deploy 目錄下新建一個名爲 mrdoc_uwsgi.ini 的文件，同理用 vim mrdoc_uwsgi.ini 寫入：

[uwsgi]

# Django-related settings
socket = :8008
# the base directory (full path)
chdir           = /home/purple/MrDoc
virtualenv = /home/purple/mrdoc_env
# Django s wsgi file
module          = MrDoc.wsgi:application
wsgi-file       = MrDoc/wsgi.py
# process-related settings
# master
master          = true

# maximum number of worker processes
processes       = 1
threads = 2
# ... with appropriate permissions - may be needed
# chmod-socket    = 664
# clear environment on exit
plugins = python3
vacuum = true
python-autoreload = 1

# buffer size
buffer-size = 65536

注：如果後續運行服務的時候出現如下問題，則需要調整 mrdoc_uwsgi.ini 下的 buffer-size 參數。

spawned uWSGI master process (pid: 21172)
spawned uWSGI worker 1 (pid: 21173, cores: 2)
invalid request block size: 21573 (max 4096)...skip
invalid request block size: 21573 (max 4096)...skip

(2) Nginx 配置文件

在 mrdoc_deploy 目錄下新建一個名爲 mrdoc_nginx.conf 的文件，使用命令 vim mrdoc_nginx.conf 寫入如下內容：

server {
    listen         80;
    server_name    此處填入域名;
    charset UTF-8;
    access_log      /var/log/nginx/mrdoc_access.log;
    error_log       /var/log/nginx/mrdoc_error.log;

    client_max_body_size 75M;

    location / {
        include /home/purple/mrdoc_deploy/uwsgi_params;
        uwsgi_pass 127.0.0.1:8008;
        uwsgi_read_timeout 60;
    }

    location /static {
        expires 30d;
        autoindex on;
        add_header Cache-Control private;
        alias /home/purple/MrDoc/static;
    }
    location /media  {
        alias /home/purple/MrDoc/media;
    }
}

注意在 server_name 參數中，需要填入自己的域名。此處我填的是雲主機的公網 IP 地址，之後訪問網站則需要輸入該 IP 地址。

(3) 爲了能讓 MrDoc 應用按我們的要求運行，使用 systemctl 工具來管理服務。

在 mrdoc_deploy 目錄下新建一個名爲 mrdoc.service 的文件，用命令 vim mrdoc.service 將如下內容寫入文件：

[Unit]
Description = MrdocApp
After = syslog.target

[Install]
WantedBy = multi-user.target

[Service]
WorkingDirectory = /home/purple/MrDoc
ExecStart = /usr/bin/uwsgi --ini /home/purple/mrdoc_deploy/mrdoc_uwsgi.ini
User = purple
Restart = always
StandardError = syslog~

6、添加進程管理

sudo systemctl enable /home/zmister/mrdoc_deploy/mrdoc.service

7、創建 Nginx 站點軟鏈接

sudo ln -s /home/zmister/mrdoc_deploy/mrdoc_nginx.conf /etc/nginx/sites-enabled/mrdoc_nginx.conf

8、啓動 MrDoc 服務

sudo systemctl start mrdoc.service

注意：當試圖啓動的時候，出現如下報錯。原因是：在配置 mrdoc.service 的時候 ExecStart 參數如果按照官方文檔寫的是 uwsgi，但實際上應該寫成絕對路徑（可以查看一下自己的路徑），我的是 /usr/bin/uwsgi。

(mrdoc_env) purple@VM-Purplezi-Ubuntu ~ % sudo systemctl start mrdoc.service
Failed to start mrdoc.service: Unit mrdoc.service is not loaded properly: Exec format error.
See system logs and 'systemctl status mrdoc.service' for details.

四、最後的最後

小白：“課代表來了，一句話總結，只需要在部署的時候費點勁，之後就可以體驗這個項目帶給我們的方便快捷了，有手即可。”

HelloGitHub：“在官方文檔中，其實還有一些功能沒有覆蓋到，比如說作者還提供了 MrDoc 瀏覽器擴展，有空記得去看看哇。記得要第一時間關注我們，我們將會不間斷正常運行爲您帶來有趣的開源項目分享。”

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/r_PGfwl5MTZCQVc87RF1ZA

猜你喜歡