ubuntu swagger怎样实现自动化部署
小樊
41
2025-12-31 20:49:55
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/
- 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）：
- 容器化 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 作业日志）、限制容器运行用户、定期更新基础镜像与依赖。