一、ShowDoc介绍

1.1 ShowDoc简介

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

1.2 ShowDoc主要特点

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

二、本次实践规划

2.1 本地环境规划

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

2.2 本次实践介绍

1.本次实践部署环境为个人测试环境，生产环境请谨慎；
2.在Docker环境下部署ShowDoc文档管理工具。

三、本地环境检查

3.1 检查Docker服务状态

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

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版本

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

3.3 检查docker compose 版本

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

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

docker pull star7th/showdoc:v3.5.0

五、部署ShowDoc服务

5.1 创建部署目录

• 创建部署目录

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

• 目录授权

chmod -R 777 /data/showdoc/

5.2 编辑部署文件

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

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文件，内容如下所示：

vim docker-compose.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容器。

docker compose up -d

5.4 查看ShowDoc容器状态

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

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服务正常运行。

docker compose logs

六、访问ShowDoc服务

6.1 访问ShowDoc初始页

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

6.2 初始化配置

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

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

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

6.3 使用体验

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

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

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

七、总结

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