代理配置

概述

在以下场景中，为 igapi 客户端配置代理非常必要：

调试与逆向分析：使用 Charles、mitmproxy 等抓包工具截获并分析 Instagram 的请求和响应，有助于理解 API 行为、排查异常。

网络访问限制：在某些网络环境中，直连 Instagram 服务器存在障碍，需要通过代理节点转发流量。

安全隔离：在自动化测试或批量操作场景中，通过代理对出口 IP 进行统一管理，避免同一 IP 下并发请求过多触发风控。

igapi 的 Client（Android/iOS 平台）和 WebClient（Web 平台）均在构造时支持代理相关参数，无需修改系统全局代理即可生效。

---

基本代理配置

所有客户端构造函数接受相同的代理参数，在实例化时传入即可：

import igapi

# Android 客户端（登录后使用）
client = igapi.Client(
    proxy="http://127.0.0.1:8080",
    danger_accept_invalid_certs=True,
    http1_only=True,
)

# Web 客户端
web = igapi.WebClient(
    proxy="http://127.0.0.1:8080",
    danger_accept_invalid_certs=True,
    http1_only=True,
)

不使用代理时，三个参数均可省略，客户端直接连接 Instagram 服务器：

# 不使用代理（默认行为）
client = igapi.Client()
web = igapi.WebClient()

---

配合 Charles / mitmproxy 抓包

Charles 配置步骤

1. 启动 Charles，默认监听 127.0.0.1:8888
2. 在 Charles 中开启 SSL Proxying（Proxy → SSL Proxying Settings），添加 *.instagram.com 和 *.cdninstagram.com
3. 在代码中配置客户端：

import asyncio
import igapi

# 配合 Charles 抓包
client = igapi.Client(
    proxy="http://127.0.0.1:8888",
    danger_accept_invalid_certs=True,  # 信任 Charles 自签证书
    http1_only=True,                   # Charles 不支持 HTTP/2，强制降级
)

web = igapi.WebClient(
    proxy="http://127.0.0.1:8888",
    danger_accept_invalid_certs=True,
    http1_only=True,
)

async def main():
    # 正常调用，所有请求均经 Charles 转发
    await web.login("用户名", "密码")

asyncio.run(main())

mitmproxy 配置步骤

1. 启动 mitmproxy，默认监听 127.0.0.1:8080

# 启动 mitmproxy 控制台界面
mitmproxy --listen-port 8080

# 或者启动 Web 界面（浏览器访问 http://127.0.0.1:8081）
mitmweb --listen-port 8080 --web-port 8081

# 或者仅输出到终端
mitmdump --listen-port 8080

1. 在代码中配置客户端：

import igapi

# 配合 mitmproxy 抓包
client = igapi.Client(
    proxy="http://127.0.0.1:8080",
    danger_accept_invalid_certs=True,  # 信任 mitmproxy 自签证书
    http1_only=True,
)

---

SOCKS5 代理

注意：当前版本依赖 reqwest 的 HTTP 代理支持，SOCKS5 支持取决于底层构建配置。如果遇到连接错误，请优先使用 HTTP 代理格式。

如需使用 SOCKS5 代理，URL 格式如下：

import igapi

# SOCKS5 代理（不含认证）
client = igapi.Client(
    proxy="socks5://127.0.0.1:1080",
)

# SOCKS5 代理（含用户名密码认证）
client = igapi.Client(
    proxy="socks5://用户名:密码@代理服务器:1080",
)

---

参数说明

参数名	类型	默认值	说明
proxy	str \| None	None	代理服务器地址，格式为 http://host:port 或 socks5://host:port，含认证时格式为 http://user:pass@host:port
danger_accept_invalid_certs	bool	False	跳过 TLS 证书验证。抓包代理（Charles、mitmproxy）使用自签证书，必须设为 True 才能正常建立 HTTPS 连接。仅用于开发调试，生产环境禁止开启
http1_only	bool	False	强制使用 HTTP/1.1，禁用 HTTP/2。部分代理软件不支持 HTTP/2 协议，开启此项可提高兼容性

---

完整示例：配合 mitmproxy 分析登录请求

以下示例演示如何通过 mitmproxy 完整抓取 Web 平台的登录请求，用于分析请求头和请求体结构。

第一步：在终端启动 mitmproxy

mitmweb --listen-port 8080 --web-port 8081

第二步：运行以下 Python 脚本

import asyncio
import igapi


async def analyze_login():
    """通过 mitmproxy 抓包分析登录请求"""

    # 创建配置了抓包代理的 WebClient
    web = igapi.WebClient(
        proxy="http://127.0.0.1:8080",
        danger_accept_invalid_certs=True,  # 信任 mitmproxy 证书
        http1_only=True,                   # 兼容 mitmproxy
    )

    try:
        await web.login("你的用户名", "你的密码")
        print("登录成功，请查看 mitmproxy 界面（http://127.0.0.1:8081）")

        # 导出账号信息用于后续复用
        session_str = web.export_account_string()
        with open("session.txt", "w") as f:
            f.write(session_str)
        print("Session 已保存到 session.txt")

    except igapi.TwoFactorRequired:
        code = input("请输入双因素验证码：")
        await web.verify_two_factor(code)
        print("二步验证通过")

    except igapi.ChallengeRequired as e:
        print(f"需要通过验证挑战：{e}")

    except ValueError as e:
        print(f"登录失败：{e}")

    except ConnectionError as e:
        print(f"代理连接失败，请检查 mitmproxy 是否已启动：{e}")


if __name__ == "__main__":
    asyncio.run(analyze_login())

第三步：在浏览器打开 http://127.0.0.1:8081，即可在 mitmproxy Web 界面中看到完整的请求和响应详情。

---

注意事项

danger_accept_invalid_certs 仅用于调试

此参数会禁用 TLS 证书链校验，使客户端接受任意自签证书。这意味着在中间人攻击下，客户端无法识别伪造的证书。请严格限制在本地开发和调试环境中使用，切勿在生产环境或处理真实用户凭据的场景下开启。

# 正确用法：仅在本地调试时开启
client = igapi.Client(
    proxy="http://127.0.0.1:8080",
    danger_accept_invalid_certs=True,  # 仅调试用
)

# 生产环境：不传此参数，默认为 False
client = igapi.Client()

http1_only 的兼容性影响

强制 HTTP/1.1 会关闭连接复用（HTTP/2 多路复用），在高频请求场景下会略微降低吞吐量。建议仅在代理工具不支持 HTTP/2 时开启，正常使用时保持默认值（False）。

代理地址格式

proxy 参数值必须包含完整协议前缀（http:// 或 socks5://）。仅填写 IP 和端口（如 127.0.0.1:8080）会导致解析失败。

# 正确
proxy="http://127.0.0.1:8080"

# 错误（缺少协议前缀）
proxy="127.0.0.1:8080"

---

常见问题

Q：配置了代理后抛出 ConnectionError，该如何排查？

A：请按以下顺序检查：(1) 确认代理软件（Charles/mitmproxy）已启动且监听端口与配置一致；(2) 确认 danger_accept_invalid_certs=True 已设置，否则 HTTPS 握手会因证书不受信任而失败；(3) 确认 http1_only=True 已设置，部分代理工具不支持 HTTP/2，不降级会导致协议协商失败。

---

Q：如何验证请求确实经过了代理？

A：在 mitmproxy 界面（http://127.0.0.1:8081）或 Charles 的 Session 列表中，执行一次 API 调用后，应能看到对应的 i.instagram.com 或 www.instagram.com 请求记录。如果没有记录，说明流量未走代理，请检查 proxy 参数是否正确传入客户端构造函数。

---

Q：代理需要用户名密码认证，如何配置？

A：在代理 URL 中直接包含认证信息：

client = igapi.Client(
    proxy="http://用户名:密码@代理服务器地址:端口",
    danger_accept_invalid_certs=True,
    http1_only=True,
)

如果密码包含特殊字符（如 @、:），需要进行 URL 编码，例如 @ 编码为 %40。