diff --git a/README.md b/README.md
index 7da00d8..f60a0b1 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,105 @@
-# czip-api
+# 纯真 IP 查询 API
 
-纯真ip查询api
\ No newline at end of file
+一个基于 Flask + 纯真 IP 库的轻量级 IP 查询服务，提供 RESTful API 和响应式 WebUI。
+
+## 功能特性
+
+- 🚀 **RESTful API** - 支持 IP 地址查询
+- 📱 **响应式 WebUI** - 手机优先设计，自动获取用户公网 IP
+- 🛡️ **高可用性** - 6 个公网 IP 自动获取服务，2 秒超时自动切换
+- 🐳 **Docker 支持** - 提供 Dockerfile 和 docker-compose 配置
+- 🏥 **健康检查** - 内置 `/health` 端点
+
+## 快速开始
+
+### 本地运行
+
+1. **安装依赖**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. **启动服务**
+   ```bash
+   python app.py
+   ```
+
+3. **访问**
+   - WebUI: http://localhost:5000
+   - API: http://localhost:5000/ip/{ip}
+
+### Docker 部署
+
+1. **构建并运行**
+   ```bash
+   docker-compose up -d
+   ```
+
+2. **环境变量**
+   - `PORT` - 服务端口，默认 5000
+
+## API 文档
+
+### 查询 IP
+
+- **URL**: `/ip/{ip}`
+- **方法**: `GET`
+- **响应**: JSON
+
+**示例响应**:
+```json
+{
+  "ip": "8.8.8.8",
+  "country": "美国",
+  "area": "加利福尼亚州圣克拉拉县山景市谷歌公司"
+}
+```
+
+### 健康检查
+
+- **URL**: `/health`
+- **方法**: `GET`
+- **响应**: `ok`
+
+## 项目结构
+
+```
+czip-api/
+├── app.py              # 主应用
+├── qqwry.dat           # 纯真 IP 数据库
+├── requirements.txt    # Python 依赖
+├── Dockerfile          # Docker 构建文件
+├── docker-compose.yml  # Docker 编排文件
+└── README.md           # 项目说明
+```
+
+## 依赖
+
+- `flask==3.0.0` - Web 框架
+- `qqwry-py3==1.2.1` - 纯真 IP 库
+
+## 公网 IP 获取服务
+
+按优先级顺序:
+1. https://1.1.1.1/cdn-cgi/trace (Cloudflare)
+2. https://checkip.amazonaws.com (AWS)
+3. https://ifconfig.me/ip (ifconfig.me)
+4. https://api.ipify.org (ipify)
+5. https://icanhazip.com (icanhazip)
+6. https://ipinfo.io/ip (ipinfo.io)
+
+## 技术栈
+
+- **后端**: Python 3.11 + Flask
+- **前端**: 原生 HTML5 + CSS3 + JavaScript
+- **数据库**: 纯真 IP 库 (qqwry.dat)
+- **部署**: Docker
+
+## 许可证
+
+MIT
+
+## 作者
+
+- 项目维护者
+- 数据提供: 纯真 IP 库