安全与操作防护

pymt5 可以通过实际网络连接读取账户数据并提交会改变状态的请求。连接代码、凭据、 日志和协议研究材料都应按敏感信息处理。本指南说明防护措施及其边界，并不保证某个 服务器、券商或集成方式一定安全。

第一次连接请遵循 快速开始 并阅读 配置。方法级细节见 API 参考；已观察到的线上行为及其证据边界见 协议参考。

授权与项目状态

pymt5 是基于 MetaTrader 5 Web Terminal 协议逆向分析的非官方客户端，与 MetaQuotes 没有隶属或背书关系。某个命令能够运行，并不代表其使用已经获得授权。

  • 只连接你拥有或已获明确授权访问的服务器和账户。遵守适用法律、券商条款、平台条款 以及所在组织的安全政策。

  • 不得利用本客户端绕过访问控制、账户限制或技术保护措施。协议行为可能随时变化， 也可能随券商、服务器 build、交易品种和交易时段而不同。

  • 从已获授权的模拟账户开始。先验证所需的全部只读流程；在考虑任何会改变状态的操作 之前，还应单独验证该操作，而用于真实账户前必须再次验证。

  • 某个服务器 build 上的观测结果只是兼容性证据，不是通用协议契约。验证集成时， 记录软件包版本和 client.server_build。

优先使用只读操作

客户端没有能够在技术上强制只读访问的全局开关，安全性取决于应用程序实际调用的方法。 开始时仅使用 connect()、login()、load_symbols()、账户查询和历史行情 查询；确有需要时再添加 tick 或订单簿订阅。

trade_request()、市价单和挂单辅助方法、持仓或订单修改、撤单和平仓、密码修改、 开户、OTP 设置、验证码校验以及服务器通知等方法都可能改变远端状态。不要把这些调用 放入启动代码、通用重连回调或所谓的只读健康检查中。运行前应检查完整调用路径，包括 兼容封装和示例代码。

除非自动交易是明确且经过评审的需求，否则应保持禁用。使用独立的模拟账户凭据、最小 可行权限、尽量小的测试范围以及由操作员控制的停止机制。离线测试通过绝不能证明实盘 交易安全。

凭据处理

使用环境变量或经过批准的密钥管理系统，不要在源代码中写入字面量。在线 integration 测试、 scripts/live_test*.py 和 scripts/demo_tick_probe.py 使用：

  • PYMT5_SERVER：已获授权的 WebSocket 地址；

  • PYMT5_LOGIN：数字 login；

  • PYMT5_PASSWORD：密码。

本地 .env 文件已被 Git 忽略，但忽略规则并不是完整的密钥管理措施。应限制文件 权限，绝不提交该文件，也不要把它复制到容器、构建产物或问题附件中。探针的 --env-file 选项还需要可选的 python-dotenv 包。如果将来确有单独授权的在线 任务，CI 中应使用掩码密钥；默认 CI 不需要在线凭据。

备注

examples/ 下的编号示例通过 os.environ 从 PYMT5_SERVER、 PYMT5_LOGIN 和 PYMT5_PASSWORD 加载 SERVER、LOGIN 和 PASSWORD。运行示例前，必须在进程环境中设置全部三个变量，且 PYMT5_LOGIN 必须包含整数。示例不会隐式加载 .env 文件。 scripts/live_test*.py 也使用相同的三个环境变量。不要发布含有真实值的终端输出。

避免把密码放在命令行参数、URL、shell 历史、源代码、notebook 单元格或异常消息中。 任何已提交、粘贴到报告中或以其他方式泄露的凭据都应立即轮换；在后续提交中删除它， 并不能清除历史记录或其他副本。

日志、报告与保留数据

在导入 pymt5 之前设置合适的日志级别。PYMT5_LOG_LEVEL 在导入 pymt5._logging 时读取。特别是，目前成功登录会在 INFO 级别记录数字 login 和 session ID，因此不能认为 INFO 输出一定可以公开发布。DEBUG 还可能增加协议时序、 命令和连接细节，而应用程序回调可能加入更多敏感数据。

绝不能在公开日志、测试夹具、覆盖率产物、截图或问题报告中包含密码、OTP、会话令牌、 session ID、CID、login 数字、账户或持仓详情、经过认证的原始帧或私有服务器数据。 优先记录异常类型、数字响应码、UTC 时间戳和脱敏后的方法名。应检查整份日志，而不是 只遮盖前几行。脱敏诊断和报告清单见 故障排查。

指标、追踪、崩溃报告以及保留的 tick 或账户缓存同样适用这些规则。与事后清理大型 归档相比，数据最小化和有界保留更为可取。

超时与交易结果未知

超时只表示客户端停止等待， 并不 表示服务器拒绝或未能执行请求。一旦可能已经 开始发送，取消和发送失败同样具有歧义。

当结果可能未知时，传输层会隔离该连接，使其他在途请求失败，并防止迟到响应在同一 连接上被分配给后续请求。启用 auto_reconnect=True 时，客户端可以创建新连接、 重新登录并恢复 tick 和订单簿订阅，但这并不能确定被中断操作在服务器侧的结果。

警告

在 MT5TimeoutError、取消、发送失败或断线之后，绝不要盲目重试交易。自动重连 并不能证明重试安全，也绝不能被用作自动交易重放机制。

交易结果不确定后，应停止受影响的工作流。在新的已授权会话中，核对服务器持仓、挂单 以及相关成交/订单历史，然后才能采取经操作员批准的下一步行动。需要考虑数据传播 延迟；查询虽然能降低不确定性，但在某些故障场景中仍不能提供绝对证明。本地请求 ID、 comment 或回调同样不能证明已经执行。响应关联边界见 协议参考， 查询和异常接口见 API 参考。

K线、tick 与请求节流

协议敏感值需要显式验证：

  • 已观察到的历史K线有 48 字节标准布局和 56 字节扩展布局。在 rate_bar_format="auto" 模式下，响应长度同时兼容两种布局或两种都不兼容时， 会抛出 ProtocolError，而不是猜测。只有识别了已授权服务器的格式后，才能选择 "standard" 或 "extended"。长度检查无法发现所有畸形或截断响应。

  • tick_price_mode="auto" 使用旧有的品种/数量级启发式规则，并非线格式保证。 在目标服务器上把归一化前的线上 tick 样本与附近K线比较后，再选择 "scaled" 或 "normalized"。可能需要按品种覆盖配置，目前没有跨券商通用的验证结论。

  • 订阅确认并不保证 tick 一定会到达。闭市、不活跃品种和服务器特定行为都可能导致 没有数据。缓存 tick 只是观测记录，不是完整的权威行情源。

  • 服务器可能拒绝 tick 退订，包括移除最后一个品种的请求。被拒绝的请求会抛出 ProtocolError，并保留最后确认的本地集合；绝不能把这种情况记录为清理成功。

可选的 rate_limit 令牌桶只是本地客户端节流器，并不代表服务器限制。应限制请求 速率和并发量，避免紧密重试循环，并遵守服务器约束。某个突发请求曾经成功，并不能 证明持续以同样速率运行是安全或获准的。

私有协议分析材料的边界

第三方 Web Terminal JavaScript 快照和生成的分析摘录是私有研究输入，不是可再分发 的 pymt5 源文件。应把合法取得的快照放在检出目录之外的私有目录中，并通过 PYMT5_ANALYSIS_DIR 指向该目录。analysis/ 目录忽略 *.js，以降低意外 纳入的可能性。

不要提交快照、生成的输出、复制的摘录或私有研究抓包，也不要把它们附加到 issue 或 pull request。从当前工作树删除文件并不会清除 Git 历史。仓库的 MIT 许可证不授予 第三方 bundle 的权利，私下保留这些材料也不能替代任何适用的许可证义务。公开协议 文档应说明观测行为和不确定性，但不能复制私有材料。

运行前检查清单

  • 已确认授权、服务器 build、账户类型和计划执行的操作。

  • 凭据来自经过批准的来源，且不存在于源代码和日志中。

  • 首次运行使用已授权模拟账户，并且只读。

  • 已明确审查会改变状态的示例及重连路径。

  • 超时处理把交易结果视为未知，并禁止盲目重试。

  • 已验证K线、tick 价格、订阅和服务器速率方面的假设。

  • 已检查报告和研究产物，确保不含秘密及私有第三方材料。

升级前请阅读 更新日志，因为兼容性和安全行为可能随版本变化。