部署 ShowDoc 到自己的服务器

一、部署到自己的服务器

• 环境要求

  PHP5.3以上版本、php-mbstring模块、php-pdo模块、mysql数据库

• 克隆或者下载代码：

  https://github.com/star7th/showdoc

• 导入数据库

  下载代码后，将根目录的showdoc.sql文件导入mysql数据库。（注意，需要创建本地 mysql 数据库，并将 showdoc.sql 脚本导入到数据库）

• 修改配置文件

  进入Application/Common/Conf/目录，编辑config.php文件，填写相应的数据库信息

• 目录权限

  请确保Application/Runtime 和Public/Uploads 有可写权限

• 错误排查

  部署时出错，请先确认是否按照上面步骤执行（例如说目录权限有没有）。然后进Application/Runtime/Log看一下日志，或清除下Application/Runtime/目录下所有文件（缓存来的）试试。再遇到无法解决的问题可联系我，联系方式有博客、github、邮件等。

• nginx下的重定向规则

  请参考：http://blog.star7th.com/2016/03/1969.html

二、Mac 下配置Apache+PHP 环境

1. Apache 常用命令：

• 开启Apache：sudo apachectl start
• 关闭Apache：sudo apachectl stop
• 重启Apache：sudo apachectl restart

在浏览器中输入localhost，如果出现如下默认的“It works!”界面，则表示Apache开启成功。

2. 开启PHP

在终端输入命令：

sudo vim /etc/apache2/httpd.conf

找到下面一行代码，去掉注释（删除前面的井号）。注意：这里是重点，不反注释这个，showdoc 文件夹无访问权限。

#LoadModule php7_module libexec/apache2/libphp7.so

mac下Apache的默认文件夹为
/Library/WebServer/Documents，在该目录下，将下载好的 showdoc 源码放入，命名文件夹为showdoc, 然后在浏览器中输入localhost/showdoc，即可访问本地搭建的 ShowDoc 服务了。

3. 修改Apache目录

当然也可以根据自己喜好修改项目根目录。修改方法为：

1. 打开终端，输入命令：sudo vim /etc/apache2/httpd.conf
2. 找到如下两处
　　DocumentRoot "/Library/WebServer/Documents"
　　<Directory "/Library/WebServer/Documents">
3. 将两处中引号中的目录替换为自定义的目录

完成以上三步后，重启Apache，将之前创建的index.php文件拷贝到自定义目录中，然后在浏览器中输入localhost，如果出现PHP的info页，则表示目录修改成功。

4. 权限问题

因为团队目前缺少一个文档管理的工具，所以最近一直在研究ShowDoc，无论是部署安装，还是编辑使用，ShowDoc非常容易上手，界面十分清爽简洁。

但是有一个方面希望可以加强，即文档与用户的管理方面
如果在团队中使用ShowDoc，会有如下几种应用策略：

策略一：开发团队共享一个ShowDoc公共账号，文档的编辑均由开发团队成员共同完成
优点：一个账号，无需管理账号；文档在一个公共账号共享与编辑，对文档能统一管理
缺点：一个账号拥有全部权限，文档可能随时被修改，虽然有版本，但没有版本比对，不知道改了什么，也不知道是哪个开发人员改了，更严重的是一旦有人将文档删除了，只能通过恢复备份库才能找回，文档安全性方面不好管理。

策略二：开发团队每位成员都拥有自己的ShowDoc账号，文档的编辑由各个开发团队在自己的账号中完成，然后通过分享链接或者二维码或者将其他人的账号加入项目成员当中来共享开发文档。
优点：文档归项目创建者所有，其他人没有权限删除文档，文档的安全性方面有了保障。
缺点：通过链接、二维码共享，需要其他人记住地址，不方便传播，将其他人员加入到项目成员，不利于某些全团队共享的文档的共享，且整个团队的文档无法统一进行管理。

策略三：在策略二的基础上，增加一个团队公共账号，每个人新建的文档项目需要将团队公共账号加入到项目成员中（只给只读权限）
优点：文档归项目创建者所有，其他人没有权限删除文档，文档的安全性方面有了保障，只要每位成员按照约定，将公共账号添加到项目成员中，团队可以有统一的文档中心。
缺点：需要创建者遵照约定，创建者可随时将公共账号的访问权限删除。

策略四：建一个管理员账号，所有文档先由管理员账号创建，具体由谁负责编写，只需将编辑权限赋予给谁即可，再建一个公共的只读权限账号，整个团队成员通过只读权限账号查看完整的文档。
优点：团队的文档可以统一管理，除了管理员账号其他人没有权限删除文档，文档的安全性方面有保障。
缺点：分配权限需要专人处理，且没新增一个账号都要添加一次，没有权限组的概念，比较麻烦。

在一些小团队中，可能策略一比较适合，但是在一些规模较大的团队中，会比较希望使用策略四，但目前这一块，类似于SVN那种分配权限组的方式，ShowDoc暂时不支持。

三、ShowDoc 版本升级

开始我部署的老版本，使用的是mysql数据库保存的信息，现在 ShowDoc 官方建议使用 sqlite，我按照官方文档更新了一下，感觉官方文档写得不是很清晰，这里总结一下。

全新安装（具体操作参考上面“全新安装”部分的文字）并初始化ShowDoc完毕后，进入之前备份的目录。将Sqlite/showdoc.db.php（这是原来的数据库文件），以及Public/Uploads/下的所有文件（这些是上传的图片。如没有图片则可忽略之），全部复制并覆盖到新showdoc目录的相应文件。覆盖后重新给这些文件可写权限。

覆盖文件后，用浏览器访问http://xxx.com/showdoc/index.php?s=/home/update/db （请将网址更改为你服务器域名或ip）。看到OK字样便证明成功升级.

以上为官方给的方法，这里有点让人读不太懂。实践后原来是这样的：

1. 在备份原来部署的 showdoc 项目。
2. 下载部署最新 showdoc 项目。
3. 将以前部署的  showdoc 项目文件夹下的 qlite/showdoc.db.php 以及 Public/Uploads/ 下的所有文件（这些是上传的图片。如没有图片则可忽略之），全部复制并覆盖到新 showdoc 目录的相应文件。覆盖后重新给这些文件可写权限。
4. 将 mysql 数据库中已有数据写入到新的 qlite 文件（showdoc.db.php），实现方法：修改新项目中 /showdoc/ThinkPHP/Library/Think/Db/Driver.class.php 文件，将 “数据库连接参数配置” 替换成自己以前的 mysql 数据库配置。此步至关重要，官方文档竟然没有说明！
5. 执行 [http://xxx.com/showdoc/index.php?s=/home/update/db](http://xxx.com/showdoc/index.php?s=/home/update/db) （请将网址更改为你服务器域名或ip）。看到 ok 字样便证明成功升级。perfect!

参考：

1. https://github.com/star7th/showdoc
2. showdoc 中文版教程
3. mac下配置Apache+PHP+MySQL环境
4. https://github.com/star7th/showdoc/issues/172