zqs1qiwan/qip-api repository overview

⁠qip-api: 带Web管理界面的自托管IP地理位置查询API

qip-api 是一个基于 FastAPI 和 IPIP.net 免费版IP数据库构建的、可自托管的轻量级IP地理位置查询API服务。它最大的特点是拥有一个用户友好的Web管理界面，让您无需触碰命令行，即可轻松上传和管理IP数据库。

⁠✨ 功能特点

• 🔐 安全认证: 管理界面 (/) 受密码保护，支持自定义或在容器首次启动时自动生成安全密码。
• ✅ 友好的Web管理界面: 无需命令行操作，通过浏览器即可完成 ipip.ipdb 数据库的首次上传或后续更新。
• 📦 无状态与持久化: 应用镜像本身不包含任何数据。您的数据库被安全地存储在通过Docker数据卷挂载的宿主机目录中，确保数据在容器重启或更新后不丢失。
• 🚀 高性能: 基于Python异步框架 FastAPI 和 Uvicorn 构建，拥有出色的性能和快速的响应能力。
• 🌐 智能IP识别: 部署在Cloudflare等反向代理后，能自动识别并使用 CF-Connecting-IP 头中的真实访客IP。
• 🐳 部署简单: 一行 docker run 命令即可启动完整服务，开箱即用。

⁠🚀 快速开始

只需四步，即可拥有您自己的IP查询API服务。

⁠第1步: 准备数据库文件

从 IPIP.net官网⁠ 下载最新的免费版 ipip.ipdb 数据库文件。或者从任意数据源获取ipdb数据库文件。

⁠第2步: 准备数据存储目录

在您的服务器上创建一个目录，用于持久化存储上传的数据库文件。

mkdir -p /opt/qip-api-data

⁠第3步: 运行Docker容器 (两种模式)

您可以选择使用自定义密码或让程序自动生成密码。

模式A：使用您自己的密码 (推荐)

通过 -e 参数传入 QIP_API_PASSWORD 环境变量来设置您自己的密码。

docker run -d \
    --name my-qip-api \
    -p 8080:80 \
    -v /opt/qip-api-data:/data \
    -e QIP_API_PASSWORD="your-strong-password-here" \
    --restart always \
    zqs1qiwan/qip-api:latest

模式B：自动生成随机密码

如果您不提供密码，服务在首次启动时会自动生成一个8位的随机密码，并打印到容器的日志中。

首先，不带 -e 参数运行：

docker run -d \
    --name my-qip-api \
    -p 8080:80 \
    -v /opt/qip-api-data:/data \
    --restart always \
    zqs1qiwan/qip-api:latest

然后，查看日志以获取密码：

docker logs my-qip-api

您会在日志开头看到类似 A random password has been generated: a1b2c3d4 的信息，a1b2c3d4 就是您的初始密码。

⁠第4步: 登录并上传数据库

在浏览器中打开 http://<你的服务器IP>:8080。您会看到一个登录页面。

• 如果您在第3步中设置了自定义密码，请使用它登录。
• 如果您没有设置密码，请通过 docker logs my-qip-api 命令查看自动生成的密码，然后用它登录。

登录成功后，您会看到上传页面，请通过该页面上传您在第一步中下载的 ipip.ipdb 文件。上传成功后，API服务即被激活！

⁠📖 API 使用说明

⁠1. 查询指定IP

• 端点: GET /api/{ip_address}
• 示例:

  curl http://<你的服务器IP>:8080/api/8.8.8.8
  

  Copy
• 成功响应:

  {
    "country_name": "美国",
    "region_name": "加利福尼亚州",
    "city_name": "山景城",
    "isp_domain": "google.com",
    "country_code": "US"
  }
  

  Copy

⁠2. 查询访问者自身IP

• 端点: GET /api/
• 示例:

  curl http://<你的服务器IP>:8080/api/
  

  Copy
• 成功响应: (返回您当前网络的IP信息)

⁠📄 许可证

本项目采用 MIT License⁠ 授权。