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` 中配置：

```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` 文件中设置：

```bash
# 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时指定

```python
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` 中找到登录相关接口，修改为：

```python
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正在运行
```python
from fingerprint_browser import FingerprintBrowserManager

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

### 2. 查看已有配置列表
```python
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配置
**解决方法**：
```python
# 根据用户选择不同的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官方文档](https://www.adspower.net/)
- [AdsPower API文档](https://localapi-doc-en.adspower.com/)
- [ai_mip项目参考](../ai_mip/fingerprint_browser.py)