# ip_proxy_manager

**Repository Path**: atiger808/ip_proxy_manager

## Basic Information

- **Project Name**: ip_proxy_manager
- **Description**: 代理管理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-01-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IP代理管理模块

> **自动化、高可用、负载均衡的IP代理管理系统**  
> 专为 Facebook 矩阵账号营销场景设计，解决 IP 关联、手动分配、资源浪费等核心痛点。

---

## 📌 概述

本项目基于 **比特指纹浏览器 + Python + SQLite** 构建，实现对 VLESS / V2Ray / SSR 多种协议代理的统一管理，自动转换为本地 HTTP 代理（`http://127.0.0.1:端口`），并为每个 FB 账号智能分配独立 IP，有效避免账号关联风险。

### ✅ 核心价值
- **自动分配**：新账号创建时自动绑定最少使用的代理
- **智能释放**：账号删除后自动回收 IP 资源
- **协议统一**：VLESS / V2Ray / SSR → 本地 HTTP 代理
- **负载均衡**：按绑定数排序，确保 IP 利用率均衡
- **安全可靠**：事务保障 + 定期备份 + 异常处理

---

## 🧩 功能特性

| 功能             | 描述                                      |
| ---------------- | ----------------------------------------- |
| **多协议支持**   | VLESS / V2Ray (VMess) / SSR 自动解析      |
| **本地代理转换** | 所有协议 → `http://127.0.0.1:20001~29999` |
| **自动分配**     | 按 `bound_accounts` 升序选择最优代理      |
| **智能同步**     | 每 2 小时自动检测并释放已删除浏览器的 IP  |
| **Web 监控面板** | 实时查看代理使用、测试可用性、手动同步    |
| **数据持久化**   | SQLite 存储 + 每日自动备份                |
| **异常处理**     | 代理失效自动标记、端口冲突跳过、事务回滚  |
| **批量操作**     | 支持导入/导出代理配置（JSON）             |

---

## 📦 技术栈

- **语言**: Python 3.7+
- **数据库**: SQLite（内置）
- **依赖库**: `requests`
- **代理客户端**: 
  - [V2Ray](https://www.v2fly.org/)（支持 VLESS/VMess）
  - [SSR 客户端](https://github.com/shadowsocksrr/shadowsocksr-libev)（可选）
- **浏览器**: [比特指纹浏览器](https://www.bitbrowser.cn/)（API 端口 `54345`）

---

## 🚀 快速开始

### 1. 环境准备

```bash
# 克隆项目
git clone https://your-repo/ip-proxy-manager.git
cd ip-proxy-manager

# 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# 安装依赖
pip install -r requirements.txt

# 安装代理客户端（如未全局安装）
# V2Ray: https://www.v2fly.org/guide/install.html
# SSR:  pip install shadowsocks-libev
```

### 2. 启动比特浏览器

- 确保 **比特浏览器已启动**
- 默认 API 地址：`http://127.0.0.1:54345/api/v1`

> 💡 验证：`curl http://127.0.0.1:54345/api/v1/browser/list`

### 3. 初始化数据库

首次运行会自动创建 `accounts.db`：

```bash
python main.py
```

### 4. 添加代理

```bash
# 添加 VLESS 代理
python main.py add-proxy "vless://uuid@server.com:443?security=tls&type=tcp#MyProxy"

# 添加 V2Ray 代理
python main.py add-proxy "vmess://eyJhZGQiOiJzZXJ2ZXIuY29tIiwicG9ydCI6IjQ0MyIsImlkIjoi..."}"

# 添加 SSR 代理
python main.py add-proxy "ssr://base64_encoded_ssr_url"
```

### 5. 为账号分配代理

```bash
# 通过邮箱分配
python main.py allocate --email user1@example.com

# 通过浏览器ID分配
python main.py allocate --browser-id b1a2c3d4
```

### 6. 启动监控面板

```bash
python monitor.py --port 9000
```

访问 `http://localhost:9000` 查看实时监控。

---

## 🛠️ CLI 命令

```bash
# 添加代理
python main.py add-proxy <URL>

# 分配代理
python main.py allocate [--email EMAIL] [--browser-id ID]

# 释放代理
python main.py release <ACCOUNT_ID>

# 手动同步（释放已删除浏览器的IP）
python main.py sync [--force]

# 查看统计
python main.py stats

# 备份数据库
python main.py backup
```

---

## 📊 监控面板

访问 `http://服务器IP:9000`：

- **仪表盘**：总代理数、绑定账号数、端口使用率
- **代理列表**：协议、端口、绑定账号、状态
- **操作**：
  - 测试代理可用性
  - 手动同步
  - 添加新代理
  - 备份数据库

![监控面板示意图](docs/monitor-screenshot.png) *(示意图，请自行截图)*

---

## ⚙️ 配置说明

### config.py（可选覆盖）

```python
class Config:
    PORT_START = 20001          # 代理端口起始
    PORT_END = 29999            # 代理端口结束
    SYNC_COOLDOWN = 7200        # 同步冷却时间（秒）
    BIT_BROWSER_API = "http://127.0.0.1:54345/api/v1"
    DB_PATH = "accounts.db"
    BACKUP_DIR = "backups"
    V2RAY_PATH = "/usr/local/bin/v2ray"  # 请根据实际路径修改
```

---

## 🐳 Docker 部署（可选）

```bash
# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 访问监控面板
http://<服务器IP>:9000
```

> 详见 [`docker-compose.yml`](docker-compose.yml)

---

## 🔒 合规与安全

⚠️ **重要提示**：
- 本系统仅适用于 **合法合规场景**（如企业跨境办公、海外业务测试）
- **禁止用于** 绕过国家网络监管、提供公共代理服务等违法用途
- 建议在部署前签署《合规使用承诺书》

---

## 📈 性能指标

| 指标         | 要求               |
| ------------ | ------------------ |
| 支持账号数   | 1000+              |
| 支持IP数     | 9999               |
| 分配响应时间 | <100ms（无同步时） |
| 同步响应时间 | <5s（100个浏览器） |
| 并发能力     | 10次/秒            |

---

## 📁 项目结构

```
ip-proxy-manager/
├── main.py                 # CLI 入口
├── monitor.py              # Web 监控面板
├── database.py             # SQLite 数据库操作
├── proxy_allocator.py      # 核心分配逻辑
├── bit_browser_manager.py  # 比特浏览器API交互
├── local_proxy_service.py  # 本地代理服务管理
├── protocol_parser.py      # 协议解析器（VLESS/V2Ray/SSR）
├── config.py               # 配置文件
├── requirements.txt        # 依赖清单
├── docker-compose.yml      # Docker 部署
└── README.md
```

---

## 📝 故障排查

| 问题                    | 解决方案                                      |
| ----------------------- | --------------------------------------------- |
| `没有可用代理`          | 检查是否已添加代理，或代理状态是否为 `active` |
| `比特浏览器API连接失败` | 确认比特浏览器已启动，端口 `54345` 可访问     |
| `端口被占用`            | 检查 `20001-29999` 是否被其他服务占用         |
| `同步不执行`            | 等待 2 小时冷却期，或使用 `--force` 强制同步  |
| `数据库损坏`            | 从 `backups/` 目录恢复最新备份                |

---

## 📄 交付清单

- ✅ 完整源代码（含协议解析、分配算法、监控面板）
- ✅ CLI 工具 + Web 监控界面
- ✅ Docker 部署方案
- ✅ systemd 服务配置（生产环境）
- ✅ 使用文档 + API 文档 + 故障排查指南
- ✅ 单元测试 + 集成测试 + 性能测试报告

---

## 📞 支持

- **适用场景**：Facebook 矩阵账号营销、跨境电商、海外社媒运营
- **维护建议**：每日自动备份 + 代理可用性监控
- **技术支持**：提供 30 天免费基础支持

> 项目版本：v2.0  
> 最后更新：2026-01-26