231 lines
6.1 KiB
Markdown
231 lines
6.1 KiB
Markdown
# DbusSmsForward
|
||
|
||
DbusSmsForward 的重构仓库目前已经具备一套可运行的 **Python 版本主链路**：
|
||
|
||
- 配置加载与兼容旧版 `appSettings`
|
||
- 文件短信源轮询
|
||
- ModemManager 短信收取/发送抽象
|
||
- 多通知通道分发（含 AutmanPush）
|
||
- Web 控制台（运行总览 / 最近事件 / 配置中心 / 短信测试台）
|
||
- CLI 运行、配置校验、环境自检、手工发送、Web 服务启动
|
||
- `env-check` 支持 text/json 两种输出，便于人看和自动化集成
|
||
- 单元测试与集成测试
|
||
|
||
仓库里仍保留原始 .NET 版本源码，便于对照迁移；当前建议优先使用 `src/` 下的 Python 实现。
|
||
|
||
---
|
||
|
||
## 当前重构状态
|
||
|
||
已完成的 Python 能力：
|
||
|
||
- `validate-config`：配置校验
|
||
- `env-check`：环境自检（检查 Python / 配置 / DBus / ModemManager 依赖）
|
||
- `run`：轮询短信源并分发通知
|
||
- `send`：手工触发通知分发；`--real-sms` 走真实短信发送
|
||
- `serve-web`：启动 Web 控制台
|
||
- Web API：
|
||
- `GET /api/health`
|
||
- `GET /api/system/status`
|
||
- `GET /api/dashboard`
|
||
- `GET /api/events`
|
||
- `GET/POST /api/settings`
|
||
- `POST /api/sms/send`
|
||
|
||
已覆盖的验证：
|
||
|
||
- 47 个自动化测试全部通过
|
||
- `appsettings.python.json` 配置校验通过
|
||
- 文件短信源手工跑通
|
||
|
||
---
|
||
|
||
## 目录说明
|
||
|
||
```text
|
||
src/dbussmsforward/ Python 重构主实现
|
||
tests/ 自动化测试
|
||
wwwroot/ Web 控制台静态资源
|
||
DbusTest/ 原始 .NET 实现（迁移参考）
|
||
appsettings.python.json Python 示例配置
|
||
```
|
||
|
||
---
|
||
|
||
## 运行要求
|
||
|
||
- Python 3.11+
|
||
- 当前项目采用 `src/` 布局，直接运行时请带上 `PYTHONPATH=src`
|
||
|
||
如果要接真实 ModemManager / DBus：
|
||
|
||
- 目标机器需要可访问系统 DBus
|
||
- 需要存在 `org.freedesktop.ModemManager1`
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1）校验配置
|
||
|
||
```bash
|
||
PYTHONPATH=src python3 -m dbussmsforward.cli validate-config --config appsettings.python.json
|
||
```
|
||
|
||
### 2）环境自检
|
||
|
||
```bash
|
||
PYTHONPATH=src python3 -m dbussmsforward.cli env-check --config appsettings.python.json
|
||
PYTHONPATH=src python3 -m dbussmsforward.cli env-check --config appsettings.python.json --format json
|
||
```
|
||
|
||
- 文件短信源场景：检查配置文件、Python 运行时、通知通道、短信文件路径
|
||
- ModemManager 场景：额外检查 `dbus_next`、`dbus-send` / `dbus-monitor` / `mmcli`、systemd 或 OpenWRT init 脚本提示
|
||
- 返回码：`0` 表示全部通过，`2` 表示存在缺项，适合部署脚本或 CI 直接判定
|
||
- `--format json`：输出 `results` + `summary`，适合安装器、CI、健康检查脚本消费
|
||
|
||
### 3）跑文件短信源示例
|
||
|
||
```bash
|
||
PYTHONPATH=src python3 -m dbussmsforward.cli run --config appsettings.python.json
|
||
```
|
||
|
||
### 3）手工发送一条测试短信到通知链路
|
||
|
||
```bash
|
||
PYTHONPATH=src python3 -m dbussmsforward.cli send --config appsettings.python.json --to 10086 --text '测试短信'
|
||
```
|
||
|
||
### 4）真实调用 ModemManager 发送短信
|
||
|
||
前提：配置中的 `sms_source.kind` 为 `modemmanager`。
|
||
|
||
```bash
|
||
PYTHONPATH=src python3 -m dbussmsforward.cli send --config appsettings.python.json --to 10086 --text '测试短信' --real-sms
|
||
```
|
||
|
||
### 5）启动 Web 控制台
|
||
|
||
```bash
|
||
PYTHONPATH=src python3 -m dbussmsforward.cli serve-web --config appsettings.python.json --host 0.0.0.0 --port 8080
|
||
```
|
||
|
||
打开：`http://127.0.0.1:8080`
|
||
|
||
---
|
||
|
||
## 配置示例
|
||
|
||
项目内置了 `appsettings.python.json`，包含：
|
||
|
||
- `forwarding.device_name`
|
||
- `notifications.console`
|
||
- `notifications.autman_push`
|
||
- `sms_source.kind=file`
|
||
- `sms_source.path=tests/fixtures/messages.json`
|
||
|
||
示例里默认启用了 console，AutmanPush 默认关闭，适合本地先验证主链路。
|
||
|
||
---
|
||
|
||
## Web 控制台功能
|
||
|
||
当前 Web 页面的核心能力：
|
||
|
||
- 运行总览：服务状态、监听地址、设备名、短信源、启用通道
|
||
- 最近事件：最近短信转发/发送结果，显示成功失败与通道
|
||
- 配置中心：在线修改配置并落盘
|
||
- 短信测试台：直接从网页发起手工测试
|
||
- 操作结果面板：展示最近一次操作返回
|
||
|
||
适合 Debian/OpenWRT 场景下作为单机维护后台。
|
||
|
||
---
|
||
|
||
## 开发者工作流
|
||
|
||
### 跑完整测试
|
||
|
||
```bash
|
||
PYTHONPATH=src python3 -m unittest discover -s tests -v
|
||
```
|
||
|
||
### 常用单命令回归
|
||
|
||
```bash
|
||
PYTHONPATH=src python3 -m dbussmsforward.cli validate-config --config appsettings.python.json
|
||
PYTHONPATH=src python3 -m dbussmsforward.cli run --config appsettings.python.json
|
||
```
|
||
|
||
### 可编辑安装
|
||
|
||
```bash
|
||
python3 -m pip install -e .
|
||
```
|
||
|
||
安装后可直接使用：
|
||
|
||
```bash
|
||
dbussmsforward validate-config --config appsettings.python.json
|
||
dbussmsforward serve-web --config appsettings.python.json --port 8080
|
||
```
|
||
|
||
---
|
||
|
||
## 兼容性说明
|
||
|
||
Python 版本配置加载器兼容两类结构：
|
||
|
||
1. 新结构：`daemon` / `forwarding` / `notifications` / `sms_source`
|
||
2. 旧结构：`.NET appSettings` 包装格式
|
||
|
||
其中 Autman Push 相关配置需包含：
|
||
|
||
- `ApiUrl` / `api_url`
|
||
- `AccessToken` / `access_token`
|
||
- `Method` / `method`
|
||
|
||
---
|
||
|
||
## 部署
|
||
|
||
本仓库已经补了部署模板，见：
|
||
|
||
- `docs/deployment.md`
|
||
- `deploy/common/appsettings.deploy.json`
|
||
- `deploy/debian/dbussmsforward.service`
|
||
- `deploy/debian/install.sh`
|
||
- `deploy/openwrt/dbussmsforward.init`
|
||
- `deploy/openwrt/install.sh`
|
||
|
||
支持两类部署方式：
|
||
|
||
1. **Debian + systemd**
|
||
2. **OpenWRT + procd**
|
||
|
||
服务文件默认使用：
|
||
|
||
- 配置路径：`/etc/dbussmsforward/appsettings.json`
|
||
- 程序目录：`/opt/dbussmsforward`
|
||
- 运行模式：`python3 -m dbussmsforward.cli run --iterations 0`
|
||
|
||
`--iterations 0` 表示持续轮询，适合作为守护进程运行。
|
||
|
||
---
|
||
|
||
## 后续建议
|
||
|
||
虽然主链路、文档和基础部署模板已经齐了，但如果继续往正式交付推进，可以按这个顺序继续：
|
||
|
||
1. 增加真实 Debian / OpenWRT 机器上的联调记录
|
||
2. 补充打包发布流程（wheel / sdist / release artifact）
|
||
3. 基于真实机器反馈继续扩展环境自检项（例如联网探测、服务状态细查）
|
||
4. 再决定是否补 Web 登录、权限和更完整的运维页面
|
||
|
||
---
|
||
|
||
## 参考
|
||
|
||
1. [ModemManager API document](https://www.freedesktop.org/software/ModemManager/api/latest/)
|
||
2. [Tmds.DBus](https://github.com/tmds/Tmds.DBus)
|