1 Star 0 Fork 82

hanhongsuai / wizard

forked from mylxsw / wizard 
加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
Apache-2.0

Wizard 开源文档管理系统

GitHub All Releases Docker Pulls

概述

Wizard是一款开源文档管理系统,目前支持三种类型的文档管理

  • Markdown:也是Wizard最主要的文档类型,研发团队日常工作中交流所采用的最常用文档类型,在 Wizard 中,对 Editor.md 项目进行了功能扩展,增加了文档模板,Json 转表格,图片粘贴上传等功能
  • Swagger:支持 OpenAPI 3.0 规范,集成了 Swagger 官方的编辑器,支持文档模板,全屏编辑,文档自动同步功能
  • Table:这种文档类型是类似于 Excel 电子表格,集成了 x-spreadsheet 项目

在Wizard中,正在编辑的文档会定时自动保存到本地的 Local Storage 中,避免错误关闭页面而造成编辑内容丢失。

目前主要包含以下功能

如果想快速体验一下Wizard的功能,有两种方式

  • 在线体验请访问 http://wizard.aicode.cc/ ,目前只提供部分功能的体验,功能预览和使用说明请参考 Wiki

  • 使用Docker来创建一个完整的Wizard服务

    进入项目的根目录,执行 docker-compose up,就可以快速创建一个Wizard服务了,访问地址 http://localhost:8080

起源

为了鼓励大家在开发过程中写开发文档,最开始我们选择了 ShowDoc 项目来作为文档管理工具,当时团队规模也非常的小,大家都是直接用 Markdown 写一些简单的开发文档。后来随着团队的壮大,前后端分离,团队分工的细化,仅仅采用 Markdown 开始变得捉襟见肘,这时候,我们首先想到了使用开源界比较流行的 Swagger 来创建开发文档。但是 Swagger 文档多了,总得有个地方维护起来吧?

项目中的文档仅仅用Swagger也是不够的,它只适应于API文档的管理,还有很多其它文档,比如设计构想,流程图,架构文档,技术方案,数据库变更等各种文档需要一起维护起来。因此,我决定利用业余时间开发一款 集成 Markdown 和 Swagger 文档的管理工具,也就是 Wizard 项目了。

起初Wizard项目的想法比较简单,只是用来将 Markdown 文档和 Swagger 文档放在一起,提供一个简单的管理界面就足够了,但是随着在团队中展开使用后,发现在企业中作为一款文档管理工具来说,只提供简单的文档管理功能是不够的,比如说权限控制,文档修改历史,文档搜索,文档分类等功能需求不断的被提出来,因此也促成了 Wizard 项目的功能越来越完善。

  • 用户权限管理 参考了 Gitlab 的权限管理方式,在用户的身份上只区分了 管理员普通用户,通过创建用户组来对用户的权限进行细致的管理,同时每个项目都支持单独的为用户赋予读写权限。
  • 项目分组 在 Wizard 中,文档是以项目为单位进行组织的,刚开始的时候发现这样是OK的,后来项目越来越多,项目分组功能应运而生,以目录的形式来组织项目结构。
  • 文档修改历史 每次对文档的修改,Wizard 都会记录一个快照,避免错误的修改了文档而造成损失,可以通过文档历史快速的恢复文档,对文档的修改,新增,删除等关键操作都会记录审计日志,以最近活动的形式展示出来。
  • 文档差异对比 在团队协助中,经常会出现很多人修改同一份文档,为了避免冲突,文档修改后,其它人在提交旧的历史版本时,系统会提示用户文档内容发生了变更,用户可以通过文档比对功能找出文档中有哪些内容发生了修改。
  • 阅读模式 当使用投影仪展示文档来过技术方案的时候,为了减少不必要的干扰,使用阅读模式,只展示文档内容部分,提供更好的展示体验。
  • 文档搜索 通过搜索功能快速查找需要的文档,目前支持通过文档标题来搜素文档,后续会增加全文检索功能。
  • LDAP支持 很多公司都会使用 LDAP 来统一的管理公司员工的账号,员工的在公司内部的所有系统中都是用同一套帐号来登录各种系统比如 Jira,Wiki,Gitlab 等,Wizard 也提供了对 LDAP 的支持,只需要简单的几个配置,就可以快速的接入公司的统一帐号体系。
  • 文档附件文档分享统计文档排序模板管理文档评论 ...

功能演示

请查看项目的 Wiki 文档。

Wizard-功能预览图

关于代码

项目采用了 Laravel 开发框架开发,目前框架的版本已经升级到最新的 5.8(最开始为5.4,一路升级过来)。为了提高开发效率,保持架构的简洁,在开发过程中,一直避免引入过多的外部组件,尽可能的利用 Laravel 提供的各种组件,比如 AuthenticationAuthorizationEventsMailNotifications 等,非常适合Laravel新手利用该项目来学习Laravel开发框架。

安装

目前支持两种安装方式,如果你熟悉Docker,可以直接使用Docker容器的方式来运行该项目,这也是最简单的方式了。如果你没有使用Docker或者不知道什么是Docker,那么请直接参考手动安装部分。

通过 Docker 安装

详细安装方法参考 Docker Hub mylxsw/wizard

我们需要创建一个Dockerfile,在Dockerfile中添加环境配置,比如我采用了宿主机上安装的MySQL服务器,就有了下面的这段Dockerfile配置

FROM mylxsw/wizard:latest

# 数据库连接配置
# 这里可以根据需要添加其它的Env配置,可用选项参考项目的.env.example文件
ENV DB_CONNECTION=mysql
ENV DB_HOST=host.docker.internal
ENV DB_PORT=3306
ENV DB_DATABASE=wizard_2
ENV DB_USERNAME=wizard
ENV DB_PASSWORD=wizard
ENV WIZARD_NEED_ACTIVATE=false
# 访问地址,只有正确配置后,导出的 markdown 文档图片才能正常展示
ENV APP_URL=http://localhost:8080

# 文件上传存储目录
VOLUME /webroot/storage/app/public

RUN php artisan config:cache

执行构建

docker build -t my-wizard .

数据库初始化

docker run -it --rm --name my-wizard my-wizard php artisan migrate:install
docker run -it --rm --name my-wizard my-wizard php artisan migrate

运行

docker run -d --name my-wizard -p 8080:80  my-wizard

然后就可以通过 http://localhost:8080 访问 Wizard 了。

手动安装

手动安装方式需要先安装配置好PHP环境,建议采用 PHP-FPM/Nginx 的方式来运行,具体配置参考 环境依赖 部分。

环境依赖

以下组件的安装配置这里就不做详细展开,可以自行 百度/Google 安装方法。

  • PHP 7.2 + (需要启用以下扩展)
    • OpenSSL PHP Extension
    • PDO PHP Extension
    • Mbstring PHP Extension
    • Tokenizer PHP Extension
    • XML PHP Extension
    • Ctype PHP Extension
    • JSON PHP Extension
    • BCMath PHP Extension
    • LDAP PHP Extension
    • Zlib PHP Extension (PDF 导出功能需要用到)
  • composer.phar
  • MySQL 5.7 + / MariaDB (需要支持ARCHIVE存储引擎,MariaDB 10.0+ 默认没有启用参考 FAQ 3
  • Nginx
  • Git

PHP 运行环境的创建,可以参考这里 https://gist.github.com/mylxsw/4b7bbe81fb7f59714423f3284c867149

下载代码

推荐使用 git 来下载项目代码到服务器,我们假定将该项目放在服务器的 /data/webroot 目录

cd /data/webroot
git clone https://github.com/mylxsw/wizard.git
cd wizard

下载代码之后,使用 composer 安装项目依赖

composer install --prefer-dist --ignore-platform-reqs

composer 会在在项目目录中创建 vender 目录,其中包含了项目所依赖的所有第三方代码库。

你也可以直接到项目的 release 页面直接下载包含依赖的软件包。

配置

复制一份配置文件

cp .env.example .env

修改 .env 中的配置信息,比如 MySQL 连接信息,文件存储目录,项目网址等。

接下来创建数据库,提前在MySQL中创建好项目的数据库,然后在项目目录执行下面的命令

php artisan migrate:install
php artisan migrate

接下来配置文件上传目录

php artisan storage:link

执行该命令后会在 public 目录下创建 storage/app/public 目录的符号链接。

在Nginx中配置项目的访问地址

server {
    listen       80;
    server_name  wizard.example.com;
    root         /data/webroot/wizard/public;
    index        index.php;

    location / {
        index index.php index.html index.htm;
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ .*\.(gif|jpg|png|bmp|swf|js|css)$ {
        try_files $uri  =302;
    }
    
    location ~ .*\.php$ {
        # php-fpm 监听地址,这里用了socket方式
        fastcgi_pass  unix:/usr/local/php/var/run/php-cgi.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_index index.php;
        include fastcgi_params;
    }
}

升级

项目升级过程非常简单,只需要使用git拉取最新代码(git pull),然后执行下面的命令完成数据库迁移和依赖更新就OK了。

composer install --prefer-dist --ignore-platform-reqs
php artisan migrate

初始化

安装完成后,Wizard项目就可以通过浏览器访问了,接下来需要访问注册页面创建初始用户

http://项目地址/register

在系统中注册的第一个用户为默认管理员角色。

FAQ

  1. 如果在执行数据库迁移(php artisan migrate)的时候,报错 SQLSTATE[42000]: Syntax error or access violation: 1071 Specified key was too long; max key length is 767 bytes

    该错误是因为 MySQL 版本低于 5.7,在低版本的 MySQL 中会出现该问题。解决方案如下,二选一即可

    • .env 文件中添加配置项 DB_CHARSET=utf8DB_COLLATION=utf8_unicode_ci,添加之后再执行 php artisan migrate 命令(缺点是这样就不支持Emoji了)
    • 升级MySQL到 5.7
  2. 报错 SQLSTATE[HY000] [2054] The server requested authentication method unknown to the clientThe server requested authentication method unknown to the client [caching_sha2_password]

    因为Mariadb版本比较新,对应的MySQL版本在8.0之后也可能会有问题(默认认证方式修改为了caching_sha2_password),解决办法连接到数据库,修改一下密码的认证方式为 mysql_native_password

     ALTER USER 'USERNAME'@'HOSTNAME' IDENTIFIED WITH mysql_native_password BY 'PASSWORD';

    参考 Caching SHA-2 Pluggable Authentication

  3. 数据库使用 Mariadb 10.0+ 版本时,执行数据库迁移报错 Unknown storage engine 'ARCHIVE'

    操作日志存储用到了 ARCHIVE 存储引擎,Mariadb 10.0 版本之后默认是没有安装这个存储引擎的

    The ARCHIVE storage engine was installed by default until MariaDB 10.0. In MariaDB 10.1 and later, the storage engine's plugin will have to be installed.

    所以解决方案有下面这两种(推荐第一种

    1. 最简单的方式时在Mariadb中安装这个插件,只需要连接到Mariadb之后执行 INSTALL SONAME 'ha_archive'; 命令就可以了,不需要 重启数据库

    2. 第二种办法时不安装 ARCHIVE 存储引擎,修改 $WIZARD_HOME/database/migrations/2017_08_03_232417_create_operation_logs_table.php 文件的第 17 行,将$table->engine = 'ARCHIVE'; 注释掉(完成迁移之后记得改回去,避免以后使用 git pull 来升级系统产生冲突)

       Schema::create('wz_operation_logs', function (Blueprint $table) {
      -$table->engine = 'ARCHIVE';
      +// $table->engine = 'ARCHIVE';
       
       $table->increments('id');
  4. 默认上传文件大小限制为 2M,这个限制并不是 Wizard 自身的限制,而是运行环境的限制,如何提高上传文件大小限制呢?

    首先需要修改 PHP 的配置文件 php.ini,修改以下两行

    ; 上传文件大小限制
    upload_max_filesize = 100M
    ; 表单提交大小限制,必须大于 upload_max_filesize,或者可以设置为 0,不做任何限制
    post_max_size = 0

    然后,根据 web 服务器的不同进行修改

    • nginx: 在 nginx 配置中添加 client_max_body_size 120M; 来指定最大 body 大小,可以参考 docker-compose/nginx.conf 的配置
    • apache:修改 Wizard 目录 public/.htaccess 文件中 LimitRequestBody 0 选项的值即可,默认为0表示不限制(默认已经修改过)
  5. 导出 Markdown 文档后,图片地址错误,无法显示图片

    需要配置 APP_URL 环境变量参数,在 .env 文件中,修改 APP_URL 地址为当前访问 URL 地址即可。

Stargazers over time

Stargazers over time

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "{}" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright {yyyy} {name of copyright owner} Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

简介

Wizard是基于Laravel开发框架开发的一款开源项目(API)文档管理工具。 展开 收起
PHP
Apache-2.0
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
PHP
1
https://gitee.com/coolinmind/wizard.git
git@gitee.com:coolinmind/wizard.git
coolinmind
wizard
wizard
master

搜索帮助