第 10 章 · 02 FreqUI 与 REST API

第 10 章 · 02 FreqUI 与 REST API

本节摘要:除了 Telegram，freqtrade 还提供两套更强的控制方式:FreqUI 是内置的 Web 界面(可视化交易、图表、回测、多 bot 仪表盘)，REST API 是底层的编程化接口(可用 curl 或 freqtrade-client 调用)。两者都依赖 api_server 配置块。本节讲清三件事:FregUI 怎么装、看什么(交易视图、仪表盘、钱包余额、回测视图、webserver 模式)；REST API 怎么配(含安全要点:别暴露公网、强密码、JWT)；WebSocket 消息端点怎么用于实时数据订阅(也是上一章 producer-consumer 的基础)。读完你能用浏览器和代码全方位操控 bot。

内容来源:原项目文档 docs/freq-ui.md、docs/rest-api.md，汉化并套用体系化模板。

⚠️ 风险提示:REST API 默认只监听 localhost，千万别改成 0.0.0.0 暴露公网，否则别人能控制你的 bot 下单。远程访问请用 SSH 隧道或 VPN。

学习目标

阅读完本节，你应当能够:

1. 用 install-ui 安装/更新 FreqUI。
2. 配置 api_server 块(含安全项)。
3. 使用 FreqUI 的交易视图、仪表盘、回测等功能。
4. 调用常用 REST 端点(/status、/profit、/forceexit)。
5. 用 WebSocket 订阅实时消息。

一、FreqUI:安装与配置

FreqUI 是 freqtrade 的官方前端(独立项目 freqtrade/frequi)。安装方式:

• 默认安装(脚本/Docker)会自动带上 FreqUI。
• 手动安装或更新:freqtrade install-ui。

启动 freqtrade trade 后(配好 api_server)，浏览器访问 http://127.0.0.1:8080 即可。FreqUI 是可选组件——不装它 freqtrade 照常跑，只是少了可视化。

FreqUI 不需要单独的配置文件，它依赖 REST API 的 api_server 配置。所以第一步是配 api_server:

"api_server": {
    "enabled": true,
    "listen_ip_address": "127.0.0.1",
    "listen_port": 8080,
    "verbosity": "error",
    "enable_openapi": false,
    "jwt_secret_key": "somethingRandomSomethingRandom123",
    "CORS_origins": [],
    "username": "Freqtrader",
    "password": "SuperSecret1!",
    "ws_token": "sercet_Ws_t0ken"
}
​

⚠️ 安全三件套:① listen_ip_address 保持 127.0.0.1(只本机)；② password 用强密码(secrets.token_hex() 生成)；③ jwt_secret_key 用 32+ 字符随机串(会话加密用)。Docker 下才需 0.0.0.0，由 Docker 端口映射管安全。

二、FreqUI 的核心视图

FreqUI 是现代响应式 Web 应用，支持亮/暗主题切换。核心视图:

交易视图(Trade view):可视化 bot 的每笔交易，含 K 线图、入场/出场标记、指标。可在这里启停 bot、强制开平仓(如配置允许)。图表配置可从策略的 plot_config 加载，也可在 UI 里自定义多套视图。

仪表盘(Dashboard):多 bot 总览。连了多个 bot 时，仪表盘展示所有 bot 的状态，可切换或筛选查看子集。

钱包余额(Wallet Balance):展示 bot 余额随时间的变化曲线，含未实现盈亏、出入金。注意历史数据是「尽力而为」填充的(不含出入金，假设起始余额=当前余额-盈亏)，有一个「Capture start」标记线表示准确数据的起点。

回测视图(Backtesting):需在 webserver 模式(freqtrade webserver)下才可用。可在 UI 里下载数据、测试 pairlist 配置、跑回测并可视化结果，还能对比多次回测。

webserver 模式 是特殊的运行模式(freqtrade webserver)，不实际交易，但提供下载数据、测试 pairlist、跑回测等增强功能。适合在不交易时做策略研究和数据准备。

💡 plot_config:策略里定义 plot_config 字典，指定主图/子图画什么。FreqUI 可点「from strategy」按钮加载，也能在 UI 里临时调整并保存多套配置。

三、REST API:端点速查

REST API 是 FreqUI 的底层，也能直接用 curl 或 freqtrade-client 调用。所有端点前缀 /api/v1/，需认证(除 /ping)。

健康检查(无需认证):

curl http://127.0.0.1:8080/api/v1/ping
# 返回 {"status":"pong"}
​

常用端点分类:

用 freqtrade-client(轻量客户端，只依赖 requests):

pip install freqtrade-client
freqtrade-client --config rest_config.json status
freqtrade-client --config rest_config.json forceenter BTC/USDT long enter_tag=GutFeeling
​

也可在 Python 里编程调用:

from freqtrade_client import FtRestClient
client = FtRestClient(server_url, username, password)
client.ping()
client.blacklist("BTC/USDT", "ETH/USDT")
​

四、认证:JWT 与 OpenAPI

REST API 用 HTTP Basic 认证登录，返回 JWT(access_token + refresh_token)。access_token 15 分钟过期，用 refresh_token 续期:

# 登录拿 token
curl -X POST --user Freqtrader http://localhost:8080/api/v1/token/login
# {"access_token":"eyJ...","refresh_token":"eyJ..."}

# 用 access_token 调用
curl -X GET --header "Authorization: Bearer ${access_token}" \
     http://localhost:8080/api/v1/count

# 续期
curl -X POST --header "Authorization: Bearer ${refresh_token}" \
     http://localhost:8080/api/v1/token/refresh
​

OpenAPI/Swagger UI:设 enable_openapi: true 后，访问 /docs 端点有交互式 API 文档，可直接在浏览器里试调每个端点，开发和调试很方便。

五、WebSocket:实时消息订阅

API 服务器含一个 WebSocket 端点 /api/v1/message/ws，用于实时订阅 bot 的 RPC 消息(开平仓通知、白名单变化、已分析数据帧等)。这也是 producer-consumer 模式的传输基础。

连接方式(需 ws_token 作查询参数):

ws://localhost:8080/api/v1/message/ws?token=你的ws_token
​

连接后发送订阅请求:

{
  "type": "subscribe",
  "data": ["whitelist", "analyzed_df"]
}
​

之后 bot 广播的对应消息会实时推送:

{
  "type": "analyzed_df",
  "data": {
      "key": ["NEO/BTC", "5m", "spot"],
      "df": {},
      "la": "2022-09-08 22:14:41.457786+00:00"
  }
}
​

消息类型见 freqtrade/enums/rpcmessagetype.py。

💡 反向代理:用 Nginx 反代 WebSocket 需额外配置 proxy_set_header Upgrade/Connection。Traefik 和 Caddy v2 开箱支持 WebSocket。配合 certbot 可上 SSL，但仍不建议把 API 直接暴露公网。

六、远程访问的正确姿势

默认配置只监听 localhost，本机访问没问题。远程访问(如 VPS 上的 bot)推荐:

1. SSH 隧道(最简单):ssh -L 8080:127.0.0.1:8080 user@vps，然后本机访问 localhost:8080。
2. VPN(openVPN/wireguard):建私有网络，bot 在内网。
3. 反向代理 + SSL:Nginx/Caddy + certbot 上 HTTPS，但仍要强认证。

⚠️ 绝不为了「方便」把 listen_ip_address 改成 0.0.0.0 并映射到公网。FreqUI 默认不支持 HTTPS，明文密码会泄露，且任何人都能控制你的 bot 下单。

本节要点回顾

1. FreqUI:freqtrade install-ui 安装/更新；依赖 api_server 配置；提供交易视图、仪表盘、钱包余额、回测(需 webserver 模式)等视图。
2. api_server 配置:安全三件套——127.0.0.1 监听、强 password、32+ 字符 jwt_secret_key。
3. REST API:端点前缀 /api/v1/，分类含控制、查询、操作、统计、数据、策略；用 freqtrade-client 或 curl 调用；/docs(OpenAPI)可交互调试。
4. 认证:Basic 登录换 JWT，access_token 15 分钟过期用 refresh_token 续期。
5. WebSocket:/api/v1/message/ws?token=，订阅 whitelist/analyzed_df 等消息类型，也是 producer-consumer 的基础。
6. 远程访问:用 SSH 隧道或 VPN，别公网暴露；反向代理上 SSL 仍要强认证。

下一节，我们看插件系统——pairlist 过滤器(VolumePairList、SpreadFilter 等)与 protection 保护机制(StoplossGuard、MaxDrawdown、CooldownPeriod)。