Axon 手工配置说明

适用场景：

• 不使用自动脚本，手工为新设备部署 Axon

• 需要明确知道哪些文件必须修改

• 需要排查某台机器为什么没有按预期接入 Axon

如果不想手工逐步执行，也可以直接使用自动脚本：

bash scripts/setup_dc87_axon.sh --tag dc87 --host 192.168.112.248

文档后半部分提供了脚本用法说明和与手工步骤的对应关系。

以下示例以 dc87 为目标设备说明。

目标

把目标机器配置成：

1. ab_patch 中的 Axon 配置已经指向当前设备

2. Docker 中存在带 Axon 的镜像 1.0.1-axon

3. deploy/config.yaml 使用 1.0.1-axon

4. deploy/start.py 会直接使用本地镜像，并在进入容器前启动 Axon

前置条件

在操作前，先确认以下条件满足：

1. 目标设备已经在 keystone 中注册

2. 目标机器可 SSH 登录

3. 目标机器存在部署目录 /home/psibot/deploy

4. 本地或来源机器已经准备好 ab_patch

5. 目标机器可运行 Docker

6. 目标机器上执行 sudo 不受限

整体步骤

手工配置的顺序建议固定为：

1. 修改 ab_patch/recorder_config.yaml

2. 修改 ab_patch/transfer_config.yaml

3. 把 ab_patch 拷到目标机器

4. 运行 install_to_docker.sh

5. 修改 /home/psibot/deploy/config.yaml

6. 修改 /home/psibot/deploy/start.py

7. 启动 deploy 或手动执行 run_axon_tools.sh

8. 做最终校验

自动脚本用法

最常用写法

bash scripts/setup_dc87_axon.sh --tag dc87 --host 192.168.112.248

如果还希望在目标机器上直接重启容器内的 Axon 服务：

bash scripts/setup_dc87_axon.sh \
  --tag dc87 \
  --host 192.168.112.248 \
  --container ITW-release005-latest

参数说明

1. --tag <tag>

必填。设备标识，例如 dc87、dc93

2. --host <host>

目标机器。支持两种写法：

--host 192.168.112.248
--host psibot@192.168.112.248

  如果只传 IP，脚本会自动补成 psibot@<ip>。

3. --source-host <host>

可选。仅当本地没有 ab_patch 时，脚本会从这里拉取参考补丁目录。

默认值是：psibot@192.168.112.197

4. --keystone <host>

可选。用于生成 recorder 和 transfer 的 websocket 地址。

默认值是：192.168.112.215

5. --container <name>

可选。传入后脚本会在目标机器上执行：

run_axon_tools.sh <container_name> --force-restart

脚本实际做的事情

执行一次脚本，等价于手工做完下面这些步骤：

1. 本地没有 ab_patch 时，从参考机器拉取一份

2. 修改 ab_patch/recorder_config.yaml

3. 修改 ab_patch/transfer_config.yaml

4. 把 ab_patch 传到目标机器

5. 在目标机器执行 install_to_docker.sh

6. 修改目标机器上的 deploy/config.yaml

7. 修改目标机器上的 deploy/start.py

8. 如果指定了 --container，则执行 run_axon_tools.sh

9. 输出关键校验结果

常见示例

为 dc93 配置环境：

bash scripts/setup_dc87_axon.sh --tag dc93 --host 192.168.112.250

为 dc54 配置环境并重启 Axon 服务：

bash scripts/setup_dc87_axon.sh \
  --tag dc54 \
  --host 192.168.112.197 \
  --container ITW-release005-latest

本地没有 ab_patch，并从指定参考机器拉取：

bash scripts/setup_dc87_axon.sh \
  --tag dc87 \
  --host 192.168.112.248 \
  --source-host 192.168.112.197

第一步：修改 recorder_config.yaml

文件：ab_patch/recorder_config.yaml

需要修改的关键字段：

rpc:
  mode: ws_client
  ws_client:
    url: ws://192.168.112.215:8091/recorder/robot_dc87

需要注意

1. 这里的 robot_dc87 要和当前设备保持一致

2. 一般规则是：设备 tag 为 dc87，则写成 robot_dc87

3. 如果还是 robot_dc86，说明 recorder 仍然会按旧设备身份连接 keystone

4. 地址中的 192.168.112.215 是 keystone 地址，改环境时如果 keystone 变了，这里也要同步改

对照示例

dc86 上当前实际值：

url: ws://192.168.112.215:8091/recorder/robot_dc86

dc87 应改为：

url: ws://192.168.112.215:8091/recorder/robot_dc87

第二步：修改 transfer_config.yaml

文件：ab_patch/transfer_config.yaml

需要修改的关键字段：

device_id: "robot_dc87"

通常还要确认：

ws:
  url: "ws://192.168.112.215:8090/transfer"

需要注意

1. device_id 必须和 recorder 配置中的设备 ID 一致

2. 也就是 recorder_config.yaml 和 transfer_config.yaml 两边都要对应同一个 robot_<tag>

3. 如果一个文件改了，另一个没改，会出现同一台机器以两个不同身份接入的问题

4. ws.url 通常是 transfer 服务地址，不一定每次都要改，但切环境时必须确认

对照示例

dc86 上当前实际值：

device_id: "robot_dc86"
ws:
  url: "ws://192.168.112.215:8090/transfer"

dc87 应改为：

device_id: "robot_dc87"
ws:
  url: "ws://192.168.112.215:8090/transfer"

第三步：拷贝 ab_patch 到目标机器

如果本地还没有 ab_patch，可以先从参考机器拷一份到当前目录。

示例：

scp -r psibot@192.168.112.197:/home/psibot/ab_patch ./

需要注意

1. 只有在本地没有 ab_patch 时才需要这一步

2. 如果本地已经有可用版本，通常不需要重新覆盖

3. 从参考机器拉下来后，仍然要把其中的 robot_dc86 改成当前设备对应的 tag

示例：

scp -r ab_patch psibot@192.168.112.248:~/

需要注意

1. 拷贝前先确认你本地 ab_patch 里的两个 yaml 已经改对

2. 如果目标机器已存在旧的 ~/ab_patch，再次拷贝会覆盖或叠加内容，要确认是否为你期望的版本

3. 最好拷贝后在目标机器再检查一遍关键字段

第四步：生成 Axon 镜像

先看 deploy/config.yaml 当前使用的基础镜像是什么，再基于它生成新镜像。

当前常见基础镜像：

repository: "docker-registry.psibot.net/synrobot/x86/release/1.0.3"
tag: "latest"

在目标机器上执行：

cd ~/ab_patch
bash install_to_docker.sh \
  docker-registry.psibot.net/synrobot/x86/release/1.0.3:latest \
  docker-registry.psibot.net/synrobot/x86/release/1.0.1-axon:latest

这个步骤做了什么

1. 启动一个基础镜像临时容器

2. 把 ab_patch 下的 .deb 包装进容器

3. 把 recorder_config.yaml 和 transfer_config.yaml 复制到 /etc/axon/

4. 提交成新的镜像 1.0.1-axon:latest

需要注意

1. 不要跳过这一步，否则 deploy 改成 1.0.1-axon 后会找不到镜像

2. 如果基础镜像版本不是 1.0.3:latest，命令里的第一个参数也要跟着变

3. 如果目标机器拉不到基础镜像，需要先解决 Docker 登录或网络问题

第五步：修改 deploy/config.yaml

文件：/home/psibot/deploy/config.yaml

1. 修改镜像仓库

把：

repository: "docker-registry.psibot.net/synrobot/x86/release/1.0.3"

改为：

repository: "docker-registry.psibot.net/synrobot/x86/release/1.0.1-axon"

2. 挂载 Axon 配置文件

在 volumes: 下增加：

  - source: "/home/psibot/ab_patch/recorder_config.yaml"
    target: "/etc/axon/recorder_config.yaml"
    enabled: true
    options: "ro"

  - source: "/home/psibot/ab_patch/transfer_config.yaml"
    target: "/etc/axon/transfer_config.yaml"
    enabled: true
    options: "ro"

需要注意

1. 这一步虽然 README 标成可选，但实际建议加上

2. 不挂载的话，后续你改 ~/ab_patch/*.yaml 不会自动反映到容器里

3. 挂载后，改主机上的 yaml 更容易调试

4. source 路径必须和目标机器上的实际位置一致

第六步：修改 deploy/start.py

文件：/home/psibot/deploy/start.py

1. 修_pull_image

找到：

def _pull_image(self, image_name: str) -> bool:

改成函数一进入就直接：

def _pull_image(self, image_name: str) -> bool:
    return True

这样做的原因

deploy 原逻辑会去拉远端镜像，但这里我们希望直接使用目标机器本地已经制作好的 1.0.1-axon 镜像。

2. 在进入容器前启动 Axon

在下面这段附近：

        # 设置 bashrc
        self._setup_bashrc(container_name)

并且在 # 进入容器 之前插入：

        axon_sh = self.script_dir / "../ab_patch/run_axon_tools.sh"
        if axon_sh.is_file():
            subprocess.run(["bash", str(axon_sh), container_name], check=False)

这样做的原因

手套采集启动时，Axon recorder 和 transfer 也要一起起来。否则容器起来了，但 Axon 没启动，数据不会按预期上传或记录。

第七步：运行 run_axon_tools.sh

有两种方式：

方式 1：通过 deploy 自动拉起

如果上一步 start.py 已经改好，那么正常启动 deploy 时，会自动执行：

bash /home/psibot/ab_patch/run_axon_tools.sh <container_name>

方式 2：手工执行

如果你只是想补启动 Axon，可以手工运行：

bash ~/ab_patch/run_axon_tools.sh ITW-release005-latest

需要注意

1. run_axon_tools.sh 需要传入已经运行中的容器名

2. 它会在容器中启动 axon-recorder 和 axon-transfer

3. 如果 tmux 会话 axon 已经存在，脚本会提示是否重建

4. 如果容器还没起来，脚本会直接报错

自动脚本 scripts/setup_dc87_axon.sh 在传入 --container 时，会使用 --force-restart 调用 run_axon_tools.sh，避免因为已存在的 tmux 会话卡在交互确认。

第八步：最终校验

建议至少检查以下内容。

1. 检查 ab_patch 配置

grep -nE 'robot_dc87|device_id:|url:' ~/ab_patch/recorder_config.yaml ~/ab_patch/transfer_config.yaml

预期至少看到：

url: ws://192.168.112.215:8091/recorder/robot_dc87
device_id: "robot_dc87"
url: "ws://192.168.112.215:8090/transfer"

2. 检查镜像是否已生成

docker images | grep 1.0.1-axon

3. 检查 deploy/config.yaml

grep -nE 'repository:|recorder_config.yaml|transfer_config.yaml' ~/deploy/config.yaml

4. 检查 deploy/start.py

grep -nE 'def _pull_image|run_axon_tools.sh' ~/deploy/start.py

5. 检查 Axon 进程是否已拉起

如果容器名是 ITW-release005-latest：

docker exec -it ITW-release005-latest tmux ls
docker exec -it ITW-release005-latest tmux attach -t axon

常见问题

1. recorder 还是显示旧设备 ID

原因通常是：

1. ab_patch/recorder_config.yaml 没改

2. 改了本地文件，但没有重新拷到目标机器

3. 容器内仍然使用旧配置，没有挂载 host 上的 yaml

2. transfer 连接的是旧设备

优先检查：

device_id: "robot_xxx"

这个字段是否和当前设备一致。

3. deploy 启动时报镜像相关错误

优先检查：

1. install_to_docker.sh 是否真正执行成功

2. docker images | grep 1.0.1-axon 是否能看到镜像

3. config.yaml 的 repository 是否已经改为 1.0.1-axon

4. Axon 没起来

优先检查：

1. start.py 是否插入了 run_axon_tools.sh

2. 容器是否已经运行

3. 手工执行 bash ~/ab_patch/run_axon_tools.sh <container_name> 是否报错

4. 容器里 tmux 是否已经创建 axon 会话

5. deploy 文件无法修改

如果 /home/psibot/deploy 属于 root:root，需要用 sudo 修改：

sudo vi /home/psibot/deploy/config.yaml
sudo vi /home/psibot/deploy/start.py

最小检查清单

如果只想快速确认是否配好，至少检查下面 6 项：

1. recorder_config.yaml 里的 robot_<tag> 是否正确

2. transfer_config.yaml 里的 device_id 是否正确

3. 目标机器 ~/ab_patch 是否是最新版本

4. docker images 中是否已有 1.0.1-axon

5. ~/deploy/config.yaml 是否引用 1.0.1-axon

6. ~/deploy/start.py 是否包含 return True 和 run_axon_tools.sh

自动脚本补充说明

scripts/setup_dc87_axon.sh 的 --host 和 --source-host 支持两种写法：

--host psibot@192.168.112.248
--host 192.168.112.248

如果只传 IP，脚本会自动补成 psibot@<ip>。

如果传了其他用户名，例如 kvzjj@192.168.112.250，脚本会直接使用你传入的用户名，不会自动替换。

推荐做法

手工配置时，建议每完成一步就做一次小检查，不要全部改完再一起排错。

推荐顺序：

1. 先改本地 ab_patch

2. 本地确认字段正确

3. 再拷贝到目标机器

4. 在目标机器生成镜像

5. 再改 deploy

最后启动并看 tmux/日志
tmux a

ctrl+b,  n 切换
ctrl+b, c  创建新窗口
ctrl+b,  d,  退出tmux

自动化部署脚本

setup_dc87_axon.sh