w1ndyb0y
46be9f483f
- Add architecture diagram and data flow - Add project directory structure tree - Add technology stack table - Add Taskfile-based quick start and common commands - Add cross-compilation instructions - Add full config YAML example with all options - Add test section with coverage info - Add license section - Keep existing download and release links
202 lines
5.6 KiB
Markdown
202 lines
5.6 KiB
Markdown
# tele-recv 串口电报接收器
|
||
|
||
[](http://d2.int.it2000.com.cn/airport/tele-recv)
|
||
|
||
机场串口电报数据缓存与分发程序。从串口读取电报（ZCZC...NNNN 格式），持久化到 SQLite，并通过 TCP 和/或 Apache Pulsar 分发。
|
||
|
||
## 架构
|
||
|
||
```
|
||
串口 (ttyS0) → serial.Port → telegram.Parser → storage.Store (SQLite)
|
||
↓
|
||
transport.Sender
|
||
↓
|
||
┌──────────┴──────────┐
|
||
↓ ↓
|
||
TCP Client Apache Pulsar
|
||
```
|
||
|
||
核心原则：**先持久化，再分发**。无论配置何种传输模式，电报始终先写入 SQLite，确保数据不丢失。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
tele-recv/
|
||
├── app/ # 应用生命周期管理 (context.Context + 信号处理)
|
||
├── cmd/ # CLI 入口 (cobra: root, start, test)
|
||
├── config/ # 配置结构体与 viper 加载
|
||
├── serial/ # 串口读接口与实现 (Reader 接口)
|
||
├── telegram/ # 电报解析器 (ZCZC...NNNN 提取)
|
||
├── storage/ # SQLite 持久化 (Repository 接口)
|
||
├── transport/ # 传输层 (Sender 接口: TCP, Pulsar, MultiSender)
|
||
├── main.go # 程序入口
|
||
├── Taskfile.yml # 构建/测试任务定义
|
||
└── telegram.yaml # 配置文件
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 技术 | 说明 |
|
||
|------|------|------|
|
||
| 语言 | Go 1.21+ | 需 Go 1.21 或更高版本 |
|
||
| CLI | cobra + viper | 命令解析与配置管理 |
|
||
| 串口 | github.com/argandas/serial | 串口通信 |
|
||
| 存储 | github.com/mattn/go-sqlite3 | SQLite 驱动 (需要 CGO) |
|
||
| 消息 | github.com/apache/pulsar-client-go | Apache Pulsar 集成 |
|
||
| 日志 | go.uber.org/zap | 结构化日志 |
|
||
| 轮转 | github.com/lestrrat-go/file-rotatelogs | 日志文件轮转 |
|
||
|
||
## 快速开始
|
||
|
||
### 前置条件
|
||
|
||
- Go 1.21+
|
||
- 如需交叉编译：`x86_64-linux-gnu-gcc` (Linux) 或 `x86_64-w64-mingw32-gcc` (Windows)
|
||
|
||
### 安装 Task (推荐)
|
||
|
||
```bash
|
||
go install github.com/go-task/task/v3/cmd/task@latest
|
||
```
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
task deps # 安装依赖
|
||
task build # 构建当前平台二进制
|
||
task build-all # 构建 Linux + Windows 二进制
|
||
task run # 构建并启动 tele-recv start
|
||
task run-test # 构建并启动 tele-recv test
|
||
task test # 运行所有测试
|
||
task test-race # 运行竞态检测测试
|
||
task test-cover # 运行测试并生成覆盖率报告
|
||
task lint # go vet 静态检查
|
||
task emu # 创建虚拟串口对 (ttyS0 ↔ ttyS1)
|
||
task clean # 清理构建产物
|
||
task dist # 构建全平台并打包 tar.gz
|
||
```
|
||
|
||
### 手动构建
|
||
|
||
```bash
|
||
go mod tidy
|
||
go build -o tele-recv .
|
||
```
|
||
|
||
### 交叉编译
|
||
|
||
```bash
|
||
# Linux (需要 CGO 和 x86_64-linux-gnu-gcc)
|
||
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 CC=x86_64-linux-gnu-gcc go build -o tele-recv-linux .
|
||
|
||
# Windows (需要 CGO 和 x86_64-w64-mingw32-gcc)
|
||
CGO_ENABLED=1 GOOS=windows GOARCH=amd64 CC=x86_64-w64-mingw32-gcc go build -o tele-recv-win64.exe .
|
||
```
|
||
|
||
### 模拟串口
|
||
|
||
```bash
|
||
task emu
|
||
# 创建 /tmp/ttyS0 ↔ /tmp/ttyS1 虚拟串口对
|
||
```
|
||
|
||
## 配置
|
||
|
||
编辑 `telegram.yaml`：
|
||
|
||
```yaml
|
||
serial:
|
||
device: /tmp/ttyS1 # 串口设备
|
||
baudrate: 9600 # 波特率
|
||
lograw: true # 控制台输出原始数据
|
||
|
||
telegram:
|
||
tcp: false # 启用 TCP 分发
|
||
pulsar: true # 启用 Pulsar 分发
|
||
|
||
sqlite:
|
||
file: telegram.db # 数据库文件
|
||
init: false # 启动时重建数据库
|
||
|
||
socket:
|
||
address: 127.0.0.1:6000 # TCP 监听地址
|
||
|
||
pulsar:
|
||
url: pulsar://localhost:6650
|
||
topic: telegram-raw
|
||
name: serial-reader
|
||
|
||
log:
|
||
dir: ./logs # 日志目录
|
||
maxage: 60 # 日志保留天数
|
||
rotatehour: 1 # 日志轮转间隔(小时)
|
||
```
|
||
|
||
### 配置选项
|
||
|
||
| 选项 | 含义 | 默认值 |
|
||
|------|------|--------|
|
||
| `serial.device` | 串口设备名 | — |
|
||
| `serial.baudrate` | 波特率 | — |
|
||
| `serial.lograw` | 控制台输出原始数据 | `false` |
|
||
| `telegram.tcp` | 启用 TCP 分发 | `false` |
|
||
| `telegram.pulsar` | 启用 Pulsar 分发 | `false` |
|
||
| `sqlite.file` | SQLite 数据库文件 | — |
|
||
| `sqlite.init` | 启动时重建数据库 | `false` |
|
||
| `socket.address` | TCP 监听地址 | — |
|
||
| `pulsar.url` | Pulsar 代理地址 | — |
|
||
| `pulsar.topic` | Pulsar 主题 | — |
|
||
| `pulsar.name` | Pulsar 生产者名称 | — |
|
||
| `log.dir` | 日志目录 | `./logs` |
|
||
| `log.maxage` | 日志保留天数 | `60` |
|
||
| `log.rotatehour` | 日志轮转间隔(小时) | `1` |
|
||
|
||
> 注意：TCP 和 Pulsar 可以同时启用。电报会先写入 SQLite，再通过所有启用的传输通道分发。
|
||
|
||
## 运行
|
||
|
||
### 测试环境
|
||
|
||
检查串口和数据库是否可用：
|
||
|
||
```bash
|
||
./tele-recv test
|
||
```
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
./tele-recv start
|
||
```
|
||
|
||
服务启动后将：
|
||
1. 打开串口设备
|
||
2. 从串口读取数据，解析 ZCZC...NNNN 电报
|
||
3. 写入 SQLite 持久化
|
||
4. 通过 TCP 和/或 Pulsar 分发
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
task test
|
||
|
||
# 带竞态检测
|
||
task test-race
|
||
|
||
# 覆盖率报告
|
||
task test-cover
|
||
|
||
# 手动运行
|
||
go test -race -v ./...
|
||
```
|
||
|
||
当前测试覆盖 6 个包，30+ 测试用例，`go test -race` 零竞态。
|
||
|
||
## 下载
|
||
|
||
发布版本：[release](https://gitea.int.it2000.com.cn/airport/tele-recv/releases)
|
||
|
||
## 许可证
|
||
|
||
详见 [LICENSE](LICENSE) |