169 lines
4.1 KiB
Markdown
169 lines
4.1 KiB
Markdown
# GoTiDB - 时序数据库
|
||
|
||
GoTiDB 是一个用 Go 语言编写的轻量级时序数据库，专门用于存储和查询时间序列数据。它支持高效的数据写入、查询和实时数据推送功能。
|
||
|
||
## 特性
|
||
|
||
- 高性能内存存储引擎
|
||
- WAL（预写日志）持久化
|
||
- REST API 接口
|
||
- WebSocket 实时数据推送
|
||
- NATS 消息系统集成
|
||
- Prometheus 指标监控
|
||
- 支持自定义标签的数据点
|
||
- 环形缓冲区数据结构
|
||
- 支持多种查询类型（最新值、所有值、持续时间）
|
||
|
||
## 安装
|
||
|
||
确保你已经安装了 Go 1.16 或更高版本。
|
||
|
||
```bash
|
||
git clone git.pyer.club/kingecg/gotidb
|
||
cd gotidb
|
||
go mod download
|
||
```
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
go build -o gotidb cmd/server/main.go
|
||
```
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
./gotidb [options]
|
||
```
|
||
|
||
### 可用选项
|
||
|
||
- `-rest-addr`: REST API 服务地址（默认：":8080"）
|
||
- `-ws-addr`: WebSocket 服务地址（默认：":8081"）
|
||
- `-metrics-addr`: 指标服务地址（默认：":8082"）
|
||
- `-quic-addr`: QUIC 服务地址（默认：":8083"）
|
||
- `-nats-url`: NATS 服务器地址（默认："nats://localhost:4222"）
|
||
- `-persistence`: 持久化类型（none, wal, boltdb）（默认："none"）
|
||
- `-persistence-dir`: 持久化目录（默认："./data"）
|
||
- `-sync-every`: 每写入多少条数据同步一次（默认：100）
|
||
- `-config`: 配置文件路径（默认："config.yaml"）
|
||
|
||
### 持久化选项
|
||
|
||
GoTiDB 支持多种持久化方式：
|
||
|
||
1. **内存存储（无持久化）**：数据仅保存在内存中，服务重启后数据丢失。
|
||
- 配置：`-persistence=none`
|
||
|
||
2. **WAL 日志持久化**：使用预写日志（Write-Ahead Log）进行持久化，支持数据恢复。
|
||
- 配置：`-persistence=wal -persistence-dir=./data -sync-every=100`
|
||
|
||
3. **BoltDB 持久化**：使用 BoltDB 进行持久化，提供更高的可靠性和查询性能。
|
||
- 配置：`-persistence=boltdb -persistence-dir=./data`
|
||
- 配置文件中可设置：`boltdb_filename`（数据库文件名）和 `boltdb_bucket_size`（数据分桶大小）
|
||
|
||
## API 使用
|
||
|
||
### REST API
|
||
|
||
#### 写入数据
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/write \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"device_id": "device1",
|
||
"metric_code": "temperature",
|
||
"labels": {
|
||
"location": "room1"
|
||
},
|
||
"value": 25.5
|
||
}'
|
||
```
|
||
|
||
#### 批量写入数据
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/batch_write \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"points": [
|
||
{
|
||
"device_id": "device1",
|
||
"metric_code": "temperature",
|
||
"labels": {
|
||
"location": "room1"
|
||
},
|
||
"value": 25.5
|
||
},
|
||
{
|
||
"device_id": "device2",
|
||
"metric_code": "humidity",
|
||
"labels": {
|
||
"location": "room2"
|
||
},
|
||
"value": 60
|
||
}
|
||
]
|
||
}'
|
||
```
|
||
|
||
#### 查询数据
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/query \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"device_id": "device1",
|
||
"metric_code": "temperature",
|
||
"labels": {
|
||
"location": "room1"
|
||
},
|
||
"query_type": "latest"
|
||
}'
|
||
```
|
||
|
||
### WebSocket API
|
||
|
||
连接 WebSocket 服务：
|
||
|
||
```javascript
|
||
const ws = new WebSocket('ws://localhost:8081/ws');
|
||
|
||
// 订阅数据点
|
||
ws.send(JSON.stringify({
|
||
device_id: "device1",
|
||
metric_code: "temperature",
|
||
labels: {
|
||
location: "room1"
|
||
}
|
||
}));
|
||
|
||
// 接收数据更新
|
||
ws.onmessage = function(event) {
|
||
const data = JSON.parse(event.data);
|
||
console.log('Received update:', data);
|
||
};
|
||
```
|
||
|
||
## 监控
|
||
|
||
访问 `http://localhost:8082/metrics` 查看 Prometheus 指标。
|
||
|
||
可用指标：
|
||
|
||
- `gotidb_write_total`: 写入操作总数
|
||
- `gotidb_query_total`: 查询操作总数
|
||
- `gotidb_write_latency_seconds`: 写入操作延迟
|
||
- `gotidb_query_latency_seconds`: 查询操作延迟
|
||
- `gotidb_active_connections`: 活跃连接数
|
||
- `gotidb_data_points_count`: 数据点数量
|
||
- `gotidb_persistence_latency_seconds`: 持久化操作延迟
|
||
- `gotidb_persistence_errors_total`: 持久化错误总数
|
||
- `gotidb_messaging_latency_seconds`: 消息操作延迟
|
||
- `gotidb_messaging_errors_total`: 消息错误总数
|
||
- `gotidb_websocket_connections`: WebSocket 连接数
|
||
|
||
## 许可证
|
||
|
||
MIT License |