Betalens新手系列 · 03 从零安装：PostgreSQL、Python 环境、Dashboard 三件套

导言

Betalens 不是一个”开箱即用”的在线服务，而是一个需要本地运行的研究框架。在你跑出第一个策略之前，需要先把三个东西装好：

1. PostgreSQL：所有因子数据都存在这里，是 Betalens 的数据底座。
2. Python 3.10+ 环境：Betalens 的运行时。
3. Node.js 20.19+：如果你想用 Dashboard（可选，但不装也能用 Python API 研究）。

装完之后，还需要把数据导入数据库——这一步由 betalens_db_manager 完成。

前置条件清单

一、PostgreSQL 安装与配置

1.1 下载安装

Windows 推荐使用 PostgreSQL 官方安装包 或 EDB 安装器。安装过程中记下：

• 端口：默认 5432，如果不是，记下你选的端口。
• 密码：安装时设置的 postgres 用户密码，必须记住，后面填配置文件要用。
• 安装路径：记下来，方便后面找 bin 目录。

1.2 创建数据库

打开 pgAdmin 或命令行，创建名为 datafeed 的数据库（这个名字是 Betalens 的约定，也可以用其他名字，但要和后面的配置保持一致）：

1

CREATE DATABASE datafeed;

1.3 配置数据库连接

Betalens 用 JSON 配置文件管理数据库连接。进入 betalens 仓库根目录：

1
2
3
4
5

cd C:\Users\Janis\OneDrive\betalens
# 复制配置模板
Copy-Item betalens\datafeed\config.example.json betalens\datafeed\config.local.json
# 用记事本打开编辑
notepad betalens\datafeed\config.local.json

模板内容大概是：

1
2
3
4
5
6
7

{
    "host": "localhost",
    "port": 5432,
    "database": "datafeed",
    "user": "postgres",
    "password": "这里填你安装时设的密码"
}

填入真实的 password，保存关闭。

注意：config.local.json 已经在 .gitignore 里，不会被提交到远程仓库。不要把真实的密码直接写在 config.example.json 里。

二、Python 环境搭建

2.1 创建虚拟环境

1
2
3

cd C:\Users\Janis\OneDrive\betalens
python -m venv .venv
.\.venv\Scripts\Activate.ps1

如果遇到执行策略报错，先调整 PowerShell 策略：

1
2

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
.\.venv\Scripts\Activate.ps1

2.2 升级 pip 并安装 Betalens

1
2
3

python -m pip install --upgrade pip setuptools wheel
# 安装 Betalens 及其全部可选依赖（推荐）
python -m pip install -e ".[full]"

如果网络慢，可以用国内镜像：

1

python -m pip install -e ".[full]" -i https://pypi.tuna.tsinghua.edu.cn/simple

[full] 包含了：viz（plotly 图表）、dashboard（FastAPI）、db（PostgreSQL 文件导入）、gui（PySide6 管理界面）。

三、初始化数据库 Schema

Betalens 的数据库有固定的表结构（fact 宽表 + 维表）。用 betalens_db_manager 来创建和验证：

1
2
3
4
5
6
7
8

# 查看创建计划（dry-run，不会真的建表）
python -m betalens_db_manager plan

# 初始化本地默认 schema
.\betalens_db_manager\init_local.bat

# 验证 schema 是否正确创建
python -m betalens_db_manager verify

verify 成功后，你会看到 datafeed 数据库中出现了 fundamentals、daily_market、trade_status、industry 等表——此时数据库是空的，数据还需要导入。

四、导入初始数据（可选）

如果你是第一次安装，数据库里可能还没有行情和财务数据。Betalens 支持以下导入方式：

• EDE 数据包：用 ImportJobRunner 导入 EDE 格式的日频行情和财务数据。
• Wind 数据：通过 Wind 接口拉取并入库。
• 指数成分：用 index_universe 模块导入指数成分股列表。
• 手动 CSV/Parquet：通过 ImportJobRunner 导入自定义文件。

详细的导入流程在 数据库管理专题 中会展开，这里先跳过。

五、安装 Node.js（仅 Dashboard 需要）

如果你只需要用 Python API 研究，可以跳过这一步。如果你想用浏览器界面管理因子和回测：

1. 去 nodejs.org 下载 LTS 版本（20.x+）。
2. 安装后验证：

1
2

node --version
npm --version

六、安装 Dashboard 前端依赖

1
2

cd C:\Users\Janis\OneDrive\betalens\dashboard
npm install

这一步从 npm 拉取前端依赖，可能需要几分钟。

七、启动 Dashboard（可选）

Dashboard 分前端（Vite）和后端（FastAPI）两部分：

1
2

# 在 betalens 仓库根目录执行
.\dashboard\run.bat

成功后会看到：

1
2
3
4
5

INFO:     Uvicorn running on http://127.0.0.1:8000
VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://127.0.0.1:5173/
  ➜  Network: use --host to expose

打开浏览器访问 http://127.0.0.1:5173，就能看到 Betalens Dashboard 了。

八、验证安装成功

在激活了 .venv 的终端里跑：

1
2
3

from betalens.datafeed import get_absolute_trade_days
days = get_absolute_trade_days("2020-01-01", "2024-12-31", "Y")
print(f"找到 {len(days)} 个调仓日：{days[:5].tolist()}")

如果没有报错，说明 Betalens 已经正确连接到 PostgreSQL。如果数据库是空的，这一步不会报错，只是返回空列表。

常见错误

1. ModuleNotFoundError: No module named 'betalens'

虚拟环境没激活。进入 .venv\Scripts\Activate.ps1，再运行 Python。

2. ConnectionRefusedError: could not connect to server

PostgreSQL 服务没有启动。Windows 上打开”服务”（services.msc），找到 postgresql-x64-xxx，右键”启动”。

3. password authentication failed for user "postgres"

config.local.json 里的密码不对。用 pgAdmin 重新设置 postgres 用户的密码，并更新配置文件。

4. npm install 报网络错误

切换 npm 镜像：

1
2

npm config set registry https://registry.npmmirror.com
npm install

5. betalens_db_manager verify 报错

Schema 创建顺序可能有问题。删库重建：

1
2

DROP DATABASE datafeed;
CREATE DATABASE datafeed;

然后重新 .\betalens_db_manager\init_local.bat。

开发者侧：为什么用 PostgreSQL

选 PostgreSQL 而非 SQLite / MySQL，有几个实际原因：

1. 时序数据友好：PostgreSQL 对时间序列查询有较好的优化（分区表、BRIN 索引）。
2. JSON 支持：Betalens 的配置和一些元数据以 JSON 形式存储在 JSONB 列里。
3. PIT（Point-in-Time）查询：用 betalens_db_manager 做数据入库时，会保留历史版本，支持”如果我知道 2020 年初的数据，用当时的信息计算因子”这类严格的时间旅行查询。
4. 丰富的窗口函数：因子计算依赖大量 SQL 窗口函数，PostgreSQL 实现成熟。

如果数据量不大（几百只股票、几年历史），PostgreSQL 的性能绰绰有余。如果你要处理全市场分钟级数据，可能需要做分区或升级硬件。

延伸阅读

• Betalens 新手系列 · 01：Betalens 是什么——架构概览。
• Betalens 新手系列 · 07：数据治理工具 betalens_db_manager——Schema、Import、GUI 详解。
• docs/getting-started/installation.rst——官方安装文档。
• Betalens 新手系列 · 21：Dashboard 启动与发现机制——Dashboard 进阶配置。