搭建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
在宝塔内的系统防火墙和服务商防火墙放行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/htmlchmod -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端口，记得在服务商也要放行端口！
完成上述步骤后，访问 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/htmlchmod -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服务端需要更新到最新代码）
