Wizard 開源文件管理系統1.0釋出啦

mylxsw發表於2019-05-06

Wizard 是一款開源文件管理系統，專案地址為 github.com/mylxsw/wiza…。這個專案是 我 在2017年就開始開發的，起初只是想做一款能夠在公司內部把Swagger文件管理起來的工具，但在這近兩年的時間裡，一直斷斷續續的為其新增各種功能，現在終於下決心釋出1.0版本了，目前支援三種型別的文件管理

  • Markdown：也是Wizard最主要的文件型別，研發團隊日常工作中交流所採用的最常用文件型別，在 Wizard 中，對 Editor.md 專案進行了功能擴充套件，增加了文件模板，Json 轉表格，圖片貼上上傳等功能

    -w590

  • Swagger：支援 OpenAPI 3.0 規範，嵌入了 Swagger 官方的編輯器，通過定製開發，使其融入到 Wizard 專案當中，支援文件模板，全屏編輯，文件自動同步功能

    -w594

  • Table：這種文件型別是類似於 Excel 電子表格，採用了 x-spreadsheet 專案，將該專案嵌入到了 Wizard 中，目前還不是很完善

    -w592

目前主要包含以下功能

  • Swagger，Markdown，Table 型別的文件管理
  • 文件修改歷史管理
  • 文件修改差異對比
  • 使用者許可權管理
  • 專案分組管理
  • LDAP 統一身份認證
  • 文件搜尋，標籤搜尋
  • 閱讀模式
  • 文件評論
  • 訊息通知
  • 文件分享
  • 統計功能

如果想快速體驗一下Wizard的功能，有兩種方式

  • 線上體驗請訪問 wizard.aicode.cc/ ，目前只提供部分功能的體驗，功能預覽和使用說明請參考 Wiki。

  • 使用Docker來建立一個完整的Wizard服務

    進入專案的根目錄，執行 docker-compose up，就可以快速建立一個Wizard服務了，訪問地址 http://localhost:8080 。

起源

為了鼓勵大家寫開發文件，最開始我們選擇了 ShowDoc 專案來作為文件管理工具，當時團隊規模也非常的小，大家都是直接用 Markdown 寫一些簡單的開發文件。後來隨著團隊的壯大，前後端分離，團隊分工的細化，僅僅採用 Markdown 開始變得捉襟見肘，這時候，我們首先想到了使用開源界比較流行的 Swagger 來建立開發文件。但是 Swagger 文件多了，總得有個地方維護起來吧？

專案中的文件僅僅用Swagger也是不夠的，它只適應於API文件的管理，還有很多其它文件，比如設計文件，流程圖，架構文件，技術方案，資料庫變更等各種文件需要一起維護起來。因此，我決定利用業餘時間開發一款 支援 Markdown 和 Swagger 的文件管理工具，也就是 Wizard 專案了。

起初打算用 Go 語言來開發，但是沒過幾天發現使用 Golang 來做 Web 專案開發效率太低（快速開發效率，並非指效能，Golang做API介面開發還是很不錯的），很多常用的功能都需要自己去實現，遂放棄使用 Golang，轉而使用 PHP 的 Laravel 框架來開發。所以雖然專案建立的時間為 2017年7月27日，但是實際上真正開始的時間應該算是 2017年7月31日。

-w986

起初Wizard專案的想法比較簡單，只是用來將 Markdown 文件和 Swagger 文件放在一起，提供一個簡單的管理介面就足夠了，但是隨著在團隊中展開使用後，發現在企業中作為一款文件管理工具來說，只提供簡單的文件管理功能是不夠的，比如說許可權控制，文件修改歷史，文件搜尋，文件分類等功能需求不斷的被提出來，因此也促成了 Wizard 專案的功能越來越完善。

  • 使用者許可權管理 參考了 Gitlab 的許可權管理方式，在使用者的身份上只區分了 管理員 和 普通使用者，通過建立使用者組來對使用者的許可權進行細緻的管理，同時每個專案都支援單獨的為使用者賦予讀寫許可權。
  • 專案分組 在 Wizard 中，文件是以專案為單位進行組織的，剛開始的時候發現這樣是OK的，後來專案越來越多，專案分組功能應運而生，以目錄的形式來組織專案結構。
  • 文件修改歷史 每次對文件的修改，Wizard 都會記錄一個快照，避免錯誤的修改了文件而造成損失，可以通過文件歷史快速的恢復文件，對文件的修改，新增，刪除等關鍵操作都會記錄審計日誌，以最近活動的形式展示出來。
  • 文件差異對比 在團隊協助中，經常會出現很多人修改同一份文件，為了避免衝突，文件修改後，其它人在提交舊的歷史版本時，系統會提示使用者文件內容發生了變更，使用者可以通過文件比對功能找出文件中有哪些內容發生了修改。
  • 閱讀模式 當使用投影儀展示文件來過技術方案的時候，為了減少不必要的干擾，使用閱讀模式，只展示文件內容部分，提供更好的展示體驗。
  • 文件搜尋 通過搜尋功能快速查詢需要的文件，目前支援通過文件標題來搜素文件，後續會增加全文檢索功能。
  • LDAP支援 很多公司都會使用 LDAP 來統一的管理公司員工的賬號，員工的在公司內部的所有系統中都是用同一套帳號來登入各種系統比如 Jira，Wiki，Gitlab 等，Wizard 也提供了對 LDAP 的支援，只需要簡單的幾個配置，就可以快速的接入公司的統一帳號體系。
  • 文件附件，文件分享，統計，文件排序，模板管理，文件評論 ...

關於程式碼

專案採用了 Laravel 框架開發，目前版本已經升級到最新的 5.8（最開始為5.4，一路升級過來）。為了提高開發效率，保持架構的簡潔，在開發過程中，一直避免引入過多的外部元件，儘可能的利用 Laravel 提供的各種元件，比如 Authentication，Authorization，Events，Mail，Notifications 等，非常適合用來學習 Laravel 框架。

總結

如果你在為公司尋找一款開源免費的 開發文件/API文件管理 工具，不妨考慮一下 Wizard 專案，一定不會讓你失望的。如果你是一名 PHP 或者 Laravel 新手，想找個專案學習一下如何用 Laravel 做 Web 開發，這個專案更加不能錯過！

最後，也是本文最核心的部分，趕緊去 Star 一下，順便給我個 Star 啊 ！如果再能貢獻點 Issues 或者P R，那就更好啦 ?！

相關文章