阅读提示

这篇讲解 Betalens Dashboard 的架构、启动方式、因子发现机制，以及如何调试前端/后端问题。学完之后，你能独立解决 Dashboard 的常见启动和运行问题。

导言

Betalens Dashboard 是一个前后端分离的浏览器应用：

  • 后端：FastAPI（Python），负责因子发现、参数配置、回测执行、API 输出。
  • 前端：React + Vite（TypeScript），负责页面渲染、参数表单、结果图表。
  • 通信：后端 http://127.0.0.1:8000，前端 http://127.0.0.1:5173。
1
浏览器 ──→ 前端(Vite) ──→ 后端(FastAPI) ──→ betalens Python 代码

启动方式

方式一：一键脚本（推荐）

1
2
cd C:\Users\Janis\OneDrive\betalens
.\dashboard\run.bat

这会同时启动 FastAPI 后端和 Vite 前端。

方式二：分别启动

1
2
3
4
5
6
7
# 终端 1：后端
cd C:\Users\Janis\OneDrive\betalens
python -m uvicorn dashboard.main:app --reload --port 8000

# 终端 2：前端
cd C:\Users\Janis\OneDrive\betalens\dashboard
npm run dev

启动成功的标志

后端日志：

1
2
INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Application startup complete.

前端日志：

1
2
3
VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://127.0.0.1:5173/

打开浏览器访问 http://127.0.0.1:5173，能看到 Dashboard 首页。

因子发现机制

Dashboard 启动时会扫描 betalens-factor/ 下的所有 YAML 文件，按以下规则发现因子：

1
2
3
4
5
6
7
扫描规则：
  1. betalens-factor/<class>/class_<class>.yaml        → 因子家族元数据
  2. betalens-factor/<class>/<name>/factor_<name>.yaml → 单个因子

发现结果：
  - 因子列表：GET /api/factors
  - 返回：class / name / meta / factor_spec / weight / run

手动刷新因子列表（新增或修改因子后）：

1
2
3
4
# 方式 1：API 刷新
curl http://127.0.0.1:8000/api/factors?refresh=true

# 方式 2：在前端页面上点击"刷新因子列表"按钮

API 端点速查

端点 方法 含义
/api/factors GET 获取因子列表
/api/factors/{class}/{name} GET 获取单个因子配置
/api/run POST 提交回测任务
/api/run/{run_id} GET 查询运行状态
/api/result/{run_id} GET 获取回测结果
/api/download/{run_id}/{type} GET 下载报告（excel/html/profiling）
/docs GET Swagger API 文档

Swagger 文档地址：http://127.0.0.1:8000/docs，可以在里面直接测试 API。

目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
dashboard/
├── main.py              # FastAPI 入口
├── routers/
│   ├── factors.py       # 因子发现 / 配置 API
│   ├── run.py           # 回测执行 API
│   └── result.py        # 结果查询 / 下载 API
├── services/
│   ├── pipeline.py      # FactorPipeline 封装
│   └── discovery.py     # YAML 扫描与解析
├── frontend/            # React 前端源码
│   ├── src/
│   │   ├── pages/       # 页面组件
│   │   ├── components/   # 公共组件
│   │   └── api/         # API 调用封装
│   └── package.json
└── run.bat              # 一键启动脚本

开发者侧：新增因子的发现流程

当你在 betalens-factor/tdx/MY_FACTOR/ 下新增了一个因子：

  1. Dashboard 后端重启（或调用 /api/factors?refresh=true）
  2. discovery.py 扫描所有 YAML 文件
  3. 动态导入 factor_MY_FACTOR.py
  4. 因子出现在前端列表里

调试发现问题的步骤：

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 直接调 discovery 服务
from dashboard.services.discovery import discover_factors

factors = discover_factors()
print(f"发现 {len(factors)} 个因子")

# 2. 检查某个因子是否被发现
my_factor = next((f for f in factors if f["name"] == "MY_FACTOR"), None)
if my_factor:
    print("因子发现成功：", my_factor)
else:
    print("因子未被发现，检查 YAML 是否在正确路径")

常见错误

1. 前端 502 / 后端连接失败

1
2
3
4
5
# 检查后端是否在运行
curl http://127.0.0.1:8000/docs

# 检查前端 Vite proxy 配置（vite.config.ts）
# proxy 应该指向 http://127.0.0.1:8000

2. 新因子不出现

1
2
3
4
5
# 强制刷新
curl http://127.0.0.1:8000/api/factors?refresh=true

# 检查 YAML 路径是否正确
# 必须在 betalens-factor/<class>/<name>/factor_<name>.yaml

3. 回测任务卡住

1
2
3
4
5
6
# 查看后端日志
# 在运行 run.bat 的终端里查看输出

# 检查是否有 Python 错误
curl http://127.0.0.1:8000/api/run/{run_id}
# 返回 status: "failed" 或 "running"

4. npm install 失败

1
2
3
4
# 切换 npm 镜像
npm config set registry https://registry.npmmirror.com
cd dashboard
npm install

延伸阅读