# phone

**Repository Path**: python_90/phone

## Basic Information

- **Project Name**: phone
- **Description**: 手机归属地
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-09
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 手机号归属地补全工具

一个**开箱即用**的小工具：自动给本地数据库里没有归属地的手机号，批量补上**省份、城市、运营商**信息。

> 数据来源：360 手机号归属地公开接口。  
> 运行方式：命令行一键运行，无需懂代码。

---

## 一、它能做什么？

| 项目 | 说明 |
| --- | --- |
| 主要功能 | 读取 `phone.db` 数据库中归属地为空的手机号，联网查询后补全 `province`（省）、`city`（市）、`sp`（运营商） |
| 适合人群 | 需要批量补全手机号归属地的人，会基本命令行操作即可 |
| 处理速度 | 多个号码同时查询（协程并发），速度快 |
| 是否改原数据 | 只补全空字段，已有归属地的号码不会被动 |

---

## 二、准备工作（只需做一次）

### 1. 安装 Python

电脑需安装 **Python 3.8 及以上**版本。打开命令行输入 `python --version`，能看到版本号说明已安装；没有的话去 [python.org](https://www.python.org/downloads/) 下载安装，安装时勾选「Add Python to PATH」。

### 2. 安装 uv（环境管理小工具，推荐）

`uv` 可以帮你一键创建独立环境，避免污染系统。  
在命令行执行：

```bash
pip install uv
```

### 3. 准备数据库文件

确保 `phone.db` 和 `app.py` 在**同一个文件夹**下。本仓库已自带示例数据库，可直接使用。

---

## 三、开始使用

### 第 1 步：打开命令行，进入项目文件夹

```bash
cd E:\code\phone
```

### 第 2 步：创建并激活独立环境

```bash
uv venv
.venv\Scripts\activate
```

激活成功后，命令行最前面会出现 `(.venv)` 字样。

### 第 3 步：安装依赖

```bash
uv pip install -r requirements.txt
```

### 第 4 步：运行工具

```bash
python app.py
```

运行后你会看到进度条和实时统计，结束后会给出「成功 / 失败 / 耗时」汇总。

---

## 四、常用命令一览

| 想做的事 | 命令 |
| --- | --- |
| 正式运行（会写入数据库） | `python app.py` |
| 先试运行（只查询、不写入，用来验证） | `python app.py --dry-run` |
| 只处理第一页（小范围测试） | `python app.py --max-pages 1` |
| 指定其他配置文件 | `python app.py --config my.ini` |
| 查看所有可用参数 | `python app.py --help` |

---

## 五、配置说明（改参数不用动代码）

所有运行参数都在 **`config.ini`** 文件里，用记事本打开即可修改。改完保存，重新运行就生效。

| 配置段 | 配置项 | 作用 | 建议值 |
| --- | --- | --- | --- |
| `[database]` | `path` | 数据库文件名或路径 | `phone.db` |
| `[api]` | `url` | 查询接口地址 | 一般不用改 |
| `[api]` | `timeout_connect` | 连接超时（秒） | `10` |
| `[api]` | `timeout_read` | 读取超时（秒） | `5` |
| `[api]` | `max_retries` | 失败重试次数 | `3` |
| `[api]` | `retry_interval` | 重试间隔（秒） | `1` |
| `[task]` | `page_size` | 每页读取条数 | `200` |
| `[task]` | `max_workers` | 同时查询的并发数 | `50` |
| `[task]` | `dry_run` | 是否只试运行 | `false` |

> 小提示：`page_size` 和 `max_workers` 调大可加快速度，但太大可能被接口限流或占用过多内存。

---

## 六、常见问题排错（FAQ）

**Q1：运行报错「未找到配置文件 config.ini」？**  
A：把 `config.ini` 放到和 `app.py` 同一个文件夹下即可。没有它也能用默认参数运行，只是不能自定义。

**Q2：报错「数据库打开失败」或「文件不存在」？**  
A：检查 `config.ini` 里 `path` 指向的数据库文件是否存在、路径是否正确。确保 `phone.db` 和程序在同一目录。

**Q3：提示「database is locked」或写入失败？**  
A：数据库被其他程序（如 Navicat）打开了。请先**关闭其他正在使用该数据库的程序**，再重新运行。本工具已做批量写入和重试，正常情况下不会出现此问题。

**Q4：大量号码显示「请求超时」或「网络连接失败」？**  
A：通常是网络问题或接口临时不可用。可适当调大 `timeout_connect`、`max_retries`，或稍后重试。

**Q5：运行中想中断怎么办？**  
A：按 `Ctrl + C` 即可安全退出，已写入的数据不会丢失。

**Q6：中文显示乱码？**  
A：本工具已自动处理 UTF-8 输出。如仍乱码，把命令行窗口切到 UTF-8：执行 `chcp 65001` 后再运行。

**Q7：怎么知道有没有真的写进去？**  
A：先用 `python app.py --dry-run` 试运行看输出；确认无误后去掉 `--dry-run` 正式运行。也可用 Navicat 等工具打开 `phone.db` 查看 `province`、`city`、`sp` 字段。

**Q8：依赖装不上 / 版本冲突？**  
A：删除 `.venv` 文件夹后重新执行第 2、3 步。若 `requirements.txt` 中的旧版本装不上，可适当升级版本号。

---

## 七、项目结构

```
phone/
├── app.py            主程序（一键运行）
├── config.ini        配置文件（改参数用）
├── requirements.txt  依赖清单
├── phone.db          手机号数据库（SQLite）
├── phone.sql         数据库结构导出脚本
└── readme.md         本说明文档
```

---

## 八、依赖管理

| 场景 | 命令 |
| --- | --- |
| 创建虚拟环境 | `uv venv` |
| 激活虚拟环境 | `.venv\Scripts\activate` |
| 安装依赖 | `uv pip install -r requirements.txt` |
| 新增依赖后导出 | `uv pip freeze > requirements.txt` |

> 旧方式（无 uv）：`pip install -r requirements.txt`

---

## 九、安全与稳定性说明

- ✅ 数据库写入使用**参数化查询**，杜绝 SQL 注入风险。
- ✅ 网络请求含**超时与重试**，不会因接口偶发故障而崩溃。
- ✅ 接口返回异常（非 JSON、字段缺失）时**自动跳过**，不影响其他号码。
- ✅ 写库集中在主线程**批量执行**，避免并发写库冲突。
- ✅ 启动时**校验所有配置**，配置错误会立刻提示原因和修正建议，不会运行到一半才报错。
- ✅ 运行结束自动**关闭数据库连接**，不残留资源。