TSP 部署教程：自托管 A 股智能量化工作台，选股、监控、回测一体化

做 A 股量化的朋友，大概都有过这样的经历：拉数用一套脚本，选股用一个网页，回测又换了个工具，盘中异动靠人盯，想接个 AI 还要自己拼。TSP（TickFlow Stock Panel）想解决的就是这件事——把「选股 + 监控 + 回测」收进一个自托管的工作台里，数据落本地、Docker 一条命令起、核心能力全部开放成接口。这篇文章根据项目 README 实测整理，把定位、部署、使用和常见坑一次讲清楚。

项目简介

TSP 官方自称「自托管 · 零运维 · 核心能力全部开放成接口的 A 股量化工作台」。它不是看盘软件，也不内置「AI 荐股 / 涨停预测」，定位是给量化爱好者提供一套本地研究工具：

• 自托管一体化：选股（Screener）、监控（Monitor）、回测（Backtest）、因子挖掘、个股分析、盘后复盘全部在同一个面板里，数据口径统一。
• TickFlow 数据源：内置 TickFlow 官方 SDK，同时数据源插件化，可接入 fuyao（同花顺 REST）、TdxQuant（通达信量化），也能用 YAML 自定义第三方数据源。
• LLM 能力驱动：配置 AI Key 后，可以让大模型生成策略、做个股四维分析、盘后复盘，还有一个「一句话问全站数据」的 AI 对话助手。
• Polars 列式引擎：全市场策略扫描做到毫秒级，只存 15 列基础数据、现算 68 列指标信号。
• 零外部数据库：Parquet 存储 + DuckDB 查询，单容器运行，数据 100% 落在本地。
• MIT 协议开源：可自由二次开发、接入第三方数据源与个性化扩展数据。

README 里作者列了一张「痛点对照表」，很能说明这个项目的动机：数据源绑死、换一家就要重写整套拉数代码，TSP 用「能力路由矩阵」把 6 类数据集按源能力独立路由，随时换源、指标与回测口径不变；策略、回测、监控各用一套工具导致口径对不上，TSP 全站统一 enriched 数据口径，从策略到回测到监控到复盘吃同一份数据；盘中异动靠人盯盘，TSP 提供竞价 / 盘中 / 偏移全时段异动加实时弹窗、语音播报、飞书推送；想基于面板数据做自己的工具只能爬页面，TSP 把核心能力全部开放成受控接口。

架构与开放能力

TSP 的设计主线是「核心底座 + 扩展层」：核心域 8 个模块拥有数据与语义，扩展域 5 条通道只消费核心契约——数据源插件、扩展数据表、自定义策略信号、页面扩展、后端 custom 模块都可以整体替换或移除而不伤核心。仓库里 11 个官方页面本身就是单文件扩展，删除目录即卸载、复制目录即导入，连 AI 对话助手都是扩展域的参考实现。

开放层面，面板走密码会话、外部程序走 Token 网关，双通道并行互不挤占：Token 在「设置 → 开放接口」创建、明文只显示一次、六档 scope 按需授予（行情读取、扩展表读写、分析读取、回测运行、模拟盘交易等），全网关共 65 个契约化端点，附带 SSE 事件流做实时告警推送；另外还提供官方 MCP 服务器，12 个工具把面板能力交给任意 AI 客户端，权限裁决复用同一套网关。

# 十行内跑通第一个开放接口调用
curl -H "Authorization: Bearer tsp_xxxx" \
  "http://localhost:3018/api/kline/daily?symbol=600519.SH&limit=10"

官方资源汇总

环境要求

按 README 的说法，不同玩法的前置条件差别很大，对号入座即可：

运行时方面：后端基于 FastAPI + Python 3.11+，前端是 React 18 + Vite + TypeScript，回测用自研仓位模拟引擎（T+1 / 费用 / 滑点 / 分钟回放）。存储不需要你额外装数据库——Parquet 文件落盘、DuckDB 本地查询。默认服务端口是 3018；Dev 模式下后端 3018、前端 3011。内存上，后端会在内存里保留一份完整的 enriched 历史宽表，实测约 1.3 GB 常驻、预热峰值 1.5–1.8 GB；2 GB 内存的小主机建议设置 POLARS_MAX_THREADS=2 压到约 0.8 GB。

部署步骤

方式一：Docker 一条命令（推荐）

仓库每次推送都由 GitHub Actions 自动构建多架构镜像，直接拉取即可，本地不需要装 Python 或 Node：

docker run -d --name tsp -p 3018:3018 -v ${PWD}/data:/app/data ghcr.io/shy3130/tick-stock-panel:latest

启动后浏览器打开 http://localhost:3018 就能看到面板。几个要点：

• -v ${PWD}/data:/app/data 把数据目录挂载到宿主机，升级重建容器时一定要保留这个挂载并提前备份 data/，否则容器层数据会随旧容器一起丢失。
• Linux 下容器内要通过 host.docker.internal 访问宿主机服务（比如自定义数据源）时，命令追加 --add-host=host.docker.internal:host-gateway。
• 需要配置时，从仓库复制 .env.example 为 .env，再给 docker run 加 --env-file .env。

方式二：Docker Compose 本地构建

适合想跑自己改过的代码、或需要全套挂载的用户：

git clone https://github.com/shy3130/tickflow-stock-panel.git
cd tickflow-stock-panel
cp .env.example .env
docker compose up --build

同样打开 http://localhost:3018。镜像内置固定版本的 Codex CLI，Compose 会把宿主机的 ~/.codex 只读挂载进容器；Windows 用户如果 PowerShell 下 HOME 变量未设置，需要在 .env 里手动写一行 CODEX_HOME_HOST=C:\Users\你的用户名\.codex。

方式三：Dev 源码模式（二次开发）

git clone https://github.com/shy3130/tickflow-stock-panel.git
cd tickflow-stock-panel
cp .env.example .env       # 按需填 TICKFLOW_API_KEY，留空 = None 模式
./dev.sh                   # Windows 用 .\dev.ps1

启动器会自动检查依赖、释放端口，同时拉起前后端。停止时请用 Ctrl-C 而不是关窗口——只有 Ctrl-C 会走清理逻辑、结束整棵进程树。日志在 data/logs/ 下排查。

桌面客户端

不想碰命令行的话，去 Releases 页面下载安装包：Windows 双击 TSP-Setup-x64-*.exe 按向导安装；macOS 下载 TSP-macos-arm64-*.dmg，把 TSP.app 拖进「应用程序」再运行。macOS 首次打开会被 Gatekeeper 拦截，到「系统设置 → 隐私与安全性」点「仍要打开」即可；若提示「已损坏」，在终端执行 xattr -dr com.apple.quarantine /Applications/TSP.app。

配置项

所有配置从根目录 .env 读取（复制 .env.example 开始），也可以在面板「设置」页改。最常用的三项：

TICKFLOW_API_KEY=              # 留空 = None 模式（历史日K免费）；填 Key 解锁更多
AI_API_KEY=                    # 留空 = 关闭 AI；填 Key 启用策略生成与 AI 对话助手
PORT=3018                      # 服务端口

注意 TICKFLOW_API_KEY 留空也能跑——None 模式下历史日 K 数据免费可用，盘中实时数据需要更高档位。完整的数据源档位、AI 供应商、服务密码、老 CPU 兼容等配置项见仓库的 docs/configuration.md。

内存紧张的机器还有三个「内存保护环境变量」可调：TICK_WORKER_RSS_LIMIT_BYTES 限制回测 / 优化独立 worker 的 RSS 上限（默认 6 GiB，超限即终止并返回明确错误，而不是拖垮整机）；TICK_HEAVY_MIN_AVAILABLE_BYTES 规定系统可用内存低于阈值时新的重任务挂起等待（默认 1 GiB）；TICK_DUCKDB_READ_CONCURRENCY 控制 DuckDB 并发读上限（默认 3，调小可降峰值内存）。容器的 /health 接口会实时返回主进程 RSS 与 cgroup 节流计数，方便观察。

首次使用流程

服务跑起来后，按 README 的推荐顺序走一遍：

1. 设置 → 凭据与能力，点「重新检测」，确认数据源档位与能力路由矩阵。
2. 设置 → 立即跑盘后管道：拉日 K、计算 enriched 表（None / Free 档位当日数据盘后 1–2 小时可用）。
3. 自选页加入关注标的；策略页点策略卡片扫描，或配置自定义信号。
4. 回测页选策略 + 时间区间，看净值、夏普、交易明细，结果可导出 CSV、存候选一键复测。
5. 监控中心配规则，盘中实时弹窗 + 持久化记录；异动监控覆盖竞价 / 盘中 / 偏移全时段。
6. 配好 AI Key 后，用悬浮球或 ⌘K / Ctrl+K 呼出 AI 对话助手，直接问市场行情。
7. 想接自己的程序？设置 → 开放接口创建 Token，按 examples/open-api 十分钟跑通第一个脚本；用 AI 客户端的话，直接按 mcp-server/README.md 配置 MCP 接入。
8. 想定制页面？核心之外的 11 个官方页面都是单文件扩展（新装默认隐藏，在「设置 → 菜单设置」一键开启）；自己开发的页面用仓库提供的 page-pack 模板打包，经「设置 → 页面插件」上传即挂载，宿主无需重建、刷新生效。

核心模块速览

除了下面这几个主页面，面板还包含一套因子平台（DSL 自定义因子 + 检验组合，与策略双向联动）、因子挖掘（样本外搜索多因子组合，显式发布、永不上线）、市场环境分析（情绪周期 6 阶段 + 概念 / 行业主线排名）、连板梯队（连板统计 + 概念轮动 + 盘后 AI 复盘）以及个股分析（9 类关键价位 + AI 四维分析）。19 个页面的完整功能细节写在仓库的 docs/features.md。

看板 Dashboard

首页汇总全市场涨跌家数、成交额、涨停连板、情绪雷达等总览信息，相当于打开面板的第一屏。

策略 Screener

全自定义策略 + 自定义信号 + AI 生成策略，基于 Polars 引擎毫秒级扫全 A 股，扫描结果直接落盘 enriched Parquet。

回测 Backtest

支持因子回测、策略回测、分钟级回测，内置 T+1、手续费、滑点与因子归因；回测跑在独立 worker 子进程里，刷新页面不丢任务。

监控中心 Monitor

竞价 / 盘中 / 偏移三类异动一页覆盖，四类规则 AND/OR 组合，支持实时弹窗、语音播报和飞书推送。

AI 对话助手

配置 OpenAI 兼容接口后，一句话问出全站数据：个股行情、财务五表、大盘总览、板块轮动、自选表现都能查；生成信号、跑回测、加自选等写操作会先弹确认卡，你点确认才执行。

常见问题

1. 不填 TickFlow API Key 能用吗？ 可以。留空进入 None 模式，历史日 K 数据免费可用；只是档位低，当日数据盘后才更新，实时行情需要更高档位。

2. 数据存在哪里？安全吗？ 全部落在本地 data/ 目录的 Parquet 文件里，没有外部数据库。升级镜像时一定保留 -v ${PWD}/data:/app/data 挂载并备份数据目录，否则重建容器后数据会丢。

3. 可以公网部署吗？ 可以，但默认有网络门禁：Token 通道只接受本机 / 内网调用，公网一律 403。确实需要远程访问时显式设置 API_TOKEN_LOCAL_ONLY=0，更推荐走 SSH 隧道。

4. 2 GB 内存的小主机能跑吗？ 能，但要做两件事：.env 里设 POLARS_MAX_THREADS=2，Compose 里加 mem_limit: 1500m。并且不要在 2 GB 机器上跑回测、稳健优化或因子挖掘（这类任务另起 worker 进程约 800 MB），也不要多开实例。

5. AI 功能是必须的吗？ 不是。AI_API_KEY 留空就完全关闭 AI 能力，选股、监控、回测照常可用。对话助手要求供应商支持工具调用（OpenAI Chat Completions / Responses 兼容协议），DeepSeek、通义、本地 Ollama 都可以接。

6. macOS 桌面端提示「已损坏」怎么办？ 打开终端执行 xattr -dr com.apple.quarantine /Applications/TSP.app 移除下载隔离标记，再重新启动。

7. 老 CPU 跑不起来现成镜像？ 官方镜像为体积考虑不含老 CPU 兼容内核。这种情况用方式二的 Compose 本地构建，Polars 的 rtcompat 兼容内核会在构建时打进去。

8. 数据源只能用 TickFlow 吗？ 不是。数据源已插件化：内置 fuyao（同花顺 REST，含财务、龙虎榜、盘前风向标）、TdxQuant（通达信，实时行情、五档盘口、分钟 K），也可以按 YAML 契约自定义第三方数据源，换源不换口径。

9. 升级项目会不会把我自己的数据和配置冲掉？ 不会。用户数据（API Key、AI 配置、自选、行情数据）都落在数据目录里，桌面端 macOS 版本更是专门放在 ~/Library/Application Support/TSP 这类用户目录下，替换应用本体不会丢。真正需要注意的是容器部署：重建容器前务必备份 data/，并在新容器命令里原样挂回 -v 挂载。

写在最后

TSP 本质上是一个「研究工具」而非「交易软件」：它明确不对标同花顺 / 通达信，也不内置 AI 荐股，回测结果不代表未来收益。工程上这个项目也有一些可圈可点的细节：全市场策略扫描靠 Polars 列式引擎做到毫秒级，指标流水线只存 15 列基础数据、现算 68 列指标信号；回测跑在 spawn 出来的子进程里，刷新页面、切页重连都不丢任务，主服务永远不会被长计算卡住；仓库里有 3000+ 条测试，GitHub Actions 后端全量加前端构建约 100 秒跑完，开放接口的 65 个端点有机器可读契约加快照测试守护。

对想把量化流程从拼凑脚本收敛到一个本地工作台、又不想付费云终端的人来说，这个 MIT 协议的项目值得拉下来跑一遍。数据准确性以数据源官方为准，A 股有风险，入市需谨慎。