Linux系统之部署showdoc文档工具
一、showdoc介绍
1.1 showdoc简介
Showdoc是一款在线文档工具，支持Markdown语法，可以用于快速记录、分享和协作文档。它拥有简洁的界面和丰富的功能，包括在线编辑、多人协作、讨论评论、版本管理、权限管理等特性。
1.2 showdoc功能
- 分享与导出：响应式网页设计，可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成word文件，以便离线浏览。
- 权限管理：公开项目与私密项目、项目转让、项目成员、团队管理。
- 编辑功能： markdown编辑、模板插入、历史版本。
- 多平台：showdoc支持网页版、手机app版和电脑客户端版。
- 自动化：可从代码注释中自动生成文档、搭配的RunApi客户端，可调试接口和自动生成文档。
- 快速部署：可使用使用开源版本showdoc，快速在本地服务器部署showdoc。
二、本地环境介绍
2.1 本地环境规划
本次实践为个人测试环境，服务器操作系统版本为centos7.6。
客户端助手版本为win10。
| hostname | IP地址 | 操作系统版本 | 内核版本 | Teleport版本 |
|---|---|---|---|---|
| jeven | 192.168.3.166 | centos 7.6 | 3.10.0-957.el7.x86_64 | 3.6.4-b3 |
2.2 本次实践介绍
1.本次实践部署环境为个人测试环境；
2.在centos7.6环境下安装showdoc文档工具。
三、检查本地环境
3.1 检查本地操作系统版本
检查本地操作系统版本
[root@jeven ~]# cat /etc/redhat-release
CentOS Linux release 7.6.1810 (Core)
3.2 检查系统内核版本
检查系统内核版本
[root@jeven ~]# uname -r
3.10.0-957.el7.x86_64
3.3 检查本地yum仓库状态
- 配置阿里云的镜像源
curl -o /etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-7.repo
sed -i -e '/mirrors.cloud.aliyuncs.com/d' -e '/mirrors.aliyuncs.com/d' /etc/yum.repos.d/CentOS-Base.repo
- 检查本地yum仓库状态
[root@jeven yum.repos.d]# yum repolist all |grep enable
base/7/x86_64 CentOS-7 - Base - mirrors.aliyun.com enabled: 10,072
extras/7/x86_64 CentOS-7 - Extras - mirrors.aliyun.com enabled: 515
updates/7/x86_64 CentOS-7 - Updates - mirrors.aliyun.com enabled: 4,996
四、安装httpd服务
4.1 安装httpd
使用使用yum安装httpd
[root@jeven yum.repos.d]# yum -y install httpd
Loaded plugins: fastestmirror, langpacks
Loading mirror speeds from cached hostfile
base | 3.6 kB 00:00:00
extras | 2.9 kB 00:00:00
updates | 2.9 kB 00:00:00
Resolving Dependencies
--> Running transaction check
---> Package httpd.x86_64 0:2.4.6-99.el7.centos.1 will be installed
--> Processing Dependency: httpd-tools = 2.4.6-99.el7.centos.1 for package: httpd-2.4.6-99.el7.centos.1.x86_64
--> Processing Dependency: /etc/mime.types for package: httpd-2.4.6-99.el7.centos.1.x86_64
--> Processing Dependency: libaprutil-1.so.0()(64bit) for package: httpd-2.4.6-99.el7.centos.1.x86_64
--> Processing Dependency: libapr-1.so.0()(64bit) for package: httpd-2.4.6-99.el7.centos.1.x86_64
--> Running transaction check
---> Package apr.x86_64 0:1.4.8-7.el7 will be installed
---> Package apr-util.x86_64 0:1.5.2-6.el7_9.1 will be installed
---> Package httpd-tools.x86_64 0:2.4.6-99.el7.centos.1 will be installed
---> Package mailcap.noarch 0:2.1.41-2.el7 will be installed
--> Finished Dependency Resolution
Dependencies Resolved
=======================================================================================================================================================
Package Arch Version Repository Size
=======================================================================================================================================================
Installing:
httpd x86_64 2.4.6-99.el7.centos.1 updates 2.7 M
Installing for dependencies:
apr x86_64 1.4.8-7.el7 base 104 k
apr-util x86_64 1.5.2-6.el7_9.1 updates 92 k
httpd-tools x86_64 2.4.6-99.el7.centos.1 updates 94 k
mailcap noarch 2.1.41-2.el7 base 31 k
Transaction Summary
=======================================================================================================================================================
Install 1 Package (+4 Dependent packages)
Total download size: 3.0 M
Installed size: 10 M
Downloading packages:
(1/5): apr-1.4.8-7.el7.x86_64.rpm | 104 kB 00:00:00
(2/5): apr-util-1.5.2-6.el7_9.1.x86_64.rpm | 92 kB 00:00:00
(3/5): mailcap-2.1.41-2.el7.noarch.rpm | 31 kB 00:00:00
(4/5): httpd-tools-2.4.6-99.el7.centos.1.x86_64.rpm | 94 kB 00:00:00
(5/5): httpd-2.4.6-99.el7.centos.1.x86_64.rpm | 2.7 MB 00:00:06
-------------------------------------------------------------------------------------------------------------------------------------------------------
Total 474 kB/s | 3.0 MB 00:00:06
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction
Installing : apr-1.4.8-7.el7.x86_64 1/5
Installing : apr-util-1.5.2-6.el7_9.1.x86_64 2/5
Installing : httpd-tools-2.4.6-99.el7.centos.1.x86_64 3/5
Installing : mailcap-2.1.41-2.el7.noarch 4/5
Installing : httpd-2.4.6-99.el7.centos.1.x86_64 5/5
Verifying : httpd-2.4.6-99.el7.centos.1.x86_64 1/5
Verifying : mailcap-2.1.41-2.el7.noarch 2/5
Verifying : apr-1.4.8-7.el7.x86_64 3/5
Verifying : httpd-tools-2.4.6-99.el7.centos.1.x86_64 4/5
Verifying : apr-util-1.5.2-6.el7_9.1.x86_64 5/5
Installed:
httpd.x86_64 0:2.4.6-99.el7.centos.1
Dependency Installed:
apr.x86_64 0:1.4.8-7.el7 apr-util.x86_64 0:1.5.2-6.el7_9.1 httpd-tools.x86_64 0:2.4.6-99.el7.centos.1 mailcap.noarch 0:2.1.41-2.el7
Complete!
4.2 启动httpd服务
- 启动httpd服务并使开机自启
systemctl enable --now httpd
- 检查httpd服务状态
[root@jeven yum.repos.d]# systemctl status httpd
● httpd.service - The Apache HTTP Server
Loaded: loaded (/usr/lib/systemd/system/httpd.service; enabled; vendor preset: disabled)
Active: active (running) since Thu 2023-06-22 16:39:57 CST; 35s ago
Docs: man:httpd(8)
man:apachectl(8)
Main PID: 45406 (httpd)
Status: "Total requests: 0; Current requests/sec: 0; Current traffic: 0 B/sec"
Tasks: 6
Memory: 2.9M
CGroup: /system.slice/httpd.service
├─45406 /usr/sbin/httpd -DFOREGROUND
├─45407 /usr/sbin/httpd -DFOREGROUND
├─45408 /usr/sbin/httpd -DFOREGROUND
├─45409 /usr/sbin/httpd -DFOREGROUND
├─45410 /usr/sbin/httpd -DFOREGROUND
└─45411 /usr/sbin/httpd -DFOREGROUND
Jun 22 16:39:51 jeven systemd[1]: Starting The Apache HTTP Server...
Jun 22 16:39:57 jeven systemd[1]: Started The Apache HTTP Server.
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://192.168.3.166/，实际请将IP替换为自己服务器的IP地址。
网站内容可以正常打开，表示httpd服务是正常的。
五、安装php服务
5.1 安装php工具
直接使用yum安装php及其相关模块。
yum -y install php php-gd php-mbstring php-pdo
5.2 编辑info.php测试文件
编辑info.php测试文件
[root@jeven ~]# cat /var/www/html/info.php
<?php
phpinfo();
?>
5.3 重启hhtpd服务
重启hhtpd服务
systemctl restart httpd
5.4 查看php安装状态
在浏览器，http://192.168.3.166/info.php
现以下页面，表示php安装正常。
六、部署ShowDoc应用
6.1 创建下载目录
创建ShowDoc软件包的下载目录
[root@jeven ~]# mkdir -p /data/showdoc
[root@jeven ~]# cd /data/showdoc/
6.2 下载ShowDoc软件包
下载ShowDoc软件包
[root@jeven showdoc]# git clone https://github.com/star7th/showdoc.git
Cloning into 'showdoc'...
remote: Enumerating objects: 20220, done.
remote: Counting objects: 100% (1812/1812), done.
remote: Compressing objects: 100% (624/624), done.
remote: Total 20220 (delta 1259), reused 1643 (delta 1139), pack-reused 18408
Receiving objects: 100% (20220/20220), 21.71 MiB | 4.48 MiB/s, done.
Resolving deltas: 100% (11942/11942), 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
七、showdoc的初始化设置
7.1 设置系统中文语言
访问：http://192.168.3.166/install/index.php，将IP替换为自己服务器的IP地址，
进入showdoc的初始配置页面，选择系统中文语言。
7.2 访问ShowDoc首页
访问地址：http://192.168.3.166/web/#/
进入ShowDoc首页
八、ShowDoc的基本使用
8.1 登录showdoc文档系统
http://192.168.3.166/web/#/user/login
默认账号密码showdoc/123456
8.2 查看示例文档效果
打开首页的API等示例文档，可以看到展现效果，可以自己单独创建项目，管理各种文档，非常方便。
8.3 创建新项目
创建一个新项目，填写项目信息。
8.4 添加文档
添加文档。编辑文本内容，这里直接使用默认模板来测试。
8.5 分享文档
选择分享文档，复制文档链接。
8.6 查看分享文档
打开分享文档链接，查看分享文档内容。
九、showdoc的后台管理
9.1 登录后台管理
访问地址：http://192.168.3.166/web/#/admin/index
9.2 用户管理
用户管理页面，新增用户，填写用户信息。
9.3 项目管理
在项目管理页面，可以查看所有的项目。
9.4 附件管理
可以对文档中的附件进行管理。
9.5 站点设置
可以对本地站点进行基本设置。
