TSP A股智能量化工作台详细部署教程

TSP 是一个自托管、零运维的 A 股量化工作台，集成了选股、监控、回测和 AI 辅助研究功能。它采用插件化数据源架构，支持分钟级策略执行和全时段异动监控，适合个人量化研究。本教程将指导您完成部署。

📋 目录

TSP 是什么
核心功能概览
系统要求与准备
开发模式部署
Docker 部署（推荐）
首次使用配置
核心功能使用指南
更新与卸载
常见问题排查
重要声明与注意事项

TSP 是什么

TSP（Tick Stock Panel）是一个开源的本地量化工作台，专为 A 股市场设计。它的核心理念是提供一个灵活、可扩展的研究环境，让用户能够自由组合数据源、自定义策略，并进行回测验证，所有数据均本地存储。

项目定位：

个人量化研究工具，而非投资软件或看盘软件。
不提供 AI 荐股、涨停预测等类似功能。
仅供学习研究使用，严禁商业用途。

核心功能概览

TSP 集成了量化研究所需的主要模块：

模块	功能描述
能力路由	多数据集（日K/实时/分钟/财务等）按源能力独立路由，可任意组合
选股引擎	18 个内置策略 + 自定义信号 + AI 生成，Polars 毫秒级扫描全 A 股
指标流水线	生成 MA/EMA/MACD/RSI/KDJ/布林等 68 列指标与信号
回测研究	支持因子回测、策略回测、分钟策略回测，考虑 T+1/费用/滑点约束
因子挖掘	嵌套样本外搜索多因子排名组合，候选库显式发布，永不自动上线
市场环境	情绪周期 6 阶段识别，概念/行业主线排名
异动监控	竞价/盘中/偏移三类异动，全时段覆盖
监控中心	四类监控规则（策略/个股信号/价格/异动），支持语音播报和飞书推送
个股分析	9 类关键价位 + AI 四维分析（技术/基本面/财务/消息面）
连板梯队	连板层级统计，概念涨幅轮动，盘后 AI 复盘

系统要求与准备

软件要求

Python：版本 3.11 或更高。
Node.js：版本 20 或更高。
包管理器：uv（Python）和 pnpm（Node.js）。
Git：用于克隆仓库。

安装 uv 和 pnpm

# 安装 uv (Python 包管理器)
pip install uv

# 安装 pnpm (Node.js 包管理器)
npm install -g pnpm

数据源准备（可选）

TSP 支持多种数据源。最常用的是 TickFlow（提供免费额度）和 fuyao（同花顺 REST 接口）。您需要：

在 TICKFLOW_API_KEY 环境变量中填入 TickFlow API Key（留空则为 None 模式，仅可使用免费历史日K）。
如需使用 fuyao 数据源，需自行获取 API Key 并在配置中设置。

开发模式部署

这是二次开发或调试推荐的模式，前后端分离，支持热重载。

1. 克隆仓库

1 2	git clone https://github.com/shy3130/tick-stock-panel.git cd tick-stock-panel

2. 配置环境变量

1 2	cp .env.example .env # 编辑 .env 文件，至少设置 TICKFLOW_API_KEY（如无，可留空）

3. 启动开发服务

macOS/Linux:

./dev.sh

Windows (PowerShell):

.\dev.ps1

脚本会自动检查/下载依赖、释放端口，并同时启动前后端服务。

后端 API：http://localhost:3018
前端界面：http://localhost:3011

Docker 部署（推荐）

这是最省心的部署方式，适合生产环境或不想处理环境依赖的用户。

1. 克隆并配置

git clone https://github.com/shy3130/tick-stock-panel.git
cd tick-stock-panel
cp .env.example .env
# 编辑 .env 文件，配置 API Key 等

2. 构建并启动容器

1	docker compose up --build

访问 http://localhost:3018 即可使用。

3. Windows 用户注意：Codex 挂载配置

Docker 容器默认挂载本机的 ~/.codex 目录（只读）以支持 Codex CLI。Windows 下 HOME 环境变量可能未设置，需在 .env 文件中显式指定：

1 2	# 在 .env 中添加（路径以本机实际为准） CODEX_HOME_HOST=C:\Users\你的用户名\.codex

4. 其他 Docker 选项

如需使用特定版本的 Codex CLI，可在构建时指定：
1
CODEX_CLI_VERSION=0.144.3 docker compose up --build
镜像已内置 stock-sdk 数据源插件，开箱即用。
更多 Docker 进阶配置（如老CPU兼容、访问密码）请参考 docs/deployment.md。

首次使用配置

服务启动后，在浏览器中打开 http://localhost:3018（或您设置的端口）。

1. 数据源检测

进入 设置 → 凭据与能力，点击 重新检测。系统会探测您配置的数据源档位，并显示能力路由矩阵。

2. 初始数据同步

在设置页面，点击 立即跑盘后管道。这会拉取日K线数据并计算 enriched 指标表（包含 MA/MACD 等 68 列）。数据量较大，首次同步可能需要一些时间。

注意：None/Free 档位走 free-api，当日数据在盘后 1-2 小时才可用。

3. 配置 AI 接口（可选）

如需使用 AI 辅助功能（如策略生成、个股分析），在设置页面配置 OpenAI 兼容的接口（支持 DeepSeek、通义、Ollama 等）。

核心功能使用指南

选股（策略）

进入 策略 (Screener) 页面。
左侧列出所有内置策略（如“MACD金叉”、“RSI超卖”等）。
点击策略卡片，系统会使用 Polars 引擎进行全市场扫描。
扫描结果会以列表形式展示，支持排序和导出。

回测

进入 回测 (Backtest) 页面。
选择要测试的策略、标的池和时间区间。
设置回测参数（初始资金、手续费、滑点等）。
点击运行，回测过程会通过 SSE 实时推送进度。
完成后，可查看净值曲线、回撤、夏普比率等绩效指标，并导出结果 CSV。

监控中心

进入 监控中心 (Monitor) 页面。
创建监控规则，支持四种类型：
- 策略信号：当策略发出买入/卖出信号时触发。
- 个股信号：监控个股的技术指标阈值。
- 价格监控：监控价格突破或跌破关键价位。
- 异动监控：监控涨停、跌停、放量等异动。
规则触发时，会弹出实时弹窗，支持语音播报和飞书推送。

更新与卸载

更新

开发模式：

1 2	git pull ./dev.sh restart # 或重新运行 dev.sh

Docker 部署：

1
2
3

docker compose down
git pull
docker compose up --build

卸载

开发模式：直接删除项目目录即可。
Docker 部署：执行 docker compose down -v（-v 会删除数据卷）。
数据文件默认存储在项目目录下的 data/ 文件夹中，可按需备份或删除。

常见问题排查

问题：首次同步数据失败或数据不完整。

解决：检查 TICKFLOW_API_KEY 是否有效。部分数据源（如 fuyao）需要额外配置。查看后端日志获取详细错误信息。

问题：Docker 容器无法启动，提示端口占用。

解决：确保 3018 端口未被占用，或在 .env 文件中修改 PORT 变量。

问题：前端页面空白或无法连接后端。

解决：检查后端服务是否正常运行（http://localhost:3018/health）。开发模式下，确保前端代理配置正确。

问题：dev.sh 或 dev.ps1 执行报错。

解决：确认已安装 uv 和 pnpm。Windows 用户建议在 PowerShell 中执行，并确保执行策略允许脚本运行。

重要声明与注意事项

⚠️ 项目用途声明

本项目仅供学习与量化研究，不构成任何投资建议。
回测结果不代表未来收益。A 股有风险，入市需谨慎。
数据准确性以数据源官方为准。
严禁将本项目用于任何商业用途。

数据源合规

本项目依赖 TickFlow 提供数据服务，使用前请遵守其服务条款。
内置数据源插件 fuyao 提供同花顺 REST 数据接口，使用前请遵守其服务条款。

通过以上步骤，您应该能够成功部署并开始使用 TSP。这是一个功能丰富的量化研究平台，其文档体系完整（docs/ 目录下），建议根据需求深入阅读相关文档。祝您在量化研究之路上有所收获！