Swagger UI Docker 部署：3 种端口配置写法，解决容器启动后的端口冲突

Swagger UI Docker 部署3 种端口配置写法解决容器启动后的端口冲突【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-uiSwagger UI 是一组由 HTML、JavaScript 和 CSS 资产构成的工具能从符合 Swagger 规范的 API 动态生成可交互的文档。官方 Docker 镜像本质是 nginx 容器内部监听PORT环境变量指定的端口默认 8080。本文解决的是docker run之后访问不到页面、宿主机 80 或 8080 端口被占用时如何用 3 种端口写法把 Swagger UI Docker 部署跑通。先跑起来一条命令看到文档界面最快的一条命令同端口映射直接启动docker run -d -p 8080:8080 docker.swagger.io/swaggerapi/swagger-ui前提只有一条本机装了 Docker 且能拉取docker.swagger.io的镜像。-p左边的 8080 是宿主机端口右边的 8080 是容器内端口必须和镜像实际监听的端口一致——镜像在 Dockerfile 中通过ENV PORT8080和EXPOSE 8080固定了默认值。预期效果浏览器访问http://localhost:8080能看到加载了 Petstore 示例的文档页面。冲突从哪来3 个高频原因宿主机端口已被其他进程占用。现象是容器起来了但浏览器访问宿主机端口报Connection refused或超时也可能是docker run直接报port is already allocated。验证命令lsof -i :8080 # 或 netstat -tuln | grep 8080有输出说明该端口已被占用需要换端口或停掉占用进程。把宿主机端口当成了容器内端口。现象是docker run -p 80:9090 ...启动成功但localhost:80打不开。原因是-p 宿主机:容器的右侧必须是容器实际监听的端口而你没设PORT时它仍是 80809090 上根本没有进程。对照docker ps的 Ports 列如果显示0.0.0.0:80-9090/tcp而访问不通基本就是这个原因。端口映射本身没生效。现象是容器状态Up但localhost无法访问。用docker ps看 Ports 列空值或只列了 8080 而没有映射关系说明-p没写对或被 Docker 默认网络拦截。此时先执行docker logs 容器名排除 nginx 启动阶段模板渲染、gzip 压缩的报错其他少见情况见文末的 docs/usage/installation.md。改动最小换宿主机映射端口不想动占用 8080 的进程就把宿主机一侧换掉容器内保持 8080 不动docker run -d -p 8081:8080 docker.swagger.io/swaggerapi/swagger-ui适用于临时排查或本机端口紧张的场景之后访问http://localhost:8081。这是影响面最小的一种写法不涉及镜像内任何配置。需要占用 80 端口用 PORT 改容器内监听镜像里的 nginx 模板 docker/default.conf.template 只有一处决定监听位置listen $PORT;。入口脚本 docker/docker-entrypoint.d/40-swagger-ui.sh 启动时渲染该模板所以把PORT设成 80、再做 80:80 映射即可docker run -d -p 80:80 -e PORT80 docker.swagger.io/swaggerapi/swagger-ui适用于需要以默认端口对外暴露、或前面还有反向代理的场景。注意此时-p右侧也要写成 80两侧必须同时改。长期部署docker-compose 固定端口映射把端口配置交给文件管理避免每次手敲-p出错services: swagger-ui: image: docker.swagger.io/swaggerapi/swagger-ui ports: - 8081:8080执行docker compose up -d启动。适用于团队共用环境或需要反复启停的场景端口冲突排查时改一处即可。两个容易和端口混淆的配置SWAGGER_JSON与SWAGGER_JSON_URL决定文档加载自哪里。挂载本地文件时用-e SWAGGER_JSON/foo/swagger.json -v 你的本地路径:/foo指向远程 URL 时只设SWAGGER_JSON_URL。文档地址不对会表现为端口通了但页面 404容易误判成端口问题。BASE_URL只改路径前缀例如-e BASE_URL/swagger后文档挂在/swagger下不改变监听端口与PORT是正交的两个变量。PORT_IPV6与EMBEDDING前者让 nginx 额外监听[::]:端口默认关闭后者控制是否允许 iframe 嵌入页面都与 IPv4 端口冲突无关排查时不必优先考虑。端口冲突的根源只有两类宿主机端口被占或-p两侧与容器实际监听端口不匹配。先lsof -i :端口确认占用再用PORT对齐容器侧即可。完整的镜像环境变量说明在 Dockerfile 的ENV段和 docs/usage/installation.md 的 Docker 小节下一步建议把常用参数固化进 compose 文件再交给团队使用。【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考