ShowDoc项目Docker部署与升级指南-优快云博客

ShowDoc项目Docker部署与升级指南

showdoc ShowDoc is a tool greatly applicable for an IT team to share documents online一个非常适合IT团队的在线API文档、技术文档工具项目地址: https://gitcode.com/gh_mirrors/sh/showdoc

前言

ShowDoc是一款优秀的文档管理系统，采用Docker方式部署可以大大简化安装和维护流程。本文将详细介绍如何使用Docker部署ShowDoc，以及如何进行后续的升级和维护工作。

环境准备

在开始部署ShowDoc之前，需要确保系统已经安装Docker环境。Docker的安装方法因操作系统而异，这里不再赘述。

基础安装步骤

1. 获取ShowDoc镜像

ShowDoc提供了官方镜像和国内加速镜像两种选择：

# 官方镜像（国内用户可能下载速度较慢）
docker pull star7th/showdoc

# 国内加速镜像（推荐国内用户使用）
docker pull registry.docker-cn.com/star7th/showdoc
docker tag registry.docker-cn.com/star7th/showdoc:latest star7th/showdoc:latest

2. 创建数据目录

为了持久化ShowDoc的数据，需要创建一个目录用于存储：

mkdir -m 777 -p /showdoc_data/html

-m 777参数确保目录有足够的权限，-p参数确保父目录不存在时会自动创建。

3. 启动容器

使用以下命令启动ShowDoc容器：

docker run -d --name showdoc -p 4999:80 -v /showdoc_data/html:/var/www/html/ star7th/showdoc

参数说明：

-d：后台运行容器
--name showdoc：为容器命名
-p 4999:80：将容器的80端口映射到主机的4999端口
-v /showdoc_data/html:/var/www/html/：挂载数据卷

4. 初始化数据

执行以下命令完成数据初始化：

docker exec showdoc cp -fr /showdoc_data/html /var/www/
chmod 777 -R /showdoc_data

5. 访问ShowDoc

安装完成后，可以通过以下地址访问：

http://服务器IP:4999

默认管理员账号：

用户名：showdoc
密码：123456

安全提示：首次登录后请立即修改默认密码。

升级指南

当ShowDoc发布新版本时，可以按照以下步骤进行升级：

1. 停止当前容器

docker stop showdoc

2. 下载最新代码

curl -fL https://github.com/star7th/showdoc/archive/master.tar.gz | tar -C /showdoc_data/ -zxv

3. 备份旧数据

rm -rf /showdoc_data/html_bak
mv /showdoc_data/html /showdoc_data/html_bak
mv /showdoc_data/showdoc-master /showdoc_data/html

4. 设置权限

chmod 777 -R /showdoc_data/html

5. 启动容器

docker start showdoc

6. 执行安装

# 中文版安装
curl http://localhost:4999/install/non_interactive.php?lang=zh

# 英文版安装
curl http://localhost:4999/install/non_interactive.php?lang=en

7. 迁移数据

# 迁移数据库
\cp -f /showdoc_data/html_bak/Sqlite/showdoc.db.php /showdoc_data/html/Sqlite/showdoc.db.php

# 迁移附件
\cp -r -f /showdoc_data/html_bak/Public/Uploads /showdoc_data/html/Public/Uploads

# 升级数据库
curl http://localhost:4999?s=/home/update/db

注意事项：如果升级过程中出现问题，可以将/showdoc_data/html_bak重命名为/showdoc_data/html并重启容器来恢复。

从非Docker安装迁移到Docker

如果之前使用的是非Docker方式安装的ShowDoc，可以按照以下步骤迁移到Docker环境：

首先按照前面的方法安装一个新的Docker版ShowDoc
假设旧版ShowDoc数据位于/tmp/showdoc目录
执行以下命令迁移数据：

# 迁移数据库
\cp -r -f /tmp/showdoc/Sqlite/showdoc.db.php /showdoc_data/html/Sqlite/showdoc.db.php

# 迁移附件
\cp -r -f /tmp/showdoc/Public/Uploads /showdoc_data/html/Public/Uploads

# 升级数据库
curl http://localhost:4999?s=/home/update/db

数据备份

定期备份是保障数据安全的重要措施。ShowDoc的所有数据都存储在/showdoc_data/html目录中，可以通过以下命令进行备份：

zip -r /showdoc_data/showdoc_bak_$(date +%Y%m%d).zip /showdoc_data/html

建议设置定时任务自动执行备份，例如每周备份一次。

常用Docker命令

以下是一些常用的Docker管理命令：

# 停止ShowDoc容器
docker stop showdoc

# 重启ShowDoc容器
docker restart showdoc

# 删除ShowDoc容器
docker rm showdoc

# 删除ShowDoc镜像
docker rmi star7th/showdoc

# 停止并删除所有容器（谨慎使用）
docker stop $(docker ps -a -q); docker rm $(docker ps -a -q)

常见问题解决

权限问题：如果遇到文件写入权限问题，可以尝试：
- 检查/showdoc_data目录权限是否为777
- 检查SELinux是否限制了Docker的写入权限
端口冲突：如果4999端口已被占用，可以修改-p参数为其他端口，例如-p 5000:80
数据恢复：如果升级失败，可以将备份目录/showdoc_data/html_bak重命名为/showdoc_data/html并重启容器