ip-service/README.md

# IP 地址查询服务

跨平台 IP 地址查询服务，支持 Windows/Linux 部署，前端采用 ES5 标准 JavaScript。

## 功能特性

- ✅ 获取访问者真实 IP 地址
- ✅ 支持代理服务器（X-Forwarded-For）
- ✅ IP 地理位置查询（国家/省份/城市/运营商/时区）
- ✅ 内存缓存优化（10 分钟 TTL）
- ✅ 跨平台兼容（Windows/Linux）
- ✅ 前端 ES5 兼容（支持 IE9+）
- ✅ CORS 跨域支持

## 快速开始

### 安装依赖

```bash
npm install
```

### 启动服务

```bash
# 开发环境
npm run dev

# 生产环境
npm start

# 或直接运行
node server.js
```

服务默认运行在 `http://localhost:3000`

## API 接口

### 1. 获取 IP 地址

```
GET /api/get-ip
```

**响应示例：**
```json
{
  "ip": "123.45.67.89",
  "timestamp": 1711162800000,
  "server": "linux"
}
```

### 2. 获取 IP + 地理位置

```
GET /api/get-ip-info
```

**响应示例：**
```json
{
  "ip": "123.45.67.89",
  "country": "中国",
  "region": "北京市",
  "city": "北京市",
  "isp": "中国电信",
  "timezone": "Asia/Shanghai",
  "query_time": 1711162800000,
  "fromCache": false
}
```

### 3. 健康检查

```
GET /health
```

**响应示例：**
```json
{
  "status": "ok",
  "uptime": 1234.56,
  "platform": "linux",
  "memory": {
    "rss": 52428800,
    "heapTotal": 8388608,
    "heapUsed": 6291456,
    "external": 1024000
  }
}
```

## 前端使用

### 浏览器中使用

```html
<script src="ip-service.js"></script>
<script>
  var ipService = new IPService();
  
  // 获取 IP
  ipService.getIP(function(error, data) {
    if (error) {
      console.error(error);
      return;
    }
    console.log('IP:', data.ip);
  });
  
  // 获取完整信息
  ipService.getIPInfo(function(error, data) {
    if (error) {
      console.error(error);
      return;
    }
    console.log('位置:', data.city, data.region, data.country);
  });
</script>
```

### 自定义 API 地址

```javascript
// 如果后端部署在不同域名
var ipService = new IPService('https://api.example.com');
```

## 部署

### Windows

```batch
# 双击运行
start.bat

# 或命令行
npm install
node server.js
```

### Linux

```bash
# 赋予执行权限
chmod +x start.sh

# 运行
./start.sh

# 或
npm install
node server.js
```

### 生产环境（PM2）

```bash
# 安装 PM2
npm install -g pm2

# 启动服务
pm2 start server.js --name ip-service

# 开机自启
pm2 startup
pm2 save

# 查看状态
pm2 status

# 查看日志
pm2 logs ip-service
```

### Nginx 反向代理

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location /api/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location / {
        root /var/www/ip-service;
        index index.html;
    }
}
```

## 配置

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| PORT | 服务端口 | 3000 |

### 缓存配置

在 `server.js` 中修改：

```javascript
var CACHE_TTL = 10 * 60 * 1000; // 缓存时间（毫秒），默认 10 分钟
```

## 项目结构

```
ip-service/
├── server.js           # 后端服务
├── ip-service.js       # 前端客户端库
├── index.html          # 示例页面
├── package.json        # 项目配置
├── .gitignore          # Git 忽略配置
├── start.bat           # Windows 启动脚本
├── start.sh            # Linux 启动脚本
└── README.md           # 说明文档
```

## 兼容性

| 组件 | 要求 |
|------|------|
| Node.js | v14.0.0+ |
| 操作系统 | Windows 7+, Linux (所有主流发行版) |
| 浏览器 | IE9+, Chrome, Firefox, Safari, Edge |

## 技术栈

- **后端**: Node.js + Express
- **前端**: 原生 JavaScript (ES5)
- **IP 数据**: ip-api.com (免费，无需 API Key)

## 注意事项

1. **ip-api.com 限制**: 免费版限速 45 次/分钟，商用需购买授权
2. **HTTPS**: 生产环境建议启用 HTTPS
3. **隐私合规**: 收集 IP 地址可能涉及隐私法规（如 GDPR），请确保合规

## 替代 IP 数据源

如需更高精度或商用，可替换 `server.js` 中的查询接口：

- [ipapi.com](https://ipapi.com/)
- [IPinfo](https://ipinfo.io/)
- [MaxMind GeoIP2](https://www.maxmind.com/)

## License

MIT

## 更新日志

### v1.0.0 (2026-03-23)
- 初始版本发布
- 支持 IP 地址查询
- 支持地理位置查询
- 跨平台部署支持
- 前端 ES5 兼容