tick-stock-panel (TSP) 是一个自托管、零运维的A股量化工作台，集成了选股、监控、回测等核心功能。它采用插件化数据源设计，并支持LLM辅助分析。

以下是一份详细的部署教程，主要包含两种方式：开发模式 (推荐二次开发) 和 Docker部署 (最省心)。

📋 部署前准备

无论选择哪种方式，请确保你的系统满足以下基本要求：

  • 操作系统: macOS, Linux, 或 Windows。
  • Python: 版本 3.11 或更高。
  • Node.js: 版本 20 或更高。
  • 包管理工具:
    • uv (Python包管理): 用于后端依赖管理。
    • pnpm (Node.js包管理): 用于前端依赖管理。可以通过 npm i -g pnpm 全局安装。

🚀 方式一：开发模式 (Dev Mode)

此方式适合希望进行二次开发或自定义配置的用户，前后端分离运行，便于调试。

  1. 克隆项目
    打开终端，克隆仓库并进入项目目录：

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

  2. 配置环境变量
    复制示例环境变量文件，并根据需要编辑：

    1
    cp .env.example .env
    • 使用文本编辑器打开 .env 文件。
    • 最重要的配置是 TICKFLOW_API_KEY：如果你有TickFlow的API Key，可以填入以解锁更多数据；留空则进入免费模式 (None模式)，仍可使用历史日K等基础数据。
    • 其他配置如 AI_API_KEY (用于LLM分析) 可按需填写。

  3. 一键启动
    在项目根目录下，运行启动脚本：

    1
    2
    3
    4
    5
    # macOS / Linux
    ./dev.sh

    # Windows
    .\dev.ps1

    该脚本会自动检查并安装前后端依赖（使用 uv 和 pnpm），释放所需端口，并同时启动后端和前端服务。

  4. 访问应用
    启动成功后，在浏览器中访问：

    • 前端界面: http://localhost:3011
    • 后端API: http://localhost:3018 (可用于接口调试)

🐳 方式二：Docker 部署 (最省心)

此方式最适合只想快速使用、不想操心环境配置的用户，所有服务都运行在一个容器内。

  1. 配置环境变量
    同样，首先需要准备 .env 文件：

    1
    cp .env.example .env

    按需编辑 .env 文件，例如填入 TICKFLOW_API_KEY 等。

  2. 启动容器
    在项目根目录下，执行 Docker Compose 命令：

    1
    docker compose up --build

    该命令会根据 Dockerfile 和 docker-compose.yml 构建镜像并启动容器。

  3. 访问应用
    启动完成后，在浏览器中打开：

    1
    http://localhost:3018

    即可访问完整的TSP应用。

⚠️ Windows 用户特别注意事项

由于Windows下 HOME 环境变量可能未设置，Docker容器挂载Codex登录凭据时可能失败。解决方法是在项目根目录的 .env 文件中显式指定你本机的Codex目录路径：

1
2
# 请将路径替换为你实际的用户目录
CODEX_HOME_HOST=C:\Users\你的用户名\.codex

🏁 跑起来后的第一次使用

首次启动成功后，建议按以下步骤完成初始化配置：

  1. 检测数据源能力：进入 设置 → 凭据与能力，点击 “重新检测” 按钮。等待检测完成，确认显示的数据源档位（如 None/Free/Starter等）和能力路由矩阵符合你的预期。
  2. 拉取基础数据：在 设置 页面，找到并点击 “立即跑盘后管道” 按钮。此操作会拉取日K线数据并计算生成 enriched 指标表（包含MA、MACD、RSI等68列指标）。数据下载速度取决于你的网络和数据源，请耐心等待。
  3. 开始探索：
    • 在 自选 页面添加你关注的股票。
    • 进入 选股 页面，点击内置策略卡片进行全市场扫描。
    • 进入 回测 页面，选择策略和时间区间，体验回测引擎。
    • 在 监控中心 配置个性化监控规则。

🔧 高级配置与扩展

  • 配置详情: 所有 .env 配置项（如服务端口、AI接口、数据目录等）的详细说明，请查阅项目文档 docs/configuration.md。
  • 自定义数据源: TSP支持插件化数据源。如果你想接入其他数据源，可以参考 docs/custom-data-source.md 中的能力路由契约和YAML配置示例。
  • 更新代码: 如果使用Docker部署，拉取最新代码后重新执行 docker compose up --build 即可。如果是开发模式，拉取代码后重新运行 ./dev.sh 或 .\dev.ps1。

❓ 常见问题

  • 数据不显示或报错: 首先检查网络连接，然后确认 .env 中的数据源API Key是否正确。进入 设置 → 凭据与能力 重新检测状态。
  • 端口被占用: 可以在 .env 文件中修改 PORT 变量（后端端口）和 VITE_BACKEND_URL（前端连接的后端地址），然后重启服务。
  • 回测速度慢: 回测是计算密集型任务，尤其是全市场回测。可以适当缩小回测的时间范围或股票池。
  • AI功能不可用: 请确保在 .env 中正确配置了 AI_API_KEY 和 AI_BASE_URL（如果使用非OpenAI官方接口，如DeepSeek、Ollama）。

至此，你已经完成了 tick-stock-panel 的全部部署。这是一个功能非常丰富的系统，建议从选股和回测这两个核心模块开始熟悉，逐步探索其更强大的监控和分析能力。如有更深入的问题，可以查阅项目 docs/ 目录下的详细文档或在GitHub仓库提交Issue。