diff --git a/README.md b/README.md index f70b6f6..6737c8a 100644 --- a/README.md +++ b/README.md @@ -40,20 +40,77 @@ ## ✨ 核心功能 -| 模块         | 一句话 | 详见    | -| :--------------- | :--------------------------------------------------------------------- | :-------------------------------- | -| 🔀 **能力路由** | 多数据集(日K/除权/实时/分钟/盘口/财务,持续扩展)按源能力独立路由,任选组合 | [custom-data-source.md](./docs/custom-data-source.md) | -| 🔍 **选股引擎** | 25 个内置策略 + 分钟策略 + 自定义信号 + AI 生成,Polars 毫秒级扫全 A 股 | [strategy.md](./docs/strategy.md) | -| 📊 **指标流水线** | MA/EMA/MACD/RSI/KDJ/布林/量比等 68 列指标与信号,一次扫表落盘 enriched Parquet | [features.md](./docs/features.md) | -| 🧪 **回测研究** | 因子/策略/分钟回测 + 财务快照因子(点时口径),T+1/费用/滑点约束,评分策略附带因子归因 | [features.md](./docs/features.md) | -| 🔬 **因子平台** | DSL 自定义因子(编辑器 25 算子点选/试算/版本) + 检验/组合,与策略双向联动(一键生成策略/触发器引用因子/回测归因) | [factor-platform-plan.md](./docs/factor-platform-plan.md) | -| ⛏️ **因子挖掘** | 嵌套样本外搜索多因子排名组合,与自有策略对照,候选库显式发布、永不自动上线 | [mining.md](./docs/mining.md) | -| 🌡️ **市场环境** | 情绪周期 6 阶段(连板梯队驱动)+ 概念/行业主线排名,与 5 档环境分并存 | [market-phase.md](./docs/market-phase.md) | -| 🚨 **异动监控** | 竞价/盘中/偏移三类异动一页覆盖:同花顺风向标 + 当日信号聚合 + 交易所偏离值口径 | — | -| 📡 **监控中心** | 四类监控(策略/个股信号/价格/异动),多条件 AND/OR + 语音播报 + 飞书推送 | [features.md](./docs/features.md) | -| 📈 **个股分析** | 9 类关键价位 + AI 四维分析(技术/基本面/财务/消息面) | [features.md](./docs/features.md) | -| 🏆 **连板梯队** | 连板层级统计 + 概念涨幅轮动 + 盘后 AI 复盘(龙虎榜/盘前风向标注入) + 炸板/翘板预警 | [features.md](./docs/features.md) | -| 🧰 **数据扩展** | 数据源插件化(TickFlow/fuyao/stock-sdk + YAML 自定义源),扩展字段配成一级页面同台分析 | [custom-data-source.md](./docs/custom-data-source.md) | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
模块一句话详见
🔀 能力路由多数据集(日K/除权/实时/分钟/盘口/财务,持续扩展)按源能力独立路由,任选组合custom-data-source.md
🔍 选股引擎25 个内置策略 + 分钟策略 + 自定义信号 + AI 生成,Polars 毫秒级扫全 A 股strategy.md
📊 指标流水线MA/EMA/MACD/RSI/KDJ/布林/量比等 68 列指标与信号,一次扫表落盘 enriched Parquetfeatures.md
🧪 回测研究因子/策略/分钟回测 + 财务快照因子(点时口径),T+1/费用/滑点约束,评分策略附带因子归因features.md
🔬 因子平台DSL 自定义因子(编辑器 25 算子点选/试算/版本) + 检验/组合,与策略双向联动(一键生成策略/触发器引用因子/回测归因)factor-platform-plan.md
⛏️ 因子挖掘嵌套样本外搜索多因子排名组合,与自有策略对照,候选库显式发布、永不自动上线mining.md
🌡️ 市场环境情绪周期 6 阶段(连板梯队驱动)+ 概念/行业主线排名,与 5 档环境分并存market-phase.md
🚨 异动监控竞价/盘中/偏移三类异动一页覆盖:同花顺风向标 + 当日信号聚合 + 交易所偏离值口径—
📡 监控中心四类监控(策略/个股信号/价格/异动),多条件 AND/OR + 语音播报 + 飞书推送features.md
📈 个股分析9 类关键价位 + AI 四维分析(技术/基本面/财务/消息面)features.md
🏆 连板梯队连板层级统计 + 概念涨幅轮动 + 盘后 AI 复盘(龙虎榜/盘前风向标注入) + 炸板/翘板预警features.md
🧰 数据扩展数据源插件化(TickFlow/fuyao/stock-sdk + YAML 自定义源),扩展字段配成一级页面同台分析custom-data-source.md
📦 主要页面与功能 @@ -256,18 +313,25 @@ flowchart TB ## 🚀 快速开始 -> 前置依赖:Python ≥ 3.11 · Node ≥ 20 · [`uv`](https://docs.astral.sh/uv/) · `pnpm`(`npm i -g pnpm`) +> 前置依赖(仅方式 D 需要):Python ≥ 3.11 · Node ≥ 20 · [`uv`](https://docs.astral.sh/uv/) · `pnpm`(`npm i -g pnpm`) +> +> 有 Docker 直接看 **方式 A**,一条命令拉现成镜像;完全不想碰命令行:看 **方式 C**,让本机 AI 帮你部署 -### 方式 A:Dev 模式(二次开发推荐) +### 方式 A:GHCR 现成镜像(免本地构建,多数用户推荐) + +本项目每次推送都由 GitHub Actions 自动构建多架构镜像(linux/amd64 · arm64)并发布到 GHCR,拿来即用,本地无需装 Python / Node,也不用现场 build: ```bash -cp .env.example .env # 按需填 TICKFLOW_API_KEY(留空 = None 模式) -./dev.sh # Windows: .\dev.ps1 +docker run -d --name tsp -p 3018:3018 -v ${PWD}/data:/app/data ghcr.io/shy3130/tick-stock-panel:latest +# 打开 http://localhost:3018 ``` -自动检查 / 下载依赖、释放端口、同时起前后端。后端 → · 前端 → 。 +- 需要配置时:从 [.env.example](./.env.example) 复制出 `.env`,命令里加 `--env-file .env`。 +- 跑自己改过的代码:fork 后到仓库 **Actions** 页启用 workflow(fork 默认禁用),构建出的 `ghcr.io/<你的用户名>/tick-stock-panel` 用法相同。 +- 想用 compose 编排(挂载 `.env` / `tiers.yaml`):参考 [docker-compose.yml](./docker-compose.yml),把 `build:` 段换成 `image: ghcr.io/shy3130/tick-stock-panel:latest`。 +- 现成镜像默认不含 stock-sdk 插件与老 CPU 兼容内核(合规与体积考虑),有此需求请用方式 B 自构建,详见 [docs/deployment.md](./docs/deployment.md)。 -### 方式 B:Docker(部署最省心) +### 方式 B:Docker Compose(本地构建,全套挂载) ```bash cp .env.example .env @@ -289,9 +353,31 @@ CODEX_CLI_VERSION=0.144.3 docker compose up --build > Codex CLI 模式允许 TickFlow 容器读取本机 Codex 登录凭据，仅应在受信任的本机环境启用。凭据目录以只读方式挂载，不会写入镜像。 -镜像已内置 **stock-sdk** 数据源插件(Node 运行时 + 依赖),开箱即用。 +镜像默认**不含** stock-sdk 插件(合规考虑);确需启用执行 `docker compose build --build-arg INCLUDE_STOCKSDK=1` 后再 `docker compose up -d`,详见 [docs/deployment.md](./docs/deployment.md)。 -> 📖 Docker 进阶、GitHub Actions 自构建、老 CPU 兼容、访问密码设置等见 [docs/deployment.md](./docs/deployment.md)。 +> 📖 Docker 进阶、老 CPU 兼容、访问密码设置等见 [docs/deployment.md](./docs/deployment.md)。 + +### 方式 C:本机 AI 代部署(小白推荐) + +装一个本机 AI 编程助手(Trae / Codex / OpenCode / ZCode / WorkBuddy 等,任选其一),新建一个空文件夹用助手打开,把下面这段话原样发给它: + +```text +帮我部署开源项目 https://github.com/shy3130/tick-stock-panel 到本机: +克隆到当前文件夹;有 Docker 优先拉 ghcr.io/shy3130/tick-stock-panel:latest 现成镜像,没有就走 Dev 模式; +缺少的依赖(Docker / Python / Node)帮我一起装好; +最后告诉我浏览器打开哪个地址、需要填哪些 Key。 +``` + +AI 会自动完成克隆、装依赖、启动服务,完成后浏览器打开 即可;`TICKFLOW_API_KEY` 等配置按 AI 提示填,详见 [配置](#️-配置)。 + +### 方式 D:Dev 模式(二次开发推荐) + +```bash +cp .env.example .env # 按需填 TICKFLOW_API_KEY(留空 = None 模式) +./dev.sh # Windows: .\dev.ps1 +``` + +自动检查 / 下载依赖、释放端口、同时起前后端。后端 → · 前端 → 。 ### 跑起来后的第一次使用 diff --git a/docs/deployment.md b/docs/deployment.md index 4ca16bf..6aa926a 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -2,42 +2,36 @@ 本项目的几种运行方式，按推荐程度排序。配置项详解见 [configuration.md](./configuration.md)。 -> 📌 前置依赖:Python ≥ 3.11 · Node ≥ 20 · [`uv`](https://docs.astral.sh/uv/) · `pnpm`（`npm i -g pnpm`） +> 📌 前置依赖(仅方式 D 需要):Python ≥ 3.11 · Node ≥ 20 · [`uv`](https://docs.astral.sh/uv/) · `pnpm`（`npm i -g pnpm`） --- -## 方式 A:Dev 模式(二次开发推荐) +## 方式 A:GHCR 现成镜像(免本地构建,多数用户推荐) -由于刚开源近期更新频繁,推荐开发模式运行,可随时 `git pull` 同步最新代码。 +GitHub Actions 每次推送都会自动构建多架构镜像(linux/amd64 · arm64)并发布到 GHCR,直接拉取运行,本地无需 Python / Node,也不用现场 build: ```bash -git clone https://github.com/shy3130/tick-stock-panel.git -cd tick-stock-panel -cp .env.example .env # 按需填 TICKFLOW_API_KEY(留空 = None 模式) -./dev.sh # Windows: .\dev.ps1 +docker run -d --name tsp -p 3018:3018 -v ${PWD}/data:/app/data ghcr.io/shy3130/tick-stock-panel:latest +# 打开 http://localhost:3018 ``` -`dev.sh` 自动检查 / 下载依赖、释放端口、同时起前后端,Ctrl-C 一并关闭。默认: +- 需要配置时:从 `.env.example` 复制出 `.env`,命令里加 `--env-file .env`。 +- 镜像默认**不含** stock-sdk 插件(合规考虑),也不含 `legacy-cpu` / `backtest` extras —— 老 CPU(无 AVX2)或需要 vectorbt 回测时,请用方式 B 通过 `BACKEND_EXTRAS` 自构建。 +- 跑自己改过的代码:fork 后到仓库 Actions 页启用 workflow(fork 默认禁用),构建出的 `ghcr.io/<你的用户名>/tick-stock-panel` 用法相同。 +- 想要 compose 全套挂载(`.env` / `tiers.yaml` / 数据卷):参考根目录 `docker-compose.yml`,把 `build:` 段换成 `image: ghcr.io/shy3130/tick-stock-panel:latest`。 -- 后端 → · 前端 → -- 自定义端口:`BACKEND_PORT=8000 FRONTEND_PORT=5173 ./dev.sh` - -### 手动分别启动(不想用 dev.sh) +更新到新版本: ```bash -# 后端 -cd backend && uv sync --extra backtest # 含回测依赖 -# 老 CPU: uv sync --extra legacy-cpu -# 老 CPU + 回测: uv sync --extra legacy-cpu --extra backtest -uv run uvicorn app.main:app --reload --port 3018 - -# 前端 -cd frontend && pnpm install && pnpm dev # http://localhost:3011 +docker pull ghcr.io/shy3130/tick-stock-panel:latest +docker rm -f tsp +# 重新执行上面的 docker run ``` --- -## 方式 B:Docker(部署最省心) + +## 方式 B:Docker Compose(本地构建,全套挂载) ```bash cp .env.example .env @@ -69,6 +63,44 @@ docker compose up --build -d --- +## 方式 C:本机 AI 代部署(小白推荐) + +装一个本机 AI 编程助手(Trae / Codex / OpenCode / ZCode / WorkBuddy 等,任选其一),把 [README · 快速开始](../README.md#-快速开始) 里方式 C 的提示词原样发给它,AI 会自动完成克隆、装依赖、启动服务。适合完全不想碰命令行的用户;AI 最终执行的仍是方式 A / B / D 之一。 + +--- + + +## 方式 D:Dev 模式(二次开发推荐) + +由于刚开源近期更新频繁,推荐开发模式运行,可随时 `git pull` 同步最新代码。 + +```bash +git clone https://github.com/shy3130/tick-stock-panel.git +cd tick-stock-panel +cp .env.example .env # 按需填 TICKFLOW_API_KEY(留空 = None 模式) +./dev.sh # Windows: .\dev.ps1 +``` + +`dev.sh` 自动检查 / 下载依赖、释放端口、同时起前后端,Ctrl-C 一并关闭。默认: + +- 后端 → · 前端 → +- 自定义端口:`BACKEND_PORT=8000 FRONTEND_PORT=5173 ./dev.sh` + +### 手动分别启动(不想用 dev.sh) + +```bash +# 后端 +cd backend && uv sync --extra backtest # 含回测依赖 +# 老 CPU: uv sync --extra legacy-cpu +# 老 CPU + 回测: uv sync --extra legacy-cpu --extra backtest +uv run uvicorn app.main:app --reload --port 3018 + +# 前端 +cd frontend && pnpm install && pnpm dev # http://localhost:3011 +``` + +--- + ## 老 CPU 兼容(avx2/fma 缺失) 如果运行时报 `avx2`/`fma` 缺失,或进程 `exit 132`,说明 CPU 不支持 AVX2 指令集(常见于老 VPS)。解决: @@ -91,12 +123,14 @@ vectorbt → numba 体积较大,作为可选 extras(`uv sync --extra backtest`) ## 更新代码(已部署用户必读) -拉取新版本只需一条命令: +拉取新版本只需一条命令(Dev / Compose 本地构建用户): ```bash git pull ``` +> 用方式 A 镜像直跑(无本地仓库)的用户:`docker pull ghcr.io/shy3130/tick-stock-panel:latest` 后删除旧容器重跑;compose 换 `image:` 的用户执行 `docker compose pull && docker compose up -d`。 + **整个 `data/` 目录都不纳入 git** —— 行情 K线、财务、自选、回测、监控记录,乃至概念/行业扩展数据,全部是程序运行时生成/拉取的用户数据,`git pull` 物理上无法影响它们。新用户首次启动时,概念/行业两份扩展数据会自动从远程接口拉取,无需任何手动操作。 > ⚠️ **切勿使用以下命令"解决冲突"或"清理",它们会一次性删光 `data/` 下所有未被 git 跟踪的数据:** diff --git a/操作说明书.md b/操作说明书.md index 6274298..cce35ae 100644 --- a/操作说明书.md +++ b/操作说明书.md @@ -62,6 +62,8 @@ TickFlow A 股智能量化工作台是一套本地优先的 A 股数据分析与 ## 2. 安装与启动 +零基础用户可以让本机 AI 编程助手代为部署（见项目 README「快速开始 · 方式 C」）；已装 Docker 的用户推荐直接拉取 GHCR 现成镜像（见 2.5），无需本地构建。 + ### 2.1 环境要求 开发模式建议准备： @@ -109,7 +111,19 @@ cp .env.example .env 默认访问地址与 macOS/Linux 开发模式一致。 -### 2.5 Docker 部署 +### 2.5 GHCR 镜像启动 + +已安装 Docker 的用户可以直接拉取 GitHub Actions 自动构建的现成镜像，无需克隆代码，也不用本地构建： + +```bash +docker run -d --name tsp -p 3018:3018 -v ${PWD}/data:/app/data ghcr.io/shy3130/tick-stock-panel:latest +``` + +启动完成后访问 `http://localhost:3018`。需要配置时，从 `.env.example` 复制出 `.env`，并在命令中追加 `--env-file .env`。 + +现成镜像默认不含 stock-sdk 插件和老 CPU 兼容内核；有这些需求时请改用 Docker 部署并按 [docs/deployment.md](./docs/deployment.md) 传入构建参数。 + +### 2.6 Docker 部署 在项目根目录执行： @@ -138,7 +152,7 @@ docker compose logs -f Docker 中的 `/app/data` 应映射到宿主机持久化目录。不要仅将数据保存在容器可写层，否则重新创建容器后可能丢失数据。 -### 2.6 停止系统 +### 2.7 停止系统 开发模式可在启动终端中按 `Ctrl+C` 停止。 @@ -1122,9 +1136,16 @@ data/strategies/ai/ ## 25. 更新与维护 -### 25.1 Docker 更新 +### 25.1 镜像与 Docker 更新 -更新前先备份，再执行： +GHCR 镜像启动的用户，备份 `data/` 目录后执行： + +```bash +docker pull ghcr.io/shy3130/tick-stock-panel:latest +docker rm -f tsp +``` + +然后按 2.5 重新执行 `docker run`。Docker Compose 用户更新前先备份，再执行： ```bash git pull