---
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]]