企业官网建设流程全解析

vnpy WebTrader 模块实战指南：基于 FastAPI 与 RPC 的 B/S 架构 Web 交易服务

【免费下载链接】vnpy基于Python的开源量化交易平台开发框架项目地址: https://gitcode.com/vnpy/vnpy

WebTrader 是 vnpy（VeighNa）量化交易平台中的 Web 服务器模块，面向 B/S（Browser/Server）架构需求设计：用户无需启动 PyQt 桌面端，直接通过浏览器即可对运行中的 VeighNa Trader 进行行情订阅、数据查询、委托下单与撤单等交易管理操作。本文以 web_trader.md 官方文档为主体，结合仓库内 RPC 底层源码，完整讲解其双进程架构、加载启动流程、REST/WebSocket 接口调用方法，以及配置要点与能力边界，读完即可在本地跑通从令牌获取到委托撤单的完整 Web 交易链路。

模块定位与核心特性

WebTrader 在 vnpy 官方文档中的定位是"用于Web 应用后端服务的功能模块"，让用户通过浏览器（而非 PyQt 桌面端）来运行和管理 VeighNa 量化策略交易。在 README.md 中，其描述为：

Web 服务模块，针对 B-S 架构需求设计，实现了提供主动函数调用（REST）和被动数据推送（Websocket）的 Web 服务器。

核心特性可归纳为两点：

• REST 主动请求调用：浏览器通过访问 HTTP URL 发起订阅行情、挂撤单、查询数据等操作；
• WebSocket 被动数据推送：行情推送、委托推送等事件数据以 JSON 格式实时推送到浏览器端。

从 CHANGELOG 记录（CHANGELOG.md）可以看出该模块的演进细节：支持了"加密鉴权""自定义监听地址和端口"，并修复过"html 静态文件缺失"问题，说明其鉴权机制与监听配置经过了持续完善。

系统架构：双进程协作设计

WebTrader 采用 FastAPI 作为后端服务器框架，运行时整体分为两个相互独立的进程：

两个进程之间通过 ZeroMQ 实现 RPC 通讯，形成"浏览器 → Web 服务进程 → 策略交易进程"的三层链路。

主动请求调用（Req-Rep 模式）

主动请求（如订阅行情、挂撤单、查询数据）的完整调用链为：

1. 浏览器发起 REST API 调用（访问某个 URL 地址提交数据）到 Web 服务进程；
2. Web 服务进程收到请求后，转换为 RPC 请求发送给策略交易进程；
3. 策略交易进程执行请求处理后，将结果返回给 Web 服务进程；
4. Web 服务进程把数据返回给浏览器。

被动数据推送（Pub-Sub 模式）

被动推送（如行情推送、委托推送）的完整链路为：

1. 浏览器发起 WebSocket 连接到 Web 服务进程；
2. 策略交易进程通过 RPC 推送将数据推送给 Web 服务进程；
3. Web 服务进程收到后，将数据通过 WebSocket API 以 JSON 格式实时推送给浏览器。

RPC 底层实现原理

双进程通信的底层依赖就位于当前仓库的vnpy/rpc目录中，可直接阅读源码印证：

• vnpy/rpc/server.py：RpcServer同时创建zmq.REP（应答）与zmq.PUB（发布）两个 Socket——REP 套接字接收客户端请求、执行注册函数并回传结果，PUB 套接字用于主动向订阅端广播数据。服务端通过register(func)注册可被远程调用的函数，publish(topic, data)实现事件广播；
• vnpy/rpc/client.py：RpcClient持有zmq.REQ（请求）与zmq.SUB（订阅）两个 Socket，并通过__getattr__动态代理实现"以调用本地方法的方式发起远程调用"；调用默认超时时间为 30000 毫秒，超时或远端执行异常时抛出RemoteException；
• vnpy/rpc/common.py：定义了心跳机制参数——心跳主题heartbeat、心跳间隔HEARTBEAT_INTERVAL = 10（秒）、容错阈值HEARTBEAT_TOLERANCE = 30（秒）。客户端在超过 30 秒未收到服务端心跳时，会通过on_disconnected打印连接异常提示，用于检测 Web 服务进程与策略交易进程之间的链路健康状态。

这正好对应了 rpc_service.md 中介绍的 RPC 通讯地址体系：请求响应地址与事件广播地址均采用 ZeroMQ 地址格式（如tcp://127.0.0.1:2014），推荐使用 TCP 协议，追求更低通讯延时的 Linux 用户可选用 IPC 协议。

加载启动 WebTrader

通过 VeighNa Station 加载

启动并登录 VeighNa Station 后，点击【交易】按钮，在弹出的配置对话框的【应用模块】栏中勾选【WebTrader】即可。

通过启动脚本加载

在启动脚本中添加如下代码：

# 写在顶部 from vnpy_webtrader import WebTraderApp # 写在创建main_engine对象后 main_engine.add_app(WebTraderApp)

参照仓库中的标准启动脚本 examples/veighna_trader/run.py 可以看到，WebTraderApp与CtaStrategyApp、DataManagerApp等同属于应用模块（App），统一通过main_engine.add_app(...)注册到主引擎中；在官方示例脚本中WebTraderApp默认以注释形式保留，取消注释即可启用。

启动前置条件与操作入口

启动模块之前，务必先连接并登录交易接口（如 CTP 等），待 VeighNa Trader 主界面【日志】栏输出"合约信息查询成功"后再启动模块，确保合约等初始化数据已就绪。

成功连接交易接口后，通过两种方式进入模块界面：

• 点击菜单栏【功能】→【Web 服务】；
• 点击左侧按钮栏中的 WebTrader 图标。

此时系统中仅运行策略交易进程，界面上方区域为服务器配置选项。

服务器配置项详解

进入 WebTrader 界面后，左上角区域的服务器配置选项包括：

• 用户名和密码：从网页端登录 Web 应用时使用的账号口令。使用时请修改为自己想用的用户名和密码，通过启动目录下.vntrader中的web_trader_setting.json文件修改。注意：这里的用户名和密码与底层交易接口的账户密码完全无关，仅用于 Web 应用的鉴权登录（CHANGELOG 中"加密鉴权"的优化即与此相关）；
• 请求和订阅地址：架构图中 Web 服务进程与策略交易进程之间进行 RPC 通讯的地址，注意端口不要与其他程序冲突即可。

点击【启动】按钮后，模块会根据用户输入的配置信息在系统后台启动 Web 服务进程，同时右侧区域会输出 FastAPI 运行过程中的相关日志信息，便于观察服务启动状态与请求处理情况。

接口演示：从令牌到撤单的完整调用链

启动 Web 服务后，在浏览器打开http://127.0.0.1:8000/docs，即可看到 FastAPI 自动生成的交互式接口文档页面，其中包含当前 WebTrader 支持的全部接口信息。下文结合 HTTP 客户端与 WebSocket 客户端演示各接口的实际用法（示例中的请求地址、账号密码等请按实际部署情况替换）。

1. 获取令牌（Token）

WebTrader 的所有业务接口都需要携带令牌进行鉴权。通过POST /token接口换取access_token：

import requests import json url = "http://127.0.0.1:8000/" username = "vnpy" password = "vnpy" r = requests.post( url + "token", data={"username": username, "password": password}, headers={"accept": "application/json"} ) token = r.json()["access_token"]

首先导入requests和json模块，定义url、用户名和密码，通过requests.post方法传入相应参数即可获得令牌（token），后续访问各类接口时直接传入该 token 即可，无需重复登录。

2. 行情订阅

通过POST /tick/{symbol}接口实现对指定合约的行情订阅，订阅成功后图形界面即可收到该合约的行情数据推送：

r = requests.post(url + "tick/" + "cu2112.SHFE", headers={"Authorization":"Bearer " + token})

注意这里合约代码与交易所代码的组合格式为合约代码.交易所代码（如上例的cu2112.SHFE），并需在请求头中以Authorization: Bearer <token>形式携带令牌。

3. 批量查询

通过主动请求可查询各类交易数据，包括 tick 数据、合约数据、账户数据、持仓数据、委托数据以及成交数据：

# 查询函数 def query_test(name): """查询对应类型的数据""" r = requests.get( url + name, headers={"Authorization": "Bearer " + token} ) return r.json() # 批量查询 for name in ["tick", "contract", "account", "position", "order", "trade"]: data = query_test(name) print(name + "-" * 20) if data: print(data[0])

批量遍历tick / contract / account / position / order / trade六个数据类别，逐一发起GET请求并打印首条数据，可用于快速验证各数据通道是否正常。

4. 委托测试（下单）

通过POST /order接口提交委托请求，请求体为 JSON 格式的字典：

# 委托测试 req = { "symbol": "cu2112", "exchange": "SHFE", "direction": "多", "type": "限价", "volume": 1, "price": 71030, "offset": "开", "reference": "WebTrader" } r = requests.post( url + "order", json=req, headers={"Authorization": "Bearer " + token} ) vt_orderid = r.json() print(vt_orderid)

委托字段说明：

下单接口返回vt_orderid（VeighNa 内部委托号），该 ID 是后续撤单操作所需的唯一标识。下单成功后，同样能在图形化界面看到对应的委托信息。

5. 撤单测试

如需撤销之前提交的委托，通过DELETE /order/{vt_orderid}接口发送主动请求：

# 撤单测试 r = requests.delete( url + "order/" + vt_orderid, headers={"Authorization": "Bearer " + token} )

撤单结果同样会在图形化界面实时更新。

6. WebSocket 被动接收推送

通过 WebSocket 可以被动接收策略交易进程推送过来的行情数据和委托数据等。使用websocket-client库建立连接：

# WebSocket测试 from websocket import create_connection ws = create_connection("ws://127.0.0.1:8000/ws/?token=" + token) while True: result = ws.recv() print("Received '%s'" % result) ws.close()

连接地址为ws://127.0.0.1:8000/ws/，令牌通过 URL 查询参数?token=传递。建立连接后循环调用recv()即可持续接收服务端推送的 JSON 数据（如行情、委托状态等），这与 RPC 的 Pub-Sub 事件广播机制一一对应。

配置与安全要点

综合官方文档与仓库变更记录，实际部署时还需注意以下几点：

• 鉴权安全：WebTrader 已支持加密鉴权（见 CHANGELOG.md），但所有接口调用仍需通过 Bearer Token 认证，务必修改web_trader_setting.json中的默认用户名和密码，避免使用文档示例中的弱口令；
• 监听地址与端口：模块支持自定义监听地址和端口。RPC 通讯地址的端口需避免与其他程序冲突；Web 服务的默认监听端口为8000（/docs接口文档即在该端口下访问）；
• 连接时序：必须先连接交易接口并等待"合约信息查询成功"后再启动 WebTrader，否则行情订阅、委托等操作可能因底层数据未就绪而失败。

能力边界与后续计划

WebTrader 目前的定位是Web 应用的后端服务：它提供了浏览器访问数据的接口，而前端页面（即浏览器中看到的网页）按照官方规划交由社区用户来实现。因此当前模块只支持基础的手动交易功能，后续计划逐渐加入策略交易应用相关的管理功能（比如 CtaStrategy 的相关调用）。

对于想要基于 WebTrader 构建完整 B/S 交易系统的开发者，建议以本文的接口调用链为基础，自行实现前端页面，并持续关注该模块后续对策略管理能力的扩展。

延伸阅读

• 官方模块文档：docs/community/app/web_trader.md
• RPC 服务模块文档：docs/community/app/rpc_service.md
• RPC 服务端实现：vnpy/rpc/server.py
• RPC 客户端实现：vnpy/rpc/client.py
• 心跳与通讯常量定义：vnpy/rpc/common.py
• 标准启动脚本示例：examples/veighna_trader/run.py
• 平台功能清单与模块说明：README.md

【免费下载链接】vnpy基于Python的开源量化交易平台开发框架项目地址: https://gitcode.com/vnpy/vnpy