98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
---
|
||
title: Geo 账号与代理模块
|
||
created: 2026-05-07
|
||
updated: 2026-05-07
|
||
type: entity
|
||
tags: [module, backend, frontend, database]
|
||
sources: [packages/backend/src/modules/geo/, packages/frontend/src/modules/geo/, docs/superpowers/specs/2026-05-03-geo-master-roadmap.md, docs/superpowers/specs/2026-05-03-geo-s1-infrastructure-design.md]
|
||
---
|
||
|
||
# Geo 账号与代理模块
|
||
|
||
Geo 模块是 2026-05-07 新增的账号、代理 IP 与浏览器 profile 绑定基础设施，服务养号、电商自动化和后续 Agent 操作账号矩阵。它和 [[netabrowser-runtime]] 协作：Geo 负责账号/IP/登录态数据，浏览器 daemon 负责真正打开带指纹、代理和持久 profile 的 Chromium。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
packages/backend/src/modules/geo/
|
||
├── config.ts
|
||
├── controller/admin/account.ts
|
||
├── controller/admin/proxy_ip.ts
|
||
├── entity/account.ts
|
||
├── entity/proxy_ip.ts
|
||
├── provider/proxy/
|
||
│ ├── interface.ts
|
||
│ ├── local.ts
|
||
│ └── tianqi.ts
|
||
└── service/
|
||
├── account.ts
|
||
├── encrypt.ts
|
||
└── proxy_ip.ts
|
||
```
|
||
|
||
前端入口在 `packages/frontend/src/modules/geo/`，包含 `accounts.vue`、`proxies.vue` 和 `dashboard.vue`。
|
||
|
||
## 数据模型
|
||
|
||
| 表 | Entity | 职责 |
|
||
| --- | --- | --- |
|
||
| `geo_account` | `entity/account.ts` | 平台账号、登录态、sessionName、fingerprintSeed、cookie、绑定 Agent 和绑定 IP |
|
||
| `geo_proxy_ip` | `entity/proxy_ip.ts` | 本地/第三方代理、协议、区域、城市、出口 IP、套餐、健康状态和账号 1:1 绑定 |
|
||
|
||
关键约束：
|
||
|
||
- `geo_account.sessionName` 唯一，对应 [[netabrowser-runtime]] 的浏览器 profile。
|
||
- `geo_account.fingerprintSeed` 让同一账号每次启动保持稳定指纹，不同账号表现为不同物理设备。
|
||
- `geo_proxy_ip.bindAccountId` 和 `geo_account.proxyId` 形成强 1:1 绑定。
|
||
- 切换 IP 或重置账号会生成新的 `sessionName` 和 `fingerprintSeed`，清空 cookie，并尝试删除旧 profile。
|
||
|
||
## 账号流程
|
||
|
||
`GeoAccountService` 的主路径：
|
||
|
||
```text
|
||
add()
|
||
-> 创建账号
|
||
-> 生成 sessionName / fingerprintSeed
|
||
-> 可选绑定 proxy
|
||
|
||
launch()
|
||
-> 根据账号和 IP 构造 daemon open 参数
|
||
-> 调用 /admin/browser-daemon/open
|
||
-> 如果同名 session 已存在则 goto 复用
|
||
-> fresh profile 时可注入数据库 cookie
|
||
|
||
captureCookies()
|
||
-> 调用 browser-daemon cookie-list
|
||
-> 写入 cookies/cookieCapturedAt/cookieExpiresAt/loginStatus
|
||
-> 尝试从 cookie 或 DOM 提取 loginAccount
|
||
```
|
||
|
||
这些流程说明 Geo 不是简单 CRUD，而是账号状态机、IP 绑定和浏览器 profile 生命周期的协调层。
|
||
|
||
## 代理 Provider
|
||
|
||
`provider/proxy/` 当前提供：
|
||
|
||
- `local`：本地直连模式。
|
||
- `tianqi`：第三方代理 Provider 骨架。
|
||
- `interface.ts`：统一 Provider 接口。
|
||
|
||
`GeoProxyIpService` 负责把数据库记录转换为浏览器 daemon 可消费的 proxy 信息；SOCKS5 用户名密码的 Chromium 兼容问题由 [[netabrowser-runtime]] 的本地 HTTP 桥处理。
|
||
|
||
## 前端入口
|
||
|
||
Geo 前端在 `packages/frontend/src/modules/geo/config.ts` 注册独立模块入口，当前页面分为：
|
||
|
||
- 账号页：新增账号、选择平台、绑定 Agent/IP、启动浏览器、抓取 cookie、重置会话、切换 IP。
|
||
- 代理页：管理本地/第三方代理、查看状态、绑定关系和健康信息。
|
||
- Dashboard：当前为轻量入口，后续可承接账号矩阵概览。
|
||
|
||
## 相关页面
|
||
|
||
- [[project-overview]]
|
||
- [[netabrowser-runtime]]
|
||
- [[database-entity-overview]]
|
||
- [[frontend-architecture]]
|
||
- [[cool-admin-framework]]
|