3045e287创建于 6 天前历史提交

Author	evanTang
Date	2026/05/27
Email

ascend-deployer适配OpenClaw组件安装部署与升级

1.方案目标

通过ascend-deployer实现OpenClaw集群的一键式安装部署与升级，支持Docker镜像加载、多实例容器拉起、删除重建升级以及批量配置热更新，降低OpenClaw集群部署与运维的复杂度。

2.方案总体设计

配置录入：在inventory_file中新增OpenClaw相关参数（镜像名称/文件、实例数量、起始端口、模型名称、推理服务URL、网关令牌、配置目录、实例名前缀、批量配置文件路径等）。
镜像加载：支持从tar文件加载镜像（docker load -i）或复用本地已有镜像，加载后提取并记录镜像名称。
集群部署：通过mindclaw/scripts/deploy.sh脚本拉起Docker容器集群，支持指定实例数、端口、模型、推理服务等参数。
升级策略：支持两种升级模式——删除重建升级（未提供批量配置文件时）和批量配置热更新（提供JSON配置文件时）。
前置校验：安装/升级前对参数格式（实例数、端口、URL、镜像tag等）及系统依赖（docker、openssl、docker-compose）进行校验，确保环境满足部署要求。

3.需求描述

前置条件

目标机器已安装Docker、docker-compose（或docker compose子命令）、openssl。
mindclaw/scripts/deploy.sh部署脚本已就绪（可通过resources_dir分发）。
若使用镜像文件加载，需确保tar文件存在且非软链接。
若使用本地已有镜像，需确保镜像名包含tag且已通过docker images验证。

约束

OS：支持ascend-deployer适配的OS。
实例数量（openclaw_instance_count）必须为正整数。
起始端口（openclaw_base_port）必须在1-65535范围内，且不能被占用。
镜像名称（openclaw_image_name）必须包含tag（如openclaw:custom）。
推理服务URL（openclaw_infer_url）必须为合法的http/https格式。
批量配置文件（openclaw_batch_config_file）必须为合法的JSON格式，且仅在upgrade场景生效。

需求描述

用户通过在inventory_file中填写OpenClaw相关参数，执行bash install.sh --install=openclaw触发安装部署，或执行bash install.sh --upgrade=openclaw触发升级操作。安装时自动完成镜像加载与集群拉起；升级时根据是否提供批量配置文件，自动选择删除重建或批量配置热更新模式。

4.详细设计

4.1 安装部署

流程概述

安装流程分为两个阶段：镜像加载（action=install）和集群拉起（action=launch），由install_openclaw.yml playbook编排。

镜像加载阶段

判断参数：若提供openclaw_image_file，执行docker load -i <file>从tar文件加载镜像；若仅提供openclaw_image_name，直接使用该名称（假设镜像已在本地）。
提取镜像名：从docker load输出中解析Loaded image:后的镜像名称；若未提供image_file，直接使用传入的image_name。
校验失败则终止，成功则记录镜像名至ansible facts供后续阶段使用。

集群拉起阶段

准备部署脚本：检查TmpPath.ROOT/mindclaw/scripts/deploy.sh是否存在；若不存在，从resources_dir/mindclaw复制整个目录至TmpPath.ROOT/mindclaw。
实例保护检查：检查配置目录（openclaw_config_dir）是否已存在docker-compose.yml或instance-*目录。若存在，则判定为已有实例，终止安装流程以保护现有数据。
清理配置目录：若通过实例检查，删除默认配置目录~/.ascend_deployer/openclaw-config（或用户指定的openclaw_config_dir），确保干净启动。
构建并执行命令：拼接deploy.sh up命令，传入所有参数：
```
bash deploy.sh up -n <count> -p <base_port> -m <model> --model-provider <provider> -u <infer_url> -c <config_dir> -i <image> --name <prefix> --skills [--token <token>]
```
- --skills参数会拷贝宿主机mindclaw下的skills 目录到容器，用户可自行控制skills 目录下的技能。
- --token参数仅在提供openclaw_gateway_token时追加。
- 执行时通过environ_update透传环境变量：API_KEY（来自openclaw_api_key）和SUBNET（来自openclaw_subnet）。
命令执行成功则保存配置至mindclaw.json并返回成功状态，失败则捕获异常并返回错误信息。

关键参数说明

参数	说明	默认值
`openclaw_image_name`	镜像名（必须带tag）	-
`openclaw_image_file`	镜像tar文件路径	-
`openclaw_instance_count`	实例数量（正整数）	必填
`openclaw_base_port`	起始端口（1-65535）	必填。每个实例占用4个端口（Gateway、SFTP、mDNS、Reserved），实例间端口间隔为4
`openclaw_model_name`	模型名称	必填
`openclaw_infer_url`	推理服务URL	必填
`openclaw_gateway_token`	网关令牌（选填，不填自动生成）	-
`openclaw_config_dir`	配置目录	`~/.ascend_deployer/openclaw-config`
`openclaw_model_provider`	模型供应商	`local`
`openclaw_instance_prefix`	实例名前缀	`openclaw`
`openclaw_api_key`	API Key（选填）	-，透传为容器环境变量`API_KEY`
`openclaw_subnet`	Docker子网（选填）	-，透传为容器环境变量`SUBNET`
`openclaw_batch_config_file`	批量配置文件路径（选填）	-，仅在upgrade场景生效

4.2 升级镜像配置（删除重建）

流程概述

升级流程同样分为两个阶段：镜像加载（action=install）和集群升级（action=upgrade），由upgrade_openclaw.yml playbook编排。当未提供openclaw_batch_config_file时，执行删除重建升级。

镜像加载阶段

与安装部署的镜像加载阶段完全一致，加载新版本镜像。

集群升级阶段（删除重建模式）

准备部署脚本：同安装流程，确保deploy.sh可用。
加载已有配置：从配置目录下的mindclaw.json读取历史配置参数（实例数、端口、模型、URL等），确保升级时参数与安装时一致。若文件不存在，则跳过加载，使用inventory_file中提供的参数。
不清理配置目录：与安装不同，升级阶段保留已有配置目录，避免丢失用户自定义配置。
构建并执行命令：与安装流程相同，执行bash deploy.sh up ...命令。deploy.sh up内部会先停止并删除旧容器，再使用新镜像和相同参数重新创建容器集群。
保存配置：升级成功后，执行_save_config(update_image_only=True)，仅更新mindclaw.json中的openclaw_image_name字段，保留其他配置不变。
命令执行成功则返回"Upgrade OpenClaw cluster success"，失败则捕获异常并返回错误信息。

与安装的区别

安装阶段会检查实例是否存在并清理配置目录，升级阶段不执行清理，保留原有配置和数据。
升级阶段会从mindclaw.json加载历史配置参数，确保升级时参数一致性。
升级阶段仅更新镜像名，其他配置参数保持不变。
升级阶段返回的成功消息为"Upgrade OpenClaw cluster success"，安装阶段为"Launch OpenClaw cluster success"。

4.3 批量配置更新（一次重启）

流程概述

当升级流程中提供了openclaw_batch_config_file参数时，跳过删除重建逻辑，执行批量配置热更新。该模式适用于仅需修改OpenClaw配置项（如并发数、超时时间、插件开关等）而无需更换镜像的场景。

执行流程

校验配置文件：检查openclaw_batch_config_file指向的JSON文件是否存在且为普通文件，不存在则终止。
准备部署脚本：确保deploy.sh可用（同安装/升级流程）。
解析批量配置：读取JSON文件，解析为配置项列表。若JSON格式非法，则终止并返回解析错误。
逐实例逐配置项更新：
- 遍历实例编号1到openclaw_instance_count，拼接容器名<prefix>-<i>（如openclaw-1）。
- 遍历配置项列表：
  - 若配置项包含value字段，执行docker exec <container> openclaw config set <path> <value>。
  - 若配置项不包含value字段，执行docker exec <container> openclaw config unset <path>（删除配置）。
- 异常处理规则：
  - 若config set返回"Config validation failed"或"Unrecognized key"，记录警告消息并跳过该项，不中断流程。
  - 若config unset返回"Config path not found"，记录提示消息并跳过该项，不中断流程。
  - 若容器不存在或其他严重错误，则终止当前节点升级并返回错误。
重启集群：
- 执行bash deploy.sh stop -c <config_dir>停止所有容器。
- 执行bash deploy.sh start -c <config_dir>重新启动所有容器。
重启成功则返回"Batch config update and restart success"，失败则捕获异常并返回错误信息。

批量配置文件格式

JSON数组格式，每个元素包含path（配置项路径）。若包含value字段则为新增/修改操作，若不包含value字段则为删除操作。示例：

[
  {
    "path": "agents.defaults.maxConcurrent",
    "value": 4
  },
  {
    "path": "browser.enabled",
    "value": true
  },
  {
    "path": "plugins.disabled_plugins"
  }
]

适用场景

需要批量新增、修改和删除多个OpenClaw实例的配置项。
无需更换镜像版本，仅调整运行时配置。
希望避免删除重建导致的容器重建开销。
注意：批量配置文件需提前分发到所有目标节点的指定路径，Ansible不会自动分发该文件。