Protocol、Host、Port、认证方式、环境变量、DNS 解析方式以及 Session / 粘性会话参数。
真正需要改多少代码，取决于原来的客户端转发方式和新代理的接入方式，不能只用“换一个地址”概括所有场景。
这类迁移问题在 922 S5、IPIDEA 等本地客户端型代理停止服务或用户更换代理供应商时尤其常见：
旧代码可能一直连接 127.0.0.1:5000 一类本地端口，而新的代理服务直接提供远程网关和认证凭证。
对开发者来说，真正要解决的不是“换一家代理商”，而是本地代理入口变成远程代理入口以后，程序哪些配置必须同步调整。
本文只讨论代码和网络配置迁移。922 S5 用户如果还需要查看产品功能如何对应、指纹浏览器如何重新配置，可参考 从 922 S5 迁移至 IPWeb：完整功能对应表与操作指南。
一、本地代理迁移到远程代理，真正会变什么？
如果旧程序通过本地客户端导出的代理端口访问网络，代码看到的通常只是一个本机地址，例如
127.0.0.1:5000。更换为远程代理后，程序需要直接连接代理服务商提供的网关，
因此连接入口、认证方式和部分运行环境配置都会发生变化。
| 检查项 | 本地客户端型代理常见情况 | 远程代理常见情况 | 迁移时要做什么 |
|---|---|---|---|
| 连接地址 | 127.0.0.1 / localhost |
远程 Host / 网关域名 | 替换实际连接入口 |
| 端口 | 由本地客户端监听 | 由代理服务商分配或固定 | 以当前后台或文档为准 |
| 认证 | 可能由本地客户端代为处理 | 常见为账密认证或来源 IP 白名单 | 把认证配置放到真正发起代理连接的一层 |
| IP 切换 / Session | 可能在客户端 UI 中控制 | 可能由用户名参数、Session 参数或后台规则控制 | 重新确认原来的“固定 / 切换”逻辑如何对应 |
| 运行依赖 | 依赖本地客户端进程 | 应用直接连接远程代理 | 检查旧客户端、启动脚本和环境变量是否仍在接管流量 |
因此，“能不能无缝迁移”不能只看代码语言。即使业务请求逻辑完全不变，只要代理入口从本地端口变成远程网关， 认证、DNS、超时和 Session 等配置仍需要重新验证。
二、改代码前先核对这 7 个参数
不要直接在项目里全局搜索并替换代理地址。先把旧配置和新配置按下面 7 项列出来，逐项确认差异。
| 参数 | 需要确认什么 | 常见迁移问题 |
|---|---|---|
Protocol |
当前使用 HTTP、HTTPS 代理还是 SOCKS5 | 代码仍按旧协议连接新端点 |
Host |
新的代理网关域名或 IP | 代码、配置文件或容器变量里仍残留 127.0.0.1 |
Port |
当前产品实际提供的端口 | 端口写死在多个环境中，改了一处但其他实例仍走旧端口 |
Username / Password |
代理认证凭证和参数格式 | 把平台登录账号当成代理认证账号，或特殊字符没有正确处理 |
Session |
是否需要保持同一出口、保持多久、如何触发切换 | 把旧客户端的 IP 生命周期直接套到新服务 |
| DNS | 域名是在本地解析还是由代理侧解析 | SOCKS5 / SOCKS5H 等解析行为变化后出现地区或连通性差异 |
| Timeout / 环境变量 | 连接超时、读取超时以及 HTTP_PROXY、HTTPS_PROXY、NO_PROXY |
程序配置已经修改，但运行环境仍覆盖为旧代理 |
IPWeb 当前动态代理的实际网关、端口和账号格式应以后台生成结果及 IPWeb 动态代理使用指南 为准，不建议把示例参数直接复制到生产环境。
三、Python / Node.js 最小迁移示例
下面只演示“本地代理地址 → 远程代理地址”的最小变化，不展开完整语言教程。 你的项目如果还使用了代理池、重试器、自定义 Agent、异步请求库或框架级中间件，需要继续检查这些封装层。
1. Python Requests：重点检查代理 URL 和环境变量
迁移前：连接本地代理端口
import requests
proxies = {
"http": "http://127.0.0.1:5000",
"https": "http://127.0.0.1:5000",
}
resp = requests.get(
"https://example.com/",
proxies=proxies,
timeout=(10, 30),
)迁移后：连接远程代理网关
import requests
proxy_url = "http://USERNAME:PASSWORD@gate1.ipweb.cc:7778"
proxies = {
"http": proxy_url,
"https": proxy_url,
}
resp = requests.get(
"https://example.com/",
proxies=proxies,
timeout=(10, 30),
)
Requests 官方支持通过 proxies 参数设置 HTTP(S) 代理，也会读取
HTTP_PROXY、HTTPS_PROXY、NO_PROXY 等环境变量。
因此“代码里已经改了，实际请求仍走旧代理”时，应同时检查运行环境。
更完整的 Requests 用法可参考
Python Requests 代理使用指南。
如果用户名或密码中包含 @、:、# 等 URL 特殊字符，
不要直接把原始值拼进代理 URL；优先使用库提供的独立认证字段，或只对凭证字段做正确的百分号编码。
2. Node.js Axios：重点检查 proxy 和 proxy.auth
import axios from "axios";
const response = await axios.get("https://example.com/", {
proxy: {
protocol: "http",
host: "gate1.ipweb.cc",
port: 7778,
auth: {
username: "USERNAME",
password: "PASSWORD"
}
},
timeout: 30000
});
Axios 在 Node.js 中可以通过 proxy 指定代理服务器，通过
proxy.auth 提供代理认证信息。若项目还配置了
httpAgent、httpsAgent 或代理环境变量，要确认最终生效的到底是哪一层配置。
不要只看业务文件里的一段代码就判断迁移已经完成。
四、迁移后怎么确认代理真的生效？
代码不报错不等于迁移完成。建议至少做下面 4 项验收。
- 确认实际出口 IP：从发生故障的同一台机器、容器或服务进程发起请求，检查返回的公网出口是否已经变成代理出口。
- 确认地区：如果使用了国家、州或城市参数，检查检测结果是否与配置目标一致；具体可用粒度以当前产品资源为准。
- 确认 Session：需要粘性会话时，连续请求观察出口是否按预期保持；需要轮换时，再验证触发切换后的结果。
- 确认原程序和最小请求一致：如果 cURL / 简单脚本可以工作，而业务程序失败，问题通常已经从“代理端点不可用”缩小到程序自身配置、环境变量或封装层。
验证时不要只看“请求是否返回 200”。还应记录实际连接的代理 Host、Port、协议、脱敏后的用户名结构和最终出口 IP， 这样后续出现问题时才能判断究竟是哪一层发生了变化。
五、迁移后常见故障怎么排查？
1. 仍然连接 127.0.0.1：旧配置没有真正退出
这是本地代理迁移最容易遗漏的问题。检查代码、配置文件、容器 Secret、启动参数以及
HTTP_PROXY / HTTPS_PROXY 等环境变量中是否仍保留旧地址。
如果旧代理客户端还在后台运行，也可能让部分请求继续走原链路。
2. HTTP 407 Proxy Authentication Required：先查代理认证
407 表示代理认证没有通过。优先检查代理账号密码、实际来源 IP 白名单、用户名参数格式和认证是否真正发给代理。 如果账号密码嵌入代理 URL，还要检查特殊字符编码。不要通过不断换出口 IP 或提高重试次数来掩盖认证错误。
3. Connection Timeout：区分“连不上代理”和“代理转发慢”
连接超时首先检查 Host、Port、防火墙、网络 ACL 和代理协议；读取超时则说明连接可能已经建立， 需要继续判断出口节点、目标站响应和当前网络质量。不要直接把所有超时都归因于“并发过高”。
4. 502 / 503：先确认错误是谁返回的
502 或 503 可能来自代理网关、上游出口、反向代理或目标服务。先结合响应头和日志确认响应来源， 再决定是否重试。对可重试请求可以使用有限次数的重试和退避策略，但不要在不了解原因时无限重试。
5. TLS / 证书错误：不要直接关闭证书校验
HTTPS 迁移后出现证书错误时，应先核对代理协议、CONNECT 隧道、系统时间、CA 信任链以及程序使用的证书包。
verify=False 或关闭严格证书校验只能作为受控调试手段，不应当作为生产环境的默认解决方案。
6. 程序和命令行结果不一致：检查运行环境
终端里的测试成功，但后台服务、Docker 容器或定时任务失败，通常意味着这些进程使用了不同的环境变量、 DNS、代理配置或运行账号。应在真正执行任务的环境里复现，而不是只在开发机终端测试。
六、原来使用 922 S5 / IPIDEA，需要额外检查什么？
922 S5 / IPIDEA 只是“本地代理迁移到远程代理”的一个典型历史场景。为了避免这篇文章继续依赖过时热点， 这里只保留迁移时真正需要检查的旧配置。
- 搜索所有
127.0.0.1/localhost代理地址：确认业务程序、浏览器配置、脚本和容器中没有继续指向旧客户端。 - 确认旧客户端是否还在监听端口：即使 UI 已关闭，后台进程或开机启动项仍可能保留。
- 重新确认认证方式：旧客户端可能代为处理认证；改成远程代理后，需要把认证信息放到应用实际发起代理连接的位置。
- 重新定义 Session / IP 生命周期：不要默认新服务的粘性时长、刷新方式和旧客户端完全一致，以当前产品规则为准。
- 浏览器类工具单独迁移：指纹浏览器、系统代理和浏览器扩展的配置不等同于代码迁移，操作步骤放到专门的迁移指南中处理。
如果你的目标仍然是完整完成 922 S5 的产品和工具迁移，而不是只修改代码，请继续查看 从 922 S5 迁移至 IPWeb：完整功能对应表与操作指南。
七、常见问题
不一定。很多项目的业务请求逻辑可以保持不变，但代理入口、认证、环境变量和 Session 等配置通常需要调整。 如果项目把代理逻辑封装在统一配置层，改动可能很小；如果代理地址散落在多个模块、容器和启动脚本中，迁移工作会明显增加。
常见原因是环境变量、全局 Session、框架中间件、自定义 Agent 或容器配置覆盖了业务代码。 应检查程序最终生效的代理设置，而不是只检查某一个配置文件。
不一定。不同库对 SOCKS5 的依赖、DNS 解析方式和 Agent 支持不同。
例如 Python Requests 使用 SOCKS 时需要安装相应依赖，且 socks5 与 socks5h 的 DNS 解析位置不同。
迁移前应先核对当前客户端库的官方说明。
这通常说明代理端点和凭证本身基本可用，应继续检查程序的环境变量、代理库、Agent、URL 编码和运行环境。 用同一台机器、同一网络、同一组凭证做最小对照，定位会更快。
先确认请求是否真的经过了新的代理 Host 和 Port，再检查系统代理、环境变量、NO_PROXY、
规则分流以及旧客户端是否仍在接管流量。只有确认请求进入新代理后，才需要继续检查出口选择和 Session 参数。
下一步你可以做什么
迁移时先建立一份“旧配置 → 新配置”对照表，再用最小请求验证新的代理端点。 最小请求通过后，再逐步恢复 Session、地区参数、业务并发和框架封装。 这样可以把“代理不可用”“认证失败”和“业务代码配置错误”分开处理，避免一次修改太多变量。
