搭建showdoc技术文档工具

教程采用宝塔+Docker的方式安装：

showdoc是什么？

ShowDoc是一个非常适合IT团队的在线API文档、技术文档工具。通过showdoc，你可以方便地使用markdown语法来书写出美观的API文档、数据字典文档、技术文档、在线excel文档等等。如果不想编辑markdown文档，你还可以利用showdoc的自动化能力，从程序注释中自动生成API文档，或者从搭配的RunApi客户端（类似postman的api调试工具）中一边调试接口、一边自动生成文档。通过分配项目成员和团队成员，你可以很方便地进行项目文档的权限管理和团队协作，也可以分享文档出去给朋友查看。ShowDoc还支持多平台客户端，有win客户端、mac客户端、ios、android等，更方便跨平台使用。目前超过100000+的互联网团队正在使用showdoc，包括知名公司内部的一些团队，比如腾讯、华为、百度、京东、字节跳动等等。更多内容可查看官方帮助文档

前端：Vue + ElementUI

后端：为了兼容低版本的php运行环境（兼容至5.3），使用的是保守的ThinkPHP3.2.3框架

数据库：showdoc自带文件型数据库（/Sqlite/showdoc.db.php)，不需要用户手动安装数据库

showdoc官方网站：https://www.showdoc.com.cn/

showdoc帮助文档：https://www.showdoc.com.cn/help/1385767280275683

1.安装Docker容器

宝塔环境LNMP or LAMP都可以

宝塔软件商店搜索：Docker

docke

在宝塔内的系统防火墙和服务商防火墙放行docker端口：5212

2.安装

官方docker安装教程：https://www.showdoc.com.cn/help/65610

基础安装

安装前请确保你的环境已经装好了docker服务

安装showdoc：

docker pull registry.cn-shenzhen.aliyuncs.com/star7th/showdoc
docker tag registry.cn-shenzhen.aliyuncs.com/star7th/showdoc:latest star7th/showdoc:latest 

数据：

#新建存放showdoc数据的目录：

mkdir -p /showdoc_data/html

chmod  -R 777 /showdoc_data

如果你是想把数据挂载到其他目录，比如说/data1，那么，可以在/data1目录下新建一个showdoc_data/目录，

然后在根目录的新建一个软链接/showdoc_data到/data1/showdoc_data

这样既能保持跟官方教程推荐的路径一致，又能达到自定义存储的目的.

启动：

#启动showdoc容器
docker run -d --name showdoc --user=root --privileged=true -p 4999:80 \
-v /showdoc_data/html:/var/www/html/ star7th/showdoc

根据以上命令操作的话，往后showdoc的数据都会存放在 /showdoc_data/html 目录下

放行端口：

showdoc使用4999端口访问，在宝塔-软件管理-系统防火墙，放行4999端口，记得在服务商也要放行端口！

放行4999端口

完成上述步骤后，访问 http://localhost:4999 就可以看到引导页

这里showdoc就已经部署成功了！

3.升级showdoc：

如何升级

这里的升级是针对上面docker安装方式的升级

备份：

rm -rf  /showdoc_data/html_bak

如果可以的话，命令中的html_bak还可以加上日期后缀，以便保留不同日期的多个备份

mv /showdoc_data/html  /showdoc_data/html_bak

新建准备存放新版代码的目录：

mkdir -p /showdoc_data/html

chmod  -R 777 /showdoc_data/html

删除旧容器：

docker stop showdoc && docker rm showdoc 

启动showdoc容器：

docker run -d --name showdoc --user=root --privileged=true -p 4999:80 \
-v /showdoc_data/html:/var/www/html/ star7th/showdoc

转移旧数据库：

\cp  -f  /showdoc_data/html_bak/Sqlite/showdoc.db.php 

转移旧附件数据：

\cp -r -f /showdoc_data/html_bak/Public/Uploads/. /showdoc_data/html/Public/Uploads

重新给权限：

chmod  -R 777 /showdoc_data/html

如果中途出错，请重命名原来的/showdoc_data/html_bak文件为/showdoc_data/html ，然后重启容器便可恢复。

4.备份数据：

备份：

备份/showdoc_data/html 目录即可。比如执行下面命令压缩存放

zip -r /showdoc_data/showdoc_bak.zip  /showdoc_data/html 
# 其中showdoc_bak.zip可以用日期后缀命名，以便多个备份。你也可以用定时任务来实现定时备份。

迁移：

这里的迁移服务器，指的是：服务器A已经安装好了showdoc， 然后现在要迁移到服务器B去。

首先参考教程，在新服务器上全新安装一个showdoc。推荐使用官方自动脚本或者docker方式安装。
假如你是官方自动脚本或者docker方式安装，那么数据将放在/showdoc_data/html下。复制旧服务器的Sqlite/showdoc.db.php，以及Public/Uploads/下的所有文件（如没有则可忽略之），覆盖到新showdoc目录的相应文件。覆盖后重新给这些文件可写权限.

（可选）如果原有文档里已经有上传的图片和附件，换新的域名的时候也许访问不了。可进入数据库把图片附件路径改一下。showdoc使用sqlite数据库。数据库文件是安装目录下的Sqlite/showdoc.db.php。你可以网络搜索如何在命令行中使用 sqlite数据库，或者使用SQLiteStudio等可视化工具。进入数据库后，执行update page set page_content = replace(page_content,’原始host’,’新host’); 和 update upload_file set real_url= replace(real_url,’原始host’,’新host’);

5.其他参考命令：

 docker stop showdoc # 停止容器
 docker restart showdoc #重启showdoc容器
 docker rm showdoc #删除showdoc容器
 docker rmi star7th/showdoc #删除showdoc镜像
 docker stop $(docker ps -a -q) ;docker rm $(docker ps -a -q) ; #停止并删除所有容器。危险命令，不懂勿用。
 docker rmi -f `docker images | grep showdoc| awk '{print $3}'` # 删除所有名字含有showdoc关键字的镜像

6.绑定域名：

这里绑定的域名是针对自动脚本或者docker安装showdoc的情况。在绑定域名之前，请确保你已经安装好了showdoc服务，确保能通过http://127.0.0.1:4999 正常访问showdoc并创建文档。假如showdoc服务本身未成功，绑定域名可能会出现一些未知问题。

绑定域名的核心思路是利用nginx转发请求到4999端口。假如你要绑定域名是 http://test.showdoc.com.cn ，则可以这样写nginx重定向规则：

server {
    listen       80;
    server_name  test.showdoc.com.cn;
    client_max_body_size 1000m;
    location ^~ / {
        proxy_pass http://127.0.0.1:4999/;
        proxy_redirect off;
        proxy_connect_timeout 90;
        proxy_send_timeout 90;
        proxy_read_timeout 90;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header http_user_agent $http_user_agent;
    }
}

假如你要安装到二级目录，如 http://test.showdoc.com.cn/showdoc/ ，则可以这样写：

server {
    listen       80;
    server_name  test.showdoc.com.cn;
    client_max_body_size 1000m;
    location ^~ /showdoc/ {
        proxy_pass http://127.0.0.1:4999/;
        proxy_redirect off;
        proxy_connect_timeout 90;
        proxy_send_timeout 90;
        proxy_read_timeout 90;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header http_user_agent $http_user_agent;
    }
    # /server/路径和后面的/Public/路径重写是为了兼容历史
    # 不设置这两条重写规则不影响showdoc主体使用，但可能图片和附件访问有问题。
    location ^~ /server/ {
        proxy_pass http://127.0.0.1:4999/server/;
        proxy_redirect off;
        proxy_connect_timeout 90;
        proxy_send_timeout 90;
        proxy_read_timeout 90;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header http_user_agent $http_user_agent;
    }

    location ^~ /Public/ {
        proxy_pass http://127.0.0.1:4999/Public/;
        proxy_redirect off;
        proxy_connect_timeout 90;
        proxy_send_timeout 90;
        proxy_read_timeout 90;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header http_user_agent $http_user_agent;
    }

}

7.客户端

ShowDoc官方提供了Mac客户端，Windows客户端，IOS版和Android

在这些版本中使用的是官方ShowDoc，你也可以把他们改成你的私有部署：

官方客户端下载地址：https://www.showdoc.com.cn/clients

Windows版：私有版用户请把地址改为私有部署的showdoc地址。你也可以稍后通过程序菜单”文件”-“修改服务器地址”来修改

Android：对于手机app，如果你正在使用 www.showdoc.com.cn ，则下载即可使用。如果你是使用私有版showdoc，则请登录手机app的时候，在页面右上角指定私有版showdoc的服务器地址（私有版showdoc服务端需要更新到最新代码）