QoderWake多版本共存配置：新旧环境兼容性测试推荐

多版本QoderWake并行运行的本质是五层隔离机制：独立安装路径与二进制文件重命名、配置目录与运行时数据分离、网络端口独占分配、Connector凭证按命名空间划分、环境变量锁定至专属启动脚本。每层看似细碎，却是版本共存不可或缺的基石。

在实际开发或运维场景中，若需在同一物理机同时运行QoderWake v1.0.2与v1.2.7以验证策略兼容性、Connector行为差异或数字员工上下文迁移效果，常暴露出命令冲突、配置相互覆盖、端口抢占、Agent实例混淆等问题——根源在于环境未实施有效隔离。下文直接给出可落地的配置方案。

一、独立安装路径与二进制命名隔离

核心原则：通过物理路径区分与可执行文件重命名，确保各版本启动入口唯一，避免系统PATH中同名"qoderwake"命令相互覆盖或误调用。

首先为v1.0.2创建独立安装目录，例如C:qoderwakev1.0.2，解压或安装时指定该路径，安装过程中务必取消"添加至系统PATH"。进入该目录，将主程序重命名为qoderwake-v102.exe。同理，为v1.2.7创建C:qoderwakev1.2.7，主程序重命名为qoderwake-v127.exe。

在PowerShell中分别验证：执行C:qoderwakev1.0.2qoderwake-v102.exe --version与C:qoderwakev1.2.7qoderwake-v127.exe --version，确认版本号输出正确且互不干扰。如需全局调用，将各版本路径分别加入用户级PATH（非系统级），例如添加C:qoderwakev1.0.2与C:qoderwakev1.2.7，避免共用公共bin目录。

二、配置目录与运行时数据空间隔离

各版本必须使用完全独立的配置、日志与缓存目录，防止策略快照、本地凭证或沙盒状态相互污染。

为v1.0.2创建专属配置根目录，例如C:qoderwakeconfig-v102，首次启动时通过命令行参数指定：qoderwake-v102.exe --config-dir C:qoderwakeconfig-v102。v1.2.7同理，创建C:qoderwakeconfig-v127，启动参数为--config-dir C:qoderwakeconfig-v127。

启动后检查各配置目录，确认独立生成config.yaml、policy-snapshot.json及logs子目录，无文件共享或硬链接。若采用服务模式，各版本需注册独立Windows服务名，例如QoderWake-Agent-v102与QoderWake-Agent-v127，同时绑定不同HTTP管理端口（如8443与8444）。

三、网络端口与进程监听地址分离

QoderWake各版本默认均监听8443端口，后启动版本将因端口占用而失败。需显式为各版本分配不同的监听地址与端口组合。

编辑v1.0.2配置文件config-v102config.yaml，设置：server: { host: "127.0.0.1", port: 8443 }。编辑v1.2.7配置文件config-v127config.yaml，设置：server: { host: "127.0.0.1", port: 8444 }。

启动后分别访问https://127.0.0.1:8443/ui与https://127.0.0.1:8444/ui，确认两套Web控制台独立加载且显示对应版本号。在任务管理器中核查两个进程的命令行参数，确保监听端口未被覆盖或从环境变量继承。

四、Connector凭证与策略快照逻辑隔离

即使服务端将策略回滚至旧版，若客户端本地缓存仍保留新版Connector OAuth Token或API Key，仍可能触发越权调用或认证失败。必须强制区分各版本的凭证存储域。

在v1.0.2配置中，向config-v102config.yaml添加：connector_storage_namespace: "v102-production"。v1.2.7配置为：connector_storage_namespace: "v127-staging"。

分别执行完整凭证刷新：对v1.0.2运行qoderwake-v102.exe connector auth --force，对v1.2.7运行qoderwake-v127.exe connector auth --force。完成后检查各配置目录下的credentials/子目录，确认生成的token文件名包含对应命名空间前缀，且内容不可互通读取。

五、环境变量作用域限定与启动脚本封装

全局环境变量（如QODERWAKE_HOME、NODE_OPTIONS）若被多版本共享，极易引发行为漂移。正确做法是通过启动脚本将变量生效范围限定于单个会话。

为v1.0.2创建批处理文件launch-v102.bat，内容示例：set QODERWAKE_HOME=C:qoderwakev1.0.2 & set NODE_OPTIONS=--max-old-space-size=2048 & C:qoderwakev1.0.2qoderwake-v102.exe --config-dir C:qoderwakeconfig-v102。v1.2.7对应创建launch-v127.bat，QODERWAKE_HOME与内存参数按需调整，指向对应二进制文件与配置路径。

双击运行各自批处理文件，观察终端输出中环境变量值，确认无跨版本泄漏。关键约束：禁止在系统属性→高级→环境变量中设置任何QoderWake相关变量，所有变量仅存在于批处理会话生命周期内。