需要为多账号营销/广告投放做浏览器指纹隔离与自动化时，用…

当你要在多账号、多广告活动场景下隔离 cookies/存储/浏览器指纹，并用 Selenium、Puppeteer 或 Playwright 程序化驱动这些浏览器配置时使用。

适用场景

解决思路

1. 安装并启用 API：从 AdsPower 官网下载桌面应用，按操作系统（Windows/macOS）安装，启动应用并创建账号，然后在 Settings → API Settings 中开启 API 访问。
2. 配置 API 接入：本地 API 基址用 http://localhost:50325/api/v1；如果使用云 API，通过环境变量 ADSPOWER_API_KEY 提供密钥；如果不用默认端口，用环境变量 ADSPOWER_API_PORT 自定义端口。
3. 创建浏览器配置：POST /user/create，payload 包含 name、group_id（默认 "0"）、domain_name、open_urls、repeat_config；当返回 code == 0 时取 data.id 作为 profile id，否则抛出包含 msg 的异常。
4. 启动配置：GET /browser/start，参数为 user_id 和可选 launch_args；成功时返回 data.ws.puppeteer（WebSocket 端点）、data.ws.selenium 和 data.debug_port。
5. 关闭配置：GET /browser/stop，参数 user_id，以 code == 0 判断是否成功。
6. Selenium 集成：先 start_profile 拿到 debug_port，用 Options() 设置 debuggerAddress 为 127.0.0.1:{debug_port}，再用 webdriver.Chrome(options=...) 连接；任务结束后 driver.quit() 并 stop_profile。
7. Puppeteer 集成：用 puppeteer-core 的 puppeteer.connect({browserWSEndpoint: connection.wsEndpoint, defaultViewport: null}) 连接；完成后 browser.disconnect() 并 stop_profile。
8. Playwright 集成：用 p.chromium.connect_over_cdp(connection['ws_endpoint']) 连接；任务结束后 browser.close() 并 stop_profile。
9. 列出配置：GET /user/list，参数 page、page_size（例如 100），可选 group_id；从 data.list 读取列表。
10. 更新配置：POST /user/update，payload 为 {user_id, ...updates}，例如修改 name、remark，以 code == 0 判断成功。
11. 删除配置：POST /user/delete，请求体为 {"user_ids": [profile_id]}，以 code == 0 判断成功。
12. 批量活动自动化：封装 CampaignAutomation 类，遍历 profile_ids，对每个 profile 连接（如 Selenium）、执行传入的 task_function、driver.quit() + stop_profile，并在 profile 之间 time.sleep(5)；异常时打印错误并 stop_profile。
13. 配置池管理：ProfilePool 用 list_profiles(group_id) 找到不在 active_profiles 中的 profile，start_profile 后记录 connection 并返回 (profile_id, connection)；release_profile 时 stop_profile 并从池中移除；无可用 profile 时抛异常。
14. 批量创建配置：按 campaign_name 循环 count 次，命名 {campaign_name}_Profile_{i+1}，group_id 用 campaign_name，收集每次返回的 profile id。
15. 自定义指纹：创建配置时传入 fingerprint_config，字段包括 ua（user_agent）、language（默认 en-US）、timezone（默认 America/New_York）、webrtc（如 proxy）、location（如 ask）、canvas（如 noise）。
16. 检查 API 连通性：GET /status（timeout 设为 5 秒），status_code == 200 视为可用，否则提示需确保 AdsPower 应用正在运行。
17. 启动失败重试：safe_start_profile 最多重试 3 次，每次失败打印错误并 time.sleep(2)，全部失败后抛出异常。
18. 清理卡住的配置：force_close_all_profiles 遍历 list_profiles，对每个 user_id 调用 stop_profile，单个失败时捕获异常并打印，不中断整体清理。
19. 遵循最佳实践：用完后总是关闭 profile 释放资源；profile 启动之间加延迟以避免被检测；用 profile group 组织活动与团队；监控活跃 profile 防止资源耗尽；为网络和 API 失败实现错误处理；长时间运行的活动要定期轮换 profile；备份重要的 profile 与指纹配置。

适用边界 · 注意事项

• 不适用于不需要多账号隔离或防关联检测的场景，普通单账号自动化直接用 Playwright/Selenium 更简单。
• 依赖 AdsPower 桌面应用与账号（含 API 访问权限），没有安装该产品或其 API 未开启时完全不可用。
• 不适合纯无界面服务器环境，本地 API 需要 AdsPower 桌面应用在对应机器上运行。