Skip to content

About

X3 天气短信管理台 — ESP32 开发板对接:天气短信定时群发、HA 全屋环境监测、企微/钉钉群转发、语音接听与录音管理台

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

📟 X3 天气短信管理台

每天定时把天气预报发成一条真短信 —— 家人不用装 App,手机有电就能收

Self-hosted weather-to-SMS gateway for the X3 GSM board · zero public IP required · two-way forwarding to WeCom groups · Home-Assistant aware · zero-dependency web console

Python FastAPI Docker License: MIT Platform Stars

管理台界面

快速开始 · 亮点 · 架构 · 界面预览 · 文档 · 常见问题


✨ 亮点

一句话:插 SIM 卡的 X3 开发板 + 这套服务 = 给家人手机发的每日天气短信,附带一个能看能管一切的可视化后台。

  • ⏰ 定时真短信 —— 多号码、多时段、多城市;天气自动拉取(Open-Meteo 主源 + wttr.in 兜底),70 字模板可视化编辑、字数条数实时提示
  • 🏠 全屋环境进短信 —— 对接 Home Assistant:室内温湿度、太阳能热水器、冰箱温度…13 个环境占位符,只在模板用到时才读 HA,读不到不影响发信
  • 📥 双向,不只发 —— 板子收到的新短信、来电、漏接、通话录音全部回流:企微群里直接收到一条可播放的原生语音消息,验证码短信单独提行
  • 🖥️ 开箱即用的后台 —— 单文件前端、零外部依赖、无构建步骤;天气/计划/模板/记录/板子事件一页全览
  • 🧨 群发能力 —— 一次 200 条,号码粘贴自动去重、去 +86、标可疑
  • 🏡 零公网依赖 —— 服务与板子同局域网直连,不需要公网 IP、不需要内网穿透
  • 🧪 没有板子也能玩 —— 自带模拟设备 + 四层诊断脚本,本地跑通全链路
  • 🔐 安全内置 —— 访问密码 + TOTP 两步验证(扫码绑定)、HMAC 签名 Cookie、防爆破锁定、开放接口凭密钥

🏗️ 架构

flowchart LR
    OM["☁️ 天气数据源<br/>Open-Meteo · wttr.in 兜底"]
    subgraph LAN["🏠 局域网 · 无需公网 IP"]
        direction TB
        UI["🖥️ 管理台(浏览器)"]
        SVC["⚙️ 本服务<br/>FastAPI · APScheduler · SQLite"]
        BOARD["📟 X3 开发板<br/>插 SIM 卡的短信模组"]
    end
    HA["🏡 Home Assistant"]
    PHONE["📱 家人的手机"]
    WECOM["👥 企业微信群"]

    OM -- "① 定时拉取天气" --> SVC
    HA -. "② 环境变量按需读取" .-> SVC
    UI -- "配置 / 预览 / 群发" --> SVC
    SVC -- "③ HTTP /ctrl 下发短信" --> BOARD
    BOARD -- "④ GSM 空口发送" --> PHONE
    BOARD -- "⑤ 回执 / 新短信 / 来电 / 录音上报" --> SVC
    SVC -- "⑥ 二次转发 · 录音转语音消息" --> WECOM
Loading

服务与板子互为客户端:服务调板子的 /ctrl 发短信,板子反过来把回执、收到的新短信、 来电和录音推给服务的上报接口——这就是为什么服务器必须和板子网络互通。

🚀 快速开始

Docker(推荐)

docker compose up -d --build     # 构建并启动,宿主机 8770 → 容器 8000
docker compose logs -f           # 看到 Uvicorn running 即成功

Windows:装 Python 3.10+ → 双击 start.bat → 打开 http://127.0.0.1:8000

Linux / 群晖 / 树莓派:

chmod +x start.sh && ./start.sh   # 自动建 venv、装依赖、起服务

部署到一台新服务器(含宝塔 / systemd / 数据迁移):看 deploy/DEPLOY-NEW-SERVER.md。 数据都在 ./data/(SQLite + 录音),重建容器不丢。

📸 界面预览

天气与趋势 定时计划
当前天气 发送计划
未来 7 天 短信模板
未来 7 天 短信模板

模板支持 16 个天气变量 + 13 个全屋环境变量,右侧一键插入、实时预览、超 70 字自动提示拆条。

🧭 功能总览

模块 说明
🌤️ 天气 实时 + 未来 7 天趋势线(内联 SVG);数据源 / 天数 / 时区 / 缓存可配
⏰ 发送计划 多号码、多时段、多城市,启用开关,下次执行倒计时
✉️ 短信模板 可视化编辑 + 变量插入 + 实时预览 + 字数/条数提示
📤 发送记录 四态跟踪:已入队 → 已发送 → 已送达 / 失败(板子回执驱动)
📨 板子事件 收到短信 / 来电 / 录音 / 设备异常,及每条是否已转进群
🧨 群发短信 200 条/次,号码解析(去重、去 +86、标可疑)
📟 设备对接 IP/端口/参数名全可配,连通性测试,演练模式(不真发)
📞 语音与录音 来电接听录音、录音转企微语音消息、语音通知/拨打
🏡 全屋环境 Home Assistant 温湿度 / 热水器 / 冰箱,环境历史曲线
🔌 开放集成 开放 API(第三方凭密钥)、MCP Server(AI 助手接入)

📚 文档导航

文档 内容
deploy/DEPLOY-NEW-SERVER.md 部署到一台新服务器(三条路线 + 首启 6 步 + 验收清单)
服务内 /guide 部署与联调全量文档(单文件、可打印、含拓扑图与故障排查)
deploy/Docker部署-小白手把手.md 第一次用 Docker?10 步每步"点哪里、输什么"
deploy/部署指南-局域网服务器.md 宝塔/局域网服务器保姆级手册(含一键安装脚本)
security-audit-20261018.md 安全审计记录(发现的坑与修法)

🧪 没有板子?本地跑通全链路

python tools/mock_device.py 8899        # 模拟板子
python tools/diagnose.py                # 四层诊断:配置→网络→设备→送达

把页面里的设备地址改成 127.0.0.1:8899,点「立即发送」——mock 终端会打印收到的号码和正文。

📁 项目结构

x3-weather-sms/
├── app/                     # 后端 · 19 个模块 · 约 1.1 万行 Python
│   ├── main.py              #   FastAPI 路由、鉴权中间件、生命周期
│   ├── config.py            #   环境变量与默认值
│   ├── db.py                #   SQLite:配置/记录/事件/录音索引
│   ├── auth.py              #   鉴权:HMAC Cookie、防爆破、TOTP MFA
│   ├── weather.py           #   Open-Meteo + wttr.in 双源天气
│   ├── device.py            #   X3 对接:token、/ctrl 调用与解析
│   ├── board.py             #   板子对接页:URL 生成、状态聚合
│   ├── sms.py               #   模板渲染、字数/条数估算
│   ├── scheduler.py         #   APScheduler 定时编排、天气缓存
│   ├── events.py            #   板子事件解析入库(短信/来电/录音/异常)
│   ├── notify.py            #   企微/钉钉群二次转发
│   ├── rec.py               #   通话录音接收(AMR multipart)
│   ├── voice.py             #   语音通知 / 拨打
│   ├── ha.py                #   Home Assistant 集成(自动登录换 token)
│   ├── home.py              #   「全家概况」聚合
│   ├── iot.py               #   家居设备读写(dryRun 保护)
│   ├── envlog.py            #   环境数据历史曲线
│   ├── openapi.py           #   开放 API(第三方凭密钥)
│   └── mcp.py               #   MCP Server(AI 助手接入)
├── static/                  # 前端 · 原生 JS 单文件 · 零构建零依赖
├── deploy/                  # 部署文档 + 宝塔/Docker/systemd 脚本
├── tools/                   # mock 设备 · 四层诊断 · 打包与 QA 脚本
├── docs/                    # 截图
├── Dockerfile · docker-compose.yml
├── start.sh · start.bat
└── requirements.txt         # 7 个直接依赖,无重依赖

📟 接 X3 开发板(关键 5 步)

1. 让板子联网

插好 SIM 卡 → 通电(5V 2A,别超 12V)→ 按说明书配 WiFi。联通卡务必在激活后立刻开启流量,规避运营商风控。

2. 找到板子的局域网 IP

设备后台首页 / 路由器 DHCP 列表 / 发短信 *#stat#000000 看回信。建议在路由器上绑定静态 IP。

3. 确认管理员密码 / token

默认 admin / admin,token = MD5("admin|" + 密码) 小写 16 进制:

echo -n "admin|admin" | md5sum     # -n 不能少

4. 在管理台填设备参数

页面「X3 开发板对接」:设备 IP、端口(默认 80)、用户名/密码、控制路径(默认 /ctrl)、 命令 sendsms、卡槽/号码/内容参数名(默认 p1/p2/p3)、卡槽号(必填,单卡填 1)。

先保持「演练模式」,点「设备测试」看到 {"code":0} 再关演练。

5. 核对 sendsms 参数名(最容易踩的坑)

X32v158 固件的 sendsms 用位置参数,三个都必填:

GET /ctrl?token=...&cmd=sendsms&p1=1&p2=13800138000&p3=短信正文&tid=1704038400

老固件可能是 phNum/smsBd。对不上不用改代码,页面上改三个参数名输入框即可。

📨 回执、群转发与录音语音(深度配置)

让回执能回来(否则状态永远停在「已入队」)

code=0 只是入队。真实发送结果靠板子异步推送 402/502/503 回执。两件事必须做:

① 板子上报地址指向本服务

curl "http://板子IP/ctrl?token=<token>&cmd=setinf&p1=http://本机IP:8000/api/device/report&p2=post&p3=json"
curl "http://板子IP/ctrl?token=<token>&cmd=askinf"   # 验证

② 删掉 502/503 的自定义消息模板(模板会把报文套成企微格式,tid 全丢)

curl "http://板子IP/ctrl?token=<token>&cmd=askcustmsg"          # 看有哪些模板
curl "http://板子IP/ctrl?token=<token>&cmd=setcustmsg&p1=502"   # 不传 p2 即删除
curl "http://板子IP/ctrl?token=<token>&cmd=setcustmsg&p1=503"

⚠️ setcustmsg 模板是本项目最大的坑:只要板子给某类消息套了模板, 该类报文就没有 type 字段,服务端认不出只能丢——「群里收不到短信也收不到语音」 最隐蔽的原因。删完 502/503 顺手检查 501/603/695。

群转发:服务端二次转发

板子上报地址只能填一个 →「板子 → 本服务 → 企微/钉钉群」。四类开关独立:

开关 消息号 群里看到的
收到短信 501 发件人/时间/正文,验证码单独提行
来电与通话 601/602/603 振铃、接通、结束(含时长),漏接单独报
录音上报 695/696 原生语音消息(可播放、可转文字)
设备异常 100/205/209/301 SIM 拔出、欠费停卡、卡槽故障

录音怎么变成群里的语音消息

板子录音是 AMR / ≤60 秒 / ≤2MB,正好符合企微群机器人语音规格,无需转码:

板子 ──AMR(multipart)──▶ /api/rec/upload ──▶ 落盘 data/rec/ + 返回 media_id
     ──▶ 板子推 695(带 media_id)──▶ upload_media → 企微 voice 消息

录音地址在页面「设备对接」里自动生成(含 k= 校验串与模板变量),原样复制到板子 setamrurl 即可。 板子「来电处理」须设为 2 = 接听并录音。

🔌 API 一览
方法 路径 说明
GET / 管理台(启用访问密码时弹登录遮罩)
GET /guide 部署与联调全量文档(单文件、可打印)
GET /health 健康检查(免登录,给 Docker/监控用)
GET /api/dashboard 设备状态、下次任务、今日统计
GET /api/weather?refresh=1 天气数据(缓存时长可配)
GET/POST /api/settings 读取/保存配置(密码类字段不回传)
POST /api/preview 渲染短信预览(不发送)
POST /api/send 立即发送
POST /api/sms/bulk 群发(去重、去 +86,单次上限 200)
GET /api/device/status?force=1 设备/网络/SIM 状态(20 秒缓存)
GET /api/logs?limit=50 发送记录
GET /api/events?limit=20 板子事件流水
POST /api/device/report 板子主动上报(1 秒内返回 200,免登录)
POST /api/rec/upload?k=… 板子上传通话录音(免登录,凭 k 校验)
POST /api/device/test 连通性测试 / 运维命令透传
POST /api/wecom/test 测试企微群机器人
GET/POST /api/login /api/logout /api/auth/status 登录态(HttpOnly Cookie,7 天)

启用访问密码后,除「免登录」接口外,其余 /api/* 未带 Cookie 一律 401。 另有开放 API(第三方凭密钥)与 MCP Server,见 app/openapi.py / app/mcp.py。

🖥️ 部署形态:宝塔 / 公网 / 开机自启

完整步骤见 deploy/DEPLOY-NEW-SERVER.md 与服务内 /guide。要点:

  • ⚠️ 必须单进程:定时任务跑在 APScheduler 进程内存里,uvicorn 加 --workers 或起多实例 = 同一手机号收到 N 条重复短信。真要多进程:外部 cron 调 /api/send 并关掉「启用定时发送」。
  • 公网部署三件必做的事:① 设访问密码 ② 8000 端口不对公网开放(只放行 80/443) ③ 改掉板子出厂密码 admin/admin
  • 服务器到板子始终是明文 HTTP(板子固件不支持 TLS),安全性靠 token 保证——不要把板子 80 端口映射到公网
  • 开机自启:Windows 任务计划 / deploy/x3sms.service(systemd)
  • 时区必须正确(Docker 镜像已装 tzdata;裸机 timedatectl set-timezone Asia/Shanghai), 否则定时任务按 UTC 跑,差 8 小时
❓ 常见问题
现象 原因 / 处理
设备测试 code=100 token 不对:重新算 MD5("admin|密码")
设备测试 code=101 参数格式错:核对 sendsms 的卡槽/号码/内容参数名
连不上(NET) IP/端口错、不同网段、板子没联网、防火墙
状态永远「已入队」 板子上报地址没指向本服务,或 502/503 配了自定义模板(见上文)
收不到短信但 code=0 SIM 欠费/停机、号码带了 +86、运营商拦截
短信被拆成 2 条 超 70 字,精简模板
天气显示 wttr.in Open-Meteo 拉取失败已自动降级;固定 open_meteo 数据源可看报错
页面一直弹登录 设置了访问密码;忘记密码:停服务后 sqlite3 data/app.db "update settings set value='' where key='admin_password'"
定时没触发 「启用定时发送」开关、服务是否常驻、时区是否 Asia/Shanghai

code=0 只代表板子接收了指令,不等于手机收到。 送达证据:板子后台有记录 + 手机确实响了。

🔐 安全清单
  • 默认不启用鉴权(局域网免登录)。放公网前务必设访问密码(页面或 .env 的 ADMIN_PASSWORD)
  • 可选 TOTP 两步验证:页面扫码绑定(纯标准库实现,二维码 SVG 渲染,无 pillow 依赖)
  • Cookie 用 HMAC-SHA256 签名;同 IP 连续错 5 次锁 60 秒;改密码旧 Cookie 立即失效
  • 建议套 HTTPS(Let's Encrypt);.env 含板子密码,勿提交 git(已配 .gitignore),权限 640
  • 板子出厂密码 admin 建议改掉;板子 80 端口不要映射公网,跨公网用 frp
  • 密钥、账号、webhook 一律不内置在代码里,全部通过页面或 .env 注入

🤝 贡献

Issue / PR 都欢迎。改代码前先看 /guide 里的「已知坑」——尤其是 setcustmsg 模板、 单进程约束和空仓库推送这几处,都是真实踩出来的。

📄 许可证

MIT © 2026 大灰狼


如果这个项目帮到了你,欢迎点个 ⭐

Keywords: weather-sms gsm sim800 esp32 fastapi home-assistant wecom 钉钉 短信 智能家居 老人 IoT APScheduler SQLite

About

X3 天气短信管理台 — ESP32 开发板对接:天气短信定时群发、HA 全屋环境监测、企微/钉钉群转发、语音接听与录音管理台

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages