部署 ShowDoc 文档工具

1）ShowDoc 介绍

1.1）ShowDoc 简介

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

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

Showdoc 是一款在线文档工具，支持 Markdown 语法，可以用于快速记录、分享和协作文档。它拥有简洁的界面和丰富的功能，包括在线编辑、多人协作、讨论评论、版本管理、权限管理等特性。

1.2）ShowDoc 功能

• 分享与导出：响应式网页设计，可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成 Word 文件，以便离线浏览。
• 权限管理：公开项目与私密项目、项目转让、项目成员、团队管理。
• 编辑功能： Markdown 编辑、模板插入、历史版本。
• 多平台：ShowDoc 支持网页版、手机 app 版和电脑客户端版。
• 自动化：可从代码注释中自动生成文档、搭配的 RunApi 客户端，可调试接口和自动生成文档。
• 快速部署：可使用使用开源版本 ShowDoc，快速在本地服务器部署 ShowDoc。

2）本地环境介绍

2.1）本地环境规划

本次实践为个人测试环境，服务器操作系统版本为 CentOS7.6。

hostname	IP地址	操作系统版本	内核版本
BLOG	10.0.59.114	CentOS7.6	3.10.0-957.el7.x86_64

2.2）本次实践介绍

1. 本次实践部署环境为个人测试环境；
2. 在 CentOS7.6 环境下安装 ShowDoc 文档工具。

3）检查本地环境

3.1）检查本地操作系统版本

检查本地操作系统版本

cat /etc/redhat-release

3.2）检查系统内核版本

检查系统内核版本

uname -r

3.3）检查本地 Yum 仓库状态

• 配置公网镜像源

mkdir /etc/yum.repos.d/backup
mv /etc/yum.repos.d/*.repo /etc/yum.repos.d/backup

cat > /etc/yum.repos.d/base.repo <<EOF
[base]
name=base
baseurl=https://mirrors.aliyun.com/centos/\$releasever/os/\$basearch/ 
        https://mirrors.huaweicloud.com/centos/\$releasever/os/\$basearch/ 
        https://mirrors.cloud.tencent.com/centos/\$releasever/os/\$basearch/
        https://mirrors.tuna.tsinghua.edu.cn/centos/\$releasever/os/\$basearch/
        http://mirrors.163.com/centos/\$releasever/os/\$basearch/
        http://mirrors.sohu.com/centos/\$releasever/os/\$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-\$releasever

[epel]
name=epel
baseurl=https://mirrors.aliyun.com/epel/\$releasever/\$basearch/
        https://mirrors.huaweicloud.com/epel/\$releasever/\$basearch/
        https://mirrors.cloud.tencent.com/epel/\$releasever/\$basearch/
        https://mirrors.tuna.tsinghua.edu.cn/epel/\$releasever/\$basearch/
gpgcheck=1
gpgkey=https://mirrors.aliyun.com/epel/RPM-GPG-KEY-EPEL-\$releasever

[extras]
name=extras
baseurl=https://mirrors.aliyun.com/centos/\$releasever/extras/\$basearch/
        https://mirrors.huaweicloud.com/centos/\$releasever/extras/\$basearch/
        https://mirrors.cloud.tencent.com/centos/\$releasever/extras/\$basearch/
        https://mirrors.tuna.tsinghua.edu.cn/centos/\$releasever/extras/\$basearch/
        http://mirrors.163.com/centos/\$releasever/extras/\$basearch/
        http://mirrors.sohu.com/centos/\$releasever/extras/\$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-\$releasever

[updates]
name=updates
baseurl=https://mirrors.aliyun.com/centos/\$releasever/updates/\$basearch/
        https://mirrors.huaweicloud.com/centos/\$releasever/updates/\$basearch/
        https://mirrors.cloud.tencent.com/centos/\$releasever/updates/\$basearch/
        https://mirrors.tuna.tsinghua.edu.cn/centos/\$releasever/updates/\$basearch/
        http://mirrors.163.com/centos/\$releasever/updates/\$basearch/
        http://mirrors.sohu.com/centos/\$releasever/updates/\$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-\$releasever

[centosplus]
name=centosplus
baseurl=https://mirrors.aliyun.com/centos/\$releasever/centosplus/\$basearch/
        https://mirrors.huaweicloud.com/centos/\$releasever/centosplus/\$basearch/
        https://mirrors.cloud.tencent.com/centos/\$releasever/centosplus/\$basearch/
        https://mirrors.tuna.tsinghua.edu.cn/centos/\$releasever/centosplus/\$basearch/
        http://mirrors.163.com/centos/\$releasever/centosplus/\$basearch/
        http://mirrors.sohu.com/centos/\$releasever/centosplus/\$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-\$releasever
EOF

yum clean all
yum repolist

检查本地 yum 仓库状态

yum repolist all | grep  enable

4）安装 httpd 服务

4.1）安装 httpd

使用 yum 安装 httpd

yum -y install httpd

4.2）启动 httpd 服务

启动 httpd 服务并使开机自启

systemctl enable --now httpd

检查 httpd 服务状态

systemctl status httpd

4.3）设置防火墙和 SELinux

防火墙设置，关闭防火墙。

systemctl stop firewalld && systemctl disable firewalld

防火墙设置，当需要开启防火墙的时候，可以放行 80 端口。

firewall-cmd --zone=public  --permanent --add-port=80/tcp
firewall-cmd --reload

关闭 SELinux

setenforce 0
sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config
getenforce

4.4）测试httpd服务

在本地浏览器，访问 http://10.0.59.114/，实际请将 IP 替换为自己服务器的 IP 地址。
网站内容可以正常打开，表示 httpd 服务是正常的。

5）安装 php 服务

5.1）安装 php 工具

直接使用 yum 安装 php 及其相关模块。

yum -y install php php-gd php-mbstring php-pdo

5.2）编辑 info.php 测试文件

编辑 info.php 测试文件

[root@blog ~] vim /var/www/html/info.php 
<?php
phpinfo();
?>

5.3）重启 httpd 服务

重启 httpd 服务

systemctl restart httpd

5.4）查看 PHP 安装状态

在浏览器，http://10.0.59.114/info.php
出现以下页面，表示 php 安装正常。

6）部署 ShowDoc 应用

6.1 创建下载目录

创建 ShowDoc 软件包的下载目录

[root@blog ~] mkdir -p /data/showdoc && cd /data/showdoc/

6.2）下载ShowDoc软件包

下载 ShowDoc 软件包

[root@blog showdoc] yum install git -y

[root@blog showdoc] git clone https://github.com/star7th/showdoc.git
Cloning into 'showdoc'...
remote: Enumerating objects: 20479, done.
remote: Counting objects: 100% (1344/1344), done.
remote: Compressing objects: 100% (217/217), done.
remote: Total 20479 (delta 1177), reused 1200 (delta 1124), pack-reused 19135
Receiving objects: 100% (20479/20479), 20.49 MiB | 5.13 MiB/s, done.
Resolving deltas: 100% (12275/12275), done.

6.3）拷贝目录

将 ShowDoc 下的内容移动到网站根目录下

mv -f  showdoc/*  /var/www/html/

6.4）目录权限设置

将网站根目录 /var/www/html 的所属用户改为 apache

chown -R  apache:apache  /var/www/html

6.5）重启 httpd 服务

重启 httpd 服务

systemctl restart httpd

7）ShowDoc 的初始化设置

7.1）设置系统中文语言

访问：http://10.0.59.114/install/index.php，将 IP 替换为自己服务器的 IP 地址，
进入 ShowDoc 的初始配置页面，选择系统中文语言。

7.2）访问 ShowDoc 首页

访问地址：http://10.0.59.114/web/#/
进入 ShowDoc 首页

8）ShowDoc 的基本使用

8.1）登录 ShowDoc 文档系统

http://10.0.59.114/web/#/user/login
默认账号密码 showdoc/123456

8.2）查看示例文档效果

打开首页的 API 等示例文档，可以看到展现效果，可以自己单独创建项目，管理各种文档，非常方便。

8.3）创建新项目

创建一个新项目，填写项目信息。

8.4）添加文档

添加文档。编辑文本内容，这里直接使用默认模板来测试。

8.5）分享文档

选择分享文档，复制文档链接。

8.6）查看分享文档

打开分享文档链接，查看分享文档内容。

9）ShowDoc 的后台管理

9.1）登录后台管理

访问地址：http://10.0.59.114/web/#/admin/indeX

9.2）用户管理

用户管理页面，新增用户，填写用户信息。

9.3）项目管理

在项目管理页面，可以查看所有的项目。

9.4）附件管理

可以对文档中的附件进行管理。

9.5）集成登录

支持对接 LDAP 认证

9.6）站点设置

可以对本地站点进行基本设置。

大功告成~