jdeip/README.md

# 🌐 EIP IP轮换服务

一个基于FastAPI的智能IP地址轮换管理系统，支持多省份选择、自动IP切换和Web控制面板。

## ✨ 功能特性

### 🔄 核心功能
- **智能IP轮换**: 自动从可用设备中选择未使用的IP地址
- **多省份支持**: 支持上海、四川、广东等多个省份的城市选择
- **随机城市选择**: 从指定省份中随机选择城市进行IP轮换
- **使用记录追踪**: 基于Redis的IP使用记录，避免重复使用
- **网关路由配置**: 自动配置网关路由规则

### 🎯 Web控制面板
- **现代化UI**: 响应式设计，支持移动端访问
- **省份选择**: 可视化省份选择，支持全选/取消全选
- **实时状态**: 显示当前IP、使用统计和网关状态
- **URL参数支持**: 通过URL参数传递客户端ID

### 🔧 技术特性
- **自动重试**: 网络请求失败时自动重试，支持指数退避
- **Token管理**: 自动处理认证令牌的获取和刷新
- **容错处理**: 兼容多种后端响应格式
- **配置管理**: 支持环境变量和配置文件

## 🚀 快速开始

### 环境要求
- Python 3.8+
- Redis服务器
- EIP服务访问权限

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

### 配置环境变量
创建 `app/.env` 文件：
```env
# EIP服务配置
EIP_BASE_URL=https://smart.jdbox.xyz:58001
EIP_USERNAME=your_username
EIP_PASSWORD=your_password
EIP_GATEWAY_MAC=your_gateway_mac
EIP_DEFAULT_CITYHASH=your_default_cityhash
EIP_DEFAULT_NUM=10

# Redis配置
REDIS_URL=redis://localhost:6379/0

# 日志级别
LOG_LEVEL=INFO
```

### 启动服务
```bash
# 开发模式
python -m app.main

# 或使用uvicorn
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

### 访问Web界面
- **主页**: http://localhost:8000/
- **带客户端ID**: http://localhost:8000/?id=123
- **API文档**: http://localhost:8000/docs

## 📚 API接口

### 核心接口

#### 1. IP轮换
```http
POST /proxy/rotate
Content-Type: application/json

{
    "id": 123,
    "citys": "上海,四川,广东"
}
```

**响应示例**:
```json
{
    "changed": true,
    "ip": "192.168.1.100",
    "edge": "edge_device_001",
    "status": {
        "gateway_status": "active"
    }
}
```

#### 2. 获取状态
```http
GET /proxy/status
```

**响应示例**:
```json
{
    "current": {
        "ip": "192.168.1.100",
        "edge_id": "edge_device_001"
    },
    "used_today": 5,
    "gateway": {
        "status": "active"
    }
}
```

#### 3. 获取城市列表
```http
GET /proxy/cities
```

**响应示例**:
```json
{
    "data": ["上海", "四川", "广东"]
}
```

### 健康检查
```http
GET /health
```

## 🏗️ 项目结构

```
jdeip/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI应用入口
│   ├── config.py               # 配置管理
│   ├── eip_client.py           # EIP客户端
│   ├── rotation_service.py     # IP轮换服务
│   ├── redis_store.py          # Redis存储
│   ├── routers/
│   │   └── proxy.py            # API路由
│   └── templates/
│       └── index.html           # Web控制面板
├── requirements.txt            # 依赖包
├── README.md                   # 项目文档
└── .env                        # 环境变量配置
```

## 🔧 核心模块

### EIP客户端 (`eip_client.py`)
- 处理与EIP服务的所有通信
- 自动认证和令牌管理
- 支持设备列表、网关配置等操作
- 内置重试机制和错误处理

### 轮换服务 (`rotation_service.py`)
- 核心IP轮换逻辑
- 随机城市选择算法
- 使用记录管理
- 网关路由配置

### Redis存储 (`redis_store.py`)
- IP使用记录存储
- 按天统计使用情况
- 当前状态管理

### Web控制面板
- 现代化响应式界面
- 省份可视化选择
- 实时状态显示
- 异步操作支持

## 🎨 Web界面功能

### 主要特性
- **省份选择**: 支持多选省份，默认全选
- **客户端ID**: 通过URL参数传递，支持 `?id=123`
- **实时轮换**: 一键执行IP轮换操作
- **状态显示**: 显示轮换结果和错误信息
- **响应式设计**: 支持桌面和移动设备

### 使用方式
1. 访问 `http://localhost:8000/` 进入控制面板
2. 选择需要的省份（默认全选）
3. 点击"开始IP轮换"按钮
4. 查看轮换结果

## 🔒 安全特性

- **环境变量**: 敏感信息通过环境变量管理
- **Token自动刷新**: 避免令牌过期问题
- **错误处理**: 完善的异常处理机制
- **输入验证**: 严格的参数验证

## 📊 监控和日志

- **健康检查**: `/health` 端点提供服务状态
- **使用统计**: Redis记录IP使用情况
- **错误日志**: 详细的错误信息和调试输出
- **状态监控**: 实时网关和连接状态

## 🛠️ 开发指南

### 添加新城市
在 `config.py` 中的 `city_dict` 添加新的省份和城市：

```python
city_dict = {
    "新省份": {
        "城市1": "城市编码1",
        "城市2": "城市编码2"
    }
}
```

### 自定义配置
修改 `app/.env` 文件中的配置项，或通过环境变量覆盖。

### 扩展功能
- 在 `rotation_service.py` 中添加新的轮换策略
- 在 `eip_client.py` 中添加新的EIP操作
- 在 `routers/proxy.py` 中添加新的API端点

## 📝 更新日志

### v1.0.0
- ✅ 基础IP轮换功能
- ✅ 多省份支持
- ✅ Redis存储集成
- ✅ Web控制面板
- ✅ 自动重试机制
- ✅ 详细中文注释

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证。

## 🆘 支持

如有问题或建议，请创建 Issue 或联系开发团队。

---

**注意**: 使用前请确保已正确配置EIP服务凭据和Redis连接。