TechMiddlewareShowdoc

【Middleware】Showdoc部署及使用

,
Views: 1000000
Words: 1.4k Read time: 5 mins.

官网

github：https://github.com/star7th/showdoc

offical-website：https://www.showdoc.com.cn/

简介

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

Docker部署

1. 安装Docker

略

2. 创建数据存储目录

1
2
3
# 新增Showdoc数据存储目录并配置访问权限
mkdir -p /usr/local/showDoc/showdoc_data/html
chmod -R 777 /usr/local/showDoc/showdoc_data

3. 拉取Docker镜像

1
docker pull star7th/showdoc

4. 启动服务

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

服务访问

直接访问服务地址及端口，默认端口：4999。
访问界面截图：

使用

直接注册登录使用。注册强烈建议使用BIP账号。

注意事项

1. 服务器迁移

官方说明：https://www.showdoc.com.cn/help/2511252204165611

如何迁移

这里的迁移服务器，指的是：服务器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’);

常见误区

复制旧服务器文件过去后，忘记给可写权限
新服务器本身没有安装好环境，如缺少php-sqlite扩展等
直接用新代码覆盖旧代码，而不是按照官方推荐方式去做。
服务器转移数据的时候使用FTP。注意，如果使用FTP，应该用二进制模式传输，否则会破坏数据库文件

2. 数据库迁移

官方说明：https://www.showdoc.com.cn/help/31990

一些说明

mysql版本由于年久失修，已经放弃维护，官方不再保证能迁移成功。现在官方已在全力支持sqlite版本，请使用新版。另外如果你依然强制使用mysql，则可自行二次开发，但官方不提供支持，也请勿浪费时间问官方团队。经过二次开发的版本有可能与官方以后的版本升级冲突导致升级失败，请谨慎考虑

为什么要迁移数据库

如果你是早期使用mysql那部分的用户，可以考虑迁移数据库到Sqlite，否则以后无法再使用官方新增的任何功能。ShowDoc使用Sqlite的理由如下：

PHP环境默认支持Sqlite，所以只需要安装好PHP环境，即可使用ShowDoc，无须再安装mysql。这对于不懂mysql的开发者（如App开发者）来说会更容易一些。同时方便官方维护ShowDoc，不用维护和测试两个数据库版本

Sqlite的性能并不差，对于总项目数在一万以内的情况，基本不用考虑性能问题。所以完全足够普通公司或者团队的使用。

Sqlite数据库文件放在/Sqlite目录下，迁移和备份都十分简单，直接复制/转移该目录即可

如何迁移

备份所有代码和数据库

下载新代码：https://github.com/star7th/showdoc

将新代码中的/Sqlite/ 复制到旧目录(如果已存在/Sqlite则覆盖之)，并赋予/Sqlite/showdoc.db.php可写权限

复制新代码中的server/Application/Home/Controller/UpdateController.class.php 覆盖原来旧的相应文件。

在浏览器访问：http://xxxx.com/index.php?s=/home/update/toSqlite ，看到ok提示后，mysql的数据已经写入/Sqlite/showdoc.db.php

此时，除了/Sqlite/showdoc.db.php文件外，旧目录的其他所有文件全部用新下载的文件覆盖。注意清理runtime缓存以及保留原来文件夹权限的设定。具体哪些文件需要权限，可参考安装手册。

(•̀ᴗ•́)و ̑̑

Share