快速开始 · Windows / Docker
在 Windows 上把 tick-stock-panel 跑起来：四条路径选一条就够
官方把部署分成镜像直跑、本地构建、AI 代部署与 Dev 模式四条路径。本页把它们并列说清前置与限制，并把 Windows 与国内网络环境下最常见的几个坑单独列成现象→原因→命令的排查表。
tick-stock-panel 的四条部署路径，各自前置是什么？
先确认自己的环境属于哪一种（有没有 Docker、有没有老 CPU、要不要改代码），再比这张表，一般 30 秒内就能定下来。
| 路径 | 适合谁 | 具体做法（官方口径） | 前置与局限 |
|---|---|---|---|
| A · GHCR 现成镜像（推荐） | 只想尽快看到界面的大多数人 | docker run -d --name tsp -p 3018:3018 -v ${PWD}/data:/app/data ghcr.io/shy3130/tick-stock-panel:latest | 镜像不含 stock-sdk，也不含 legacy-cpu / backtest extras |
| B · Compose 本地构建 | 改过代码、需要 extras、想全套挂载 | git clone 后在项目根执行 docker compose up -d --build | 需 Docker；首次构建耗时较长，国内网络靠镜像源兼容 |
| C · 本机 AI 代部署 | 不想碰命令行，但不介意让 AI 在本机操作 | 将仓库交给任一 AI 编程助手，让它按官方文档完成部署 | 它最终仍执行 A / B / D 之一，不构成第四种技术路径 |
| D · Dev 模式 | 二次开发与调试 | Windows 执行 dev.ps1，Linux / macOS 执行 dev.sh | Python ≥ 3.11、Node ≥ 20、uv、pnpm；前后端分列两个端口 |
legacy-cpu extra。这类情况必须走路径 B 自己构建，并在构建前把 extra 配好。逐条路径具体怎么操作？命令在哪里执行？
下面把官方文档里散在不同小节的步骤合成一条线，重点标出容易忽略的执行位置与参数。
B-1 拉代码并进入项目根
tick-stock-panel 的 Compose 文件在仓库根目录，不在子目录里，所以命令必须在根目录执行。
B-2 准备 .env
从 .env.example 复制一份 .env。最小可跑配置可以只留空白值（None 模式）；但 DATA_DIR 、PORT 这类基础项建议确认一遍。
B-3 构建并启动
docker compose up -d --build。Compose 会把 DATA_DIR 强制写为 /app/data，避免 .env 里开发用的 ./data 被原样带进容器。
B-4 确认端口与挂载
默认对宿主开 3018，容器内数据目录是 /app/data。先用 docker compose ps 看容器状态，再看日志里是否出现盘后管道的调度日志。
D-1 Windows 跑 dev.ps1
脚本会自动检查依赖、释放端口、前后端一同启动，Ctrl-C 时一并关闭。前端默认 3011，后端 3018。
D-2 改端口
可用 BACKEND_PORT 与 FRONTEND_PORT 覆盖。dev 模式下前端与后端分列两个端口，与单容器模式不同。
C 路径的实质
让 AI 代部署时，建议把官方 docs/deployment.md 一并交给它，并要求它先读完再执行；否则它很可能自己发明一套没有依据的步骤。
CONTRIBUTING.md 与 AGENTS.md 都强调「分清已实现能力与目标契约，不得据设计示例虚构尚不存在的 API」。这条纪律对「让 AI 代部署」同样适用：要求它只做官方写明的事，遇到未写明的就停下来问你。Windows 与国内网络环境，最容易卡在哪里？
这是中文用户最容易反复搞错的一段。下表每一行都对应官方文档或配置里的具体设定。
| 现象 | 原因 | 处理 |
|---|---|---|
| 拉镜像很慢或失败 | 默认从 GHCR / 官方源拉取，国内网络不稳定 | 本地构建时 Dockerfile 默认 USE_CN_MIRROR=1：npm 走 npmmirror、PyPI 走清华主源 + 阿里云备用；构建时可显式传 --build-arg USE_CN_MIRROR=0 关掉 |
| Windows 下容器启动后读不到 Codex 登录态 | 纯 PowerShell / CMD 环境下 HOME 常未设置，Compose 的 ${HOME}/.codex 解析失败 | 在 .env 里显式设 CODEX_HOME_HOST 指向真实路径（官方 README 与 docker-compose.yml 都有注明） |
容器内 uv run 卡死启动 | Dockerfile 里 ENV UV_DEFAULT_INDEX 没有跳过构建阶段，容器内重新解析时回落到官方源 | 官方已在 Dockerfile 里用 ENV 持久化镜像源；如你自己改过 Dockerfile，务必保留这一行 |
| 目录挂载后数据不见了 | 把宿主目录挂到了错误的容器路径，或没挂载 | 统一挂到 /app/data（Compose 已强制）；自己写 docker run 时注意 -v 左右两边 |
| 端口被占 | 3018 或 3011 已被其他服务占用 | Compose 下改端口映射；Dev 模式用 BACKEND_PORT / FRONTEND_PORT 覆盖（脚本会尝试释放端口） |
| 宿主上没有任何 API Key | 这不是错误 | None 模式下仍可拉历史日 K、跑选股与回测；只是实时、分钟与财务相关页面会给提示 |
老 CPU 上跑不起来：tick-stock-panel 对 CPU 有什么要求？
这一节只说一件事：当你的 CPU 缺 AVX2 / FMA 时，该怎么改构建参数。
| 情形 | 官方行为 | 你该怎么办 |
|---|---|---|
启动日志报 avx2 / fma 缺失 | 进程可能直接退出，退出码 132 | 构建时加 BACKEND_EXTRAS=legacy-cpu |
| 老 CPU 上还想跑回测 | extra 需要同时带上回测依赖 | 参数写成 legacy-cpu backtest |
想用 POLARS_SKIP_CPU_CHECK 绕过 | 官方明确反对 | 它只隐藏警告，实际运行仍可能崩；请老老实实用 legacy-cpu |
| 用的是 GHCR 现成镜像 | 镜像里没有 legacy-cpu / backtest extras | 必须改走路径 B 自构建，无法靠现成镜像解决 |
| 想在 ARM 设备（如 Apple Silicon / ARM 服务器）上跑 | CI 发布包含 linux/amd64 与 linux/arm64 | 一般可直接拉；遇到某个 extra 在 ARM 上缺 wheel 时再改走 B 自构建 |
访问密码和公网部署：有什么特殊设定？
tick-stock-panel 在这里做了一个不太常见的限制，知道它就不会白折腾半天。
首次设置访问密码只能在本机或内网做
后端会校验来源地址：127.0.0.1、::1、10.x、192.168.x、172.16-31.x。这是为了防止公网上的人抢先把你的实例锁死。
公网部署用 AUTH_PASSWORD 预置
在 .env 里设 AUTH_PASSWORD（至少 6 位），启动时自动生成 PBKDF2 哈希并写入 data/user_data/auth.json。注意它仅首次生效，后续改 .env 不会覆盖已生成的哈希。
忘了密码怎么重置
删除 data/user_data/auth.json 后重启，就回到「本次还没设密码」的初始状态。
反向代理后面要传对头
官方文档提到反代场景需正确传递 X-Forwarded-For，否则内网判定会失效（看起来像公网访问，于是拒绝设密码）。
密码与数据都在 data/ 里
这意味着你的备份策略只需要针对一个目录；也意味着删掉这个目录就等于恢复出厂设置。
装完之后，第一次使用的正确顺序是什么？
官方把它写成六步。本节额外补上「每一步该看到什么」。
第一步 · 设置
先设访问密码（若未设）与基础选项。盘后管道的触发时间默认 15:35 CST，可调。
第二步 · 凭据与能力 重新检测
这一步决定后续哪些页面可用：没配 Key 时会标为 None 模式，只有历史日 K 能用。这里也是第一个应该回头检查的地方。
第三步 · 立即跑盘后管道
拉日 K → 重算 enriched。首次拉取量比较大，耗时取决于股票池与档位限频。
第四步 · 自选加标的
先加几只你熟悉的标的，用来验证口径：看指标值是不是和你从别处看到的一致。
第五步 · 选股扫描
选一个内置策略扫全 A 股，看结果数量与标的分布是否合理。零命中时不要马上改策略，先回头检查第二步的能力与股票池。
第六步 · 回测验证与监控
拿刚才的结果跑一次回测，再到监控中心配一条规则，用来确认推送渠道能不能收到消息。
怎么更新代码？为什么官方反复强调数据目录？
这是自托管项目最容易出事的环节：一条习惯性的 git 命令就可能删光你的数据。
先明白 data/ 不进 git
tick-stock-panel 的 data/ 整个目录不在版本控制里，它里面有你拉下来的行情、策略、信号、设置与密码哈希。
升级用 git pull
本地构建的路径是 git pull 后重新 docker compose up --build -d；直跑镜像的路径则是重新 pull 并重建容器。
三条绝对不要做的事
官方在部署文档里直接列了三个禁区：git clean -fdx、git reset --hard、以及删掉整个项目目录重新 clone。它们会一次删光未被跟踪的数据。
想清空重来怎么办
如果确实想重来，应该是「先备份 data/，再手动删除具体子目录」，而不是整目录清空。
备份的边界
因为所有状态都在 data/，备份这一个目录就等于备份整个实例；但它会持续增长，分钟级数据尤其占空间。
tick-stock-panel 部署后上不了手，应该按什么顺序排查？
比起“报什么错”，更重要的是排查顺序：先排环境，再排数据，最后才怀疑策略。
| 现象 | 最常见的原因 | 处理顺序 |
|---|---|---|
| 打开页面弹出设置访问密码 | 初次使用，或 auth.json 被删 | 在本机 / 内网设置；公网环境先用 AUTH_PASSWORD |
| 能力列表里缺了你以为买到的能力 | Key 没生效、（企）业端点选错、或档位未在服务器侧生效 | 重新检测 → 看官方档位表对照 → 再看能力路由页的档位归属表 |
| 盘后管道跑完但选股为空 | 股票池口径不对，或策略条件过严，或时间窗口不足 | 先看日 K 最新交易日 → 再换一个宽松策略 → 最后才怀疑策略逻辑 |
| 容器日志里看不到盘后调度 | 启动时间早于交易日判定，或非交易日 | 非交易日不会跑；交易日默认 15:35 CST 触发 |
| 面板能开但数据空白 | 目录挂载错误或权限不足 | 先看容器内 /app/data 是否有内容 → 再看宿主对应目录 |
| 安装完想回退版本 | 升级后发现不适合自己的用法 | 因为数据在 data/ 不受版本影响，可以切回旧 tag / 镜像标签后重建 |
tick-stock-panel 部署与首次运行常见问题
以下答案基于官方仓库与文档的核验结果；涉及版本、数据源口径与许可条款的内容一律以官方仓库与官方文档为准。没有 Docker 能不能用 tick-stock-panel？
可以走 Dev 模式，但前提更高：Python ≥ 3.11、Node ≥ 20，还需 uv 与 pnpm。一般用户仍然建议用 Docker：一条命令就能起来，环境问题也少。官方把 Dev 模式定位为二次开发而不是日常使用。
Windows 上能不能跑？有什么特殊條件？
能跑，且官方为 Windows 单独准备了 dev.ps1 与安装步骤。最典型的 Windows 坑是纯 PowerShell / CMD 环境下 HOME 未设置，导致 Compose 里 ${HOME}/.codex 这类挂载路径解析失败；解法是在 .env 里显式设 CODEX_HOME_HOST。另外 Windows 下中文路径与盘符在挂载时容易出问题，建议用英文路径。
内网机器拉不动镜像怎么办？
官方已经在构建链路里做了镜像源兼容：默认 USE_CN_MIRROR=1，npm 用 npmmirror、PyPI 用清华主源并以阿里云为备用、apt 也换阿里云。它甚至把镜像索引写进 ENV UV_DEFAULT_INDEX——因为实测发现不这样做，容器内 uv run 重新解析时会回到官方源并卡死启动。
我的机器很老，启动直接退出怎么办？
大概率是 CPU 缺 AVX2 / FMA。官方文档写明这种情况会报相关字段缺失或直接以退出码 132 退出。解法是自己构建时加 BACKEND_EXTRAS=legacy-cpu，需要回测就写 legacy-cpu backtest。不要用 POLARS_SKIP_CPU_CHECK 绕过：它只是把警告藏起来，实际运行时该崩还是会崩。
安装会不会把我的数据弄丢？
不会——前提是你不要去执行官方明令禁止的命令。整个 data/ 目录不入 git，官方在部署文档里特别提醒三个禁区：git clean -fdx、git reset --hard、以及删掉整个项目目录重新 clone。Compose 还把 DATA_DIR 强制写成 /app/data，就是为了防止你把开发用的相对路径带进容器。
更新新版本要重新配置吗？
不用。因为配置与数据都在 data/，升级只替换应用代码与容器镜像。不过建议在升级前先备份这个目录；且因为项目更新频繁，最好先看一眼官方仓库 VERSION 与最近提交说明，再决定是否要跑这一版。
我不想自己搞这些，有更省事的选择吗？
有，但它解决的是另一类问题。如果你只想快速得到一个研究结论（某只标的的指标、某个板块的筛选），本机免部署技能路线更合适；但它不提供自托管的数据库、不能自定义策略文件、也不做回测可信度审计。两条路线各适合不同任务，本站对比页列了逐项差异，并写明两者无已证实集成。