FastAPI 本地接口怎么给外部同事调试用 cpolar 打通 Swagger 文档和回调测试链路后端接口写在本机自己访问http://127.0.0.1:8000/docs一切正常同事在异地测试时却不能打开你的 Swagger 文档也不能直接调用回调接口。这不是 FastAPI 的问题而是localhost只指向调用者自己的电脑。这篇文章用一个最小 FastAPI 项目演示完整联调链路本地启动接口、用 curl 验证、打开 Swagger 文档再用 cpolar 把本地 8000 端口临时映射成公网 HTTPS 地址让外部同事可以访问/docs并调用测试接口。本文专注通用 FastAPI Swagger 接口联调。它和近期常见的 n8n Webhook 教程、RAG 知识库问答演示不同n8n Webhook 重点是自动化流程触发本文重点是后端接口文档与接口调试。RAG 演示重点是向量库、知识检索和模型回答本文不引入数据库、向量库和大模型。本文只保留/health、/api/echo、/api/callback-test三个简单接口保证命令可复现。一、准备环境本文命令以 macOS / Linux 终端为例Windows 用户可在 PowerShell 中执行等价命令。先创建一个干净目录mkdirfastapi-cpolar-democdfastapi-cpolar-demo创建 Python 虚拟环境python3-mvenv .venv激活虚拟环境source.venv/bin/activate安装 FastAPI 和 Uvicornpipinstallfastapi uvicorn确认安装结果python-cimport fastapi, uvicorn; print(fastapi and uvicorn installed)二、编写一个最小 FastAPI 服务创建main.pycatmain.pyPY from fastapi import FastAPI, Header, HTTPException from pydantic import BaseModel app FastAPI( titleFastAPI cpolar 联调示例, description用于演示本地 FastAPI 接口通过 cpolar 暴露给外部同事调试, version1.0.0, ) DEMO_TOKEN dev-token-123 class EchoRequest(BaseModel): message: str class CallbackPayload(BaseModel): event: str data: dict {} app.get(/health) def health(): return {status: ok} app.post(/api/echo) def echo(body: EchoRequest): return {received: body.message} app.post(/api/callback-test) def callback_test( payload: CallbackPayload, x_demo_token: str Header(default), ): if x_demo_token ! DEMO_TOKEN: raise HTTPException(status_code401, detailinvalid token) return { message: callback received, event: payload.event, data: payload.data, } PY这个示例做了三件事/health给同事快速确认服务是否在线。/api/echo测试普通 POST JSON 请求。/api/callback-test模拟第三方回调接口并用X-Demo-Token请求头做一个简单边界保护。这里的DEMO_TOKEN只用于本地开发演示。真实项目不要把生产密钥、数据库密码、云服务 AccessKey 写进示例代码也不要把带生产权限的接口直接暴露到公网。三、本地启动 Uvicorn执行uvicorn main:app--host127.0.0.1--port8000--reload看到类似输出即表示服务已启动Uvicorn running on http://127.0.0.1:8000--host 127.0.0.1表示服务只监听本机回环地址。这样做适合开发调试避免局域网内其他设备直接访问你的开发服务。后面由 cpolar 负责建立临时公网访问入口。四、先用 curl 做本地验证新开一个终端进入项目目录并激活虚拟环境cdfastapi-cpolar-demosource.venv/bin/activate验证健康检查接口curlhttp://127.0.0.1:8000/health返回{status:ok}验证 echo 接口curl-XPOST http://127.0.0.1:8000/api/echo\-HContent-Type: application/json\-d{message:hello fastapi}返回{received:hello fastapi}验证带请求头的回调测试接口curl-XPOST http://127.0.0.1:8000/api/callback-test\-HContent-Type: application/json\-HX-Demo-Token: dev-token-123\-d{event:order.created,data:{id:1001}}返回{message:callback received,event:order.created,data:{id:1001}}再验证一次错误 tokencurl-i-XPOST http://127.0.0.1:8000/api/callback-test\-HContent-Type: application/json\-HX-Demo-Token: wrong-token\-d{event:order.created,data:{id:1001}}返回状态码为401 Unauthorized说明简单请求头校验已经生效。五、打开本地 Swagger 文档浏览器访问http://127.0.0.1:8000/docsFastAPI 会自动生成 Swagger UI。你可以在页面里看到/health、/api/echo、/api/callback-test三个接口并直接点击Try it out调试请求。本地链路到这里已经打通浏览器 / curl - 127.0.0.1:8000 - FastAPI - 返回 JSON但是外部同事的电脑访问127.0.0.1:8000时访问的是他自己电脑的 8000 端口不是你的电脑。要让同事访问你的本地 FastAPI需要一个临时公网入口。六、用 cpolar 暴露本地 8000 端口保持 Uvicorn 终端不要关闭。再新开一个终端执行cpolar http8000cpolar 会为本地 8000 端口生成一个公网访问地址终端中会显示类似下面的转发信息Forwarding https://xxxx.cpolar.top - http://localhost:8000把其中的 HTTPS 地址记下来。下文用https://xxxx.cpolar.top作为示例请替换成你终端里实际显示的地址。此时访问链路变成外部同事浏览器 - cpolar 公网 HTTPS 地址 - 你的本机 8000 端口 - FastAPI七、让外部同事访问 Swagger 文档把下面地址发给同事https://xxxx.cpolar.top/docs同事打开后可以看到同一份 FastAPI Swagger 文档。让同事先调/healthcurlhttps://xxxx.cpolar.top/health返回{status:ok}再调/api/echocurl-XPOST https://xxxx.cpolar.top/api/echo\-HContent-Type: application/json\-d{message:hello from teammate}返回{received:hello from teammate}最后调模拟回调接口curl-XPOST https://xxxx.cpolar.top/api/callback-test\-HContent-Type: application/json\-HX-Demo-Token: dev-token-123\-d{event:payment.success,data:{trade_no:T202605310001}}返回{message:callback received,event:payment.success,data:{trade_no:T202605310001}}与此同时你本机运行 Uvicorn 的终端会打印请求日志。调试接口时可以一边让同事发请求一边观察本地日志快速确认请求是否到达、路径是否正确、状态码是否符合预期。八、常见联调问题排查1./docs能打开但接口请求失败先看 Uvicorn 终端有没有请求日志。有日志请求已经到达 FastAPI检查接口路径、请求方法、JSON 字段和请求头。没日志检查同事访问的公网 URL 是否复制完整确认 cpolar 终端仍在运行。2./api/callback-test返回 401检查请求头名称和值X-Demo-Token: dev-token-123FastAPI 中使用的是x_demo_token: str Header(default)它对应的 HTTP 请求头就是X-Demo-Token。3. 本地 curl 正常公网访问不通按顺序检查curlhttp://127.0.0.1:8000/health再检查 cpolar 是否仍在运行cpolar http8000同一个联调会话中以当前 cpolar 终端显示的 HTTPS 地址为准。重启隧道后地址会刷新需重新发送给同事。九、安全边界只做开发/测试联调把本地接口暴露到公网前先确认下面几条只用于开发/测试环境不要把生产服务、生产数据库管理接口、生产后台管理接口直接映射出去。不要暴露生产密钥示例里的dev-token-123只是开发 token。真实项目中不要把生产 Token、Cookie、AccessKey、数据库密码发给同事调试。不要开放无鉴权管理接口删除用户、修改订单、导出数据、执行系统命令等接口不要通过临时公网 URL 裸露。公网 URL 用完关闭联调结束后立即关闭 cpolar 隧道避免调试入口长期暴露。控制日志内容本地日志中不要打印身份证号、手机号、密码、完整 Token 等敏感信息。这套方案适合短时间联调后端同事本机写接口测试同事或前端同事远程访问 Swagger 文档双方围绕请求参数、返回结构和状态码快速确认问题。十、关闭服务和隧道联调结束后在运行 cpolar 的终端按Ctrl C这会关闭公网隧道外部同事无法继续通过该 URL 访问你的本地服务。再到运行 Uvicorn 的终端按Ctrl C这会关闭本地 FastAPI 服务。如需退出虚拟环境deactivate十一、完整命令回顾mkdirfastapi-cpolar-democdfastapi-cpolar-demo python3-mvenv .venvsource.venv/bin/activate pipinstallfastapi uvicorncatmain.pyPY from fastapi import FastAPI, Header, HTTPException from pydantic import BaseModel app FastAPI( titleFastAPI cpolar 联调示例, description用于演示本地 FastAPI 接口通过 cpolar 暴露给外部同事调试, version1.0.0, ) DEMO_TOKEN dev-token-123 class EchoRequest(BaseModel): message: str class CallbackPayload(BaseModel): event: str data: dict {} app.get(/health) def health(): return {status: ok} app.post(/api/echo) def echo(body: EchoRequest): return {received: body.message} app.post(/api/callback-test) def callback_test( payload: CallbackPayload, x_demo_token: str Header(default), ): if x_demo_token ! DEMO_TOKEN: raise HTTPException(status_code401, detailinvalid token) return { message: callback received, event: payload.event, data: payload.data, } PYuvicorn main:app--host127.0.0.1--port8000--reload新开终端验证curlhttp://127.0.0.1:8000/healthcurl-XPOST http://127.0.0.1:8000/api/echo\-HContent-Type: application/json\-d{message:hello fastapi}curl-XPOST http://127.0.0.1:8000/api/callback-test\-HContent-Type: application/json\-HX-Demo-Token: dev-token-123\-d{event:order.created,data:{id:1001}}新开终端启动公网隧道cpolar http8000外部同事访问https://xxxx.cpolar.top/docs关闭隧道和服务Ctrl C总结FastAPI 自带 Swagger 文档很适合接口联调cpolar 解决的是“外部同事访问不到你本机localhost”这个网络问题。两者组合后本地开发者不用把代码部署到云服务器也能临时提供一个公网 HTTPS 地址给同事访问/docs、调用测试接口、验证回调请求。关键点只有三个先在本地用 curl 验证 FastAPI 接口可用。再用cpolar http 8000生成公网入口。联调完成后关闭隧道不把开发接口长期暴露在公网。按照这个流程后端、前端、测试三方可以围绕同一份 Swagger 文档完成低成本接口联调。