Space Router — 住宅IP代理路由

通过Space Router的正向代理，将您的HTTP请求经由住宅IP地址路由。

设置

环境变量SPACEROUTERPROXY_URL必须包含完整的代理URL，包括API密钥凭证：

SPACEROUTERPROXYURL=https://srliveYOURAPI_KEY@gateway.spacerouter.org

默认网关为https://gateway.spacerouter.org（端口443）。本地开发时，主机通常为localhost:8080。

何时使用此技能

当任务需要以下任一情况时，请使用Space Router：

• - 访问屏蔽数据中心IP或云提供商IP范围的网站
• 需要住宅IP轮换的网络爬取
• 用户明确要求您通过住宅代理路由流量
• 之前的HTTP请求因403错误或CAPTCHA挑战失败，表明存在基于IP的屏蔽
• 用户提到使用Space Router、住宅代理或住宅IP

在以下情况下不要通过代理路由：

• - 访问本地服务（localhost、127.0.0.1、内部主机名）
• 访问通过IP白名单进行身份验证的API（住宅IP不会被列入白名单）
• 用户明确要求直接发起请求

如何路由流量

Python SDK（推荐用于Python）

bash
pip install spacerouter

python
from spacerouter import SpaceRouter

with SpaceRouter(srliveYOURAPIKEY) as client:
resp = client.get(https://example.com)
print(resp.statuscode, resp.requestid)

异步用法：

python
from spacerouter import AsyncSpaceRouter

async with AsyncSpaceRouter(srliveYOURAPIKEY) as client:
resp = await client.get(https://example.com)
print(resp.statuscode, resp.requestid)

JavaScript/TypeScript SDK（推荐用于Node.js）

bash
npm install @spacenetwork/spacerouter

ts
import { SpaceRouter } from @spacenetwork/spacerouter;

const client = new SpaceRouter(srliveYOURAPIKEY);
const resp = await client.get(https://example.com);
console.log(resp.status, resp.requestId);
client.close();

CLI（用于Shell脚本和快速任务）

bash
pip install spacerouter-cli
spacerouter config set api-key srliveYOURAPIKEY
spacerouter request get https://example.com

其他有用的CLI命令：

bash
spacerouter status # 检查服务健康状态
spacerouter api-key list # 列出API密钥
spacerouter node list # 列出代理节点
spacerouter request get https://httpbin.org/ip --region US

curl / 环境变量

设置HTTPPROXY和HTTPSPROXY，使Shell会话中的所有HTTP客户端自动使用代理：

bash
export HTTPPROXY=$SPACEROUTERPROXYURL
export HTTPSPROXY=$SPACEROUTERPROXYURL

或者显式地将代理传递给curl：

bash
curl -x $SPACEROUTERPROXY_URL https://httpbin.org/ip

区域定位

使用ISO 3166-1 alpha-2代码（例如US、KR、JP、DE）通过特定国家的住宅IP路由请求：

Python：

python
client = SpaceRouter(srlivexxx, region=US)

动态更改区域（返回新客户端）

JavaScript：

ts
const client = new SpaceRouter(srlivexxx, { region: US });
const jpClient = client.withRouting({ region: JP });

curl：

bash
curl -x $SPACEROUTERPROXY_URL -H X-SpaceRouter-Region: US https://httpbin.org/ip

IP类型过滤

按IP地址类型过滤代理节点：residential（住宅）、mobile（移动）、datacenter（数据中心）或business（商业）。

Python：

python
client = SpaceRouter(srlivexxx, ip_type=mobile)

JavaScript：

ts
const client = new SpaceRouter(srlivexxx, { ipType: mobile });

SOCKS5支持

两个SDK都支持SOCKS5作为替代代理协议（默认端口1080）：

Python：

python
pip install spacerouter[socks]

client = SpaceRouter(srlivexxx, protocol=socks5, gateway_url=socks5://gateway:1080)

JavaScript：

ts
const client = new SpaceRouter(srlivexxx, {
protocol: socks5,
gatewayUrl: socks5://gateway:1080,
});

验证代理是否正常工作

配置代理后，确认流量通过住宅IP路由：

bash
curl -x $SPACEROUTERPROXY_URL https://httpbin.org/ip

返回的IP应与您机器的公网IP不同。您也可以运行验证脚本：

bash
bash {baseDir}/scripts/verify-proxy.sh

错误处理

SDK会针对代理层错误引发类型化异常：

Python示例：

python
from spacerouter import SpaceRouter, RateLimitError
import time

with SpaceRouter(srlivexxx) as client:
try:
resp = client.get(https://example.com)
except RateLimitError as e:
time.sleep(e.retry_after)

JavaScript示例：

ts
import { SpaceRouter, RateLimitError } from @spacenetwork/spacerouter;

const client = new SpaceRouter(srlivexxx);
try {
const resp = await client.get(https://example.com);
} catch (e) {
if (e instanceof RateLimitError) {
await new Promise((r) => setTimeout(r, e.retryAfter * 1000));
}
}

响应头

Space Router会向代理响应添加以下头信息：

在代理CONNECT请求上发送的路由头信息：

重要说明

• - 默认网关为https://gateway.spacerouter.org（HTTPS，端口443）。代理会为TLS流量建立CONNECT隧道——您的端到端加密得以保留。
• 当使用SPACEROUTERPROXYURL环境变量与curl时，即使目标是HTTPS，URL方案也可能是HTTP。代理会处理TLS隧道。
• 不要将代理URL放入NOPROXY或绕过列表中。
• API密钥以srlive为前缀，并作为代理URL中的用户名传递（密码为空）。
• 速率限制按API密钥计算，默认为每分钟60个请求。
• Python SDK需要Python >= 3.10。JS SDK需要Node.js >= 18。