首页 > 问答 >
智能运维 >
Swagger在Linux环境下如何实现自动化部署
Swagger在Linux环境下如何实现自动化部署
小樊
39
2025-12-17 23:39:19
Linux环境下Swagger自动化部署实践
一、方案总览
容器化部署：使用官方镜像快速起 Swagger Editor 与 Swagger UI ，配合脚本或 Jenkins/GitLab CI 实现一键拉起、滚动更新与回滚，适合演示、内网文档与团队协作。
内嵌式部署：在 Spring Boot 项目中集成 springfox-swagger2/springfox-swagger-ui ，随应用发布自动提供 /swagger-ui.html 页面，适合生产环境随服务发布文档。
传统静态托管：用 Nginx/Apache 托管 Swagger UI 的 dist 静态文件，结合 Git 与 CI 自动拉取并发布，适合已有静态发布流水线的团队。
二、容器化一键部署与自动化脚本
安装 Docker（示例为 Debian/Ubuntu）
安装依赖与 GPG 密钥，添加 Docker 仓库，安装并启动服务：
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo “deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable” | sudo tee /etc/apt/sources.list.d/docker.list > /devref
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io
sudo systemctl start docker && sudo systemctl enable docker
启动 Swagger Editor 与 Swagger UI（示例端口：Editor 8088 ，UI 8080 ）
docker run -d --name swagger-editor -p 8088:8080 swaggerapi/swagger-editor:v4.6.0
docker run -d --name swagger-ui -p 8080:8080 swaggerapi/swagger-ui:v4.15.5
远程访问
Editor：http://<服务器IP>:8088
UI：http://<服务器IP>:8080
自动化部署脚本 deploy_swagger.sh（示例）
#!/usr/bin/env bash
set -e
IMG_EDITOR=“swaggerapi/swagger-editor:v4.6.0”
IMG_UI=“swaggerapi/swagger-ui:v4.15.5”
docker rm -f swagger-editor swagger-ui 2>/dev/null || true
docker pull $IMG_EDITOR
docker pull $IMG_UI
docker run -d --name swagger-editor -p 8088:8080 $IMG_EDITOR
docker run -d --name swagger-ui -p 8080:8080 $IMG_UI
echo “Swagger Editor: http://$(curl -s ifconfig.me):8088”
echo “Swagger UI: http://$(curl -s ifconfig.me):8080”
更新与回滚
更新：重复拉取新镜像并启动新容器（如上脚本即为无状态更新）。
回滚：记录旧镜像标签，docker rm -f 新容器 && docker run 旧镜像标签。
三、内嵌式部署 Spring Boot 集成
依赖（Maven，示例版本）
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
配置类
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
访问与发布
启动应用后访问：http://<服务器IP>:8080/swagger-ui.html
允许外部访问：java -jar -Dserver.address=0.0.0.0 your-app.jar
自动化
将 Swagger 依赖与配置纳入项目代码，随应用构建与发布流水线自动部署，无需额外服务。
四、CI/CD 集成与远程访问
Jenkins 示例（声明式流水线）
pipeline {
agent any
stages {
stage(‘Checkout’) { steps { git url: ‘git@your-repo.git’, branch: ‘main’ } }
stage(‘Build’) { steps { sh ‘mvn clean package -DskipTests’ } }
stage(‘Deploy’) {
steps {
sh ‘’’
docker rm -f swagger-ui 2>/dev/null || true
docker pull swaggerapi/swagger-ui:v4.15.5
docker run -d --name swagger-ui -p 8080:8080 swaggerapi/swagger-ui:v4.15.5
‘’’
}
}
}
post { success { slackSend channel: ‘#api-team’, message: ‘Swagger UI deployed.’ } }
}
GitLab CI 示例（.gitlab-ci.yml 片段）
deploy:
stage: deploy
script:
- docker rm -f swagger-ui 2>/dev/null || true
- docker pull swaggerapi/swagger-ui:v4.15.5
- docker run -d --name swagger-ui -p 8080:8080 swaggerapi/swagger-ui:v4.15.5
only: [main]
远程访问与隧道
内网环境可用 Cpolar 等工具将本地端口映射到公网，生成临时或固定公网地址，便于外网访问演示环境。
五、生产可用性与安全加固建议
反向代理与端口管理：使用 Nginx/Apache 统一暴露端口与域名，配置 TLS/HTTPS ，隐藏容器直曝端口；Nginx 示例：
server {
listen 443 ssl;
server_name api-doc.example.com;
ssl_certificate /etc/ssl/certs/api-doc.crt;
ssl_certificate_key /etc/ssl/private/api-doc.key;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
访问控制：限制内网访问或增加 Basic Auth/Token ；对公网仅开放必要路径与方法。
数据与版本管理：将 OpenAPI 规范文件（YAML/JSON） 纳入 Git 管理，CI 自动校验与发布；为镜像与规范打 标签（如 v1.2.3） ，便于回滚。
资源与稳定性：设置容器 重启策略（–restart=always） ，监控容器与节点资源，必要时使用 Nginx 缓存 与 CDN 加速静态资源。
