VN-Freq 在本仓库内集成 Freqtrade 与预构建的 FreqUI 静态资源，目标场景为 币安 USDT-M 黄金永续（如 XAU/USDT:USDT 或 PAXG/USDT:USDT）的量化交易与 Web 监控。
- 交易引擎：Freqtrade 2026.2（本地源码
freqtrade-2026.2/，可编辑安装）。 - 控制台：FreqUI（
freqUI/），需复制到 Freqtrade 的ui/installed后由内置 API 提供页面（见下文）。 - 交易所：币安合约；
trading_mode: futures，margin_mode: isolated（与 Freqtrade 对币安期货的要求一致）。
- 操作系统：macOS / Linux / Windows
- Miniconda 或 Anaconda
- Python 3.11+（与
freqtrade-2026.2/pyproject.toml中requires-python一致）
需已安装 Miniconda / Anaconda，且 conda 可在终端中使用（macOS/Linux 若提示找不到 conda，请按安装程序说明执行 conda init 后重开终端；Windows 若双击脚本提示找不到 conda，请使用 Anaconda Prompt 或在「开始菜单」里选用已配置好 PATH 的终端）。
| 系统 | 脚本 | 作用 |
|---|---|---|
| macOS / Linux | setup_env.sh |
创建 Conda 环境 vn_freq（Python 3.11）、pip install -r requirements.txt、执行 freqtrade create-userdir、将 freqUI/ 同步到 freqtrade-2026.2/.../ui/installed/ |
| Debian / Ubuntu | setup_debian.sh |
先通过 apt 安装系统依赖；若无 Conda 自动安装 Miniconda；然后创建环境、安装依赖、初始化 user_data、同步 FreqUI |
| Windows | setup_env.cmd |
同上（使用 robocopy 同步 FreqUI） |
# macOS / Linux
chmod +x setup_env.sh start_bot.sh # 首次克隆后
./setup_env.shREM Windows（在仓库根目录）
setup_env.cmd# Debian / Ubuntu（在仓库根目录）
chmod +x setup_debian.sh start_bot_debian.sh
./setup_debian.sh可选环境变量（两脚本一致）：
| 变量 | 默认 | 说明 |
|---|---|---|
VN_FREQ_CONDA_ENV |
vn_freq |
Conda 环境名 |
VN_FREQ_PYTHON |
3.11 |
仅创建新环境时使用 |
VN_FREQ_SKIP_UI |
未设置 | 设为 1 时跳过复制 FreqUI |
VN_FREQ_INSTALL_RL |
未设置 | 设为 1 且存在 rl_agent/requirements-rl.txt 时，额外安装 RL 训练依赖（仍装在同一环境中） |
若已存在 user_data/config.json 等文件，create-userdir 会补全子目录；不会自动覆盖你改过的配置。本仓库已附带一份可用的 user_data/config.json（dry_run、黄金对白名单、api_server）。
若未使用 setup_env.sh / setup_env.cmd，可在仓库根目录执行：
conda create -n vn_freq python=3.11 -y
conda activate vn_freq
pip install -r requirements.txt说明：requirements.txt 使用可编辑安装 -e ./freqtrade-2026.2，会安装 Freqtrade 及其 pyproject.toml 中的全部运行时依赖。根目录 requirements.txt 另对 Starlette / FastAPI 做了上限约束（避免 Starlette 1.x 与当前 Freqtrade ApiServer 的启动钩子不兼容）；升级依赖时若遇 add_event_handler 相关报错，请先检查这两库版本。
历史数据：币安 XAU/USDT:USDT 永续 K 线在交易所侧约从 2025-12-11 起可用；download-data 的 --timerange 需落在该日期之后，否则无 5m K 线可下。
可选组件（按需）：
conda activate vn_freq
pip install -e "./freqtrade-2026.2[plot]"- 与主项目共用同一 Conda 环境
vn_freq，不要为 RL 再建vn_freq_rl等第二个环境。 - 切换环境：在终端执行
conda activate vn_freq；退出当前环境可用conda deactivate。 - 安装 RL 额外依赖（仍在已激活的
vn_freq内）：pip install -r rl_agent/requirements-rl.txt（该文件未并入根目录requirements.txt，以避免与 Starlette 钉选冲突）。 - 训练与观测说明见
rl_agent/README.md；设计见docs/RL_AGENT_MODULE_PLAN.md。 - Freqtrade + RL 网页控制台 + 网页训练一条命令：在仓库根执行
./start_rl_stack.sh（后台守护用./start_rl_daemon.sh）。控制台默认http://127.0.0.1:8765/（可改VN_FREQ_DASH_PORT）；网页可改control.json、编辑训练 YAML、触发训练；同一脚本会启动freqtrade trade并为其设置PYTHONPATH，以便RlSarStrategy加载rl_agent。 - 若使用
setup_env.sh、setup_debian.sh或 Windows 的setup_env.cmd，可设置VN_FREQ_INSTALL_RL=1在安装主依赖后自动安装rl_agent/requirements-rl.txt（环境变量说明见 0. 一键配置环境 中的表格）。未设置该变量时，可在 Anaconda Prompt 中conda activate vn_freq后手动执行pip install -r rl_agent/requirements-rl.txt。
若未跑过配置脚本：
conda activate vn_freq
freqtrade create-userdir --userdir ./user_data在 user_data/config.json 中配置（本仓库默认已切到 SarStrategy）：
trading_mode:futuresmargin_mode:isolatedexchange.pair_whitelist: 例如["XAU/USDT:USDT"]或["PAXG/USDT:USDT"]api_server.enabled:true（用于 FreqUI 与 REST API）- 开发阶段建议
dry_run:true
SarStrategy 逻辑（user_data/strategies/SarStrategy.py）：
- 价格向上穿越 SAR 且高于 EMA200：开多
- 价格向下穿越 SAR 且低于 EMA200：开空
- 出现反向 SAR 穿越：平仓
将币安 API Key / Secret 写入配置或使用环境变量（勿提交密钥到 Git）。
若未使用 setup_env：将本仓库 freqUI/ 下的静态文件（含 index.html、assets/ 等）复制到：
freqtrade-2026.2/freqtrade/rpc/api_server/ui/installed/
复制后，启动机器人即可通过 api_server 所绑定的地址访问 Web 界面。
conda activate vn_freq
freqtrade download-data --config user_data/config.json --pairs XAU/USDT:USDT --timeframes 5m --timerange 20251211-
freqtrade backtesting --config user_data/config.json --strategy SampleStrategy --timerange 20251211-conda activate vn_freq
freqtrade trade -c user_data/config.json或使用仓库根目录的一键脚本（依赖 conda 在 PATH 中，默认环境名 vn_freq）：
- macOS / Linux：
./start_bot.sh - Windows：
start_bot.cmd（可在资源管理器中双击，或在「Anaconda Prompt」/cmd中运行）
可通过环境变量覆盖：VN_FREQ_CONDA_ENV（默认 vn_freq）、VN_FREQ_CONFIG（默认 user_data/config.json）。
无需事先执行 conda activate：脚本使用 conda run -n vn_freq 直接调用已安装好的环境。
启动方式建议：
chmod +x start_bot.sh # 仅首次
./start_bot.sh也可使用 bash start_bot.sh 或 sh start_bot.sh（脚本已用 POSIX sh 兼容写法，并会用 $0 正确定位仓库目录）。
若终端里几秒没有新输出：多为 Conda 首次解析环境或正在连接交易所；请稍等。若超过 1～2 分钟仍无任何输出，请确认本机已安装 Conda，且终端能直接运行 conda --version；若只有「Anaconda Prompt」里能用 conda，请在该类终端中运行脚本，或按安装说明执行一次 conda init zsh 后重开终端。脚本也会尝试自动 source 常见路径下的 conda.sh（如 ~/miniforge3/...）。
浏览器访问配置中的 listen_ip_address 与 listen_port（默认常见为 http://127.0.0.1:8080），使用 api_server 中的用户名与密码登录。可先访问 GET /api/v1/ping（无需登录）确认服务已启动。
另外已提供 SAR 专用监控页面：
http://127.0.0.1:8080/sar-monitor.html- 登录后每 5 秒轮询：
/show_config、/count、/profit、/status、/trades，以及/pair_candles（与机器人当前策略一致的已分析 K 线，含sar与开平仓信号列） - 图表：蜡烛图 + SAR 折线；在对应 K 线上用箭头/圆点标注 开多、开空、平多、平空（来自策略 DataFrame 信号）
- 模拟挂单价位线：对当前持仓绘制 开仓价、止损价，以及未成交订单的
safe_price限价（来自/status里每笔orders；限价单在 dry_run/实盘均可能出现在订单列表中） - 需 先运行
freqtrade trade，否则/pair_candles无分析数据；图表脚本依赖 unpkg CDN 加载 Lightweight Charts，离线环境需自备脚本地址
| 路径 | 说明 |
|---|---|
freqtrade-2026.2/ |
Freqtrade 源码 |
freqUI/ |
FreqUI 前端构建产物 |
user_data/ |
策略、config.json、K 线数据（data/binance/）等 |
requirements.txt |
通过 -e 安装本地 Freqtrade |
setup_env.sh / setup_env.cmd |
一键创建 Conda 环境、安装依赖、初始化 user_data、同步 FreqUI |
setup_debian.sh |
Debian/Ubuntu 一键安装（含 apt + Miniconda 自动安装） |
start_bot.sh / start_bot.cmd |
一键启动 freqtrade trade（默认读取 user_data/config.json）；已设置 PYTHONPATH 为仓库根，便于 RlSarStrategy 加载 rl_agent |
start_bot_debian.sh |
Debian/Ubuntu 一键启动（同上含 PYTHONPATH） |
start_rl_stack.sh / start_rl.sh |
推荐（RL 全流程）：同一终端先后台起 RL 网页控制台（默认 http://127.0.0.1:8765/），再前台起 freqtrade trade；网页内可点「开始训练」；脚本为 Freqtrade 进程设置 PYTHONPATH |
start_rl_daemon.sh |
将上述栈以后台方式启动（日志 .runtime/dual_stack.log，停止见 stop_rl_daemon.sh） |
scripts/load_conda.sh |
供脚本 source：在未把 conda 加入 PATH 时尝试加载常见 conda.sh |
- 合约与杠杆有强平与资金费率风险；请从小仓位、
dry_run与充分回测开始。 - 币安账户需开通合约权限；API 权限与 IP 白名单请自行在交易所侧配置。
此前 readme 中规划的 VN.py + FastAPI 伪装 Freqtrade API 路线已不作为当前默认路径；若仍需要 MT5 / VeighNa，请在单独 Conda 环境中安装 VN.py 相关依赖，避免与 Freqtrade 的 Python 版本和包冲突。