Trantor Local Proxy

Trantor 提供一个轻量的本地代理工具 ，以便在有线上开发环境的情况下，使开发者可以最轻量化的在本地进行开发，并且可以一定程度上与线上开发环境联调打通。以下简称 TLP

注意：Trantor 从 0.9.0 版本开始支持多环境，因此 MetaStore 分为了研发态的主 MetaStore 和运行态的从 MetaStore 两种模式。tlp 只作用于运行态的从 MetaStore 。

这个本地代理工具伪装成运行态 MetaStore 和 Gateway ，通过修改和路由浏览器发往 MetaStore 和 Gateway 的请求来做到：

• 线上统一工作台可渲染本地模块的 View 、ViewAction 、Widget 、Container 等
• 使线上统一工作台能调用到本地模块的 ServerAction 和 DataAction
• 可混合获取到线上 MetaStore 中的其它资源
• 对非本地开发中的模块的调用能代理到线上的 Gateway

如何使用

1. 使用 trantor proxy run -v 0.14.0-SNAPSHOT 命令下载并启动tlp。
2. 根据需要编辑相关配置( 参考相关配置 )
3. 启动本地业务模块
   • 本地模块连接的 DataStore 地址配置线上开发环境
     • 如本地模块使用 Dubbo 协议连接 DataStore ，可以使用 DS_DIRECT_URL 环境变量配置 dubbo 地址直连（格式为 dubbo://host:port），无需连接线上 ZK/Nacos 。
     • 如本地模块使用 http 协议连接 DataStore ，则要使用环境变量 DUBBO_ENABLED=false 来关闭 Dubbo 协议从而使用 http 协议连接 DS ，直接使用 DS_URL 环境变量配置 DataStore 地址即可。
   • 本地模块连接的 MetaStore 地址则配置连接 tlp 的地址 + /meta-store
     • 因为 tlp 同时承担了 MetaStore 和 Gateway 的职责，为了正确区分发给 MetaStore 的 API ，需要增加一级 path 作为 MetaStore 的 endpoint ，因此需要拼上 /meta-store 。例如tlp跑在 8008 端口，则要连接的 MetaStore 地址为：http://127.0.0.1:8008/meta-store
     • 使用环境变量 META_STORE_URL 来配置 MetaStore 地址
   • 如果线上开发环境未 mock 用户和 ACL ，则本地模块也需要关闭用户和 ACL 的 mock 并连接线上开发环境同样的用户和 ACL
   • 添加环境变量 LOCAL_MODE=true
   • 建议添加环境变量 DUBBO_ENABLED=false 关闭本地模块中对 DataStore 和用户的 Dubbo 协议连接而使用 http 协议连接，配置上会简单很多
4. 打开统一工作台，并配置debug信息。

统一工作台需提前在环境变量中增加DEBUG=true配置。

如果只代理 View 、ViewAction 、Widget 和 Container 可以不用启动本地业务模块

相关配置

metaStoreUrl: http://meta-store.url
gatewayUrl: http://gateway.url
modules:
  <your-module-key>:
    url: http://127.0.0.1:8081
    resourcePath: /t_project/trantor/base/src/main/resources/trantor/resources/<your-module-key>

父标签	属性	类型	必填	解释	备注
-	metaStoreUrl	String	是	线上meta sotre地址	该地址可以为 https
	gatewayUrl	String	是	线上网关地址	该地址可以为 https
	modules	List	是	本地需要代理的模块列表	-
modules		Object	是	需要代理的模块key	模块key与trantor.yml中的moudleKey一致
	url	String	否	本地模块的web地址	本地地址加端口号
	resourcePath	String	否	本地模块资源路径	Trantor resources目录

命令详解

• 快速使用

  快速开始使用，会下载最新RELEASE版本，并已8008端口启动服务。

trantor proxy run

• 启动轻量化底座

  -v, —version version 指定版本 默认值 (最新的RELEASE版) -c, —config path 配置文件地址 默认值 (第一次会让其编辑配置文件) -p, —port int 代理服务器端口 默认值 (8008) 以上参数可选填。如果不指定，将全部使用默认值。

trantor proxy run  [ -v version] [-c path] [-p int]

• 查看所有版本

trantor proxy list

• 删除版本

  -v, —version version 指定版本 删除版本时，版本号为必填项

trantor proxy delete  [ -v version]

• 查看帮助

  -h, —help 查看proxy的相关解释

trantor proxy -h

常见问题

• Q: TLP目前不支持https。

  A: Dice可以在 微服务治理平台 -> 选择对应的项目和环境 -> API 网关 -> 流量入口管理 -> 统一域名入口(详情) -> 全局策略 -> 业务策略；取消 强制跳转HTTPS 选项的选中状态，提交即可(确保开启规则为已启用)。

• Q: 在工作台 DEBUG 面板填错信息后，整个工作台都打不开了。 A: 请清除浏览器的 localStorage 。

• Q: 在有UC的环境下使用tlp会无限循环跳转。 A: 请在hosts文件中增加与统一工作台一致的一级域名的本地映射。

  例如：线上统一工作的域名是 trantor-workspace.terminus.io。那么在hosts文件中就需要加入 local.terminus.io 127.0.0.1

• Q: tlp启动时有[TLP] WARNING! ts-compiler not work as expect. 的警告

  A: ts-compiler 用于编译视图中的自定义 controller 部分的代码。正常是由 MetaStore 打包在一起跑的，但使用 tlp 时由于本地没有 MetaStore ，因此目前需要自己手动安装才可以使 tlp 支持编译从本地模块中获取的视图的 controller 部分。如果你的视图并不包含 controller 代码，则可以不安装。

  ts-compiler 基于 nodejs 构建，因此需要先安装 nodejs 。一旦你安装完成后，应该就会同时安装了 nvm 命令。执行 npm i @terminus/ts-compiler -g --registry=https://registry.npm.terminus.io/ 即可。如果需要升级 ts-compiler ，重复执行上述命令即可。

相关概念

以下是使用 tlp 时的部署调用关系：

• 可以看到除了 tlp 和本地开发模块（以及如果多个本地开发模块需要互调时的本地 Nacos）外，其余组件使用的都是线上的

• 打开统一工作台的本地开关并配置 tlp 地址，目的是让统一工作台原本从浏览器直接发往线上 MetaStore 和 Gateway 的请求转而发往本地 tlp ，从而将线上和本地打通

• 本地 tlp 接受到统一工作台发来的对 MetaStore 和 Gateway 的请求后，按照 config 中的配置进行代理或拦截转发

  • 对于本地模块的数据访问和 ServerAction 调用，拦截后转发给本地模块
  • 对于非本地模块的数据访问和 ServerAction 调用，直接代理给线上 Gateway
  • 对于元数据获取的 API ，首先代理访问线上 MetaStore 拿到结果后，和本地模块中的元数据进行一次 Merge

以下是使用tlp时的一些限制：

• 为了避免多人同时开发一个模块时元信息互相覆盖，本地开发的模块连接 tlp 时默认不会向线上开发环境注册元信息。对于 View 、ViewAction 、ServerAction 等信息，tlp 会直接代理因此不受影响，但模型定义信息修改后不会反应到线上环境，需要通过正常的元信息注册发布流程才能使模型定义的改变在目标环境生效。

• 目前已知如果本地 ViewAction 中配置的 DataProcessorAction 和 ViewAction 所属模型不在同一模块时，无法调通。

• 当本地多个模块中有同样 key 的资源时，最后一个被扫描到的会生效，这个行为本身不稳定，因此尽量不要出现本地多个模块中出现同样 key 的情况。

  • 本地启动模块过多时，可能会有性能问题。
  • 只在本地模块中有的资源，在交付控制台无法看到。
  • 模块间直接进行的互相调用（例如 Dubbo 、SpringCloud），目前无法被 tlp 影响，请使用对应协议自己的方法自行解决。

• 线上调本地比较麻烦，但本地调线上 Dubbo 和 SpringCloud 都可以通过直连方式实现

高级使用

• 快速刷新本地启动的模块资源：

  • 模块增加环境变量 LOCAL_MODE=true 后，会提供一个 API ：GET /api/trantor/dev/reload 。修改 View 、ViewAction 等文件资源后，只需要重新 build 文件或 project 保证这些文件被写入 target 后，即可调用该 API 在不重启模块的情况下刷新资源。

    

  • Model 、ServerAction 、DataAction 等本身通过 Java hotreload 无法刷新的内容无效。

• tlp 本身提供了几个 API 帮助获取本地模块信息：
  • GET /_tlp/api/inspect ：tlp 版本和配置信息等
  • GET /_tlp/api/actions/{key} ：模糊搜索，列出 action 的 key
  • GET /_tlp/api/actions/full/{key} ：模糊搜索，列出 action 的完整信息
  • GET /_tlp/api/views/{key} ：模糊搜索，列出 view 的 key
  • GET /_tlp/api/views/full/{key} ：模糊搜索，列出 view 的完整信息
  • GET /_tlp/api/modules/{key}/reload ：（since v1.0.2）重新加载模块内资源，效果等同于直接调用模块的 /api/trantor/dev/reload
• 模块间的远程调用，注意这部分和 Trantor 本身无关，在这里只是为了方便而列出解决办法
  • 本地模块间 SpringCloud / Dubbo 互调
    • 本地多个模块都注册到本地 Nacos / ZK ，正常互调即可
  • 开发环境模块调用本地模块
    • 取决于开发环境有没有可能直接访问到本地 IP 和 port ，但大概率是不支持的，并且也不推荐。建议将模块发布到开发环境进行联调
  • 多人本地模块间互调（即开发 A 在自己机器上想要调用开发 B 的服务）
    • 需要保证两人内网可通
    • A 通过直接指定地址来调用
      • SpringCloud

// 通过为增加 url 配置并从环境变量读取，默认值留空的形式，可以通过环境变量控制调用目标
// 此为 Spring OpenFeign 自带机制，与 Trantor 无关
// Dubbo 方式类似，Consumer 可直接指定目标地址
@FeignClient(name = "base", path = "/api/tmodel/base_User", url = "${DIRECT_URL_BASE_USER_CLIENT:}")
public interface BaseUserClient extends TModelFeignClient<User, Long> {}