debian swagger怎么排查故障

在 Debian 上排查 Swagger（OpenAPI）相关故障，通常可以按「服务是否起来 → 接口是否暴露 → Swagger 配置是否正确 → 网络/权限问题」这个思路来。下面按常见场景给你一个排查清单。

一、先确认服务本身是否正常

1. 服务是否在运行

systemctl status your-service
# 或
ps aux | grep your-app

如果是 Docker：

docker ps
docker logs <container_id>

2. 端口是否监听

ss -lntp | grep 8080
# 或
netstat -lntp | grep 8080

二、确认 Swagger 接口是否可访问

1. 直接访问 Swagger 地址

常见路径：

• Spring Boot: /swagger-ui.html 或 /swagger-ui/index.html
• FastAPI: /docs
• Node (swagger-ui-express): /api-docs

curl -i http://localhost:8080/swagger-ui.html

如果返回：

• 404 → Swagger 未启用或路径不对
• 403 → 权限/安全配置问题
• 500 → 后端异常

三、检查 Swagger 配置（按技术栈）

Spring Boot（最常见）

spring:
  profiles:
    active: dev

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true

或旧版：

@EnableSwagger2

常见坑：

• spring.profiles.active=prod 时 Swagger 被禁用
• Spring Security 拦截了 /swagger-ui/**

Spring Security 示例：

.antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()

FastAPI

from fastapi import FastAPI
from fastapi.openapi.docs import get_swagger_ui_html

app = FastAPI(docs_url="/docs")

排查：

curl http://localhost:8000/openapi.json

Node.js (swagger-ui-express)

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

确认：

curl http://localhost:3000/api-docs

四、查看日志（最关键）

Java

journalctl -u your-service -f
# 或
tail -f logs/app.log

重点看：

• Failed to load API definition
• Unable to infer base url

五、常见故障及原因

1. Swagger 页面空白

原因：

• JS/CSS 被 Nginx 拦截
• 反向代理没配 X-Forwarded

Nginx 示例：

location /swagger-ui/ {
    proxy_pass http://backend/;
}

2. Swagger 能开但接口为空

原因：

• 未扫描 Controller 包
• Docket / OpenAPI Bean 未创建

3. Debian 防火墙问题

ufw status
iptables -L

六、快速定位命令汇总

curl http://localhost:端口/swagger-ui.html
curl http://localhost:端口/v3/api-docs
journalctl -u 服务名 -n 100
ss -lntp

如果你能告诉我：

• Debian 版本
• 用的什么技术（Spring / FastAPI / Node）
• 具体报错信息

我可以直接帮你定位到具体配置。