EasyXT 增强版配置指南

📖 本指南补充 INSTALL.md，提供针对不同场景的详细配置说明

❓ 遇到问题？ 查看 TROUBLESHOOTING.md 疑难问题解答

📋 目录

快速诊断：我应该配置哪些内容？
1. 配置文件说明
2. 数据源配置
3. IDE 配置（Trae/VSCode/PyCharm）
4. 常见场景配置清单

快速诊断：我应该配置哪些内容？

场景选择器

请选择你的使用场景，了解需要配置哪些内容：

🔴 场景 A：我想使用 QMT/miniQMT 进行交易

✅ 必需：xtquant 配置
✅ 必需：QMT 路径配置
⚙️ 可选：Tushare Token（用于数据下载）
⚙️ 可选：DuckDB 数据库（用于加速回测）

🔵 场景 B：我想使用通达信（TDX）数据

✅ 必需：TDX 数据源配置
⚙️ 可选：DuckDB 数据库
❌ 不需要：QMT/xtquant

🟢 场景 C：我只想做回测（不交易）

✅ 必需：任一数据源（Tushare/TDX/QMT）
🚀 推荐：DuckDB 数据库（提速 10-30 倍）
❌ 不需要：QMT 交易配置

🟡 场景 D：我想使用雪球跟单策略

✅ 必需：xtquant 配置
✅ 必需：雪球 Cookie 配置
✅ 必需：QMT 路径配置

🟣 场景 E：我是 Mac/Linux 用户

✅ 必需：xqshare 远程客户端配置
⚙️ 可选：Tushare/TDX 数据源
❌ 不需要：本地 QMT（不支持）

1. 配置文件说明

本项目使用统一配置系统，支持多个配置文件。理解配置文件的优先级很重要。

1.1 配置文件优先级

运行时配置（代码中动态设置）
    ↓ (优先级最高)
用户配置文件（unified_config.json）
    ↓
系统默认配置（代码中的默认值）
    ↓ (优先级最低)

1.2 主要配置文件

配置文件	位置	用途	是否必需
unified_config.json	`config/unified_config.json`	主配置文件，包含大部分配置项	✅ 推荐创建
.env	项目根目录	环境变量（Token、路径等）	✅ 如需使用 Tushare/雪球
realtime_config.json	`config/realtime_config.json`	实时数据配置（WebSocket、监控等）	⚙️ 高级功能
策略独立配置	`strategies//config/.json`	各策略的独立配置	⚙️ 使用特定策略时

1.3 如何编辑配置文件

Windows 最简单方法：

按 Win + R，输入 notepad
打开配置文件（.env 或 config/unified_config.json）
编辑并保存

如果 .env 不存在：

Copy-Item .env.example .env

Windows 路径注意事项：在 JSON 文件中，Windows 路径需要特殊处理：

✅ "D:\\\\国金QMT交易端模拟\\\\userdata_mini" （双反斜杠）
✅ "D:/国金QMT交易端模拟/userdata_mini" （正斜杠，推荐）
❌ "D:\国金QMT交易端模拟\userdata_mini" （单反斜杠，错误！）

1.4 创建配置文件

步骤 1：复制配置模板

# Windows PowerShell
Copy-Item config\unified_config.json config\unified_config.json.backup

# 如果没有 .env 文件
Copy-Item .env.example .env

步骤 2：编辑 unified_config.json

配置文件包含详细注释，以下是关键配置项：

{
  "settings": {
    "account": {
      // QMT 路径配置（使用 QMT 交易时必需）
      "qmt_path": "D:\\\\国金QMT交易端模拟\\\\userdata_mini",
      "account_id": "39020958",
      "auto_detect_qmt": true
    },
    "logging": {
      // 日志配置（调试时建议设为 DEBUG）
      "level": "INFO",
      "file": "logs/application.log"
    },
    "trading": {
      // 交易模式（paper_trading=仿真，real=实盘）
      "trade_mode": "paper_trading",
      "auto_confirm": false  // ⚠️ 实盘交易前确认此配置
    }
  }
}

步骤 3：编辑 .env 文件

# Tushare Token（使用 Tushare 数据源时必需）
TUSHARE_TOKEN=你的Token粘贴在这里

# DuckDB 路径（使用 DuckDB 时推荐配置）
DUCKDB_PATH=D:/StockData/stock_data.ddb

# 雪球 Cookie（使用雪球跟单时必需）
XUEQIU_COOKIE=你的雪球Cookie

1.5 QMT 路径配置

QMT 路径查找

常见的 QMT 安装路径：

D:\国金证券QMT交易端\userdata_mini\
D:\国金QMT交易端模拟\userdata_mini\
D:\QMT\userdata_mini\
C:\QMT\userdata_mini\

自动检测 QMT 路径

from easy_xt.config import config
config.print_qmt_status()

手动设置 QMT 路径

from easy_xt.config import config
config.set_qmt_path('D:\\国金QMT交易端模拟')

或在 unified_config.json 中设置：

{
  "settings": {
    "account": {
      "qmt_path": "D:\\\\国金QMT交易端模拟\\\\userdata_mini"
    }
  }
}

2. 数据源配置

本项目支持多种数据源，系统会按优先级自动选择可用的数据源。

2.1 数据源优先级

DuckDB（本地数据库）
    ↓ 失败/未配置
QMT/miniQMT（本地数据）
    ↓ 失败/未配置
Tushare（在线数据）
    ↓ 失败/未配置
TDX（通达信）
    ↓ 失败/未配置
Eastmoney（东方财富）

2.2 数据源配置清单

Tushare 数据源

何时需要：需要在线股票数据（日线、财务、指数等）

配置步骤：

注册并获取 Token：
- 访问 https://tushare.pro
- 注册账号
- 进入「用户中心」→「接口Token」→ 复制 Token

配置 Token：

方法 A：使用 .env 文件（推荐）

TUSHARE_TOKEN=你的Token粘贴在这里

方法 B：环境变量

setx TUSHARE_TOKEN "你的Token"

方法 C：配置文件

{
  "data_providers": {
    "tushare": {
      "token": "你的Token"
    }
  }
}

验证配置：

python -c "from dotenv import load_dotenv; load_dotenv(); import os; print('✓ Token配置成功' if os.getenv('TUSHARE_TOKEN') else '✗ Token未配置')"

常见问题：

Q: Token 会被限流吗？ A: 是的。可以在 .env 中配置备用 Token：TUSHARE_TOKEN_2=你的备用Token
Q: 免费账户够用吗？ A: 基础功能（日线行情）够用。高频数据或高级财务数据需要更多积分。

TDX（通达信）数据源

何时需要：使用通达信作为数据源

配置步骤：

安装 pytdx：
```
pip install pytdx
```

配置 TDX 服务器（可选，有默认配置）：

编辑 config/unified_config.json：

{
  "data_providers": {
    "tdx": {
      "enabled": true,
      "timeout": 30,
      "retry_count": 3,
      "servers": [
        {
          "host": "115.238.56.198",
          "port": 7709,
          "name": "杭州主站"
        }
      ]
    }
  }
}

验证连接：

from easy_xt.realtime_data.providers import TdxDataProvider
tdx = TdxDataProvider()
if tdx.connect():
    print("✓ TDX 连接成功")

常见 TDX 服务器列表：

服务器	地址	端口
杭州主站	115.238.56.198	7709
南京主站	115.238.90.165	7709
上海主站	114.80.63.12	7709
深圳主站	119.147.212.81	7709

QMT/miniQMT 数据源

何时需要：已安装 QMT/miniQMT，想使用本地数据

配置步骤：

确保 xtquant 已正确安装（见 xtquant 配置）
配置 QMT 路径（见 QMT 路径配置）
启动 QMT/miniQMT 客户端并登录

验证连接：

from easy_xt import get_api
api = get_api()
data = api.get_price(['000001.SZ'], count=10)
print(f"获取到 {len(data)} 条数据")

xqshare（跨平台）数据源

何时需要：Mac/Linux 用户，或远程连接 QMT

配置步骤：

安装 xqshare：
```
pip install xqshare
```

配置环境变量：

XQSHARE_REMOTE_HOST=你的服务器IP
XQSHARE_REMOTE_PORT=18812

验证连接：

from xqshare import XtQuantClient
client = XtQuantClient('你的服务器IP', 18812)
# 正常使用 EasyXT，会自动检测并使用 xqshare

详细说明：见 README.md 跨平台支持章节

DuckDB 数据库配置

何时需要：频繁回测、因子分析，需要提速 10-30 倍

配置步骤：

安装 DuckDB：
```
pip install duckdb
```
下载/生成数据库：

方式 A：GUI 下载（推荐）
```
python run_gui.py
```
在 "Tushare下载" 标签页中选择要下载的数据

方式 B：命令行下载
```
python tools/setup_duckdb.py
```
方式 C：使用现有数据库 将数据库文件放到指定位置，如 D:/StockData/stock_data.ddb

配置路径：

方法 A：.env 文件

DUCKDB_PATH=D:/StockData/stock_data.ddb

方法 B：配置文件

{
  "data_providers": {
    "duckdb": {
      "path": "D:/StockData/stock_data.ddb"
    }
  }
}

方法 C：代码中指定

from easyxt_backtest import DataManager
data_manager = DataManager(duckdb_path='D:/StockData/stock_data.ddb')

验证数据库：

import duckdb
con = duckdb.connect('D:/StockData/stock_data.ddb', read_only=True)
tables = con.execute("SHOW TABLES").fetchall()
print("数据库表:", [t[0] for t in tables])

性能对比：

数据源	获取 100 只股票 1 年数据	适用场景
DuckDB	~1 秒	频繁回测、因子分析
QMT 本地	~10-30 秒	偶尔回测
Tushare 在线	~30-60 秒	无本地数据时

3.3 数据源选择建议

使用场景	推荐数据源	原因
实盘交易	QMT 本地	最实时、最稳定
频繁回测	DuckDB	速度最快
偶尔回测	Tushare / TDX	无需预先下载
Mac/Linux 用户	xqshare + Tushare	跨平台支持
因子分析	DuckDB	大数据查询优化

3. IDE 配置（Trae/VSCode/PyCharm）

3.1 通用步骤

所有 IDE 都需要完成以下步骤：

安装核心库：
```
pip install -e ./easy_xt
```
配置 Python 解释器：
- 确保使用正确的 Python 环境
- 验证：python --version（需要 >= 3.9）

验证安装：

python -c "from easy_xt import get_api; print('✓ 安装成功')"

3.2 VSCode 配置

创建 .vscode/settings.json：

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",
  "python.envFile": "${workspaceFolder}/.env",
  "python.analysis.extraPaths": [
    "${workspaceFolder}"
  ]
}

创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: 当前文件",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  ]
}

3.3 PyCharm 配置

设置项目根目录：

File → Open → 选择项目根目录
File → Settings → Project → Python Interpreter
选择正确的 Python 解释器

配置运行配置：

Run → Edit Configurations
添加环境变量：
- Name: PYTHONPATH
- Value: 项目根目录路径

3.4 Trae 配置

已知问题和解决方案：

问题 1：模块导入错误

解决方案：

在项目根目录创建 trae_config.json：

{
  "pythonPath": "你的Python路径",
  "env": {
    "PYTHONPATH": "项目根目录路径"
  }
}

或在 Trae 的终端中手动设置：

export PYTHONPATH="项目根目录路径:$PYTHONPATH"

问题 2：xtquant 导入失败

解决方案：

确保 XTQUANT_PATH 环境变量已设置并在 Trae 中生效：

系统环境变量中设置：
```
setx XTQUANT_PATH "xtquant所在路径"
```
重启 Trae IDE

验证：

import os
print(os.getenv('XTQUANT_PATH'))  # 应该输出路径
from xtquant import xtdata  # 不应该报错

3.5 Jupyter Notebook 配置

安装 IPython Kernel：

pip install ipykernel
python -m ipykernel install --user --name=easyxt-env

在 Notebook 中设置路径：

import sys
sys.path.insert(0, '项目根目录路径')

4. 常见场景配置清单

4.1 场景 A：QMT 实盘交易

配置文件位置：config/unified_config.json

配置清单：

xtquant 已正确安装
QMT 路径已配置（config/unified_config.json）
QMT 客户端已启动并登录
交易模式已设置（real 或 paper_trading）
账户 ID 已配置

配置步骤：

编辑配置文件 config/unified_config.json：

{
  "settings": {
    "account": {
      "qmt_path": "D:\\\\国金QMT交易端模拟\\\\userdata_mini",
      "account_id": "你的账户ID",
      "auto_detect_qmt": true
    },
    "trading": {
      "trade_mode": "real",
      "auto_confirm": false
    }
  }
}

⚠️ 重要提示：
- Windows 路径中的反斜杠需要写成 \\\\（双转义）
- 或者使用正斜杠：D:/国金QMT交易端模拟/userdata_mini
- trade_mode: "real" 表示实盘交易，请谨慎操作！
- 建议先使用 trade_mode: "paper_trading" 测试
启动 QMT 客户端并登录

验证命令：

# 验证 xtquant
python -c "from xtquant import xtdata; print('✓ xtquant OK')"

# 验证配置
python -c "from easy_xt.config import config; config.print_qmt_status()"

# 验证连接
python -c "from easy_xt import get_api; api = get_api(); print('✓ 连接成功')"

4.2 场景 B：TDX 数据源 + 回测

配置文件位置：

主配置：config/unified_config.json
环境变量：项目根目录的 .env 文件（可选）

配置清单：

pytdx 已安装（pip install pytdx）
TDX 服务器已配置（可选，有默认值）
easyxt_backtest 已安装
DuckDB 已配置（可选，但推荐）

配置步骤：

安装 pytdx：
```
pip install pytdx
```

编辑配置文件 config/unified_config.json：

{
  "data_providers": {
    "tdx": {
      "enabled": true,
      "timeout": 30,
      "retry_count": 3,
      "servers": [
        {
          "host": "115.238.56.198",
          "port": 7709,
          "name": "杭州主站"
        }
      ]
    }
  }
}

（可选）配置 DuckDB 以提升回测速度：

编辑项目根目录的 .env 文件：
```
DUCKDB_PATH=D:/StockData/stock_data.ddb
```

验证命令：

# 验证 TDX
python -c "from pytdx.hq import TdxHq_API; print('✓ pytdx OK')"

# 验证回测
python -c "from easyxt_backtest import BacktestEngine; print('✓ backtest OK')"

# 测试 TDX 连接
python easy_xt/realtime_data/providers/tdx_provider.py

4.3 场景 C：雪球跟单策略

配置文件位置：

主配置：config/unified_config.json 或 strategies/xueqiu_follow/config/unified_config.json
环境变量：项目根目录的 .env 文件

配置清单：

xtquant 已正确安装
QMT 路径已配置
雪球 Cookie 已配置（.env 文件）
雪球跟单配置已设置

配置步骤：

编辑项目根目录的 .env 文件：

# 雪球 Cookie（必需）
XUEQIU_COOKIE=你的雪球Cookie

编辑配置文件 config/unified_config.json：

{
  "settings": {
    "account": {
      "qmt_path": "D:\\\\国金QMT交易端模拟\\\\userdata_mini",
      "account_id": "你的账户ID"
    },
    "trading": {
      "trade_mode": "paper_trading"
    }
  },
  "xueqiu": {
    "cookie": "你的雪球Cookie",
    "follow_combination_id": "你要跟单的组合ID"
  }
}

获取雪球 Cookie：
- 浏览器访问 https://xueqiu.com 并登录
- F12 打开开发者工具 → 网络(Network)标签
- 刷新页面，点击任意 xueqiu.com 请求
- 在请求头中复制完整 Cookie 值

验证命令：

# 验证雪球 Cookie
python -c "from dotenv import load_dotenv; load_dotenv(); import os; print('✓ Cookie 已配置' if os.getenv('XUEQIU_COOKIE') else '✗ Cookie 未配置')"

# 启动雪球跟单
python strategies/xueqiu_follow/start_xueqiu_follow_easyxt.py

4.4 场景 D：Mac/Linux 用户

配置文件位置：

主配置：config/unified_config.json
环境变量：项目根目录的 .env 文件

配置清单：

xqshare 已安装（pip install xqshare）
远程服务器地址已配置
Tushare Token 已配置（备用数据源）
DuckDB 已配置（可选，但推荐）

配置步骤：

安装 xqshare：
```
pip install xqshare
```

编辑项目根目录的 .env 文件：

# xqshare 远程服务器配置
XQSHARE_REMOTE_HOST=你的服务器IP
XQSHARE_REMOTE_PORT=18812

# 备用数据源（推荐）
TUSHARE_TOKEN=你的Token

编辑配置文件 config/unified_config.json：

{
  "data_providers": {
    "xqshare": {
      "enabled": true,
      "remote_host": "你的服务器IP",
      "remote_port": 18812
    },
    "tushare": {
      "enabled": true,
      "token": "你的Token"
    }
  }
}

验证命令：

# 验证 xqshare
python -c "from xqshare import XtQuantClient; print('✓ xqshare OK')"

# 验证数据源
python -c "from easy_xt import get_api; api = get_api(); data = api.get_price(['000001.SZ'], count=10); print(f'✓ 获取到 {len(data)} 条数据')"

5. 快速检查清单

在开始使用前，请确认以下事项：

6. 获取帮助

自助资源

📖 完整安装指南 - 安装步骤和故障排查
❓ 疑难问题解答 - 常见问题 FAQ
📐 系统架构文档 - 项目架构说明
📖 项目 README - 项目说明和快速导航

诊断工具

# 完整诊断
python easy_xt/check_xtquant.py

# QMT 状态检查
python -c "from easy_xt.config import config; config.print_qmt_status()"

# 配置验证
python -c "from core.config import get_global_config_manager; cm = get_global_config_manager(); print(cm.validate())"

报告问题

如果问题仍未解决，请提交 Issue： https://github.com/quant-king299/EasyXT/issues

提交时请包含：

完整的错误信息
操作系统和 Python 版本
配置文件内容（脱敏后）
复现步骤

祝你配置顺利！ 🎉

如有任何问题，请先查看 TROUBLESHOOTING.md

FilesExpand file tree

SETUP_GUIDE.md

Latest commit

History

SETUP_GUIDE.md

File metadata and controls

EasyXT 增强版配置指南

📋 目录

快速诊断：我应该配置哪些内容？

场景选择器

🔴 场景 A：我想使用 QMT/miniQMT 进行交易

🔵 场景 B：我想使用通达信（TDX）数据

🟢 场景 C：我只想做回测（不交易）

🟡 场景 D：我想使用雪球跟单策略

🟣 场景 E：我是 Mac/Linux 用户

1. 配置文件说明

1.1 配置文件优先级

1.2 主要配置文件

1.3 如何编辑配置文件

1.4 创建配置文件

1.5 QMT 路径配置

2. 数据源配置

2.1 数据源优先级

2.2 数据源配置清单

Tushare 数据源

TDX（通达信）数据源

QMT/miniQMT 数据源

xqshare（跨平台）数据源

DuckDB 数据库配置

3.3 数据源选择建议

3. IDE 配置（Trae/VSCode/PyCharm）

3.1 通用步骤

3.2 VSCode 配置

3.3 PyCharm 配置

3.4 Trae 配置

3.5 Jupyter Notebook 配置

4. 常见场景配置清单

4.1 场景 A：QMT 实盘交易

4.2 场景 B：TDX 数据源 + 回测

4.3 场景 C：雪球跟单策略

4.4 场景 D：Mac/Linux 用户

5. 快速检查清单

6. 获取帮助

自助资源

诊断工具

报告问题