# northstar

**Repository Path**: lower/northstar

## Basic Information

- **Project Name**: northstar
- **Description**: Northstar Pro（盈富量化交易平台）是一套面向期货、股票、外汇、数字资产等场景的专业级开源量化交易系统，基于 Java 25 + Spring Boot 3.5 构建，采用 B/S 架构与事件驱动（LMAX Disruptor）设计。平台以网关插件方式接入行情与交易通道（内置模拟网关与历史回放，可扩展 CTP、OKX 等外部网关），覆盖从合约定义、指数与主连合成、手工与画线交易、撮合与手
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-10-27
- **Last Updated**: 2026-11-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

 Northstar盈富量化平台

**免责声明：**  
**本项目仅属于技术分享，不构成任何交易建议。使用者自身在交易前，需要清楚其可能面对的交易风险与相关法律规定，并为自身行为负责！**

## 最近更新（2026-11-01）

本轮补齐「移动端」与「外部 Agent 接入」两条链路，让平台既能 PC 端配置研究，也能手机端盯盘与轻量干预，还能被外部大模型直接查询：

**移动端 App（`northstar-app/`）**
- uni-app（Vue 3 + TypeScript）一套代码构建 H5 / iOS / Android，定位「看 + 收 + 停」
- 页面：概览、持仓、告警、行情、K 线、权益走势、回测记录、待确认委托、清仓、手动下单、通知与诊断
- 登录即换取设备令牌，支持多设备查看与逐个下线；前台轮询 + SSE 双通道刷新

**手动下单**
- 三处入口：持仓行「平仓」（预填反向 + 平仓）、行情行「下单」、K 线页底部半浮层快速下单
- 术语统一为期货标准叫法：买开 / 卖开 / 买平 / 卖平；支持市价 / 限价、价格步进与买一卖一快捷取价
- 服务端统一做价格精度、手数精度与上下限、可平手数校验，按 `clientOrderId` 5 分钟去重，复用 Web 手工单的风控与网关连接检查

**行情实时推送**
- 新增 App 专用 SSE 端点 `GET /northstar/app/sse/quotes`，每秒推送活跃合约报价并按令牌资源白名单裁剪
- H5 用 `fetch` 读流（`EventSource` 无法携带 Authorization），原生端自动降级为 3 秒轮询

**K 线页**
- 图表由 klinecharts 换成 uCharts（不依赖 DOM，可跑在 App 端）
- 顶部信息条显示时间 / 开高低收 / 涨跌 / MA5 / MA10，按住拖动出十字线并按最近 K 线刷新数值
- 成交量独立副图，数值浮标跟随指针；隐藏自带图例，避免与图形重叠

**Agent / MCP 接入**
- 17 个只读工具覆盖账户、持仓、委托、成交、资金流水、模组、回测、结算、告警、行情与 K 线
- 双出口共用同一门面：REST `POST /northstar/agent/tools/{tool}` 与 MCP Streamable HTTP `POST /northstar/agent/mcp`
- 统一信封 `{ok,data,meta,error}`，HTTP 恒 200（认证与限流除外）；令牌按 scope 授权，限制 IP 白名单、限流、失败锁定，调用逐条审计

## 最近更新（2026-10-28）

本轮把交易链路从「能下单」补到「能结算、能风控、能换月、能追溯」：

**交易生命周期**
- 涨跌停价格边界校验（超出即废单/拒单）、交易时段约束（可按配置关闭）
- 开仓 / 平今 / 平昨差异化手续费（支持按手数 + 按金额）
- 回测与模拟盘统一撮合核心：同一份排队撮合实现，支持参与率部分成交、同 tick 不自我成交、可配滑点

**日终结算与经济**
- 新增日终盯市结算：按交易日生成账户结算快照 + 逐持仓结算明细，结转盈亏并重置持仓成本
- 结算台账可在监控台按交易日回溯，重启后成本与已结算盈亏保持一致

**风控**
- 风控规则扩展：高水位回撤熔断、异常价格波动拦截、账户级停止动作（停用绑定模组）
- 新增风险度（保证金 / 权益）实时计算与超限自动强平，账户风险总览页支持手工强平

**主力换月与主连行情**
- 按品种跟踪持仓量判定主力月份，挑战者持仓量超过现任主力 5% 才换月（含 30 秒启动预热，避免并发推送误判）
- 换月时按后复权因子生成连续价，主连合约（`9999`）在所有渠道注册，行情与普通合约一样推送，可被订阅与回溯
- 监控台新增「交易中心 → 主力换月」，展示主力、持仓量、复权因子与历次换月记录

**其他**
- 行情数据导入增加去重与质量校验（交易日去重、OHLC 合法性、非法记录单独计数）
- 修复一批缺陷：委托次数上限 off-by-one、合约查询空查询 NPE、CTP 涨跌停为 0 时价格被压成 0 等

![多端图表分析](https://foruda.gitee.com/images/1774058878046188583/c3896234_1676852.png "屏幕截图")

![历史回放](https://foruda.gitee.com/images/1774059802333287433/2cd1aef0_1676852.gif "屏幕截图")

![自动化](https://foruda.gitee.com/images/1774060471531122258/c86a5fd5_1676852.png "屏幕截图")

![策略监控](https://foruda.gitee.com/images/1774060637481944200/93d230bb_1676852.png "屏幕截图")

## 产品简介

专业级量化交易软件，用于期货、股票、外汇、炒币等多种交易场景，实现自动交易。  
[【演示版网站】](https://northstar.quantit.tech:8443/#/)

![监控台首页](northstar-doc/docs/public/images/monitor-dashboard-home.png "监控台首页：总权益概览、实时行情、K 线、账户风险与待办中心")

已对接的网关示例：
- CTP网关：[https://gitee.com/NorthstarQuant/northstar-gateway-ctp](https://gitee.com/NorthstarQuant/northstar-gateway-ctp)
- OKX网关：[https://gitee.com/NorthstarQuant/northstar-gateway-okx](https://gitee.com/NorthstarQuant/northstar-gateway-okx)

## 功能模块

### 一、网关与行情接入

| 能力 | 说明 |
|---|---|
| 多渠道网关 | 网关新增 / 编辑 / 删除、连线 / 断开、自动重连、按合约订阅；内置 SIM（模拟行情与模拟交易）、PLAYBACK（历史回放），外部 CTP / CTP_SIM 以插件方式接入 |
| 合约与合约定义 | 按「交易所 + 品种类别 + 代码规则」匹配合约定义，自动带出保证金率、手续费、交易时段、最小变动价位、合约乘数；支持按单个合约覆盖费率 |
| 指数合约 | 同一品种的各月份合约自动聚合为指数合约（`0000`） |
| 主力换月与主连 | 按持仓量实时判定主力月份（5% 换月阈值 + 30 秒启动预热），换月时计算后复权因子；主连合约（`9999`）对所有渠道注册，价格连续、最新价真实，可被订阅与推送 |
| 行情推送 | 基于 SSE 实时推送 Tick、K 线、账户、持仓、委托、成交与网关状态，K 线支持多周期聚合 |
| 期权支持 | 期权链聚合、期权日历、行权价与期权类型透出 |

### 二、交易与执行

| 能力 | 说明 |
|---|---|
| 手工交易 | 市价 / 限价下单，开平与平今 / 平昨标志，撤单，委托全生命周期状态跟踪与废单处理 |
| 画线交易计划 | 入场价 + 止盈 + 止损组合计划、移动止损、单独止损 / 止盈线、计划状态机与重启恢复 |
| 交易前校验 | 涨跌停价格边界、交易时段（可配置关闭，回测渠道跳过）、资金与保证金充足性、单笔手数上限 |
| 撮合模型 | 回测与模拟盘共用排队撮合核心：按委托先后成交、按 tick 成交量 × 参与率限额（不足则部分成交）、同一 tick 不自我成交、触发判定用 high/low；回测也可选立即成交模型用于加速寻优 |
| 手续费与成本 | 开仓 / 平今 / 平昨差异化费率，按手数 + 按成交金额混合计费；成交、持仓、账户成本口径一致 |

### 三、风控

| 能力 | 说明 |
|---|---|
| 风控规则 | 模组级与账户级：单笔手数、单日委托次数、持仓上限、高水位回撤熔断、异常价格波动（相对最新价偏离） |
| 风险度与强平 | 实时风险度 = 保证金 / 权益；超过阈值自动强平（亏损优先），支持手动一键强平 |
| 处置动作 | 拦截委托、停用模组、停止账户（停用该账户绑定的全部模组） |
| 风控留痕 | 每次拦截记录作用域、合约、违规类型、提示信息、处置动作与是否停用模组，可在监控台检索 |
| 账户风险总览 | 逐账户展示权益、保证金、风险度与持仓明细 |

### 四、结算与经济

| 能力 | 说明 |
|---|---|
| 日终结算 | 按交易日盯市结算：生成账户结算快照（权益、可用、保证金、持仓数）与逐持仓结算明细（结算价、结转盈亏） |
| 成本重置 | 结算后持仓成本重设为结算价，已结算盈亏结转进账户权益，重启后保持一致 |
| 结算台账 | 按账户 + 交易日回溯结算结果与明细 |
| 资金管理 | 出入金、账户资金流水、账户余额 / 可用 / 保证金查询 |

### 五、数据能力

| 能力 | 说明 |
|---|---|
| 历史回放 | 对接国内期货、A 股、港股、美股、币圈、外汇六大市场分钟级历史数据（数据服务需付费订阅），支持多合约、多周期回放 |
| 本地行情数据 | Tick / 分钟 K 线导入导出、数据缺口检测与补齐提示，导入时做交易日去重与 OHLC / 价格合法性校验 |
| 图表分析 | 多图同列、多周期联动、常用指标与画线工具、自定义指标（JavaScript 脚本）、画线下单 |
| 权限隔离 | 行情数据、网关、模组等资源按用户 / 角色做可见性控制 |

### 六、策略与回测

| 能力 | 说明 |
|---|---|
| Java 策略框架 | 模组化运行：策略上下文、账户与持仓抽象、指标框架、参数动态更新、运行状态可视化 |
| 脚本策略 | JavaScript 脚本策略，热更新、参数校验、策略库管理与错误提示 |
| 回测引擎 | 快速回测、批量回测、高精度逐笔回测；支持滑点、参与率、成交价基准等执行参数 |
| 参数寻优 | 参数集批量回测与 Walk-Forward 滚动验证 |
| 回测记录 | 运行结果、参数集、绩效指标与净值曲线落库，可在监控台回溯 |
| 策略风控 | 策略级资金隔离、绩效统计、熔断（触发后自动停用模组） |

### 七、监控台（前端）

| 菜单 | 页面 |
|---|---|
| 首页 | 账户与模组概览 |
| 网关管理 | 网关列表与配置 |
| 合约配置 | 合约费率 / 保证金覆盖配置 |
| 数据管理 | 本地行情数据（导入、导出、缺口检查） |
| 交易中心 | 活跃行情报价、多图同列、移动端图表、期权日历、委托订单、成交记录（含资金流水）、结算台账、主力换月 |
| 交易自动化 | 模组管理、模组运行时（桌面 / 移动）、策略探索、策略库、自定义指标、回测记录 |
| 风控中心 | 风控规则、风控事件、账户风险 |
| 日志中心 | 平台日志、模组日志（在线调整日志级别） |
| 系统管理 | 用户管理、角色管理、消息告警、通知记录 |
| 智能助手 | AI 对话 |

监控台支持中英文切换、主题切换与功能权限码（`GATEWAY_VIEW`、`MARKETDATA_VIEW`、`TRADE_EXECUTE`、`MODULE_VIEW`、`EXPLORER_VIEW`、`SCRIPT_VIEW`、`INDICATOR_VIEW`、`RISK_VIEW`、`LOG_VIEW`、`USER_MANAGE`、`NOTIFICATION_VIEW`）控制菜单可见性。

### 八、系统与运维

| 能力 | 说明 |
|---|---|
| 认证与授权 | 自定义 Session + CSRF Token；用户 / 角色 / 功能权限 + 资源级数据权限 |
| 安全防护 | 登录失败次数锁定、按 IP 冻结与封禁、恶意 404 请求拦截 |
| 通知告警 | 邮件与 Webhook（企业微信等）通知，网关上下线、委托与成交、风控告警、系统消息均可推送，并记录发送结果 |
| 通知记录 | 渠道、事件类型、标题、内容、成功标记、失败原因与时间可追溯 |
| 日志 | 平台日志与模组日志隔离，支持在线调整打印级别 |
| 数据库 | H2（生产为文件模式，测试为内存模式），历史行情主要依赖外部数据服务 |

### 九、AI 助手

- 对接主流大模型平台（OpenAI、Moonshot、DeepSeek、Ollama、百川等）
- SSE 流式对话、函数调用（下单查询、行情查询等）、联网搜索与向量检索

### 十、移动端 App

独立工程 `northstar-app/`，uni-app（Vue 3 + `<script setup>` + TypeScript）一套代码构建 H5 / iOS / Android。定位「看 + 收 + 停」：手机做查看、接收告警与轻量干预，PC 做配置与研究。

| 页面 | 路由 | 说明 |
|---|---|---|
| 配网 / 登录 | `pages/connect`、`pages/login` | 填服务器地址做连通性探测，账号密码换取设备令牌 |
| 概览 | `pages/overview` | 总权益、当日盈亏、最大风险度、账户卡片、模组运行数 |
| 持仓 | `pages/positions` | 跨账户分组持仓，行内「平仓」直达下单 |
| 行情 | `pages/quotes` | 活跃合约报价（SSE 实时）、合约搜索、涨跌红绿着色 |
| K 线 | `pages/kline` | 1m/5m/15m/1h/1D，MA5/MA10 + 成交量副图、十字线、底部快速下单条 |
| 下单 | `pages/order` | 买开 / 卖开 / 买平 / 卖平，市价与限价，5 秒倒数二次确认 |
| 告警 | `pages/alerts` | 通知与风控告警流，按天分组，未送达单独标记 |
| 权益 / 回测 | `pages/equity`、`pages/backtests`、`pages/backtest-detail` | 权益曲线与回撤、回测运行列表与绩效指标 |
| 干预 | `pages/confirmations`、`pages/close-all` | 待确认委托逐笔确认 / 拒绝、账户级一键清仓 |
| 我的 | `pages/settings` 等 | 推送开关、通知偏好、登录设备管理、诊断与关于 |

| 能力 | 说明 |
|---|---|
| 设备令牌 | 与 Agent 令牌同表，用 `kind=DEVICE` 区分；访问令牌默认 2 小时、刷新令牌 30 天且一次性轮换，可在「登录设备」逐个下线 |
| 实时行情 | `GET /northstar/app/sse/quotes` 每秒推送活跃合约报价；H5 用 `fetch` 读流，原生端降级 3 秒轮询 |
| 手动下单 | `GET /northstar/app/orders/context` 取资金、合约参数、盘口与多空持仓；`POST /northstar/app/orders` 提交，服务端做精度、手数上下限、可平校验与 `clientOrderId` 5 分钟去重 |
| 写操作管控 | 统一受 `northstar.app.write-enabled` 与 `write:*` scope 双重控制，要求 `TRADE_EXECUTE` + 账户 `GATEWAY:TRADE` 数据权限，逐条写审计 |
| 推送 | 通知通道「App推送」把事件 POST 到自建推送网关，推送令牌存 `APP_PUSH_DEVICE`，后端不保存 APNs / FCM 凭据 |
| 限流 | 设备令牌 240 次/分钟（`northstar.app.rate-limit-per-minute`），与 Agent 令牌 60 次/分钟分开计算 |

### 十一、Agent 与 MCP 接入

把平台数据以只读工具的形式暴露给外部 Agent（大模型、脚本、IDE 插件），两个出口共用同一门面 `AgentQueryFacade`：

| 出口 | 地址 |
|---|---|
| REST | `POST /northstar/agent/tools/{tool}` |
| MCP | `POST /northstar/agent/mcp`（Streamable HTTP，`northstar.agent.enabled=true` 时装配） |

17 个只读工具：`list_accounts`、`account_overview`、`overview_summary`、`list_modules`、`module_status`、`query_orders`、`query_deals`、`query_positions`、`query_account_flows`、`list_backtest_runs`、`get_backtest_report`、`get_equity_curve`、`get_settlement_report`、`list_alerts`、`search_contracts`、`get_quote`、`get_kline`。

| 能力 | 说明 |
|---|---|
| 统一信封 | `{ok,data,meta,error}`，HTTP 恒 200（认证与限流除外），异常收敛为结构化错误码与提示，不暴露堆栈 |
| 权限口径 | 令牌按 scope（`read:*` / `write:*`）授权，并按账号真实超管身份写入 `PermissionContext`，资源级裁剪与 Web 会话一致 |
| 数据瘦身 | 分页上限、字段裁剪、净值曲线等距下采样，避免单次返回撑爆上下文 |
| 安全基线 | IP 白名单、每令牌限流、失败锁定、`AGENT_AUDIT` 逐条审计 |

## 代码结构

```
northstar/
├── northstar-api/                  # 核心接口与模型：合约/行情/交易模型、策略与指标框架、网关抽象、数据仓库接口
├── northstar-gateway-sim/          # 模拟网关：随机行情生成、模拟账户与排队撮合、日终结算
├── northstar-gateway-playback/     # 回放网关：历史数据回放与逐笔撮合
├── northstar-strategy-example/     # 策略示例
├── northstar-copilot/              # AI 助手（LLM 接入、流式对话、函数调用）
├── northstar-main/                 # Spring Boot 主应用：REST 接口、服务层、事件引擎、数据访问、监控台静态资源
├── northstar-monitor-next-rebuild/ # 监控台前端（Vue 3 + Vite）
├── northstar-app/                  # 移动端 App（uni-app，H5 / iOS / Android）
├── northstar-doc/                  # 用户文档（VitePress）
└── northstar-dist/                 # 构建产物输出目录
```

外部网关（不随主仓库发布）：

```
northstar-gateway-ctp/              # CTP / CTP_SIM 网关（Linux 依赖 CTP 动态库）
```

核心分层：

- **数据流**：外部网关 → `MarketCenter`（防腐层，聚合指数/主连合约、合成行情）→ 模组 → 策略
- **订单流**：策略 / 手工 → `IModuleContext` → 撮合（回测或模拟）→ 交易网关 → 券商
- **事件流**：LMAX Disruptor 事件引擎 → 各类 Handler（账户、持仓、委托、成交、K 线、SSE 广播、通知）
- **配置存储**：网关配置、模组配置、合约配置、结算与业务记录均落 H2，重启自动恢复

## 技术栈

- **后端**：Java 25、Spring Boot 3.5、Spring Data JPA、H2、LMAX Disruptor、Protocol Buffers、Netty、OkHttp、Lombok
- **前端**：Vue 3、Vite 5、TypeScript、Pinia、Vue Router、Element Plus、TailwindCSS、klinecharts、ECharts、Monaco Editor
- **移动端**：uni-app（Vue 3 + TypeScript）、uCharts
- **测试**：JUnit 5、Mockito、AssertJ、JaCoCo；前端 vue-tsc + ESLint + Stylelint

## 快速开始

```bash
# 1. 构建前端（产物会被复制进 northstar-main 的静态资源）
cd northstar-monitor-next-rebuild && pnpm install && pnpm build

# 2. 构建后端可执行 jar（输出到 northstar-dist/）
cd .. && mvn clean package -DskipTests

# 3. 启动（默认 prod profile：443 + HTTPS + H2 文件库）
java -jar northstar-dist/northstar-9.1.6.jar

# 开发调试：80 端口 + 无 SSL
java -Denv=dev -jar northstar-dist/northstar-9.1.6.jar
```

默认账号 `admin / 123456`（可用环境变量 `NS_USER` / `NS_PWD` 覆盖）。

```bash
# 运行单元测试
mvn test

# 前端类型检查与规范检查
cd northstar-monitor-next-rebuild && pnpm typecheck && pnpm lint

# 移动端 App（H5 预览，默认 5180，/northstar 代理到后端）
cd northstar-app && pnpm install
VITE_PROXY_TARGET=http://<服务器>:8899 pnpm dev:h5
```

## 适用人群

专业量化操盘手、全栈技术爱好者、小型私募技术团队

## 运行环境

建议使用 Linux 云服务器，或者 Windows 系统（MAC 系统不支持 CTP、XTP 动态库）

## 程序架构

- B/S 架构
- northstar 项目为服务端（包含了 web 网页监控端）
- 数据库采用 H2（历史行情数据主要依赖数据服务，本地仅保存账户、模组、结算与业务记录）
- 事件驱动 + 插件式开发

![输入图片说明](https://foruda.gitee.com/images/1684034911905355451/683de173_1676852.png "总体架构图")

## 技术支持

![输入图片说明](https://foruda.gitee.com/images/1774021779966463771/d5bfc03f_1676852.jpg "知识星球")

## 注意事项

- 更多详细文档请加星球获取
- 前端项目不开源，可自行借助大模型来搭建你自己的监控台；或付费购买
- 项目使用了缓存，最大堆内存不应该小于 2G，否则会有 OOM
- 服务器时间校正为北京时间，时间不准会影响行情接收
- 尽量不要在开市期间重启程序，因为行情是实时接收的，重启会导致当天的 K 线数据会缺失；主力判定会在重启后重新进入 30 秒预热窗口
- 编写策略逻辑时如需使用时间属性，务必使用 TICK 行情自带的时间戳，否则策略回测时会不准确
- 本项目为技术分享，对交易行为并不负责
- 使用者需要自行开发交易策略并需要一定的 JAVA 基础
- master 分支不是一个稳定的版本，稳定的版本请以 tag 为准

## 特别鸣谢

[redtorch](https://github.com/sun0x00/redtorch) 作者，本项目保留了小部分其源码，同时感谢 redtorch 作者的技术分享。  
[klinechart](https://klinecharts.com/zh-CN) 作者，提供了优秀的 K 线前端库，并提供了相关的技术支持。