每天定时把天气预报发成一条真短信 —— 家人不用装 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
一句话:插 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
服务与板子互为客户端:服务调板子的
/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 天 | 短信模板 |
![]() |
![]() |
模板支持 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 步)
插好 SIM 卡 → 通电(5V 2A,别超 12V)→ 按说明书配 WiFi。联通卡务必在激活后立刻开启流量,规避运营商风控。
设备后台首页 / 路由器 DHCP 列表 / 发短信 *#stat#000000 看回信。建议在路由器上绑定静态 IP。
默认 admin / admin,token = MD5("admin|" + 密码) 小写 16 进制:
echo -n "admin|admin" | md5sum # -n 不能少页面「X3 开发板对接」:设备 IP、端口(默认 80)、用户名/密码、控制路径(默认 /ctrl)、
命令 sendsms、卡槽/号码/内容参数名(默认 p1/p2/p3)、卡槽号(必填,单卡填 1)。
先保持「演练模式」,点「设备测试」看到 {"code":0} 再关演练。
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



