winodws下cpolar 公网穿透保姆级安装使用教程
适用场景：把本机运行的服务（如 FastAPI 天气接口）暴露为公网 HTTPS，供 Dify、Apifox、手机等访问。
重要：cpolar 是独立客户端，不是npm 包，不要使用npm install cpolar或npx cpolar。
一、cpolar 是什么
- 内网穿透工具：把本机某个端口（例如
8081）映射到公网上的一个HTTPS 地址。 - 和 localtunnel 的区别：cpolar 在国内网络下通常更稳定；不需要localtunnel 那种
bypass-tunnel-reminder请求头（不稳定需要科学上网）。
二、下载与安装（Windows）
- 浏览器打开https://www.cpolar.com（以官网为准）。
- 注册 / 登录账号。
- 进入下载页面，选择Windows版本，下载安装包。
- 双击安装，按向导完成（记住安装目录，后面若命令行找不到会用到）。
- 安装完成后，本机会有
cpolar.exe。- 若安装时勾选了「加入 PATH」，则任意打开CMD / PowerShell都能直接输入
cpolar。 - 若提示「不是内部或外部命令」，请看第八章。
- 若安装时勾选了「加入 PATH」，则任意打开CMD / PowerShell都能直接输入
三、绑定账号（authtoken）—— 只做一次即可
3.1 去哪里找 token
- 登录 cpolar控制台 / 个人中心。
- 找到Authtoken（或「认证令牌」），点击复制。
- 不要把 token 发给他人、不要提交到 Git、不要截图发到公开群。
3.2 去哪里执行绑定命令
在Windows 终端里执行：
正确方式：
- 按
Win + R，输入powershell或cmd，回车； - 或在 VS Code / Cursor下方终端里操作。
3.3 命令格式
若已加入 PATH：
cpolar authtoken<粘贴你的token>若未加入 PATH，先进入安装目录（示例路径请改成你的实际路径）：
cd"C:\Program Files\cpolar".\cpolar.exe authtoken <粘贴你的token>或者直接找到你安装的目录在路径处点击输入cmd打开
看到成功提示即表示本机已与账号绑定，一般换电脑或重装才需要重新绑定。
四、最常用命令：把本机 8081 端口穿透出去
4.1 前提：本机服务已在监听
例如你的 FastAPI 使用8081端口，且监听0.0.0.0（示例）：
uvicorn.run(app,host="0.0.0.0",port=8081)先在本机浏览器或 Apifox 测试：
http://127.0.0.1:8081/你的路径- 本机200再开 cpolar，否则公网也一定不通。
4.2 启动穿透
再打开第二个终端（第一个继续跑你的 Python 服务），执行：
cpolar http8081端口数字必须和本机服务完全一致。
若命令找不到，使用安装目录下的：
.\cpolar.exe http 80814.3 看公网地址
终端或 cpolar 控制台会显示类似：
https://xxxxxxxx.cpolar.io（具体域名以你控制台为准）
复制这个 HTTPS 地址，后续在浏览器/Apifox/第三方平台配置回调地址或 base URL 时会用到。
4.4 保持窗口不关
- 关掉运行
cpolar http 8081的终端≈ 隧道断开，公网地址不可用。 - 需要长期联调时：一个窗口跑服务，一个窗口跑 cpolar。
五、在 Apifox 里自测
- 方法、路径与 FastAPI 一致，例如POST
https://你的cpolar域名/weather。 - Header：
Authorization: Bearer itcast，Content-Type: application/json。 - Body：
{"location":"广州"}（示例）。 - 若 Apifox 报DNS / 代理类错误，可尝试更换 Agent或使用系统终端 curl对比。
六、免费版与地址变化
- 免费隧道子域名可能每次重启 cpolar 后变化。
- 每次域名变了，都要在 Apifox 或你配置过的第三方平台里更新 base URL。
- 需要固定子域名请查看官网付费套餐 / 保留域名说明。
七、常见问题排查
| 现象 | 原因 | 处理 |
|---|---|---|
npm ERR! 404搜不到 cpolar | 误用 npm | cpolar不是npm 包，用官网exe安装 |
cpolar不是内部或外部命令 | 未加入 PATH | cd到安装目录用\.\cpolar.exe，或手动添加 PATH |
| 公网 502 / 超时 | 本机服务未起或端口错 | 确认127.0.0.1:端口本机先通 |
| 第三方平台提示无法访问 localhost | 对方无法访问你电脑 | 必须用cpolar 提供的 https 域名，不能填127.0.0.1 |
| 昨天能用今天不行 | 隧道未开或域名变了 | 重新执行cpolar http 端口，更新 URL |
八、安全建议
- Authtoken、Bearer 密码不要写入公开仓库；可用环境变量或本地配置。
- 若 token 曾泄露，在cpolar 控制台重置。
- 个人学习用的简单 token（如
itcast）勿用于生产环境。
九、与 localtunnel 对照（便于笔记）
| 项目 | localtunnel | cpolar |
|---|---|---|
| 安装方式 | Node.js +npx localtunnel | 官网Windows 客户端 |
| 公网域名示例 | *.loca.lt | *.cpolar.io等（以控制台为准） |
| 额外请求头 | 常需bypass-tunnel-reminder | 不需要 |
| 国内稳定性 | 易 DNS / 超时 | 一般更适合国内联调 |
十、最简命令备忘（复制区）
# 1. 绑定账号（仅首次或重装后）cpolar authtoken<你的token># 2. 本机服务已在 8081 监听后，新开终端执行：cpolar http8081# 3. 用控制台给出的 https 地址 + 你的 API 路径做联调与第三方平台配置文档版本：整理自用笔记，命令以cpolar 官网最新说明为准；若界面或命令有更新，请以官网文档为准。