ubuntu swagger怎样实现自动化部署

Ubuntu 上 Swagger 自动化部署实践

一、方案总览

使用容器化部署 Swagger Editor / Swagger UI，通过 Docker Compose 编排，配合 Nginx 反向代理与 HTTPS，适合团队协作与快速交付。
使用 GitLab CI/CD 或 Jenkins 实现“提交即部署”，自动拉取最新镜像、重启服务、发布静态文档。
若后端是 Go，用 swag 从注释自动生成 Swagger JSON/YAML，再接入静态托管或容器化 UI。

二、容器化一键部署与自动更新

安装 Docker 与 Docker Compose（Ubuntu 20.04/22.04 示例）
- 安装 Docker：sudo apt update && sudo apt install -y docker.io && sudo systemctl enable --now docker
- 安装 Docker Compose（v2 推荐）：sudo apt install -y docker-compose-plugin
编排目录与示例文件
- 目录结构
  - swagger-deploy/
    - docker-compose.yml
    - editor-data/（可选：持久化编辑器内容）
    - ui-data/（可选：自定义静态资源）
    - nginx/
      - nginx.conf
      - ssl/（放证书）
- docker-compose.yml
  - version: “3.8” services: editor: image: swaggerapi/swagger-editor:latest container_name: swagger-editor restart: unless-stopped volumes: - ./editor-data:/var/lib/editor # 可选：持久化 networks: - swagger-net ui: image: swaggerapi/swagger-ui:latest container_name: swagger-ui restart: unless-stopped environment: SWAGGER_JSON: /specs/openapi.yaml volumes: - ./openapi.yaml:/specs/openapi.yaml:ro - ./ui-data:/usr/share/nginx/html # 可选：自定义静态文件 networks: - swagger-net nginx: image: nginx:alpine container_name: swagger-nginx restart: unless-stopped ports: - “80:80” - “443:443” volumes: - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro - ./nginx/ssl:/etc/nginx/ssl:ro depends_on: - editor - ui networks: - swagger-net networks: swagger-net: driver: bridge
- nginx.conf（最简示例，开启 HTTPS）
  - events {} http { server { listen 80; server_name your-domain.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; location /editor/ { proxy_pass http://editor:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /ui/ { proxy_pass http://ui:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } }
启动与验证
- 启动：docker compose up -d（或 docker-compose up -d）
- 访问：Editor 在 /editor/，UI 在 /ui/（如 https://your-domain.com/ui/）
自动更新
- 在 CI 或生产主机上执行“拉取新镜像并重启”脚本：
  - docker compose pull && docker compose up -d --remove-orphans
- 建议为镜像设置固定标签（如 v5.17.14），避免 latest 带来的不确定性；变更 openapi.yaml 后仅需重启 UI 服务：docker compose restart ui。

三、CI/CD 自动化示例

GitLab CI 示例（.gitlab-ci.yml）
- stages:
  - deploy deploy_prod: stage: deploy image: docker:24.0 services:
    - docker:24.0-dind before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY script:
    - cd $CI_PROJECT_DIR
    - docker compose pull
    - docker compose up -d --remove-orphans only:
    - main
说明
- 将镜像推送到私有仓库时，在 script 中先 docker build/tag/push，再在目标主机 pull/up。
- 也可使用 Jenkins Pipeline 执行相同逻辑（拉取最新镜像、docker compose up -d、健康检查）。

四、Go 项目自动化生成文档并托管

安装 swag（Go 1.19+）
- go install github.com/swaggo/swag/cmd/swag@latest
生成文档
- swag init -g cmd/api/main.go -o docs/api
- 生成产物：docs/api/swagger.json、docs/api/swagger.yaml、docs/docs.go
托管方式
- 静态站点托管（GitLab Pages/对象存储/Nginx）
  - 将 docs/api/swagger.json 发布到站点目录，使用公共 Swagger UI 入口加载该 JSON。
  - 示例 public/index.html（使用 CDN 的 Swagger UI）：
    - <!doctype html>
- 容器化 UI 托管
  - 将生成的 swagger.json 挂载到 UI 容器（见第二节 docker-compose.yml 的 volumes 示例），通过 Nginx 暴露访问。

五、运维与安全要点

版本与回滚
- 固定镜像标签；回滚时执行 docker compose up -d 指定上一版本镜像标签。
健康检查与自恢复
- 在 docker-compose.yml 的 ui/editor 下添加 healthcheck，配合 restart: unless-stopped 提升可用性。
数据与权限
- 需要持久化的目录（如编辑器内容、自定义静态资源）挂载为卷，注意目录权限与属主。
网络与隔离
- 使用独立网络（如 swagger-net），仅暴露必要端口（80/443），UI 与 Editor 不直连公网。
合规与审计
- 记录变更（CI/CD 作业日志）、限制容器运行用户、定期更新基础镜像与依赖。

最新问答

相关标签