NautilusTrader 是一个基于 Rust 的高性能、事件驱动型交易引擎

NautilusTrader 是一个基于 Rust 的高性能、事件驱动型交易引擎，支持从回测到实盘交易的全流程。它以 Rust 为核心提供性能与安全保证，以 Python 作为策略开发的控制平面，允许同一套策略代码在回测和实盘环境中无缝运行。

本教程将指导您完成 NautilusTrader 的安装、配置与运行。

1. 核心概念与架构

NautilusTrader 的核心设计思想是将底层的高性能引擎与上层的策略逻辑分离。

Rust 核心引擎：负责事件循环、订单管理、风险管理、数据持久化等高性能、低延迟的核心交易逻辑。编译为原生代码，执行效率极高。
Python 控制平面：策略逻辑、系统配置、数据分析和可视化通过 Python 编写。通过 PyO3 绑定与 Rust 核心交互。
事件驱动架构：所有操作（如接收行情、下单、成交）都以事件形式在系统中流转，保证了执行流程的确定性和可回溯性。
资产类别无关：通过模块化适配器，可连接加密货币（CEX/DEX）、外汇、股票、期货、期权，甚至博彩交易所。

2. 环境准备

2.1 基础要求

操作系统：Linux (x86_64/ARM64), macOS (ARM64), Windows (x86_64)。
Python 版本：Python 3.12, 3.13, 或 3.14。
Rust 工具链：必须安装。项目 MSRV (最低支持 Rust 版本) 通常与最新稳定版保持一致。
包管理工具：uv - 项目官方推荐的快速 Python 包管理器。

2.2 安装 Rust 与 uv

安装 Rust:

# Linux / macOS
curl https://sh.rustup.rs -sSf | sh
# Windows: 下载并运行 rustup-init.exe，并安装 "Desktop development with C++"
# 安装后，重新打开终端并验证
rustc --version

安装 uv:

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

2.3 安装 Clang (编译依赖)

NautilusTrader 编译需要 clang。

Linux (Debian/Ubuntu)：sudo apt-get install clang lld
macOS：xcode-select --install
Windows：在 Visual Studio Build Tools 中，确保勾选 “C++ Clang tools for Windows”。

3. 安装方式

NautilusTrader 支持三种主要安装方式，您可以根据需要选择。

方式一：从 PyPI 安装 (推荐)

最简单快捷的方式，适合大多数用户。该方式安装的是官方发布的预编译二进制轮子 (wheel)，无需本地编译。

# 使用 uv 在隔离环境中安装 (推荐)
uv venv
. .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate  # Windows
uv pip install nautilus_trader

安装包含可视化依赖（回测图表）的版本：

1	uv pip install "nautilus_trader[visualization]"

方式二：从源码编译安装

适合需要修改 Rust 核心代码、使用最新开发特性或进行二次开发的用户。

克隆仓库:

1 2	git clone --branch develop --depth 1 https://github.com/nautechsystems/nautilus_trader.git cd nautilus_trader

同步依赖:
1
uv sync --all-extras

设置环境变量 (Linux/macOS):

1
2
3

export PYO3_PYTHON="$PWD/.venv/bin/python"
# Linux 特有: 设置动态库路径
export LD_LIBRARY_PATH="$("$PYO3_PYTHON" -c 'import sysconfig; print(sysconfig.get_config_var("LIBDIR"))')${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"

编译与安装:
1
make build # release 模式
编译过程可能需要几分钟。编译完成后，包会安装到项目的虚拟环境中。

方式三：使用 Docker (最便捷的环境)

如果您希望快速上手体验，无需配置本地环境，可以使用官方 Docker 镜像，其中包含了 JupyterLab 和示例回测笔记本。

1
2
3

# 拉取并运行包含 JupyterLab 的镜像 (nightly 版本)
docker pull ghcr.io/nautechsystems/jupyterlab:nightly --platform linux/amd64
docker run -p 8888:8888 ghcr.io/nautechsystems/jupyterlab:nightly

然后在浏览器中打开 http://127.0.0.1:8888/lab 即可开始。

注意：Docker 镜像中的示例将日志级别设为 ERROR，因为 Nautilus 的详细日志会超过 Jupyter 的输出速率限制，可能导致笔记本卡顿。

4. 快速开始：运行你的第一个回测

下载示例数据 (如果使用源码或 Docker，部分示例数据需下载):

1 2	# 在项目根目录下 curl https://raw.githubusercontent.com/nautechsystems/nautilus_data/main/nautilus_data/hist_data_to_catalog.py \| python -

运行示例策略:
在 examples/ 目录下有许多完整的示例。例如，运行一个简单的 EMA 交叉策略回测：
1
python examples/backtest/ema_cross.py
编写你自己的策略:
核心是继承 Strategy 类，并实现 on_start, on_data, on_order_event 等生命周期方法。你可以参考 examples/ 或官方教程。

5. 配置与调优

精度模式 (Precision Mode)：NautilusTrader 支持两种数值精度：
- 高精度 (128-bit)：支持最多 16 位小数，默认启用，适合加密货币等价格精度要求极高的场景。
- 标准精度 (64-bit)：支持最多 9 位小数，性能略优。
  从源码编译时，可以通过设置环境变量 HIGH_PRECISION=true 来切换。
Redis 支持：Redis 是可选组件，仅在您需要将其用作缓存数据库或消息总线后端时才需要配置。

6. 常见问题与排查

问题	可能原因与解决方案
编译失败 (Rust相关错误)	Rust 工具链未正确安装或版本过低。运行 `rustup update`。确保 `clang` 已安装且可执行。
`uv sync` 失败	Python 版本不符（需 3.12-3.14）。网络问题导致依赖下载失败，尝试配置国内镜像源。
找不到 `nautilus_trader` 模块	未在正确的虚拟环境中。确保运行 `source .venv/bin/activate` 或使用 `uv run` 前缀。
Jupyter Notebook 卡顿	日志级别过高。按照官方示例，将日志级别设为 `ERROR` 或 `WARNING` 即可解决。
运行多节点时出现进程冲突	由于全局单例状态，同一进程内不支持同时运行多个 `BacktestNode` 或 `LiveNode`。请确保顺序执行或在不同进程中运行。