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;
    }
}
```

---

## Docker 部署（推荐）

### 方式一：Docker Compose（最简单）

```bash
# 1. 克隆项目
git clone http://git.joywaygames.cn:3000/daoqi/ip-service.git
cd ip-service

# 2. 构建并启动
docker-compose up -d

# 3. 查看状态
docker-compose ps

# 4. 查看日志
docker-compose logs -f

# 5. 测试
curl http://localhost:3000/api/get-ip
```

### 方式二：纯 Docker 命令

```bash
# 1. 构建镜像
docker build -t ip-service:latest .

# 2. 运行容器
docker run -d \
  --name ip-service \
  -p 3000:3000 \
  --restart unless-stopped \
  -e NODE_ENV=production \
  ip-service:latest

# 3. 查看状态
docker ps

# 4. 查看日志
docker logs -f ip-service

# 5. 测试
curl http://localhost:3000/api/get-ip
```

### 方式三：生产环境部署（带 Nginx）

创建 `docker-compose.prod.yml`：

```yaml
version: '3.8'

services:
  ip-service:
    build: .
    container_name: ip-service
    restart: unless-stopped
    expose:
      - "3000"
    environment:
      - NODE_ENV=production
    networks:
      - app-network

  nginx:
    image: nginx:alpine
    container_name: nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - ip-service
    networks:
      - app-network

networks:
  app-network:
    driver: bridge
```

启动：

```bash
docker-compose -f docker-compose.prod.yml up -d
```

### Docker 常用命令

```bash
# 启动
docker-compose up -d

# 停止
docker-compose down

# 重启
docker-compose restart

# 查看日志
docker-compose logs -f

# 重新构建
docker-compose build --no-cache

# 进入容器
docker-compose exec ip-service sh

# 查看资源使用
docker stats ip-service

# 清理（删除容器和镜像）
docker-compose down --rmi all
```

### 更新部署

```bash
# 1. 拉取最新代码
git pull origin master

# 2. 重新构建并启动
docker-compose up -d --build

# 3. 清理旧镜像
docker image prune -f
```

## 配置

### 环境变量

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

### 缓存配置

在 `server.js` 中修改：

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

## 项目结构

```
ip-service/
├── server.js           # 后端服务
├── ip-service.js       # 前端客户端库
├── index.html          # 示例页面
├── package.json        # 项目配置
├── Dockerfile          # Docker 镜像配置
├── docker-compose.yml  # Docker Compose 配置
├── .dockerignore       # Docker 忽略配置
├── .env.example        # 环境变量示例
├── .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 兼容