Ec2ElasticIpSwapper/README.md

# EC2 EIP Rotator - 自动区域EIP更换工具

一个基于FastAPI的AWS EC2 Elastic IP自动更换工具，支持自动区域检测和Web界面操作。

## 功能特性

- 🔍 **自动区域检测**：只需输入当前EIP公网IP，自动定位所属区域和实例
- 🚀 **一键更换**：自动分配新EIP并绑定到实例
- 🗑️ **可选释放**：可选择是否释放旧的EIP
- 📊 **操作记录**：完整的操作日志记录和查看
- 🔄 **软重启**：支持服务器软重启功能
- 🎨 **现代UI**：响应式Web界面，支持深色主题

## 系统要求

- Python 3.8+
- AWS账户和相应的API权限
- 网络连接（用于访问AWS服务）

## 安装步骤

### 1. 克隆项目
```bash
git clone <your-repo-url>
cd Ec2ElasticIpSwapper
```

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

### 3. 配置环境变量
创建 `.env` 文件并配置AWS凭证：

```env
# AWS配置（仅用作起始区域获取区域清单）
AWS_REGION=ap-northeast-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=xxxx...
```

**注意**：`AWS_REGION` 仅用作获取区域清单的起始区域，真正的操作区域由自动检测结果决定。

## 启动服务

```bash
python -m uvicorn app:app --host 0.0.0.0 --port 9099
```

服务启动后，访问 `http://localhost:9099` 即可使用Web界面。

## 使用方法

### Web界面操作

1. **打开浏览器**访问 `http://localhost:9099`
2. **输入当前EIP**：在"当前 EIP 公网IP"字段输入要更换的EIP地址
3. **点击"换新EIP"**：系统会自动：
   - 检测EIP所属区域和实例
   - 分配新的EIP
   - 绑定到实例
   - 可选释放旧EIP
4. **查看记录**：在"更换记录"表格中查看所有操作历史

### API接口

#### 更换EIP
```bash
curl -X POST http://localhost:9099/api/rotate_by_ip \
  -H "Content-Type: application/json" \
  -d '{"current_ip": "1.2.3.4", "release_old": true}'
```

#### 查看日志
```bash
curl http://localhost:9099/api/logs
```

#### 清空日志
```bash
curl -X POST http://localhost:9099/api/logs/clear
```

#### 重启服务器
```bash
curl -X POST http://localhost:9099/api/restart
```

#### 健康检查
```bash
curl http://localhost:9099/healthz
```

## 权限要求

确保您的AWS凭证具有以下权限：

- `ec2:DescribeAddresses` - 查询EIP信息
- `ec2:DescribeRegions` - 获取区域列表
- `ec2:DescribeInstances` - 查询实例信息
- `ec2:AllocateAddress` - 分配新EIP
- `ec2:AssociateAddress` - 绑定EIP到实例
- `ec2:ReleaseAddress` - 释放EIP
- `ec2:CreateTags` - 为新EIP添加标签

## 项目结构

```
Ec2ElasticIpSwapper/
├── app.py              # 主应用文件
├── requirements.txt    # Python依赖
├── README.md          # 项目说明
└── .env              # 环境变量配置（需要创建）
```

## 技术架构

- **后端框架**：FastAPI
- **AWS SDK**：boto3
- **前端**：原生HTML/CSS/JavaScript
- **模板引擎**：Jinja2
- **服务器**：Uvicorn

## 功能说明

### 自动区域检测
系统会自动遍历所有AWS区域，查找指定EIP的归属区域，无需手动选择区域。

### 重试机制
对于偶发的状态错误和限流，系统会自动重试最多3次，确保操作成功率。

### 操作日志
所有操作都会记录到内存日志中，包括：
- 操作时间
- 区域信息
- 实例信息
- 旧IP和新IP
- 操作状态
- 错误信息

### 软重启功能
支持通过Web界面或API进行服务器软重启，使用SIGTERM信号优雅关闭。

## 故障排除

### 常见问题

1. **EIP未找到**
   - 确认EIP属于当前AWS账户
   - 确认EIP是Elastic IP而非普通公网IP

2. **权限不足**
   - 检查AWS凭证配置
   - 确认具有必要的EC2权限

3. **网络连接问题**
   - 确认网络连接正常
   - 检查防火墙设置

### 日志查看
通过Web界面的"更换记录"表格或API接口 `/api/logs` 查看详细的操作日志。

## 开发说明

### 本地开发
```bash
# 安装开发依赖
pip install -r requirements.txt

# 启动开发服务器
python -m uvicorn app:app --host 0.0.0.0 --port 9099 --reload
```

### 生产部署
建议使用进程管理器如systemd、supervisor或Docker进行部署。

## 许可证

本项目采用MIT许可证。

## 贡献

欢迎提交Issue和Pull Request来改进这个项目。

## 更新日志

- **v1.0.0**：初始版本，支持自动区域检测和EIP更换
- **v1.1.0**：添加软重启功能和改进的UI界面