基于docker使用showdoc搭建API开发文档服务器

以下是基于 Docker 快速搭建 ShowDoc API 文档服务器的完整指南，包含优化配置和常见问题解决方案：

---

1. 快速部署方案

# 创建数据目录（确保权限）
mkdir -p /showdoc_data/html && chmod 777 -R /showdoc_data

# 一键启动容器（推荐国内镜像）
docker run -d --name showdoc \
  -p 8080:80 \
  -v /showdoc_data/html:/var/www/html/ \
  --restart=always \
  registry.cn-shenzhen.aliyuncs.com/star7th/showdoc:latest

---

2. 生产环境优化配置

2.1 使用 Docker Compose（docker-compose.yml）

version: '3'
services:
  showdoc:
    image: registry.cn-shenzhen.aliyuncs.com/star7th/showdoc
    container_name: showdoc
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - /showdoc_data/html:/var/www/html/
    environment:
      - TZ=Asia/Shanghai  # 时区设置

2.2 启用 HTTPS（Nginx 反向代理示例）

server {
    listen 443 ssl;
    server_name doc.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

---

3. 关键功能配置

3.1 初始化后操作

1. 访问 http://服务器IP:8080
2. 修改默认密码（初始账号：showdoc/123456）
3. 进入「管理后台」→「系统设置」：
   • 配置站点名称、LOGO
   • 开启/关闭注册功能
   • 设置附件存储路径（建议映射到宿主机）

3.2 团队协作配置

• 项目权限：创建项目时可选择「公开」或「私密」
• 成员管理：通过邮箱邀请团队成员，设置「浏览/编辑」权限
• 操作日志：查看文档修改历史（支持版本对比）

---

4. 数据备份与迁移

4.1 备份数据

# 备份数据库（SQLite）
docker exec showdoc sqlite3 /var/www/html/Sqlite/showdoc.db .dump > showdoc_backup.sql

# 备份附件
tar -czvf showdoc_attachments.tar.gz /showdoc_data/html/Public/Uploads/

4.2 迁移到新服务器

1. 在新服务器重复安装步骤
2. 将备份文件还原到对应目录
3. 重启容器：docker restart showdoc

---

5. 常见问题解决

Q1: 访问时出现 502 错误

• 检查容器是否正常运行：docker ps -a
• 查看日志：docker logs showdoc
• 确认端口未被占用：netstat -tulnp | grep 8080

Q2: 上传附件失败

• 确保 /showdoc_data/html/Public/Uploads 目录有写入权限
• 检查 PHP 上传限制（容器内修改 /usr/local/etc/php/php.ini）：

  upload_max_filesize = 20M
  post_max_size = 20M
  

Q3: 如何升级版本？

docker stop showdoc
docker rm showdoc
docker pull registry.cn-shenzhen.aliyuncs.com/star7th/showdoc:latest
# 重新运行启动命令（保持原有数据卷）

---

6. 高级功能扩展

1. 对接 Git/SVN：通过「Webhook」实现文档自动同步
2. API 文档自动化：集成 Swagger/OpenAPI 数据导入
3. 自定义模板：在 /showdoc_data/html/Public/static/md 下添加 Markdown 模板

---

通过以上步骤，您将获得一个稳定、可协作的 API 文档管理系统。