ai_wht_wechat/backend/ADSPOWER_USAGE.md

AdsPower 指纹浏览器配置指南

问题：为什么点击"获取验证码"打开的是默认Chrome？

当前代码默认使用普通Playwright浏览器，不是AdsPower指纹浏览器。

要启用AdsPower模式，需要：

1. 启动AdsPower应用
2. 配置AdsPower参数（见下文）
3. 代码中启用AdsPower模式

---

AdsPower 配置方法

方法1：修改YAML配置文件（推荐）

在 config.dev.yaml 或 config.prod.yaml 中配置：

# ========== AdsPower指纹浏览器配置 ==========
adspower:
  enabled: true  # 是否启用AdsPower
  api_base: "http://local.adspower.net:50325"  # AdsPower API地址
  api_key: "e5afd5a4cead5589247febbeabc39bcb"  # API Key（可选）
  user_id: "user_h235l72"  # 用户ID（可选）
  default_group_id: "0"  # 默认分组ID
  # 指纹配置
  fingerprint:
    automatic_timezone: true  # 自动设置时区
    language: ["zh-CN", "zh"]  # 浏览器语言
    user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"

方法2：使用环境变量

在系统环境变量或 .env 文件中设置：

# AdsPower配置
ADSPOWER_ENABLED=true
ADSPOWER_API_BASE=http://local.adspower.net:50325
ADSPOWER_API_KEY=e5afd5a4cead5589247febbeabc39bcb
ADSPOWER_USER_ID=user_h235l72
ADSPOWER_DEFAULT_GROUP_ID=0

注意：环境变量优先级高于YAML配置。

---

获取AdsPower配置参数

1. API地址 (api_base)

• 默认本地地址：http://local.adspower.net:50325
• 或使用：http://127.0.0.1:50325

2. API Key (api_key)

1. 打开AdsPower应用
2. 点击右上角设置 → 安全 → 本地API
3. 开启"允许本地API访问"
4. 复制API Key

3. User ID (user_id)

1. 打开AdsPower应用
2. 点击右上角头像
3. 查看"用户ID"（如：user_h235l72）

4. Profile ID (adspower_profile_id)

• 在AdsPower中创建浏览器配置
• 右键配置 → 复制配置ID（如：jvqjvvp）
• 如果不指定，系统会自动创建新配置

---

代码中启用AdsPower模式

方法1：直接在创建XHSLoginService时指定

from xhs_login import XHSLoginService

# 启用AdsPower模式
service = XHSLoginService(
    use_adspower=True,  # 关键参数
    adspower_profile_id="jvqjvvp"  # 可选：指定配置ID
)

# 发送验证码
await service.send_verification_code(
    phone="13800138000",
    proxy={'server': 'http://proxy_ip:port', 'username': 'user', 'password': 'pass'}  # 可选
)

方法2：修改main.py中的登录接口

在 main.py 中找到登录相关接口，修改为：

from config import get_config

@app.post("/api/xhs/send-code")
async def send_verification_code(request: SendCodeRequest):
    try:
        # 从配置读取是否启用AdsPower
        config = get_config()
        use_adspower = config.get_bool('adspower.enabled', False)
        
        service = XHSLoginService(
            use_adspower=use_adspower,  # 使用配置项
            headless=False
        )
        
        result = await service.send_verification_code(phone=request.phone)
        return result
    except Exception as e:
        return {"success": False, "message": str(e)}

这样就可以通过YAML配置文件中的 adspower.enabled 来控制是否使用AdsPower。

---

验证步骤

1. 确认AdsPower正在运行

from fingerprint_browser import FingerprintBrowserManager

manager = FingerprintBrowserManager()
is_running = await manager.check_adspower_status()
print(f"AdsPower运行状态: {is_running}")

2. 查看已有配置列表

profiles = await manager.get_browser_profiles()
for profile in profiles:
    print(f"配置ID: {profile['user_id']}, 名称: {profile['name']}")

3. 测试发送验证码

• 启动服务后调用发送验证码接口
• 观察打开的浏览器窗口标题：
  • AdsPower模式：窗口标题会显示"AdsPower"
  • 普通模式：普通Chrome窗口

---

AdsPower vs 普通Chrome的区别

特性	AdsPower	普通Chrome
指纹隔离	✅ 每个配置独立指纹	❌ 使用本机真实指纹
环境隔离	✅ Cookie、缓存隔离	❌ 共享环境
反检测	✅ 模拟真实设备	❌ 易被识别为自动化
多账号管理	✅ 支持多配置	❌ 不便于管理
代理管理	✅ 配置级代理	⚠️ 需要手动设置

建议：生产环境强烈建议使用AdsPower模式，以避免账号风控。

---

常见问题

Q1: "AdsPower 未运行，请先启动 AdsPower"

解决方法：

1. 确认AdsPower应用已启动
2. 检查API地址是否正确（默认50325端口）
3. 确认防火墙没有阻止本地API

Q2: API调用返回401/403错误

解决方法：

1. 检查API Key是否正确
2. 确认在AdsPower设置中开启了"允许本地API访问"
3. 某些版本AdsPower不需要API Key，可以留空

Q3: 浏览器启动失败

解决方法：

1. 检查AdsPower版本是否最新
2. 确认配置ID存在且可用
3. 查看AdsPower日志排查错误

Q4: 想要为不同用户使用不同的AdsPower配置

解决方法：

# 根据用户选择不同的profile_id
user_profile_mapping = {
    "13800138000": "jvqjvvp",
    "13900139000": "kprklms"
}

profile_id = user_profile_mapping.get(phone)
service = XHSLoginService(
    use_adspower=True,
    adspower_profile_id=profile_id
)

---

参考资料

• AdsPower官方文档
• AdsPower API文档
• ai_mip项目参考