WeKnora Swagger 空白页排查：HTTP 200 不代表访问到了正确服务

浏览器访问 /swagger/index.html 返回 HTTP 200，页面却没有 Swagger UI。这个现象不一定是接口文档构建失败，也不一定需要登录：请求可能只是落到了前端的 SPA 回退页面。

围绕这个问题，我提交了 WeKnora 文档 PR #3620，补充 Docker Compose 下访问 Swagger 的步骤与排查方法。截至 2026-09-23，PR 尚未合并，腾讯扫描存在一项失败；本地文档检查和构建已通过。

同一个路径，不同端口对应不同服务#

WeKnora 的前端和后端分别处理请求。Swagger 由 app 后端提供，而默认前端端口以及 Vite 开发端口没有配置 /swagger/ 代理。

如果访问前端的 /swagger/index.html，Nginx 可能返回 SPA 的入口 HTML。状态码是 200，但内容并不是 Swagger 页面。登录前端也不会自动增加一条反向代理规则。

排查时需要同时看三件事：请求发到哪个端口、响应状态是什么、返回的正文究竟是什么。

现象	优先检查
200，但 HTML 包含普通前端的 `<div id="app">`	是否访问了前端端口，触发 SPA 回退
后端 401 或 404，没有 Swagger UI	实际 `GIN_MODE` 与后端映射端口
UI 能显示，但无法加载 API 定义	`/swagger/doc.json` 及代理是否覆盖整个路径

Swagger 路由只在非 release 模式注册，而 Docker Compose 默认使用 release。因此，即便找对后端端口，也需要确认容器中的实际环境变量。

本地开发排障时，可以在项目 .env 设置 GIN_MODE=debug，再重新创建 app 容器：

1
docker compose up -d --no-deps --force-recreate app
2
docker compose exec app printenv GIN_MODE
3
docker compose port app 8080

这里使用重新创建，是因为 docker compose restart app 不会把修改后的环境变量写进已有容器。

第一项检查应输出 debug。第二项检查用于确认实际后端映射端口：默认是 8080，如果改过 APP_PORT，就应使用相应端口。排障后将 GIN_MODE 恢复为 release 并再次创建容器；该变量还影响其他开发模式行为。

1
curl -i http://localhost:8080/swagger/index.html
2
curl -i http://localhost:8080/swagger/doc.json

正常情况下，前者返回包含 Swagger UI 的 HTML，后者返回包含 swagger 与 paths 字段的 JSON。发布镜像已经包含生成后的文档，只有修改接口注释、需要重新生成并构建后端时才需要 make docs。

验证使用隔离的 Docker Compose 环境：官方 v0.8.0 后端镜像，以及当时主分支的 Nginx 配置和入口脚本。前端使用已有静态资源，没有重新构建完整应用。

观察到的结果是：

文档检查覆盖 232 条内部链接和 60 个 Mermaid 图，无失败；文档构建通过，保留了已有的包大小提示。

该 PR 只修改两份文档。GitHub 上失败的是腾讯扫描，公开结果中的“安全漏洞严重问题数”为 null，没有具体文件或行号标注。

这不足以判断是文档引入了漏洞，也不足以确认扫描基础设施故障。准确的说法是：本地文档验证通过，但远端这一检查仍待排查，不能把 PR 描述为全部验证完成。

HTTP 200 只能说明某个服务返回了成功响应，不能证明请求到达了预期服务。调试 Agent 或其他多服务应用时，端口、代理、运行模式和容器配置都可能造成“看起来成功，实际走错路径”的问题。

这次贡献补全了部署文档，没有新增代理，也没有修改应用默认模式。排障过程和文章整理使用了 AI 辅助。