中国电信手机话费、流量、语音通话监控工具。纯 Python 实现，无需 Docker，一个脚本搞定全量查询 + 多渠道通知推送。
- 全量数据查询 — 余额、欠费、本月消费、费用明细、通话用量（含分类）、通用/专用/总流量、流量包明细、共享套餐用量
- 登录风控保护 — 连续失败 5 次自动停止，防止账号被风控锁定
- 9 种通知推送渠道 — SMTP / PushPlus / Server酱 / Bark / Telegram / 企业微信 / 钉钉 / 飞书 / 自定义 Webhook，配置驱动，填了就推送、不填就跳过，可同时启用多个
- 灵活输出控制 — 全局默认 + 每号独立覆盖，按需开关任意字段，输出内容完全由配置文件定义
- 数据完整性补全 — 当 API 未返回通用/专用流量总量时，自动从流量包明细反算补全
- 全中文配置 — JSON 配置文件全部使用中文键名，直观易读，零学习成本
- Token 持久化 — 登录凭证自动缓存，避免频繁登录触发风控
- 多号批量查询 — 配置文件一次配好，双击 BAT 即可查全部
- 零依赖快速部署 — 纯 Python，双击 BAT 或定时任务即可运行；也支持 Docker 容器化部署
- 可扩展架构 — 通知推送采用统一入口 + 渠道分发模式，新增渠道只需添加一个函数；输出字段通过配置映射表驱动，新增查询项只需扩展映射即可
- I/O 密集型并发 — 多账号查询使用
asyncio.gather并发，速度快
pip install -r requirements.txtcp telecom_config.example.json telecom_config.json编辑 telecom_config.json，填入手机号、服务密码，按需调整输出设置：
{
"输出设置": {
"通用流量": 1,
"专用流量": 1,
"总流量": 1,
"通话分类": 0
},
"手机号": [
{ "号码": "18000000000", "服务密码": "your_password" }
]
}服务密码为电信 6 位数字服务密码，非登录密码。如忘记可在电信 APP 或拨打 10000 重置。
# 从配置文件读取所有号码
python telecom_query.py
# 单号查询
python telecom_query.py --phone 18000000000 --password your_password
# JSON 格式完整数据输出
python telecom_query.py --json
# 强制显示流量包明细
python telecom_query.py --packages双击 查询话费.bat 即可查询配置文件中的所有号码。
以下手机号已脱敏处理，实际输出显示完整号码。
手机号：180****5334 城市：江西南昌
余额：¥280.62
本月消费：¥41.90
通用流量：已用 0 KB / 总 40.00 GB
专用流量：已用 5.22 GB / 总 540.00 GB
总流量：已用 5.22 GB / 总 580.00 GB
查询时间：2026-05-22 19:36:58
手机号：180****5393 城市：江西南昌
余额：¥15.30
本月消费：¥29.00
通用流量：已用 3.14 GB / 总 40.00 GB
专用流量：已用 1.20 GB / 总 30.00 GB
总流量：已用 4.34 GB / 总 70.00 GB
查询时间：2026-05-22 19:36:58
telecom_config.json 中的 输出设置 控制每个字段是否显示，全局默认 + 每号独立覆盖，灵活度远高于固定输出脚本。
| 字段 | 默认 | 说明 |
|---|---|---|
城市 |
1 | 所在省市 |
余额 |
1 | 账户余额 |
欠费 |
0 | 欠费金额 |
本月消费 |
1 | 当月已产生费用 |
费用明细 |
0 | 套餐/增值业务等逐项构成 |
通话已用 |
0 | 已用/总量（分钟） |
通话剩余 |
0 | 剩余分钟数 |
通话分类 |
0 | 省内/国内等分类明细 |
通用流量 |
1 | 通用流量已用/总量 |
专用流量 |
1 | 专用流量已用/总量 |
总流量 |
1 | 总流量已用/总量 |
流量包明细 |
0 | 每行一条流量包 |
账单提示 |
0 | 账单周期等提示 |
查询时间 |
1 | 查询时间戳 |
1= 显示，0= 隐藏。在号码的输出设置中覆盖即可独立定制。
{
"输出设置": {
"通用流量": 1,
"专用流量": 1,
"总流量": 1,
"通话分类": 0
},
"手机号": [
{
"号码": "18000000000",
"服务密码": "your_password",
"输出设置": {
"费用明细": 1,
"流量包明细": 1
}
}
]
}该号码会额外显示费用明细和流量包明细，其余字段继承全局默认值。
输出字段由脚本内的 FIELD_MAP 映射表驱动，新增查询项只需：
- 在
parse_query_data()中解析新字段 - 在
FIELD_MAP中注册中文字段名 → 英文 key 的映射 - 在
DEFAULT_OUTPUT中设置默认开关
无需修改输出逻辑，配置即可生效。通知推送采用同样的扩展模式，新增渠道只需在 send_notify() 中添加对应分发函数。
在配置文件中添加 通知推送 段，设置 "启用": true 后，脚本会在查询完成后自动推送结果。
{
"通知推送": {
"启用": true
}
}启用：是否开启通知推送（默认false）
填入对应字段即可自动启用，不填则跳过。支持同时启用多个渠道。
| 渠道 | 配置字段 | 说明 |
|---|---|---|
| SMTP 邮件 | SMTP服务器 SMTP端口 SMTP_SSL 发件邮箱 邮箱密码或授权码 收件邮箱 |
最通用的推送方式 |
| PushPlus | PushPlus令牌 |
微信推送，填令牌即可 |
| Server酱 | Server酱密钥 |
微信推送，支持 Turbo 版 |
| Bark | Bark设备码 |
iOS 推送 |
| Telegram | Telegram机器人Token Telegram用户ID |
Telegram Bot 推送 |
| 企业微信 | 企业微信机器人Key |
机器人 Webhook 推送 |
| 钉钉 | 钉钉机器人Token 钉钉机器人密钥 |
支持签名验证 |
| 飞书 | 飞书机器人Key |
机器人 Webhook 推送 |
| 自定义 Webhook | 自定义Webhook地址 自定义Webhook方法 自定义Webhook请求体 |
通用兜底，支持模板变量 $title $content |
{
"通知推送": {
"启用": true,
"推送渠道": {
"SMTP服务器": "smtp.qq.com",
"SMTP端口": 465,
"SMTP_SSL": true,
"发件邮箱": "your@qq.com",
"邮箱密码或授权码": "your_auth_code",
"收件邮箱": "receiver@example.com"
},
"可选渠道": {
"PushPlus令牌": "your_pushplus_token",
"企业微信机器人Key": "your_wecom_key"
}
}
}项目根目录下提供 Dockerfile，可直接打包为镜像运行。配置文件和 Token 缓存通过挂载目录 /app/data 持久化。
构建与运行：
# 构建镜像
docker build -t telecom-monitor .
# 运行（挂载配置文件目录）
docker run --rm \
-v /path/to/your/config:/app/data \
telecom-monitor将
telecom_config.json放在宿主机挂载目录中，脚本会自动从/app/data/telecom_config.json读取。Token 缓存也会保存在该目录下。也可通过-e TELECOM_DATA_DIR=/other/path指定其他数据目录。
定时任务（cron）：
# 每天早上 8 点自动查询并推送
0 8 * * * docker run --rm -v /path/to/your/config:/app/data telecom-monitor详见 QINGLONG.md
核心优势：
电信脚本基于纯 API 登录，无需 Playwright 浏览器，比移动脚本更适合青龙面板环境。
快速步骤：
- 在青龙「依赖管理」安装
requestspycryptodome - 将
telecom_query.py上传到青龙「脚本管理」 - 在同目录创建
telecom_config.json（参考telecom_config.example.json） - 在青龙「定时任务」中新建任务，命令填
task telecom_query.py
Token 缓存在
data/tokens.json，首次登录后后续直接复用，无需重复输入密码。
登录连续失败 5 次会自动停止，防止账号被风控锁定。
脚本运行时会在数据目录下生成以下文件（已在 .gitignore 中排除）：
telecom_tokens/
├── tokens.json # 登录 Token 缓存
└── fail_count.json # 登录失败计数（风控保护）
TelecomMonitor/
├── telecom_query.py # 主脚本（查询 + 通知推送）
├── telecom_config.example.json # 配置文件模板（脱敏）
├── telecom_config.json # 实际配置（需自建，含敏感信息）
├── Dockerfile # Docker 打包配置
├── requirements.txt # Python 依赖
├── 查询话费.bat # Windows 快捷启动
├── .gitignore
└── README.md
感谢 gsons/boxjs 仓库提供的电信接口数据与分析。
本项目仅供个人学习和研究使用。请勿用于任何商业或非法用途。使用本工具所产生的任何后果由使用者自行承担。请合理使用，避免频繁调用对电信服务器造成压力。
MIT