lesson-05

5.1 为什么我们需要"局部"代理？

在抓取数据时，我们常常面临一个两难的境地：

1. 不挂代理：IP 被封，抓取失败。
2. 挂全局 VPN：宿主机的所有流量（如 GitHub push、SSH 登录、甚至系统更新）都被迫走 VPN，不仅网速受影响，还可能违反企业合规策略。

解决方案：局部 SOCKS5 代理。

通过将 Cloudflare WARP 配置为 SOCKS5 代理，WARP 客户端只会在宿主机上开放一个特定端口（如 localhost:40000）。只有主动将请求发送到这个端口的程序（如我们的 Docker 容器），其流量才会通过 WARP 路由出海。 宿主机的其余流量完全不受影响。

---

5.2 macOS 环境下的 WARP 配置实战

注意：macOS 上不能仅仅安装命令行工具，必须安装 Desktop GUI 客户端。

步骤 1：安装 Cloudflare WARP 客户端

访问 Cloudflare WARP 官网 (1.1.1.1) 下载并安装 macOS 客户端。 安装完成后，在系统状态栏会出现一朵灰色的云朵图标，请暂时不要点击开启连接。

步骤 2：使用 CLI 将模式切换为 Proxy

打开终端，使用 Cloudflare 提供的内置 CLI 工具 warp-cli 进行配置：

# 1. 接受服务条款
warp-cli registration new

# 2. 将模式从默认的 'warp' (全局DNS) 切换为 'proxy' (局部 SOCKS5)
warp-cli mode proxy

# 3. 指定 SOCKS5 监听的本地端口 (默认是 40000，推荐明确设置)
warp-cli proxy port 40000

# 4. 开启连接
warp-cli connect

# 5. 查看当前连接状态
warp-cli status
# 预期输出: Status update: Connected

步骤 3：验证代理是否生效

现在，你的宿主机上运行着一个监听在 127.0.0.1:40000 的 SOCKS5 代理。我们来测试一下：

# 测试一：直接访问（显示你的真实宽带 IP）
curl -s https://www.cloudflare.com/cdn-cgi/trace | grep "ip\|warp"
# 输出示例: 
# ip=114.254.x.x
# warp=off

# 测试二：通过代理访问（应该显示 Cloudflare 边缘 IP）
curl -s -x socks5h://localhost:40000 https://www.cloudflare.com/cdn-cgi/trace | grep "ip\|warp"
# 输出示例: 
# ip=104.28.208.x (Cloudflare IP)
# warp=on

恭喜！如果两个测试的输出如上所示，说明你的局部代理已经完美搭建成功。

---

5.3 Linux / Docker 宿主机环境下的配置

如果你是在 Ubuntu 等 Linux 服务器上部署，步骤会更直接，不需要 GUI：

# 1. 添加 Cloudflare 源并安装
curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | sudo gpg --yes --dearmor --output /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflare-client.list
sudo apt-get update && sudo apt-get install cloudflare-warp

# 2. 注册并配置代理模式
warp-cli registration new
warp-cli mode proxy
warp-cli proxy port 40000

# 3. （可选且重要）修改监听地址以允许 Docker 访问
# 默认只监听 127.0.0.1，Docker 容器可能无法访问。
# 需要让其监听 Docker 网桥地址（如 172.17.0.1）或 0.0.0.0（不推荐）
warp-cli add-custom-endpoint 172.17.0.1:40000

# 4. 连接
warp-cli connect

---

5.4 故障排除 (Troubleshooting)

问题现象	可能原因	解决办法
curl 返回 Connection refused	WARP 未连接，或端口未监听	检查 warp-cli status，确保已 connect
warp-cli 命令找不到	环境变量未更新	macOS 重启终端，或手动执行 /Applications/Cloudflare WARP.app/Contents/Resources/warp-cli
无法在 Docker 容器中访问 localhost:40000	localhost 指向了容器内部，而非宿主机	请看下一课：在 Docker 中使用 host.docker.internal

---

5.5 课后问题

1. macOS 和 Linux 安装 warp-cli 的最大区别是什么？
2. curl 命令中的 -x socks5h:// 中，h 代表什么含义？为什么要用 socks5h 而不是 socks5？
3. 如果我不小心使用了 warp-cli mode tunnel，会发生什么？