文档 / 快速开始

快速开始

目标：在一台干净的 Windows 机器上把宿主跑起来，并看到第一个可用页面。全程不需要注册账号。

先明确一件事：OpenStock 不含任何行情数据。装完之后你看到的每个页面，数据都来自你自己配置的数据源（公开网页接口 / 掘金终端 / tushare 等）。没配数据源不影响宿主启动，只是相关插件没数。

前置条件

项	要求
系统	Windows 10 / 11（宿主与启动脚本按 Windows 设计）
Python（仅源码方式需要）	3.11 以上，推荐 3.12 / 3.13。用便携包则完全不用装 —— 包内已内置 Python 3.13 与全部依赖
掘金客户端（可选 · 数据源）	要用 gm 组插件时：去 myquant.cn 下载客户端 → 安装 → 登录并保持运行 → 在客户端里新建/注册一个策略 id（下面第 4 步要用）

先分清"依赖"和"数据源"：依赖（Python / fastapi / pandas / gm SDK / tushare）便携包已全部内置，解压即用；客户端与账号属于数据源，必须你自己装、自己登录。本项目不含任何数据，也不提供任何凭证。

1 · 拿到软件（两种方式）

方式 A（推荐）· 便携包：去下载页取 openstock-0.1.0-portable.zip（约 55 MB），解压到任意目录即可。 已内置 Python 3.13 与全部依赖（含 gm SDK、tushare），机器上不用装 Python、也不要用 pip。

方式 B · 源码：适合想改代码、或本来就有 Python 环境的人：

git clone https://gitee.com/alex6168/openstock.git
cd openstock

没有 git 就去仓库页下 ZIP 解压，效果一样。

2 · 装依赖（仅源码方式需要）

用便携包的话跳到第 3 步 —— 包里已经有这些，什么都不用装。

源码方式下依赖分三层，核心层不装宿主根本起不来。

层	包	覆盖范围
核心（必装）	`fastapi uvicorn httpx requests`	宿主本体 + 东财直连类插件
数据层（按需）	`pandas numpy openpyxl`	全市场统计 / 估值分位 / 资金流类插件
可选层	`gm`（掘金 SDK）、`tushare`	gm 组插件、研报盈利预测（仍需自备客户端与账号）

pip install fastapi uvicorn httpx requests
pip install pandas numpy openpyxl
pip install gm tushare          # 可选层

requirements-core.txt / requirements-data.txt / requirements-optional.txt 三件套仍在开发中，源码方式当前请直接用上面的命令。进度见下载页。

3 · 启动宿主

启动（便携包）
```
双击 setup.bat     :: 自检运行时是否完整，幂等，可重复跑
双击 start.bat     :: 启动宿主，约 4 秒后自动打开浏览器
```
setup.bat 正常就是这两行 +「请按任意键继续」：
[setup] python 3.13.15
[setup] done. Double-click start.bat to launch.
若出现 MISSING ... 说明包不完整（缺内置运行时或站点包），重新下载即可。

启动（源码方式）

python main\launcher\app.py
:: 或双击 main\start-launcher.bat（会顺带拉起 8771 竞价价源窗口）

打开页面

浏览器访问 http://127.0.0.1:8080/，默认落在「插件中心」——它是唯一首页，列出所有已发现的插件。
确认状态
```
http://127.0.0.1:8080/api/health
```
返回当前解释器路径、插件目录、已被托管的常驻脚本列表（daemon）等，排查问题先看它。便携包用户的 python 字段应指向 ...\winPython\python.exe —— 这证明宿主与插件都在用包内自带的运行时。

关于 main\start-launcher.bat（源码方式）：该脚本第 8 行仍写死了开发者的本机 python 路径，找不到时会回落到 PATH 里的 python（所以多数机器仍可用）；要更稳就直接 python main\launcher\app.py。端口变更只需改 main/launcher/app.py 的 DEFAULT_PORT。便携包的 start.bat 不受此影响。

4 · 配置数据源（按需）

数据源	用在哪	怎么配
掘金 GM	核心行情、财务、估值分位（gm 组多数插件）	① 到 myquant.cn 下载并安装掘金客户端，登录后保持运行； ② 在客户端里新建一个策略，拿到策略 id与登录 token； ③ 把 `main/config/myquant.env.example` 复制成 `myquant.env`，填入 `MYQUANT_STRATEGY_ID`（必须与客户端里的完全一致，否则连不上）和 `MYQUANT_TOKEN`。 gm SDK 便携包已内置，无需再 pip 安装；没装客户端/没填凭证时，gm 组插件只是拿不到数据，不会影响其它插件。
tushare	研报盈利预测（report_rc）、口径校验	在 `main/config/tushare.env` 填 `TUSHARE_TOKEN`（积分制）。注意其条款禁止商用与再分发。
公开网页接口	东财（板块 / 资金流 / 人气 / 暗盘）、FT 海外指数	无需配置，开箱可用。但它们是非官方接口，可能随时变更或限流，请勿高频请求。
交易日历	交易日判定（全站共用）	仓库自带（`database/tudata/`），无需配置。

凭证只存在你本机。main/config/myquant.env 已被 .gitignore 忽略，不要把自己的 token 提交进任何仓库；如果你 fork 了项目，也请确认这类文件没有被跟踪。

目录结构速览

openstock/
├─ winPython/              便携包内置 Python 3.13 + 全部依赖（源码方式没有这个目录）
├─ main/
│  ├─ launcher/app.py      宿主薄壳（端口 8080）
│  ├─ shared/              页面共享件（快捷侧栏 / 行情侧栏 / 板块侧栏 / 主题）
│  └─ config/              数据源凭证（env 文件，不入库）
├─ extension/              插件目录
│  └─ gm/…                 掘金数据源的一组插件
├─ database/<插件>/        个人数据（不入库；新机器首访自动播种）
├─ setup.bat / start.bat   便携包的启动入口
└─ site/                   本官网（纯静态，与宿主运行无关）

日常使用要点

改了页面文件不用重启

宿主对 .html / .js / .css / .json 一律发 no-store，刷新即生效。但改了 main/launcher/app.py 必须重启宿主。

插件名与排序

插件显示名默认等于目录名，可在「插件中心 → 管理」里覆写，改完全站生效。分组与顺序写在 database/插件中心/ 下，属于个人配置。

常驻脚本

extension/<插件>/script/daemon.py 会被宿主自动拉起并监督（异常指数退避重启、退出统一回收）。要停掉或删除，记得连它的进程一起清，否则会留下孤儿进程。

别并发狂打取数接口

取数是「一次请求起一个 Python 子进程」的模型，多个请求同时跑会互相拖慢（尤其是连本地行情终端的插件）。页面里的轮询已做自调度，改代码时也请沿用。

常见问题

setup.bat 报 MISSING ... / 退出码 1

说明包内运行时被破坏了（多半是解压不完整，或被安全软件删了文件）。对照报错看： MISSING winPython\Lib\site-packages\sitecustomize.py → 站点包缺失； MISSING "import site" in winPython\python313._pth → 解释器初始化被改坏。这两种都会让所有插件请求变成 502。别自己修，重新解压或重新下载一次包最快。

便携包想补装 / 升级某个 Python 包

必须用包内那个解释器，别敲系统的 pip（那会装到别的环境里，页面还是找不到）：

winPython\python.exe -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <包名>

例如补可选层：winPython\python.exe -m pip install gm tushare。想确认包到底装进哪个环境，看 http://127.0.0.1:8080/api/health 的 python 字段。

启动报端口被占用 / 打不开页面

宿主默认 8080。先确认是不是已经起了一个实例： netstat -ano | findstr ":8080 " | findstr LISTENING。有的话直接访问即可，不要重复启动；确实要换端口就改 main/launcher/app.py 的 DEFAULT_PORT 后重启。

取数接口返回 502

含义是「取数子进程非 0 退出」，常见原因是缺包（如 No module named 'pandas'）或脚本自身报错。响应里会带上 stderr 摘要，照它装包或修脚本即可。宿主本身能起来 ≠ 依赖装齐了。 便携包用户装包请用 winPython\python.exe -m pip install ...（见上一条）。

插件请求 404，但页面看起来"什么都没发生"

先看请求 URL 里的 script= 是不是空的 —— 取数地址必须是 /api/plugin/run?plugin=<插件>&script=<脚本名>，只写到 ...&script= 就会 404。

点「获取数据」进度条走完，但页面数据一直是旧的

典型原因是生成脚本的落盘路径 ≠ 页面读取路径（两边指向不同文件），日志全绿但页面永远读旧文件。排查方法：分别打印两边的绝对路径比对；目录层级写死（parents[N]）的脚本在分组布局下最容易出这个问题。

gm 组插件没数据 / 集合竞价涨幅恒为 +0.00%

先确认掘金终端在运行、myquant.env 里的策略 id 与终端一致。竞价时段（09:15–09:24）行情源本身不给成交价，项目有一个独立的竞价价源进程（127.0.0.1:8771）来补价；它没起来时页面会静默退化成普通价，看起来就是涨幅 +0.00%。查 http://127.0.0.1:8771/tick/health 是否可达。

改了 .bat 之后执行报错

Windows cmd 按 GBK 读取批处理文件，含中文注释/中文 echo 会出错 —— 批处理文件请保持纯 ASCII。