1. 问题现象与根因剖析1.1 白屏、转圈、加载失败的典型现场先说说我碰到这个问题的场景。公司内部有一套数据中台项目后端接口用的是FastAPI开发阶段一切正常/docs一点就出Swagger UI接口列表、参数模型、在线调试都挺好用。结果到了生产环境——一台只能访问内网、完全没法出公网的服务器——部署完之后/docs直接白屏。浏览器控制台一片红全是Failed to load resource要么是cdn.jsdelivr.net超时要么是unpkg.com连接被拒。/redoc也一样Redoc的CDN资源加载不出来整个文档页面就是一个空白壳子。如果你也遇到这种状况先别怀疑代码逻辑十有八九是Swagger UI和Redoc的前端静态资源没有落地。为什么会这样FastAPI默认的/docs页面是一个非常薄的HTML壳子它内部通过script和link标签去加载CDN上的swagger-ui-bundle.js、swagger-ui.css、redoc.standalone.js这些资源。开发环境能上公网浏览器自然能把这些文件拉下来到了内网/离线环境这条通路就断了文档自然就废了。这跟你用Vue或React打包后不把JS/CSS放本地、而是引了一堆外链是一个道理。1.2 根因FastAPI默认的CDN依赖机制我记得FastAPI的源码里默认的get_swagger_ui_html函数会生成类似这样的HTMLdef get_swagger_ui_html( *, openapi_url: str, title: str, swagger_js_url: str https://cdn.jsdelivr.net/npm/swagger-ui-dist5/swagger-ui-bundle.js, swagger_css_url: str https://cdn.jsdelivr.net/npm/swagger-ui-dist5/swagger-ui.css, swagger_favicon_url: str https://fastapi.tiangolo.com/img/favicon.png, ): ...注意这些默认URL全是公网CDN地址。也就是说FastAPI默认的交互式API文档是“在线版”的。你的应用本身可以完全离线运行但只要浏览器需要打开/docs它就一定得能访问这些外部地址。从机制上看/docs页面只有三步第一步FastAPI返回HTML页面框架第二步浏览器去CDN拉取Swagger UI的JS和CSS第三步Swagger UI再去请求你的/openapi.json把接口定义渲染成可视化文档。在内网环境里前两步就挂了第三步根本走不到。所以你会看到页面有标题但下面的接口列表区域始终空白或者一直转圈。Redoc同理它依赖redoc.standalone.js这一个文件加载不了就是一张白纸。1.3 内网环境的连锁问题DNS、代理、防火墙我在排查这类问题时还见过几种变体。一种是有网但没配代理浏览器能打开但特别慢等了半天资源才超时另一种是服务器本身能上外网但安全策略只允许特定域名走代理cdn.jsdelivr.net不在白名单里还有一种是内网DNS解析不了外网域名直接net::ERR_NAME_NOT_RESOLVED。这种现象不只在FastAPI上出现很多API文档工具都默认走CDN比如Django REST Framework的Swagger、Knife4j等。但你如果做的是纯内网交付尤其像政企项目、军工科研、生产网环境文档就必须“自带干粮”。把这个问题想清楚之后方案其实也就明确了把Swagger UI、Redoc这些静态资源全部变成应用自己托管的本地产物。2. 方案选型离线化docs的几条路线2.1 方案对比总览业界和内网实战中把FastAPI docs离线化主要有这么几条路方案原理侵入性适用场景fastapi-offline库用本地打包的swagger-ui和redoc资源替换CDN低改几行代码大多数离线部署推荐优先试手动挂载StaticFiles自己下载静态资源通过自建HTML模板静态路由实现中需改代码对依赖包敏感、不想引入第三方库内网代理/反向代理CDN在内网提供一个代理把CDN地址映射到内网可访问的地址低但需额外基础设施已有Nginx等网关但不想改应用代码离线镜像CDN站点自建静态资源服务器作为内网版本的jsdelivr低但运维重多项目、多框架统一离线资源平台先说结论如果项目比较小、不想折腾fastapi-offline是最省事的如果对第三方依赖有洁癖或者要求完全可控手动挂载方案更合适如果团队已经有一套Nginx网关也可以考虑反向代理方案。下面我会把前两种展开成完整实操把第三种也提一下思路。2.2 为什么fastapi-offline能省事fastapi-offline这个库的设计思路很直接它把Swagger UI和Redoc的静态文件直接打进Python包里然后提供与FastAPI原生几乎一致的函数让你在注册路由时使用这些本地资源不再引用外网CDN。对比原生FastAPI你需要改动的点非常少原来你可能是这样注册的from fastapi import FastAPI from fastapi.openapi.docs import ( get_swagger_ui_html, get_redoc_html, ) app FastAPI(docs_urlNone, redoc_urlNone) app.get(/docs, include_in_schemaFalse) async def custom_swagger_ui_html(): return get_swagger_ui_html( openapi_urlapp.openapi_url, titlef{app.title} - Swagger UI, oauth2_redirect_urlapp.swagger_ui_oauth2_redirect_url, ) app.get(/redoc, include_in_schemaFalse) async def redoc_html(): return get_redoc_html( openapi_urlapp.openapi_url, titlef{app.title} - ReDoc, )用了fastapi-offline之后你只需要把import来源换掉from fastapi_offline import FastAPI_Offline from fastapi_offline.auth import optional_auth from fastapi_offline.core import create_local_swagger_ui_html, create_local_redoc_html app FastAPI_Offline(docs_url/docs, redoc_url/redoc)它甚至连FastAPI_Offline这个App类都帮你封装好了。如果你不想改原来的FastAPI实例化方式也可以继续用原生FastAPI只是手动加两个文档路由时把get_swagger_ui_html换成create_local_swagger_ui_htmlRedoc同理。这些本地化的HTML模板引用的全部是包内自带的静态资源。2.3 手动挂载静态资源的思路如果你不想为了一个文档功能引入额外的第三方包那就走手动路线。核心思路是在有网机器上下载swagger-ui-dist、redoc的静态文件一般是npm包或GitHub release里的dist目录。在自己的FastAPI项目里建一个static/docs目录把这些静态文件放进去。用app.mount(/static/docs, StaticFiles(directory...))把目录暴露成可访问的静态资源路径。自己写/docs和/redoc的HTML模板把CDN的URL改成指向/static/docs/...。看起来步骤多一点但好处是不依赖第三方Python库、资源文件完全可控、静态资源可以走Nginx缓存、还能顺便加上访问控制。对于那种安全审计比较严格、不允许随便引Python包的环境这个方案更稳妥。2.4 方案选型的决策建议我一般按下面这套逻辑来判断到底用哪个方案如果是个人小项目、快速验证直接上fastapi-offline10分钟搞定。如果是公司正式项目且以后会有多人协作、多个服务都要暴露文档建议手动挂载资源到公共目录或者做一套公共静态资源服务。如果已经有Nginx入口并且统一管理所有服务的路由可以考虑用Nginx的sub_filter或者反向代理把CDN路径替换掉但这样调试成本偏高只适合你对Nginx非常熟的情况。另外有个细节不管用哪个方案记得关闭FastAPI默认的docs_url和redoc_url避免暴露两个没有任何资源的空壳页面。3. 实操路线A基于fastapi-offline快速适配3.1 在有网机器上准备离线wheel包既然目标是离线环境那么第一步就是在能联网的开发机/构建机上把fastapi-offline及其依赖全部下载成wheel包。推荐用pip download它会连同依赖一起拉下来mkdir offline_packages cd offline_packages pip download fastapi-offline -d .这条命令会把fastapi-offline本身、以及它运行时依赖的fastapi、starlette、pydantic等包都下载到当前目录如果本地环境已存在某些版本可以加--no-deps单独获取你要的包但更稳妥是直接全量拉。注意一个坑pip download默认会下载当前Python版本和平台对应的wheel包。如果你的离线服务器是Windows构建机是Linux那你得用--platform和--python-version指定目标平台pip download fastapi-offline -d ./offline_packages \ --platform win_amd64 \ --python-version 3.9 \ --only-binary:all:如果不指定拉下来的可能是构建机平台专用的包传到服务器上一装就会报“不支持的wheel平台”。我自己踩过这个坑后来都是先确认目标环境的系统架构和Python版本再拉取。3.2 离线环境安装与验证把offline_packages整个目录拷贝到内网服务器上后执行pip install --no-index --find-links./offline_packages fastapi-offline--no-index是关键它告诉pip不要尝试访问PyPI只从本地目录找包。如果项目本身有其他离线依赖也可以把该目录一并挂上去注意包的版本兼容性即可。安装完成后先做一个最小验证from fastapi import FastAPI from fastapi_offline import FastAPI_Offline # 方式一直接用封装的App类 app FastAPI_Offline() app.get(/health) def health(): return {status: ok}启动服务后浏览器访问http://内网IP:8000/docs。如果能看到完整的Swagger UI页面接口列表正常加载且Network面板里没有任何对外域名的请求就说明成功了。3.3 代码改造点详解如果你不想用FastAPI_Offline类想把改造范围压到最小也可以保留原生FastAPI。举个例子假设原来的代码是from fastapi import FastAPI app FastAPI()那么你只需要三处改动第一处改成from fastapi import FastAPI from fastapi_offline.core import ( create_local_swagger_ui_html, create_local_redoc_html, ) app FastAPI(docs_urlNone, redoc_urlNone)第二处增加两个路由from fastapi.responses import HTMLResponse app.get(/docs, include_in_schemaFalse) async def offline_docs(): return create_local_swagger_ui_html( openapi_urlapp.openapi_url, title接口文档 - Swagger UI, oauth2_redirect_urlapp.swagger_ui_oauth2_redirect_url, ) app.get(/redoc, include_in_schemaFalse) async def offline_redoc(): return create_local_redoc_html( openapi_urlapp.openapi_url, title接口文档 - ReDoc, )第三处如果项目里有用到swagger_ui_oauth2_redirect_url也把它关掉或指向本地实现。因为fastapi-offline里面同样提供了本地化的OAuth2跳转页面但你如果不依赖OAuth2授权直接保持默认即可。这里特别提醒一下docs_urlNone, redoc_urlNone一定要设置。因为FastAPI实例化时如果默认带上/docs和/redoc你再用自定义路由去覆盖FastAPI内部可能会把原来的路由和自定义路由搞混导致路径冲突或assert报错。离线化改造最常见的错误就是忘了关默认路由。按照上面这种方式改完之后你的/docs和/redoc都是完全本地的不依赖任何公网地址。你可以打开浏览器的开发者工具在Network里过滤一下看看有没有请求发往非内网域名。正常情况下所有资源加载都来自/static/...或其他本机路径。4. 实操路线B完全不引入第三方依赖的手动静态资源方案4.1 下载并整理swagger-ui与redoc静态文件先解决资源来源。Swagger UI的静态文件可以到官方GitHub仓库的dist目录拿也可以直接通过npm下载npm pack swagger-ui-dist这个命令会生成一个swagger-ui-dist-x.x.x.tgz的压缩包解压后里面就是swagger-ui.css、swagger-ui-bundle.js、swagger-ui-standalone-preset.js、favicon.png等文件。Redoc同理可以到redoc仓库的bundles目录拿redoc.standalone.js。我习惯把目录结构整理成这样project_root/ ├── app/ │ └── main.py ├── static/ │ └── docs/ │ ├── swagger-ui.css │ ├── swagger-ui-bundle.js │ ├── swagger-ui-standalone-preset.js │ ├── redoc.standalone.js │ └── favicon.png这里有个小经验swagger-ui-dist包解压后可能还会包含swagger-ui.js、swagger-ui-es-bundle.js等文件但实际HTML里只需要swagger-ui-bundle.js和swagger-ui.css这两个核心文件其他可以不要减少体积。4.2 在FastAPI中挂载静态资源目录接下来在main.py里挂载静态目录from fastapi import FastAPI from fastapi.staticfiles import StaticFiles app FastAPI(docs_urlNone, redoc_urlNone) app.mount(/static, StaticFiles(directorystatic), namestatic)注意directory路径要写对。如果你用uvicorn app.main:app启动工作目录是项目根目录那么上面的static就没问题。如果用了包内路径建议用pathlib动态计算from pathlib import Path BASE_DIR Path(__file__).resolve().parent app.mount(/static, StaticFiles(directoryBASE_DIR.parent / static), namestatic)这样不管从哪个目录启动都不会因为相对路径问题导致静态文件404。这也是离线环境下特别常见的坑稍微一疏忽HTML出来了CSS和JS却返回404页面照样乱七八糟。4.3 自定义docs与redoc的HTML模板挂载完静态资源后需要自己写两个HTML响应函数。Swagger UI的HTML模板可以这样写from fastapi.responses import HTMLResponse SWAGGER_UI_HTML !DOCTYPE html html head meta charsetutf-8/ meta nameviewport contentwidthdevice-width, initial-scale1/ title{title} - Swagger UI/title link relstylesheet href/static/docs/swagger-ui.css/ link relicon typeimage/png href/static/docs/favicon.png/ /head body div idswagger-ui/div script src/static/docs/swagger-ui-bundle.js/script script src/static/docs/swagger-ui-standalone-preset.js/script script window.onload function() {{ window.ui SwaggerUIBundle({{ url: {openapi_url}, dom_id: #swagger-ui, deepLinking: true, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], layout: BaseLayout }}); }}; /script /body /html app.get(/docs, include_in_schemaFalse) async def custom_swagger_ui_html(): return HTMLResponse( SWAGGER_UI_HTML.format( titleapp.title, openapi_urlapp.openapi_url, ) )Redoc的HTML更简单redoc.standalone.js是自包含的REDOC_HTML !DOCTYPE html html head meta charsetutf-8/ meta nameviewport contentwidthdevice-width, initial-scale1/ title{title} - ReDoc/title style body {{ margin: 0; padding: 0; }} /style /head body div idredoc-container/div script src/static/docs/redoc.standalone.js/script script Redoc.init( {openapi_url}, {{ scrollYOffset: 50, hideDownloadButton: false, }}, document.getElementById(redoc-container) ); /script /body /html app.get(/redoc, include_in_schemaFalse) async def custom_redoc_html(): return HTMLResponse( REDOC_HTML.format( titleapp.title, openapi_urlapp.openapi_url, ) )这里有两个细节要提醒。第一是Redoc.init的第三个参数必须是document.getElementById(redoc-container)如果误传成字符串redoc-container页面会一直空白且不报错。第二是HTML里的大括号如果你用Python的str.format格式化记得把CSS和JS里的大括号都写成双括号{{}}否则会报KeyError。如果觉得转义麻烦也可以换成string.Template或者直接不换行拼接字符串但双括号是最标准的做法。然后不要忘了也可以一并处理/openapi.json。虽然FastAPI默认会暴露这个路径但如果你的部署环境对API元数据有安全要求也可以加上访问控制后面我会专门说。4.4 复用CDN缓存带版本号的本地映射手动方案还有一个进阶玩法把CDN资源按版本号保存下来统一放到一个静态资源根目录然后多个服务共享引用。比如/opt/offline-docs/ ├── swagger-ui/ │ └── 5.17.14/ │ ├── swagger-ui.css │ └── swagger-ui-bundle.js ├── redoc/ │ └── 2.1.5/ │ └── redoc.standalone.js这样你只需要在一个服务器上维护一套离线文档资源各服务通过Nginx或内部HTTP服务引用即可。更新的逻辑就是替换版本号目录然后改一下模板里的版本号不用每个服务都塞一份静态文件。内网环境如果有多个后端服务建议采用这种集中式管理减少重复体积也方便后续升级Swagger UI版本。5. 部署现场实录与常见问题排查5.1 常见问题速查表离线化改造过程中我整理了下面这张排查表基本覆盖了大部分现场情况症状可能原因处理方法/docs白屏控制台显示CDN域名超时没走离线化方案用的默认CDN按上文方案做本地化改造/docs可以打开但样式全是裸HTML只有HTML模板改了静态资源没挂载或路径不对检查app.mount(/static, ...)和浏览器Network里的CSS请求静态资源请求404StaticFiles目录路径错误或工作目录不同用Path(__file__).resolve()计算绝对路径Swagger页面出现“Unable to render this definition”/openapi.json路径不对或CORS问题检查openapi_url内网跨域时配置CORS中间件Redoc一直转圈redoc.standalone.js没加载或版本太老确认脚本加载成功换成最新release版本接口文档能看但点“Try it out”无响应JS被CSP内容安全策略拦截检查服务返回的Content-Security-Policy头页面中文显示乱码HTML模板没有指定charsetutf-8在head里补上meta charsetpip离线安装失败wheel包平台不匹配用--platform/--python-version重新下载5.2 动态参数下Swagger调试失败怎么办还有一个画面很常见内网部署后Swagger UI能正常显示了接口列表也出来了但你点开一个接口填好参数点“Execute”结果请求发不出去或者请求地址跟你预期的不一样。问题往往出在servers配置上。FastAPI默认的openapi里servers是空的Swagger UI会使用当前页面的host作为请求地址。如果前端通过http://192.168.1.10:8000/docs访问Swagger默认请求http://192.168.1.10:8000通常是没问题的。但如果你的服务前面挂了Nginx且对外暴露的端口或路径做了映射就得手动在FastAPI里配置serversapp FastAPI( docs_urlNone, redoc_urlNone, servers[ {url: http://192.168.1.10:8000, description: 内网环境}, ], )这样Swagger UI的请求地址就会以这里配置的为准。内网环境通常没有公网域名写清内网IP或内部域名即可。如果服务后面还有网关路径前缀比如/api/v1那servers的url也要带上路径前缀否则调试时路径对不上。5.3 安全加固内网文档访问控制文档能做出来是一回事但内网不等于安全。很多内网环境最终还是要过等保或安全审计/docs、/redoc、/openapi.json都算敏感信息暴露面。我一般建议至少做两层控制第一层简单认证。用fastapi_offline.auth.optional_auth或者自己加一个依赖函数from fastapi import Depends, HTTPException, status from fastapi.security import HTTPBasic, HTTPBasicCredentials security HTTPBasic() def verify_docs_auth(credentials: HTTPBasicCredentials Depends(security)): if credentials.username ! admin or credentials.password ! your_password: raise HTTPException( status_codestatus.HTTP_401_UNAUTHORIZED, detail认证失败, headers{WWW-Authenticate: Basic}, ) return credentials.username app.get(/docs, include_in_schemaFalse, dependencies[Depends(verify_docs_auth)]) async def custom_docs(): ...第二层限制来源IP。如果服务部署在Nginx后可以在Nginx里加allow/deny规则只允许运维网段或办公网段访问/docs、/redoc和/openapi.json。FastAPI应用自身也可以根据request.client.host做判断但更推荐在网关层做应用层尽量保持简单。5.4 性能提升资源缓存与压缩离线化之后还有一个额外的好处你可以放心给这些静态资源加长缓存。因为内网这些文件基本不会变Swagger UI的JS和CSS动辄一两MB如果不做缓存每次打开文档都会拉一遍全量资源内网用户多了也会给服务带来不必要的压力。在FastAPI层面可以用StaticFiles自带的缓存头或者干脆用Nginx托管/static/docs目录并配置location /static/docs/ { alias /opt/myapp/static/docs/; expires 30d; add_header Cache-Control public, immutable; }如果对响应体积敏感还可以开启gzip压缩。Swagger UI的JS是压缩过的但CSS和Redoc的redoc.standalone.js仍有压缩空间Nginx配置gzip on; gzip_types text/css application/javascript;即可。实测下来静态资源这一块能减少70%左右的传输体积文档页首次打开速度快不少。结尾这套离线化方案我在好几个政企内部项目里都实际落地过从最开始折腾CDN代理到后面固定用fastapi-offline或手动挂载踩过的坑基本都写在上面了。如果只让我留一条建议那就是只要你的服务可能部署到内网哪怕现在还在开发阶段也建议从一开始就关掉默认的docs_url把文档路由改成离线化实现。这样等真正上生产的时候不会在文档白屏这种小事上卡流程。另外把静态资源版本号记录下来以后升级Swagger UI或Redoc时只要替换资源目录并更新模板里的引用路径就行整个维护成本非常低。