cpolar-connect 0.3.0

Easy-to-use CLI tool for cpolar tunnel management and SSH connections

Cpolar Connect

中文 | English

🚀 自动化管理 cpolar 内网穿透连接的命令行工具

✨ 为什么需要这个工具？

cpolar 免费版的隧道地址会时不时重置，每次都需要：

1. 登录 cpolar 网站查看新地址
2. 手动更新 SSH 配置
3. 记住新的端口号

Cpolar Connect 会解决这些问题。

🎯 主要特性

• 🔄 自动更新: 自动获取最新的 cpolar 隧道地址
• ⚡ 一键连接: 无需记忆地址和端口
• 🔑 SSH 密钥: 自动配置免密登录
• 🛡️ 主机密钥校验: 自动记录并校验服务器主机密钥，防中间人攻击
• 👥 多账户: cpc use / -a 在多个 cpolar 账户间快捷切换
• 📦 简单安装: 一行命令即可使用

📦 安装方法

方式一：使用 uv（推荐，最快）

首先安装 uv：

Linux/macOS:

# 使用官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 pip
pip install uv

Windows:

# 使用 PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或使用 pip
pip install uv

然后运行 cpolar-connect：

# 直接运行（无需安装）
uvx cpolar-connect

# 或安装到系统
uv tool install cpolar-connect

方式二：使用 pipx（独立环境）

# 安装
pipx install cpolar-connect

# 升级
pipx upgrade cpolar-connect

方式三：使用 pip

pip install cpolar-connect

🚀 快速开始

服务器端配置

服务器需要先安装并运行 cpolar，详见 服务器配置指南

快速配置（Linux）：

# 1. 安装 cpolar
curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash

# 2. 配置认证（需要先注册 cpolar 账号）
cpolar authtoken YOUR_TOKEN

# 3. 设置开机自启
sudo systemctl enable cpolar
sudo systemctl start cpolar

# 4. 查看用户名（客户端配置需要）
whoami

客户端配置

1️⃣ 初始化配置

cpolar-connect init

交互式配置向导（三步完成）：

┌ Cpolar Connect 配置向导
◆  步骤 1: Cpolar 账户
│  请输入 cpolar 用户名: [e-mail]
│  ✓ 用户名: [e-mail]
│  请输入 cpolar 密码: ********
│  ✓ 密码已保存
│  ◌ 正在验证账户...
│  ✓ 账户验证成功
◆  步骤 2: 服务器配置
│  请输入服务器用户名: root
│  ✓ 服务器用户: root
│  请输入要转发的端口（逗号分隔） (8888,6666): 8888
│  ✓ 端口: 8888
◆  步骤 3: 连接选项
│  更新后自动连接？ (Y/n):
│  ✓ 自动连接: 是
│
│  ─── 配置摘要 ───
│  用户名:     [e-mail]
│  密码:       是
│  服务器用户: root
│  端口:       8888
│  自动连接:   是
│
└ 配置完成！运行 'cpolar-connect' 开始连接。

2️⃣ 连接服务器

# 直接连接
cpolar-connect

# 或使用环境变量提供密码
CPOLAR_PASSWORD=your_password cpolar-connect

就这么简单！ 工具会自动：

• 登录 cpolar 获取最新地址
• 生成 SSH 密钥（首次）
• 配置免密登录
• 建立连接并转发端口

⚙️ 配置管理

查看配置

cpolar-connect config show

修改配置

# 修改服务器用户
cpolar-connect config set server.user root

# 修改端口
cpolar-connect config set server.ports 8080,3000

# 直接编辑配置文件
cpolar-connect config edit

切换语言

# 中文
cpolar-connect language zh

# English
cpolar-connect language en

查看状态

cpolar-connect status

显示当前隧道地址、SSH 配置等信息（不发起连接）：

字段	值
隧道	tcp://x.tcp.vip.cpolar.cn:xxxxx
主机	x.tcp.vip.cpolar.cn
端口	xxxxx
SSH 别名	cpolar-server
SSH 密钥	~/.ssh/id_rsa_cpolar
自动连接	是
转发端口	8888

🔒 密码管理

选项 1：初始化时保存（推荐）

运行 cpolar-connect init 时输入密码，会自动存储到 ~/.cpolar_connect/accounts/<账户>/.password 文件。

选项 2：环境变量

export CPOLAR_PASSWORD=your_password
cpolar-connect

选项 3：临时通过环境变量提供

初始化时密码直接按回车跳过，连接前通过 CPOLAR_PASSWORD 环境变量提供。

🛡️ 主机密钥校验

从 v0.2.4 起，工具会校验服务器的 SSH 主机密钥以防中间人攻击：

• 首次连接自动记录服务器主机密钥到 ~/.cpolar_connect/accounts/<账户>/known_hosts（TOFU，按 SSH 别名存储，不受隧道地址变化影响）
• 之后每次连接（包括密钥测试与公钥上传）都会校验，密钥不一致将拒绝连接
• 服务器重装等导致主机密钥合法变更时，运行以下命令重置后重连：

cpolar-connect config clear-hostkey

此外，首次连接会先尝试使用已有 SSH 密钥（ssh-agent/默认密钥）自动完成公钥上传，成功则全程无需输入服务器密码。

👥 多账户

从 v0.3.0 起支持多个 cpolar 账户（对应不同服务器）。所有命令均可使用短入口 cpc（与 cpolar-connect 完全等价）：

cpc init -a work          # 创建账户 work 并切换过去（SSH 别名自动为 cpolar-work）
cpc use home              # 切换当前账户，长期生效
cpc -a work               # 临时用 work 账户连接一次，不改当前选择
cpc list                  # 列出所有账户（等价于 cpc account list）
cpc account remove work   # 删除账户（连带清理对应的 SSH 配置块）

• 账户解析优先级：-a 参数 > CPOLAR_ACCOUNT 环境变量 > 当前账户 > default
• 旧版单账户配置会在升级后首次运行时自动迁移为 default 账户，无需任何操作
• 注意：CPOLAR_PASSWORD 环境变量对所有账户生效，各账户密码不同时请勿使用
• 已知限制：PyPI 上存在同名的 cpc 包（竞赛编程工具）。若你已安装该包，用 pipx/uv tool 安装本工具时会因命令名冲突需要 --force；主入口 cpolar-connect 不受影响

📚 使用场景

Jupyter Notebook

# 配置端口 8888
cpolar-connect config set server.ports 8888

# 连接后本地访问
# http://localhost:8888

多端口转发

# 配置多个端口
cpolar-connect config set server.ports 8888,6006,3000

# 连接后：
# localhost:8888 -> 服务器:8888 (Jupyter)
# localhost:6006 -> 服务器:6006 (TensorBoard)
# localhost:3000 -> 服务器:3000 (Web App)

SSH 别名快速连接

# 连接成功后，可使用别名
ssh cpolar-server

🔔 适用范围与限制

• 支持的套餐：当前仅支持并在 cpolar 免费套餐（Free）下验证。该工具依赖"隧道地址会周期性重置"的前提来获取最新地址并更新 SSH 配置。
• 订阅套餐：订阅套餐（如固定域名、自定义域名、专属隧道、多隧道等）未在本工具中做兼容性验证，行为未预期

📁 文件位置

• 配置文件：~/.cpolar_connect/accounts/<账户>/config.json
• 密码文件：~/.cpolar_connect/accounts/<账户>/.password（权限 600）
• 主机密钥：~/.cpolar_connect/accounts/<账户>/known_hosts
• 当前账户：~/.cpolar_connect/current
• SSH 密钥：~/.ssh/id_rsa_cpolar
• 日志文件：~/.cpolar_connect/logs/cpolar.log

🏥 诊断工具

遇到问题时，使用内置诊断工具快速定位：

cpolar-connect doctor

检查项	说明
配置文件	配置文件完整性
密码存储	密码是否已保存
网络连接	网络连通性
SSH 密钥	私钥/公钥是否存在
SSH 配置	~/.ssh/config 配置项
Cpolar 认证	账户验证
隧道状态	活动隧道检测

❓ 常见问题

无法连接？

1. 运行诊断：cpolar-connect doctor
2. 确认服务器 cpolar 正在运行：sudo systemctl status cpolar
3. 确认用户名密码正确
4. 查看详细日志：CPOLAR_LOG_LEVEL=DEBUG cpolar-connect

如何卸载？

# uv
uv tool uninstall cpolar-connect

# pipx
pipx uninstall cpolar-connect

# pip
pip uninstall cpolar-connect

支持哪些系统？

• ✅ Linux (Ubuntu, CentOS, Debian...)
• ✅ macOS
• ❓ Windows

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 详见 LICENSE

🔗 相关链接

• cpolar 官网
• 服务器配置指南
• 问题反馈

---

感谢你的STAR🌟，希望这一切对你有所帮助。