Docker搭建文档工具ShowDoc-Fish's Embedded Study & Share

1. ShowDoc介绍

1.1 简介

ShowDoc是一个非常适合IT团队的在线API文档、技术文档工具。通过showdoc，你可以方便地使用markdown语法来书写出美观的API文档、数据字典文档、技术文档、在线excel文档等等。如果不想编辑markdown文档，你还可以利用showdoc的自动化能力，从程序注释中自动生成API文档，或者从搭配的RunApi客户端（类似postman的api调试工具）中一边调试接口、一边自动生成文档。通过分配项目成员和团队成员，你可以很方便地进行项目文档的权限管理和团队协作，也可以分享文档出去给朋友查看。ShowDoc还支持多平台客户端，有win客户端、mac客户端、ios、android等，更方便跨平台使用。

1.2 特性

分享与导出，响应式网页设计，可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成word文件，以便离线浏览。
权限管理。
项目转让。
项目成员管理。
团队管理。
编辑功能，markdown编辑。
模板插入。
支持深色模式。
多平台。
自动化，可从代码注释中自动生成文档。

2. 环境准备

在开始部署前，请确保你的系统已经安装 Docker 和 Docker Compose。

2.1 安装 Docker（Ubuntu 示例）

如果你的系统尚未安装 Docker，可以使用以下命令进行安装：

sudo apt update
sudo apt install -y docker.io
sudo systemctl enable --now docker

验证安装：

docker --version

2.2 安装 Docker Compose

sudo apt install -y docker-compose

验证安装：

docker-compose --version

3. 创建 `docker-compose.yml` 配置文件

我们可以使用 Docker Compose 来管理 ShowDoc。

在 showdoc 目录下创建 docker-compose.yaml 文件，并写入以下内容（端口啥的都能自定义，主要是映射到该showdoc容器80端口）：

version: '3'
services:
    showdoc:
          image: star7th/showdoc
          container_name: showdoc
          restart: always
          ports:
            - "4999:80"
          volumes:
            - ./showdoc_data:/var/www/html/

4. 启动 ShowDoc 服务

在 docker-compose.yaml 所在目录运行以下命令：

sudo docker-compose up -d

该步骤如果遇到docker拉取镜像报错，可尝试手动docker pull拉取镜像，如果仍有问题可能需要换源或者科学上网解决，例如将yaml文件中image改为registry.cn-shenzhen.aliyuncs.com/star7th/showdoc。

5. 验证部署

检查正在运行的容器：

docker ps

如果 showdoc容器都在运行，则说明启动成功。

root@DESKTOP-G52VFSH ~/w/showdoc# docker ps
CONTAINER ID   IMAGE                                                         COMMAND                  CREATED              STATUS
  PORTS                                                        NAMES
ee36573ae9cf   registry.cn-shenzhen.aliyuncs.com/star7th/showdoc             "/entrypoint bash do…"   About a minute ago   Up About a minute
  443/tcp, 9000/tcp, 0.0.0.0:4999->80/tcp, [::]:4999->80/tcp   showdoc

访问 Hoarder：

在浏览器中输入：
```
http://localhost:4999
```
如果是远程服务器，则访问：（如果是云服务器记得开启安全组的对应端口放行）
```
http://服务器IP:4999
```

6. 管理 ShowDoc

showdoc初始化

继上一步登录后，首次登录会进入初始化页面，可选择语言为中文或者英文，这边我选择中文

初始化成功后，默认管理员账户密码是showdoc/123456。

登录后，在右上角可以看到管理后台入口：

停止 ShowDoc

docker-compose down

重启 ShowDoc

docker-compose restart

更新 ShowDoc

docker-compose pull
docker-compose up -d

7. 配置 Nginx 反向代理（可选）

如果希望使用域名访问 ShowDoc，可以使用 Nginx 作为反向代理。

7.1 安装 Nginx

sudo apt install -y nginx

7.2 配置 Nginx

在 /etc/nginx/sites-available/ShowDoc 添加以下内容：

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

启用配置：

sudo ln -s /etc/nginx/sites-available/hoarder /etc/nginx/sites-enabled/
sudo systemctl restart nginx

8. 配置 HTTPS（可选）

如果使用域名访问，可以使用 Let’s Encrypt 配置 HTTPS：

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com

证书续期：

sudo certbot renew --dry-run

问题 1：Docker 容器无法启动

运行以下命令查看错误日志：

docker-compose logs showdoc

问题 3：端口被占用

如果4999端口已被占用，可以修改 docker-compose.yml：

ports:
  - "5000:80"

然后重新启动：

docker-compose up -d

并使用 http://服务器IP:5000 访问。

10. 基础使用介绍

10.1 ShowDoc后台管理

访问地址：http://127.0.0.1:4999，登录，选择后台管理，这里可以进行成员新增，给部门内多个成员新增showdoc文档权限：

10.2 新增项目

11.3 添加文档

选择对应项目，点击左下角新建页面，文档按照标准markdown格式编辑即可：

注：更多高级功能自行调研，也可以评论区讨论，包括根据注释生成文档，AI等功能

Docker搭建文档工具ShowDoc