Ec2ElasticIpSwapper/README.md

# Lightsail 静态IP 更换工具

一个用于自动更换 AWS Lightsail 实例静态IP的Web工具，支持自动区域检测和实例定位。

## 功能特性

- 🔍 **自动区域检测** - 输入静态IP地址后自动定位所属AWS区域
- 🎯 **自动实例定位** - 自动找到绑定的Lightsail实例
- 🆕 **新IP分配** - 自动分配新的静态IP地址
- 🔗 **自动绑定** - 将新静态IP绑定到实例
- 🗑️ **可选释放** - 可选择是否释放旧静态IP
- 📊 **操作日志** - 记录所有操作历史和状态
- 🔄 **重试机制** - 处理临时错误和API限流
- 🌐 **Web界面** - 简洁易用的Web操作界面

## 系统要求

- Python 3.7+
- AWS账户和相应的API权限
- 网络访问AWS Lightsail服务

## 安装步骤

### 1. 克隆项目

```bash
git clone <your-repo-url>
cd Ec2ElasticIpSwapper
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置AWS凭证

#### 方法一：环境变量（推荐）

创建 `.env` 文件：

```bash
# .env
AWS_REGION=ap-northeast-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=xxxx...
```

#### 方法二：AWS CLI配置

```bash
aws configure
```

#### 方法三：IAM角色（EC2实例）

如果运行在EC2实例上，可以配置IAM角色。

### 4. 启动服务

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

### 5. 访问Web界面

打开浏览器访问：`http://localhost:9099`

## 使用方法

1. **输入当前静态IP** - 在输入框中输入当前绑定在Lightsail实例上的静态IP地址
2. **点击更换按钮** - 系统会自动：
   - 检测IP所属区域
   - 找到绑定的实例
   - 分配新的静态IP
   - 绑定到实例
   - 释放旧静态IP（可选）
3. **查看操作日志** - 在下方表格中查看所有操作记录

## 所需AWS权限

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

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "lightsail:GetStaticIps",
                "lightsail:AllocateStaticIp",
                "lightsail:AttachStaticIp",
                "lightsail:DetachStaticIp",
                "lightsail:ReleaseStaticIp",
                "lightsail:GetInstance",
                "lightsail:GetRegions",
                "sts:GetCallerIdentity"
            ],
            "Resource": "*"
        }
    ]
}
```

## API接口

### 更换静态IP

```http
POST /api/rotate_by_ip
Content-Type: application/json

{
    "current_ip": "1.2.3.4",
    "release_old": true
}
```

**响应示例：**

```json
{
    "ok": true,
    "region": "ap-northeast-1",
    "instance_id": "my-instance",
    "old_ip": "1.2.3.4",
    "new_ip": "5.6.7.8",
    "old_released": true
}
```

### 获取操作日志

```http
GET /api/logs
```

### 清空操作日志

```http
POST /api/logs/clear
```

### 健康检查

```http
GET /healthz
```

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `AWS_REGION` | 起始区域（用于获取区域列表） | `us-east-1` |
| `AWS_ACCESS_KEY_ID` | AWS访问密钥ID | - |
| `AWS_SECRET_ACCESS_KEY` | AWS秘密访问密钥 | - |

### 重试配置

代码中内置了重试机制，用于处理临时错误：

- **最大重试次数**: 3次
- **重试间隔**: 0.8秒（指数退避）
- **重试条件**: 实例状态错误、请求限制、限流异常等

## 故障排除

### 常见错误

1. **"静态IP not found in any region"**
   - 检查IP地址是否正确
   - 确认IP属于当前AWS账户
   - 验证AWS凭证权限

2. **"静态IP is not attached to any instance"**
   - 确认静态IP已绑定到Lightsail实例
   - 检查实例状态是否正常

3. **权限错误**
   - 检查AWS凭证是否正确配置
   - 确认具有所需的Lightsail权限

### 日志查看

- 在Web界面下方查看操作日志
- 每个操作都会记录时间、区域、实例、IP地址、状态等信息

## 注意事项

- ⚠️ **备份重要数据** - 更换IP可能影响服务连接
- ⚠️ **DNS更新** - 更换IP后需要更新相关DNS记录
- ⚠️ **防火墙规则** - 检查安全组和防火墙规则
- ⚠️ **费用考虑** - 未使用的静态IP会产生费用，建议及时释放

## 技术栈

- **后端**: FastAPI + Python
- **AWS SDK**: Boto3
- **前端**: 原生HTML/CSS/JavaScript
- **服务器**: Uvicorn ASGI

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 更新日志

### v1.0.0
- 初始版本
- 支持Lightsail静态IP自动更换
- Web界面和API接口
- 自动区域检测和实例定位