# star-midplatform

**Repository Path**: Ky1eYang/star-midplatform

## Basic Information

- **Project Name**: star-midplatform
- **Description**: 基于go语言实现的行情数据中台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: v1
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-24
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Star Platform Go

这是 Python `star_platform` 行情/合约服务的 Go 重构版本。目标是尽量保持现有外部契约不变，同时用 Go 接管服务入口、`instrument/v1` 接口、Redis 缓存、Postgres K 线读写、定时任务和常驻 websocket worker。

当前首批数据源：OKX、Binance、RQData。

当前明确未迁移：openctp、jupiter、polymarket、okx_web3、ccxt 等扩展数据源和任务。

## 环境变量

程序启动时会自动读取项目根目录的 `.env` 文件；如果同名变量已经存在于系统/PowerShell 环境中，则系统环境变量优先。服务启动至少需要 Redis。需要读取或写入 K 线数据库时还需要 Postgres：

```bash
REDIS_URL=redis://localhost:6379/0
DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres
```

常用可选配置：

```bash
APP_NAME=midplatform
APP_TIMEZONE=Asia/Shanghai
HOST=0.0.0.0
PORT=7800
MAX_THREADS=8
DEFAULT_DEPTH_SIZE=10
RQDATAC_LICENSE_KEY=your_rqdata_license
```

说明：

- `HOST`/`PORT` 控制 HTTP 监听地址，也可以用启动参数覆盖。
- `MAX_THREADS` 会设置 Go 的 `GOMAXPROCS`，用于限制 Go 调度器并行使用的 CPU/线程数量；默认是当前机器 CPU 数。
- `LOG_DIR` 控制日志目录，默认 `logs`。Go 版会输出控制台日志，同时写入 `logs/debug.log` 和 `logs/err.log`。
- `RQDATAC_LICENSE_KEY` 为空时，RQData 实时 worker 和拉取任务会跳过授权相关工作。

## 启动服务

在项目根目录运行：

```bash
go mod download
go run ./cmd/star-platform
```

显式使用 `serve`：

```bash
go run ./cmd/star-platform serve
```

指定监听地址和线程数：

```bash
go run ./cmd/star-platform serve --host 0.0.0.0 --port 7800 --max-threads 8
```

编译并启动：

```bash
go build -o star-platform ./cmd/star-platform
./star-platform serve --host 0.0.0.0 --port 7800
```

健康检查：

```bash
curl http://127.0.0.1:7800/v1/healthz
```

## Docker

```bash
docker build -t star-platform-go .
docker run --rm --env-file .env -p 7800:7800 star-platform-go
```

容器默认启动 HTTP 服务、定时任务和常驻 websocket worker。

## CLI 使用

Go 二进制包含维护命令，用于替代 Python 侧 CLI。

查看帮助：

```bash
go run ./cmd/star-platform help
```

清空当前应用名前缀下的 Redis key，即删除 `{APP_NAME}:*`：

```bash
go run ./cmd/star-platform rclear
# 编译后：
./star-platform rclear
```

按模式删除 Redis key，实际匹配 `{APP_NAME}:<pattern>`：

```bash
go run ./cmd/star-platform rdeletes 'cex:okx:*'
go run ./cmd/star-platform rdeletes 'instruments:list'
```

下载 OKX 官方 1 分钟历史归档并写入 Postgres：

```bash
go run ./cmd/star-platform okx-cache-1m BTC-USDT-SWAP 2024-01-01 2024-01-31 --inst_type SWAP
```

现货示例：

```bash
go run ./cmd/star-platform okx-cache-1m BTC-USDT 2024-01-01 2024-01-02 --inst_type SPOT
```

即使某个 UTC 日期已经有 1440 根 1m K 线，也强制重新下载：

```bash
go run ./cmd/star-platform okx-cache-1m BTC-USDT-SWAP 2024-01-01 2024-01-01 --inst_type SWAP --force
```

数据写入表结构与 Python 版兼容，例如：

```text
okx."BTC-USDT-SWAP@swap@okx_1m"
```

## 已实现接口

- `GET /v1/healthz`
- `GET /v1/instruments/list`
- `GET /v1/instruments/query`
- `GET /v1/instruments/subscriptions`
- `GET /v1/instruments/subscribe`
- `GET /v1/instruments/unsubscribe`
- `GET /v1/instruments/kline`
- `GET /v1/instruments/cachekline`
- `GET /v1/instruments/tick`
- `GET /v1/instruments/rtick`

## 定时任务和常驻 Worker

服务启动后会启动 Go 原生进程内 scheduler。cron 只负责投递任务，本地 worker pool 消费任务队列，并通过 jobID 进程内互斥避免同一任务重入：

- OKX 合约列表缓存和公共 websocket worker
- Binance 合约列表缓存、现货/合约 websocket worker、资金费率 worker
- RQData 合约列表缓存和实时 websocket worker
- OKX、Binance、RQData 的每日合约列表更新任务

Redis 仅用于业务缓存、订阅集合和实时行情 PubSub，不再用于任务队列或任务锁。Redis key、PubSub channel 和 Postgres K 线表命名尽量保持 Python 版兼容。

注意：当前原生 scheduler 的去重范围是单个 Go 进程。如果多实例部署且仍要求同一任务全局唯一，需要引入外部协调机制，例如 Postgres advisory lock、Kubernetes lease，或重新启用 Redis/etcd 这类外部锁。

## 日志轮转

Go 版启动时会自动创建日志目录，默认与 Python 版一致使用 `logs/`：

- 控制台：INFO 及以上，便于 Docker/supervisor 收集。
- `logs/debug.log`：DEBUG 及以上，JSON 格式，单文件 5MB，保留 5 个备份：`debug.log.1` 到 `debug.log.5`。
- `logs/err.log`：WARNING 及以上，文本格式，按日期轮转，保留 7 个日期备份。

## Go 端尚未覆盖的 Python 能力

当前 Go 版已经覆盖本次要求的 instrument/v1、portfolios、Redis 缓存、Postgres K 线读写、OKX/Binance/RQData、调度/常驻 worker、Redis 清理 CLI 和 OKX 历史缓存 CLI。仍未迁移的 Python 能力包括：

- polymarket 数据源和 polymarket news websocket 持久化
- `/v1/tasks`、`/v1/workers` 调试/ introspection 接口
- quotation 之外的 news、OKX Web3、Jupiter 专用 DB helper

## 验证

格式化和编译测试：

```bash
gofmt -w cmd internal
go test ./...
```

编译二进制：

```bash
go build -o star-platform ./cmd/star-platform
```