【Docker项目实战】使用Docker部署ShowDoc文档管理工具

一、ShowDoc介绍
- [1.1 ShowDoc简介](#1.1 ShowDoc简介)
- [1.2 ShowDoc主要特点](#1.2 ShowDoc主要特点)
二、本次实践规划
- [2.1 本地环境规划](#2.1 本地环境规划)
- [2.2 本次实践介绍](#2.2 本次实践介绍)
三、本地环境检查
- [3.1 检查Docker服务状态](#3.1 检查Docker服务状态)
- [3.2 检查Docker版本](#3.2 检查Docker版本)
- [3.3 检查docker compose 版本](#3.3 检查docker compose 版本)
四、拉取ShowDoc镜像
五、部署ShowDoc服务
- [5.1 创建部署目录](#5.1 创建部署目录)
- [5.2 编辑部署文件](#5.2 编辑部署文件)
- [5.3 创建ShowDoc容器](#5.3 创建ShowDoc容器)
- [5.4 查看ShowDoc容器状态](#5.4 查看ShowDoc容器状态)
- [5.5 检查容器运行日志](#5.5 检查容器运行日志)
六、访问ShowDoc服务
- [6.1 访问ShowDoc初始页](#6.1 访问ShowDoc初始页)
- [6.2 初始化配置](#6.2 初始化配置)
- [6.3 使用体验](#6.3 使用体验)
七、总结

一、ShowDoc介绍

1.1 ShowDoc简介

ShowDoc 是一个专为 IT 团队设计的在线技术文档协作工具，适用于 API 文档、数据字典、项目说明等场景，帮助团队高效共享和管理技术文档。

1.2 ShowDoc主要特点

API 文档快速生成：内置 API 模板，轻松编写结构清晰、格式统一的接口文档。
数据字典可视化管理：直观展示数据库结构，支持字段定义与说明，便于团队理解数据模型。
支持 Markdown 编辑：使用简洁高效的 Markdown 语法，提升文档编写与阅读体验。
模板一键插入：提供 API 和数据字典等常用模板，减少重复编辑，提升效率。
响应式网页设计：适配电脑与移动端，随时随地查看文档内容。
文档导出功能：可将项目导出为离线 Word 文件，方便归档或分享。
公共与私有项目：支持设置公共项目（开放访问）和私有项目（需登录查看），灵活控制可见范围。
细粒度权限管理：项目所有者可添加成员，成员可编辑文档，但仅所有者能删除或转让项目。
项目自由转让：项目所有者可将项目所有权转移给其他用户，便于团队协作交接。
历史版本记录：自动保存页面编辑历史，支持随时回滚到任意历史版本。
团队协作便捷：支持多人协同编辑，提升文档维护效率。
本地化部署支持：可私有化部署，保障企业数据安全与合规性。

二、本次实践规划

2.1 本地环境规划

本次实践为个人测试环境，操作系统版本为 Ubuntu 24.04.2 LTS。

hostname	IP地址	操作系统版本	Docker版本	部署项目
jeven01	192.168.3.88	Ubuntu 24.04.2 LTS	28.3.3	ShowDoc

2.2 本次实践介绍

1.本次实践部署环境为个人测试环境，生产环境请谨慎；

2.在Docker环境下部署ShowDoc文档管理工具。

三、本地环境检查

3.1 检查Docker服务状态

检查Docker服务是否正常运行，确保Docker正常运行。

bash 复制代码

root@jeven:~# systemctl status docker
● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: enabled)
     Active: active (running) since Mon 2025-08-04 10:10:52 UTC; 30min ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 860 (dockerd)
      Tasks: 10
     Memory: 97.2M (peak: 98.4M)
        CPU: 606ms
     CGroup: /system.slice/docker.service

3.2 检查Docker版本

检查Docker版本

bash 复制代码

root@jeven:~# docker -v
Docker version 28.3.3, build 980b856

3.3 检查docker compose 版本

检查Docker compose版本，确保2.0以上版本。

bash 复制代码

root@jeven:~# docker -v
Docker version 28.3.3, build 980b856

四、拉取ShowDoc镜像

下载ShowDoc容器镜像，拉取镜像为Docker hub中的v3.5.0版本。如果因网速问题，可以拉取官方提供的镜像registry.cn-shenzhen.aliyuncs.com/star7th/showdoc:latest star7th/showdoc:latest

bash 复制代码

docker pull star7th/showdoc:v3.5.0

五、部署ShowDoc服务

5.1 创建部署目录

bash 复制代码

mkdir -p /data/showdoc/html &&  cd /data/showdoc/

bash 复制代码

chmod -R 777 /data/showdoc/

5.2 编辑部署文件

使用docker-cli方式部署，可参考以下命令：

bash 复制代码

docker run -d --name showdoc --user=root --privileged=true -p 5930:80  --restart always -v /data/showdoc/html:/var/www/html/ star7th/showdoc:v3.5.0

在部署目录下，创建docker-compose.yaml文件，内容如下所示：

bash 复制代码

vim docker-compose.yaml

yaml 复制代码

version: '3.9'
services:
    showdoc:
        image: 'star7th/showdoc:v3.5.0'
        volumes:
            - '/data/showdoc/html:/var/www/html/'
        restart: always
        ports:
            - '5930:80'
        privileged: true
        user: root
        container_name: showdoc

5.3 创建ShowDoc容器

执行以下命令，创建ShowDoc容器。

bash 复制代码

docker compose up -d

5.4 查看ShowDoc容器状态

检查ShowDoc容器运行状态，确保ShowDoc容器正常启动。

bash 复制代码

root@jeven:/data/showdoc#  docker compose ps
WARN[0000] /data/showdoc/docker-compose.yaml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
NAME      IMAGE                    COMMAND                   SERVICE   CREATED              STATUS              PORTS
showdoc   star7th/showdoc:v3.5.0   "/entrypoint bash do..."   showdoc   About a minute ago   Up About a minute   443/tcp, 9000/tcp, 0.0.0.0:5930->80/tcp, [::]:5930->80/tcp

5.5 检查容器运行日志

检查ShowDoc容器运行日志，确保ShowDoc服务正常运行。

bash 复制代码

docker compose logs

六、访问ShowDoc服务

6.1 访问ShowDoc初始页

浏览器地址： http://<个人的服务器IP>:5930，访问ShowDoc的初始页。如果无法访问，请确保宿主机的防火墙已关闭或已放行相关端口，对于云服务器还需配置相应的安全组规则。

6.2 初始化配置

在ShowDoc初始界面中，我们可以看到语言选择提示，这里我们选择中文。

初始华成功后，可以看到提示默认管理员账户密码是showdoc/123456。

重新登录ShowDoc，输入迷人账号密码，点击登录即可。

6.3 使用体验

查看示例文档，效果如下：

添加文档：创建项目后，点击"添加页面"，在编辑器中撰写或粘贴文章内容。本次实践将本篇文章导入编辑器后，点击"保存"即可完成操作。

文档编辑完成后，可预览文章的最终效果。此外，我们还可以对文章进行分享等操作。

七、总结

本次Docker项目实战成功完成了ShowDoc文档管理工具的部署与验证。通过Docker容器化方式，实现了ShowDoc服务的快速搭建与运行，极大简化了安装配置流程。实践过程中，从环境准备、镜像拉取到服务启动各环节衔接顺畅，验证了方案的可行性。ShowDoc界面简洁、功能实用，为团队文档协作提供了一个高效便捷的管理平台。