CentOS 上 Swagger 的网络设置与可达性配置
一、目标与总体思路
- 让 Swagger 的访问地址在局域网或公网可达，常见做法是：在本机启动 Swagger Editor/UI 的静态服务，并通过 防火墙放行端口，或在前端用 Nginx 反向代理 统一暴露域名与端口。
- 若服务器位于内网，需确保从客户端到服务器的 IP 与路由可达，必要时配置网关与 DNS，以便域名解析与跨网段访问正常。
二、最小化部署与端口放行
- 安装与启动示例（Node.js 方式，适合快速验证）：
- 安装 Node.js/npm：
- curl -sL https://rpm.nodesource.com/setup_14.x | sudo -E bash -
- sudo yum install -y nodejs
- 启动 Swagger Editor（示例端口 8081）：
- git clone https://github.com/swagger-api/swagger-editor.git
- cd swagger-editor && npm install -g http-server
- http-server -p 8081
- 启动 Swagger UI（示例端口 3000）：
- git clone https://github.com/swagger-api/swagger-ui.git
- cd swagger-ui && npm install
- 将你的 swagger.json 放入 public 目录，并修改 public/index.html 中的 URL 指向该文件
- node index.js（或将其托管到静态站点目录）
- 防火墙放行（示例）：
- 放行端口（以 firewalld 为例）：
- sudo firewall-cmd --permanent --add-port=8081/tcp
- sudo firewall-cmd --permanent --add-port=3000/tcp
- sudo firewall-cmd --reload
- 如使用云服务器，还需在 安全组 放行对应端口。完成后，可在浏览器访问：http://服务器IP:8081 与 http://服务器IP:3000。
三、使用 Nginx 反向代理统一暴露
- 安装 Nginx（示例）：
- sudo yum install -y epel-release && sudo yum install -y nginx
- 配置示例（将域名或 IP 的 /swagger/ 路径代理到本地 3000 端口）：
- 编辑 /etc/nginx/conf.d/swagger.conf：
- server {
listen 80;
server_name your-domain-or-ip;
location /swagger/ {
proxy_pass http://127.0.0.1:3000/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
- 校验并重载：
- sudo nginx -t && sudo systemctl reload nginx
- 访问方式：
- 通过域名或 IP 加路径访问：http://your-domain-or-ip/swagger/
- 注意 Swagger UI 中 “URL” 应填写后端或上游服务的 实际地址（如后端 API 地址），而非代理路径本身。
四、网络连通性与系统网络设置检查
- 基本连通性自检：
- 查看本机 IP：ip addr
- 测试网关连通：ping 网关IP
- 测试外网连通：ping 8.8.8.8
- 测试 DNS 解析：nslookup your-domain.com
- 静态 IP 配置要点（/etc/sysconfig/network-scripts/ifcfg-eth0 示例）：
- DEVICE=eth0
- BOOTPROTO=static
- ONBOOT=yes
- IPADDR=192.168.1.10
- NETMASK=255.255.255.0
- GATEWAY=192.168.1.1
- DNS1=114.114.114.114
- DNS2=8.8.8.8
- 重启网络服务（视系统而定）：systemctl restart NetworkManager 或 service network restart
- 网关与 DNS 文件位置：
- 网关可在 /etc/sysconfig/network 中设置（如：GATEWAY=…）
- DNS 可在 /etc/resolv.conf 中配置（如：nameserver 114.114.114.114）
- 端口连通性测试（从客户端）：
- curl -I http://服务器IP:3000 或 telnet 服务器IP 3000
- 若不通，优先检查服务器防火墙与云安全组策略。
五、常见问题与排查要点
- 访问被拒绝或超时：
- 核对服务是否在目标端口监听（ss -ltnp | grep 3000）
- 核对防火墙与云安全组已放行对应端口
- Swagger UI 空白或 “Failed to load API definition”：
- 检查 index.html 中 “url” 是否指向可访问的 JSON（可使用相对路径或完整 URL）
- 若通过 Nginx 代理，确保静态资源与 API 地址可达，必要时设置 proxy_set_header 传递 Host 与协议头
- 跨域问题（浏览器控制台 CORS 报错）：
- 在后端或 Nginx 增加跨域头，例如：
- add_header Access-Control-Allow-Origin “*”;
- add_header Access-Control-Allow-Methods “GET,POST,PUT,DELETE,OPTIONS”;
- add_header Access-Control-Allow-Headers “Content-Type,Authorization”;
- 路径与代理前缀：
- 使用 Nginx 的 location 前缀时，确保 proxy_pass 结尾斜杠与前端资源引用路径一致，避免 404 或资源加载失败。
