HomeProxy 开发者文档

标准代理协议接入,无 SDK 依赖。阅读本文档约需 5 分钟,之后即可通过住宅代理网络发出第一个请求。遇 401/403 等控制台接口问题请参考联系支持。

快速开始

1注册账户并完成邮箱验证,在控制台「代理配置 → 子用户」创建一个子用户(如crawler_01),得到网关用户名hp-crawler_01。
2使用子用户密码,向端点发起代理请求(HTTP 与 SOCKS5 同端口):

curl -x "http://hp-crawler_01:你的密码@gw.homeproxy.io:8000" \
  https://ip.homeproxy.io/location

# 返回出口 IP 归属地,响应头包含:
# X-Proxy-Egress-Ip: 104.28.219.87
# X-Proxy-Country: us

3需要定向或粘性会话时,在用户名中追加参数(见参数参考);也可使用控制台的端点生成器可视化生成。

认证方式

网关支持用户名密码与 IP 白名单两种认证,可并存。

用户名密码(推荐)

控制台创建的代理子用户凭据,格式为hp-<子用户名>+ 参数,密码即子用户密码。支持 HTTP Basic 与 URL 内嵌。

http://hp-USER:[email protected]:8000

IP 白名单免密

将服务器公网 IP 加入白名单(最多 10 条)后,通过独立端口免密使用,适合无法附带凭据的固定环境。控制台支持一键添加当前出口 IP。

http://gw.homeproxy.io:8080

# 白名单内 IP 无需用户名密码
curl -x "http://gw.homeproxy.io:8080" \
  https://ip.homeproxy.io/location

参数参考

所有控制参数通过代理用户名携带,以 - 分隔,顺序任意。

格式:  hp-<子用户名>[-session-<id>][-country-<国家>][-city-<城市>][-st-<州>][-asn-<编号>][-ttl-<时长>]

示例:  hp-USER_abc123-session-x7f2-country-us-city-losangeles-ttl-30m
密码:  对应子用户密码

参数	示例	必填	说明
session	session-x7f2	粘性会话必填	会话标识。携带后保持同一出口 IP;相同 session 复用同一会话。轮换模式不携带。
country	country-us	可选	国家代码(ISO 3166-1 alpha-2 小写),如 us、de、jp。不携带时随机全球出口。
city	city-losangeles	可选	城市定向,需配合 cc 使用,值为小写无空格城市名,如 losangeles、frankfurt。
state	state-california	可选	州/省定向,值为小写无空格州名,如 california、bavaria。
asn	asn-7224	可选	运营商 ASN 编号,如 7224(Rackspace)、3320(Deutsche Telekom),粒度最细。
ttl	ttl-30m	粘性会话必填	会话保持时长,可选 1m / 10m / 30m / 24h,超时后自动更换出口 IP。

会话控制(ttl)

粘性会话保持同一出口 IP 的时长,取值如下。

ttl	适用场景
1m	适合单页短流程,轻微 IP 抖动无影响
10m	适合分页 API、列表翻页采集
30m	适合需要短时登录态的操作
24h	适合账号管理、长期监控任务

响应头X-Proxy-Session-Id会回显当前 session,便于排查会话未命中的问题。轮换模式(不携带 session)下每个请求分配新出口 IP。

协议说明

HTTP/HTTPS 与 SOCKS5 统一端点;白名单免密走独立端口。

端点	协议	认证
gw.homeproxy.io:8000	HTTP/HTTPS CONNECT + SOCKS5	用户名密码
gw.homeproxy.io:8080	HTTP/HTTPS	IP 白名单免密

HTTPS 通过 CONNECT 隧道转发,端到端 TLS 加密,网关无法解密内容;上下行总流量按 GB 计费,协议头部开销不计入。调试时响应头X-Proxy-Egress-Ip / X-Proxy-Country可验证出口归属。

错误码

网关通过 HTTP 状态码与 X-Proxy-Error 头传递失败原因。

407Proxy Authentication Required

常见原因: 子用户密码错误、子用户被删除或账号流量用尽
排查建议: 在控制台「代理配置 → 子用户」核对凭据;确认套餐用量未达上限;重置子用户密码。

429Too Many Requests / quota-exceeded

常见原因: 流量配额用尽(X-Proxy-Error: quota-exceeded)或触发公平使用限速
排查建议: 前往「账单」充值流量包或升级套餐;确认任务并发在合理范围。

502Bad Gateway / no-match-location

常见原因: 定向参数无匹配在线出口(X-Proxy-Error: no-match-location)
排查建议: 放宽定向粒度(如去掉 city/asn);稍后重试,网关会自动换 IP 重试最多 3 次。

代码示例

多语言接入示例,可直接复制到本地运行。

通过 HomeProxy 发起代理请求

import requests

proxies = {
    "http": "http://hp-crawler_01:[email protected]:8000",
    "https": "http://hp-crawler_01:[email protected]:8000",
}

# 轮换代理:每个请求分配不同出口 IP
r = requests.get("https://ip.homeproxy.io/location", proxies=proxies)
print(r.json())

# 粘性会话:通过 session + ttl 控制会话时长
username = "hp-crawler_01-session-x7f2-country-us-ttl-30m"
proxies = {
    "http": f"http://{username}:[email protected]:8000",
    "https": f"http://{username}:[email protected]:8000",
}
r = requests.get("https://ip.homeproxy.io/location", proxies=proxies)
print(r.headers.get("X-Proxy-Session-Id"))  # x7f2

第三方集成

住宅代理与主流工具链即开即用,以下为常见配置方式。

Scrapy(middlewares.py)

class ProxyMiddleware:
    def process_request(self, request, spider):
        request.meta["proxy"] = "http://hp-crawler_01-country-us:[email protected]:8000"

# settings.py
DOWNLOADER_MIDDLEWARES = {"yourproject.middlewares.ProxyMiddleware": 350}

环境变量(cURL / 多数 CLI 工具)

export http_proxy="http://hp-crawler_01:[email protected]:8000"
export https_proxy="http://hp-crawler_01:[email protected]:8000"

curl https://ip.homeproxy.io/location

Puppeteer / Playwright

const browser = await puppeteer.launch({
  args: [
    `--proxy-server=http://gw.homeproxy.io:8000`,
  ],
});

const page = await browser.newPage();
await page.authenticate({
  username: "hp-crawler_01-country-us-ttl-10m",
  password: "PASS",
});