# 栖渡

**Repository Path**: xialijun/qidu

## Basic Information

- **Project Name**: 栖渡
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

栖渡 (Qidu) — 轻量级消息中间件
================================

栖渡是一个从零自研的轻量级消息中间件，定位类似 MQTT 的极简版。
核心设计目标：协议干净、部署简单、SDK 对调用方零负担。


架构
====

  [sensor] ---> [qd-bridge] ---> [display]
                  |
                  +-- Topic Router（按 topic 转发）
                  +-- Node Registry（在线节点管理）
                  |
               TCP / Unix Socket


帧协议
======

固定 16 字节头部 + 变长 NodeID + 变长 Payload（大端序）：

  偏移    字段          长度    说明
  0-1     Magic         2B     0x5144 ("QD")
  2       Version       1B     0x01
  3       Type          1B     帧类型
  4       Flags         1B     保留
  5       TTL           1B     跳数限制
  6-7     NodeID Len    2B     NodeID 字节长度
  8-11    Payload Len   4B     Payload 字节长度
  12-15   保留          4B     将来扩展
  16+     NodeID + Payload    变长

帧类型：

  0x01  HELLO      握手/注册（Payload 可带订阅列表，换行分隔）
  0x02  HEARTBEAT  心跳（SDK 自动发，15 秒间隔）
  0x03  DATA       业务数据（Payload 为 JSON）
  0x04  CLOSE      优雅断开

DATA Payload 格式（JSON）：

  {
    "topic": "temperature",
    "data": {"value": 28.0, "unit": "celsius"},
    "ts": 1723968000
  }

  Bridge 只解析 topic 字段做路由，data 原样透传，Bridge 不关心业务内容。


快速开始
========

1. 启动 Bridge：

   go run ./cmd/qd-bridge -log-level=debug

2. 启动 display（订阅者）：

   go run ./cmd/display

3. 启动 sensor（发布者）：

   # 默认发 temperature
   go run ./cmd/sensor

   # 发 humidity
   go run ./cmd/sensor sensor-humidity --topic=humidity

4. display 终端应该看到：

   🌡️  temperature | 温度: 25.0°celsius (来自 sensor-1)
   💧 humidity | 湿度: 66.0% (来自 sensor-humidity)

HTTP API：

  GET /health         健康检查
  GET /api/v1/status  查看所有在线节点和订阅关系


项目结构
========

  cmd/
    qd-bridge/        Bridge 服务端
    sensor/           传感器示例（发布者）
    display/          显示示例（订阅者）
  internal/
    bridge/           Node 注册表 + Topic 路由
    config/           配置加载（YAML + ENV + CLI）
    frame/            帧协议编解码
  pkg/
    client/           Node SDK（自动心跳/重连/回调）
  config.yaml         默认配置


当前版本
========

  v0.1.0-mvp — 完整的消息中间件最小闭环。
  参见 git tag -l 查看所有里程碑。