7.3 KiB
部署指南
本项目的几种运行方式，按推荐程度排序。配置项详解见 configuration.md。
📌 前置依赖:Python ≥ 3.11 · Node ≥ 20 ·
uv·pnpm（npm i -g pnpm）
方式 A:Dev 模式(二次开发推荐)
由于刚开源近期更新频繁,推荐开发模式运行,可随时 git pull 同步最新代码。
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
dev.sh 自动检查 / 下载依赖、释放端口、同时起前后端,Ctrl-C 一并关闭。默认:
- 后端 → http://localhost:3018 · 前端 → http://localhost:3011
- 自定义端口:
BACKEND_PORT=8000 FRONTEND_PORT=5173 ./dev.sh
手动分别启动(不想用 dev.sh)
# 后端
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
方式 B:Docker(部署最省心)
cp .env.example .env
docker compose up --build
# 打开 http://localhost:3018
Docker 采用两阶段构建,前端 dist 拷进后端镜像,单容器运行,数据完全在自己手里。
⚠️ stock-sdk 插件默认不打包(合规考虑)
stock-sdk 数据源本质是抓取第三方财经网站(如东方财富)的行情接口,未经对方授权,可能违反其服务条款并涉及交易所行情版权问题。出于合规考虑,Docker 默认构建不再内置 stock-sdk 插件依赖。
- 默认行为:
docker compose up --build构建出的镜像不含 stock-sdk,插件不可用。- 如确需启用(自行承担合规责任):
docker compose build --build-arg INCLUDE_STOCKSDK=1 docker compose up -d- 启用后镜像会额外内置 Node.js 运行时并预装 stock-sdk 依赖,插件开箱即用。
- 建议优先使用 TickFlow 等正规授权数据源。
更新到新版本:
git pull
docker compose up --build -d
老 CPU 兼容(avx2/fma 缺失)
如果运行时报 avx2/fma 缺失,或进程 exit 132,说明 CPU 不支持 AVX2 指令集(常见于老 VPS)。解决:
- Dev 源码启动:在根目录
.env设置后运行./dev.sh或 Windows 的.\dev.ps1;即使已有.venv,启动器也会同步兼容内核 - Docker:在根目录
.env设置后执行docker compose up --build
BACKEND_EXTRAS=legacy-cpu # 兼容老 CPU
BACKEND_EXTRAS=legacy-cpu backtest # 兼容老 CPU + 回测依赖
手动启动源码时，也可以在 backend/ 目录直接执行 uv sync --extra legacy-cpu。不要设置 POLARS_SKIP_CPU_CHECK，它只会隐藏警告，实际执行不支持的指令时仍可能崩溃。
回测依赖说明
vectorbt → numba 体积较大,作为可选 extras(uv sync --extra backtest)。macOS / Intel 无预构建 wheel 时需 brew install cmake 现场编译。
更新代码(已部署用户必读)
拉取新版本只需一条命令:
git pull
整个 data/ 目录都不纳入 git —— 行情 K线、财务、自选、回测、监控记录,乃至概念/行业扩展数据,全部是程序运行时生成/拉取的用户数据,git pull 物理上无法影响它们。新用户首次启动时,概念/行业两份扩展数据会自动从远程接口拉取,无需任何手动操作。
⚠️ 切勿使用以下命令"解决冲突"或"清理",它们会一次性删光
data/下所有未被 git 跟踪的数据:
git clean -fdx(最危险,会删掉所有.gitignore忽略的文件)git reset --hard- 直接删除整个项目文件夹重新
git clone若
git pull报冲突,通常是本地误改了被跟踪的文件,请先git stash暂存再 pull,或单独联系作者,不要直接执行上面的命令。
访问密码设置(公网部署必读)
面板部署在公网服务器时,首次设置访问密码有限制 —— 必须从本机或内网访问,以防公网上陌生人抢先设置密码锁死你的面板。
如果你在公网浏览器直接打开页面,会看到提示:
首次设置密码仅允许本机或内网访问,请通过 SSH/本地浏览器操作
有两种方式解决,任选其一。
方式一:环境变量预置密码(最简单,推荐)
在 .env 文件(或 Docker / 系统环境变量)里设置 AUTH_PASSWORD:
AUTH_PASSWORD=你的密码
然后重启服务。启动时会自动:
- 读取
AUTH_PASSWORD - 用 PBKDF2 哈希后写入
auth.json(chmod 600,只存哈希不存明文) - 之后这个环境变量就不再被读取 —— 是一次性的初始化
设完后即可用公网地址 + 这个密码正常登录。后续改密码请用页面 UI(设置 → 修改密码),不受环境变量影响。
注意事项:
- 密码至少 6 位,否则会被跳过并记一条 warning 日志
- 仅在未设过密码时生效。已设过密码后,改这里不会覆盖(避免重启时重置你在 UI 改的密码)
.env文件权限保持600,不要提交到 Git- 明文密码只存在于
.env/ 环境变量中,落盘的是哈希,安全性等同auth.json
重置密码(忘密码时): 删除或清空 data/user_data/auth.json,重启服务,会回到"未设密码"状态,此时 AUTH_PASSWORD 会重新生效。
rm data/user_data/auth.json # 停服后执行,清空后重启
方式二:SSH 端口转发
不用改配置,在你自己电脑的终端执行(不是服务器上):
ssh -L 3018:127.0.0.1:3018 用户名@服务器IP
例如服务器是 123.45.67.89、用户名 root、面板端口 3018:
ssh -L 3018:127.0.0.1:3018 root@123.45.67.89
保持这个 SSH 连接不要关,然后在自己电脑的浏览器打开 http://127.0.0.1:3018。此时后端看到的客户端 IP 是 127.0.0.1(本机),能通过校验,正常显示设置密码界面。
设完密码后,SSH 连接可以断开 —— 密码已存进服务器,之后直接用公网地址 + 刚设的密码访问即可。
如果用
PORT改过端口(比如PORT=8080),两处都要替换:ssh -L 8080:127.0.0.1:8080 root@IP。
两种方式怎么选
| 环境变量 | SSH 转发 | |
|---|---|---|
| 操作 | 改一行配置 + 重启 | 一条 ssh 命令 |
| 需要改配置 | 是 | 否 |
| 适合 | Docker / 自动化部署 / 不熟 SSH | 临时设密码 / 能 SSH 到服务器 |
| 后续改密码 | UI(设置 → 修改密码) |
同左 |
推荐方式一(环境变量),一次配置即可,Docker 部署尤其方便。
原理说明
- 为什么限制本机/内网? 面板部署到公网后,任何人都能访问 URL。如果不限制,攻击者可以在你之前打开页面、设置一个密码,把你的面板锁死。
- 本机/内网如何判断? 后端检查客户端 IP 是否属于
127.0.0.1 / ::1 / 10.x / 192.168.x / 172.16-31.x。 - SSH 转发为什么有效?
-L把本机端口通过 SSH 隧道转发到服务器的127.0.0.1,等同于在服务器本地访问,客户端 IP 变成127.0.0.1,通过校验。 - 反向代理注意: 若面板在 Nginx 等反代之后,需正确配置
X-Forwarded-For头,后端据此取真实客户端 IP。