agent-browser Session 管理：认证持久化与状态复用

问题：每次启动都要重新登录

浏览器自动化最常见的痛点是登录态管理。每次运行脚本都要重新输入账号密码、处理 2FA 验证码，效率极低。

agent-browser 提供了多种方案解决这个问题：

方案	配置方式	适合场景	持久化内容
Chrome Profile 复用	`--profile <name>`	已有 Chrome 登录态	Cookie、localStorage、IndexedDB、Service Worker
持久化 Profile	`--profile <path>`	自定义状态目录	同上，可跨机器
Session Name	`--session-name <name>`	轻量级状态管理	Cookie + localStorage
State 文件	`--state <path>`	显式导入导出	登录态快照

方案一：Chrome Profile 复用（零配置）

如果你已经在 Chrome 浏览器中登录了目标站点，可以直接复用该状态：

# 列出可用的 Chrome Profile
agent-browser profiles

# 复用 Default profile 的登录态
agent-browser --profile Default open https://example.com

# 使用指定名称的 profile（按显示名称或目录名）
agent-browser --profile "Work" open https://app.example.com

原理：agent-browser 将 Chrome profile 复制到临时目录（只读快照，不修改原 profile），浏览器启动时继承所有 Cookie 和会话。

从正在运行的 Chrome 导入

# 1. 用远程调试端口启动 Chrome
# macOS:
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222

# 2. 连接并导出状态
agent-browser --auto-connect state save ./my-auth.json

# 3. 后续使用
agent-browser --state ./my-auth.json open https://app.example.com/dashboard

注意：--remote-debugging-port 暴露了浏览器完整控制权，仅限在可信机器上使用。

方案二：Session Name 自动管理

# 首次运行——登录后状态自动保存
agent-browser --session-name mysite open https://example.com/login
# 手动登录...

# 后续运行——Cookie 和 localStorage 自动恢复
agent-browser --session-name mysite open https://example.com/dashboard
# 已经处于登录状态！

状态文件存储在 ~/.agent-browser/sessions/，默认保留 30 天。

Session 隔离

# 不同 site 使用不同 session
agent-browser --session-name site-a open https://example.com
agent-browser --session-name site-b open https://example.com

# 通过环境变量
export AGENT_BROWSER_SESSION_NAME=mysite
agent-browser open https://example.com

Session 加密

# 生成加密密钥
openssl rand -hex 32

# 设置环境变量
export AGENT_BROWSER_ENCRYPTION_KEY=你的64位十六进制密钥

# 状态文件自动 AES-256-GCM 加密
agent-browser --session-name secure-site open https://example.com

环境变量	说明
`AGENT_BROWSER_SESSION_NAME`	自动保存/恢复的 session 名称
`AGENT_BROWSER_ENCRYPTION_KEY`	AES-256-GCM 加密密钥（64位 hex）
`AGENT_BROWSER_STATE_EXPIRE_DAYS`	状态过期天数（默认 30）

方案三：显式 State 管理

# 保存当前状态
agent-browser state save ./project-auth.json

# 查看已保存的状态摘要
agent-browser state show ./project-auth.json

# 列出所有状态文件
agent-browser state list

# 加载状态
agent-browser --state ./project-auth.json open https://example.com

# 重命名
agent-browser state rename project-auth.json site-auth.json

# 清理过期状态
agent-browser state clean --older-than 7

对接代理：固定 IP + 固定 Session

对于需要长期运营的账号（如电商平台店铺管理），将 16YUN 独享代理与 session 绑定：

# session 绑定：固定出口 IP + 固定 session
export HTTP_PROXY=http://user:pass@dedicated.16yun.cn:8888
export AGENT_BROWSER_SESSION_NAME=shop-manager

# 首次：登录
agent-browser open https://seller.example.com/login
# 手动登录...

# 之后：自动恢复登录态
agent-browser open https://seller.example.com/dashboard
# 已登录，IP 固定，session 一致

多账号隔离方案

账号	Profile/Session	代理	用途
shop-01	`--session-name shop-01`	独享代理 IP A	店铺 1 管理
shop-02	`--session-name shop-02`	独享代理 IP B	店铺 2 管理
scraper	`--profile Default`	爬虫代理	批量数据采集

# 每个账号独立 session + 独立代理
HTTP_PROXY=http://user:pass@dedicated-a.16yun.cn:8888 \
  agent-browser --session-name shop-01 open https://seller.example.com

HTTP_PROXY=http://user:pass@dedicated-b.16yun.cn:8888 \
  agent-browser --session-name shop-02 open https://seller.example.com

安全注意事项

State 文件包含明文会话 Token，--session-name 文件默认未加密
生产环境务必设置 AGENT_BROWSER_ENCRYPTION_KEY 启用加密
将 state 文件加入 .gitignore，使用后及时清理
独享代理的 IP 白名单应限制为仅允许采集服务器的 IP

总结

方案	一句话概括	复杂度
`--profile <name>`	继承 Chrome 已有登录态	零配置
`--session-name <name>`	自动保存恢复，适合代码化	低
`--state <path>`	显式导入导出，适合 CI/CD	中
加密 + 代理	生产级安全方案	中