搭建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：** ```dockerfile 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端口，记得在服务商也要放行端口！  完成上述步骤后，访问 [http://localhost:4999](http://localhost:4999/) 就可以看到引导页   这里showdoc就已经部署成功了！ ## 3.升级showdoc： ### 如何升级 > 这里的升级是针对上面docker安装方式的升级 #### 备份： ``` rm -rf /showdoc_data/html_bak ``` 如果可以的话，命令中的html_bak还可以加上日期后缀，以便保留不同日期的多个备份 ``` mv /showdoc_data/html /showdoc_data/html_bak ``` #### 新建准备存放新版代码的目录： ```bash mkdir -p /showdoc_data/html ``` ``` chmod -R 777 /showdoc_data/html ``` #### 删除旧容器： ```bash docker stop showdoc && docker rm showdoc ``` #### 启动showdoc容器： ```bash 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 ``` #### 重新给权限： ```bash chmod -R 777 /showdoc_data/html ``` **如果中途出错，请重命名原来的/showdoc_data/html_bak文件为/showdoc_data/html ，然后重启容器便可恢复。** ## 4.备份数据： #### 备份： 备份/showdoc_data/html 目录即可。比如执行下面命令压缩存放 ```bash 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.其他参考命令： ```bash 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](http://127.0.0.1:4999/) 正常访问showdoc并创建文档。假如showdoc服务本身未成功，绑定域名可能会出现一些未知问题。 绑定域名的核心思路是利用nginx转发请求到4999端口。假如你要绑定域名是 [http://test.showdoc.com.cn](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服务端需要更新到最新代码） Loading... 搭建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：** ```dockerfile 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端口，记得在服务商也要放行端口！  完成上述步骤后，访问 [http://localhost:4999](http://localhost:4999/) 就可以看到引导页   这里showdoc就已经部署成功了！ ## 3.升级showdoc： ### 如何升级 > 这里的升级是针对上面docker安装方式的升级 #### 备份： ``` rm -rf /showdoc_data/html_bak ``` 如果可以的话，命令中的html_bak还可以加上日期后缀，以便保留不同日期的多个备份 ``` mv /showdoc_data/html /showdoc_data/html_bak ``` #### 新建准备存放新版代码的目录： ```bash mkdir -p /showdoc_data/html ``` ``` chmod -R 777 /showdoc_data/html ``` #### 删除旧容器： ```bash docker stop showdoc && docker rm showdoc ``` #### 启动showdoc容器： ```bash 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 ``` #### 重新给权限： ```bash chmod -R 777 /showdoc_data/html ``` **如果中途出错，请重命名原来的/showdoc_data/html_bak文件为/showdoc_data/html ，然后重启容器便可恢复。** ## 4.备份数据： #### 备份： 备份/showdoc_data/html 目录即可。比如执行下面命令压缩存放 ```bash 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.其他参考命令： ```bash 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](http://127.0.0.1:4999/) 正常访问showdoc并创建文档。假如showdoc服务本身未成功，绑定域名可能会出现一些未知问题。 绑定域名的核心思路是利用nginx转发请求到4999端口。假如你要绑定域名是 [http://test.showdoc.com.cn](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服务端需要更新到最新代码） 最后修改：2026 年 06 月 16 日 © 允许规范转载 打赏 赞赏作者 支付宝微信 赞 如果觉得我的文章对你有用，请随意赞赏
