ubuntu swagger怎样实现容器化部署

Ubuntu 上 Swagger 容器化部署指南

一 准备环境

• 在 Ubuntu 20.04/22.04 上安装 Docker（建议 20.10+），并启动服务：
  • 安装：sudo apt update && sudo apt install -y docker.io
  • 启动与开机自启：sudo systemctl start docker && sudo systemctl enable docker
• 可选：安装 Docker Compose 以便编排多服务（示例命令：sudo curl -L “https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)” -o /usr/local/bin/docker-compose && sudo chmod +x /usr/local/bin/docker-compose）。

二 快速部署 Swagger UI

• 使用官方镜像一键启动（容器内默认端口为 8080，映射到主机 8080）：
  • 命令：docker run -d -p 8080:8080 --name swagger-ui swaggerapi/swagger-ui
  • 访问：打开浏览器进入 http://localhost:8080 查看 Swagger UI 页面。
• 常用环境变量（示例）：
  • 指定远程规范：docker run -d -p 8080:8080 -e SWAGGER_JSON_URL=https://api.example.com/openapi.json swaggerapi/swagger-ui
  • 指定本地规范文件：docker run -d -p 8080:8080 -v /path/to/swagger.json:/app/swagger.json -e SWAGGER_JSON=/app/swagger.json swaggerapi/swagger-ui
  • 多规范切换：docker run -d -p 8080:8080 -e “URLS=[{url:‘/specs/v1.json’,name:‘V1’},{url:‘/specs/v2.json’,name:‘V2’}]” -v /path/to/specs:/usr/share/nginx/html/specs swaggerapi/swagger-ui
  • 说明：官方镜像基于 Nginx/Alpine，体积小、适合生产使用。

三 部署 Swagger Editor

• 使用官方镜像运行编辑器（容器内端口 8080）：
  • 命令：docker run -d -p 8081:8080 --name swagger-editor swaggerapi/swagger-editor:latest
  • 访问：打开浏览器进入 http://localhost:8081 使用在线编辑与预览。
• 更新方式：停止并删除旧容器后拉取最新镜像重启即可（见下文“更新与回滚”）。

四 使用 Docker Compose 编排与多实例

• 单服务编排示例（将主机 80 映射到容器 8080，并挂载本地规范目录与 Nginx 配置）：
  • 文件：docker-compose.yml version: ‘3.8’ services: swagger-ui: image: swaggerapi/swagger-ui container_name: swagger-ui ports: - “80:8080” environment: - SWAGGER_JSON_URL=/specs/openapi.json - BASE_URL=/api-docs volumes: - ./specs:/usr/share/nginx/html/specs - ./nginx/conf.d:/etc/nginx/conf.d restart: always healthcheck: test: [“CMD”, “wget”, “–no-verbose”, “–tries=1”, “–spider”, “http://localhost:8080/api-docs/health”] interval: 30s timeout: 10s retries: 3
  • 启动：docker-compose up -d
• 多实例/集群示例（多端口对外提供多个 UI 实例，便于横向扩展与灰度）：
  • 文件：docker-compose.yml version: ‘3.8’ services: ui-1: image: swaggerapi/swagger-ui ports: [“8081:8080”] environment: - SWAGGER_JSON_URL=/specs/openapi.json volumes: [“./specs:/usr/share/nginx/html/specs”] ui-2: image: swaggerapi/swagger-ui ports: [“8082:8080”] environment: - SWAGGER_JSON_URL=/specs/openapi.json volumes: [“./specs:/usr/share/nginx/html/specs”]
  • 启动：docker-compose up -d
• 说明：多实例适合高可用与分流；也可在前端接入 Nginx/Ingress 做统一域名与负载均衡。

五 生产化与安全加固

• HTTPS 与访问控制：挂载自定义 Nginx 配置与证书，仅开放 443，按需限制来源 IP：
  • 挂载：docker run -d -p 443:443 -v /path/to/custom-nginx.conf:/etc/nginx/conf.d/default.conf -v /path/to/ssl:/etc/nginx/ssl swaggerapi/swagger-ui
  • 配置要点：listen 443 ssl; ssl_certificate/ssl_certificate_key 指向证书；可加入 allow/deny 规则限制网段。
• 数据与配置持久化：将 /usr/share/nginx/html/specs（规范文件）、/etc/nginx/conf.d（Nginx 配置）、/etc/nginx/ssl（证书）挂载到宿主机，避免容器重建丢失。
• 高可用与健康检查：在 docker-compose.yml 中配置 restart: always 与 healthcheck，并接入反向代理/负载均衡实现故障转移与滚动更新。
• 更新与回滚：
  • 拉取新镜像：docker pull swaggerapi/swagger-ui
  • 重启服务：docker-compose up -d --force-recreate（或 docker restart ）
  • 回滚：保留旧镜像标签，切换镜像版本后重启；多实例时逐个滚动更新降低影响。