feat: 初始版本 - 跨平台 IP 地址查询服务
- 后端服务 (Express + ES5) - 支持获取真实客户端 IP - 支持代理服务器 (X-Forwarded-For) - IP 地理位置查询 - 内存缓存优化 (10 分钟 TTL) - 健康检查接口 - 前端客户端 (ES5 兼容) - IPService 类库 - 支持回调函数 - 示例页面 - 跨平台部署 - Windows 启动脚本 (start.bat) - Linux 启动脚本 (start.sh) - PM2 生产环境支持 - 文档 - README.md 完整说明 - .gitignore 配置
This commit is contained in:
Coding Expert
269
README.md
Normal file
269
README.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# 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 兼容
|
||||
Reference in New Issue
Block a user