windy/tele-recv
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update README with new architecture and project structure

Browse Source 
- 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
This commit is contained in:
w1ndyb0y
2026-07-10 16:07:48 +08:00
parent 7f65004cd4
commit 46be9f483f
1 changed files with 181 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+181 -43
View File
@@ -1,64 +1,202 @@
# 电报接收
# tele-recv 串口电报接收器
[![Build Status](http://d2.int.it2000.com.cn/api/badges/airport/tele-recv/status.svg)](http://d2.int.it2000.com.cn/airport/tele-recv)
机场串口电报数据缓存程序。从串口读取电报，保存，等待处理程序处理
机场串口电报数据缓存与分发程序。从串口读取电报（ZCZC...NNNN 格式），持久化到 SQLite，并通过 TCP 和/或 Apache Pulsar 分发。
## 下载
## 架构
下载发布版本 [release](https://gitea.int.it2000.com.cn/airport/tele-recv/releases)
## 安装
解压下载文件 tele-recv-XXX.tag.gz
如果是linux
```Shell
tar xzvf tele-recv-XXX.tar.gz
```
串口 (ttyS0) → serial.Port → telegram.Parser → storage.Store (SQLite)
↓
transport.Sender
↓
┌──────────┴──────────┐
↓ ↓
TCP Client Apache Pulsar
```
文件包中包含两个可执行文件和一个.yaml的配置文件
核心原则：**先持久化，再分发**。无论配置何种传输模式，电报始终先写入 SQLite，确保数据不丢失。
tele-recv-linux: linux 可执行文件
tele-recv-win64.exe: windows 64位可执行文件
## 项目结构
### 配置
```
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 # 配置文件
```
| 选项 | 含义 | 取值 | 例子 |
|------- |---------------------|-----------------|------------------------|
|device | 串口设备名称 | ttyS1 | win: COM1 linux: ttyS1 |
|baudrate| 波特率 | 9600 | 19200,38400 .... |
|lograw | 是否向控制台输出通讯内容| ture | true/false |
|file | sqlite 文件名 | telegram.db | tele.db |
|init | 是否新建电报数据库 | true | true/false |
|address | 本地处理监听端口 | 127.0.0.1:6000 | |
## 技术栈
| 组件 | 技术 | 说明 |
|------|------|------|
| 语言 | 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，再通过所有启用的传输通道分发。
## 运行
### 测试环境
linux:
```Shell
./tele-recv-linux test
检查串口和数据库是否可用：
```bash
./tele-recv test
```
windows:
```Shell
tele-recv-win64.exe test
### 启动服务
```bash
./tele-recv start
```
测试运行的环境是否能正确开始串口设备，以及初始化数据库
服务启动后将：
1. 打开串口设备
2. 从串口读取数据，解析 ZCZC...NNNN 电报
3. 写入 SQLite 持久化
4. 通过 TCP 和/或 Pulsar 分发
### 开始接收电报
## 测试
linux:
```Shell
./tele-recv-linux start
```bash
# 运行所有测试
task test
# 带竞态检测
task test-race
# 覆盖率报告
task test-cover
# 手动运行
go test -race -v ./...
```
windows:
```Shell
tele-recv-win64.exe start
```
当前测试覆盖 6 个包，30+ 测试用例，`go test -race` 零竞态。
开始从串口设备读取数据，并开启TCP服务等待处理程序连接。
如果没有处理程序，电报则保存在本地数据库中。
等到处理程序连上端口，则把未处理电报以此发送给处理程序。
## 下载
发布版本：[release](https://gitea.int.it2000.com.cn/airport/tele-recv/releases)
## 许可证
详见 [LICENSE](LICENSE)