• 人工智能
• 强化学习
• 计算机视觉
• 游戏开发
• 测试

本篇技术指南聚焦于如何在 macOS 母机上，通过 Docker 容器方式运行基于图像的游戏 AI 自动化框架 GameAISDK 及其配套可视化配置工具 SDKTool。文章完整覆盖从基础环境安装（Docker、socat、XQuartz、adbkit）、镜像导入与容器挂载、容器内动态库配置、图形显示链路打通、Android 手机 TCP 桥接，到最终启动 SDKTool 的每一个关键步骤。读完本文，你将能够在 Mac 上独立搭建一套"容器跑 AI、母机出界面、手机供图像"的完整可运行环境，并掌握 Docker 部署 AISDK 的底层原理。

一、部署方案与整体架构

GameAISDK 本身是运行在 Linux 环境下的图像识别与 AI 推理框架。为了让 Windows / macOS 用户也能直接使用，官方提供了基于 Docker 的部署方案：AISDK 与 SDKTool 运行在 Linux 容器中，而消费 AISDK 服务的 AIClient 依旧运行在母机上（见 doc/dockerdeployment/UseGuide.md）。对于 SDKTool 这类带界面的工具，则通过显示重定向的方式，把容器内界面显示到母机桌面上。

因此在 macOS 上需要额外安装四类工具：

说明：Windows 侧对应方案是使用 VcXsrv 替代 XQuartz 完成显示映射（参考 doc/dockerdeployment/BaseInstall.md），本文只讨论 macOS 环境。

二、基础环境安装

以下命令均在 macOS 终端中执行，前提是本机已安装 Homebrew。

1. 安装 Docker

brew install docker

安装完成后，打开 Docker 应用，并在终端执行docker version验证安装成功（能正常输出版本信息即说明 Docker 服务可用）。

2. 安装 socat

brew install socat # 可能需要 cask 命令安装: brew cask install socat

socat 是一个强大的双向数据转发工具。在本方案中，它负责把 macOS 本机的 X11 显示服务（unix socket）暴露为 TCP 端口，从而让容器内的图形程序（SDKTool 的 UI）能够把画面画到母机屏幕上。

3. 安装 XQuartz

brew install xquartz

XQuartz 是 macOS 下的 X11 显示服务器，承担"将容器中显示的内容映射到母机"的角色（doc/dockerdeployment/BaseInstall.md 中明确说明容器内自身无法显示、会报错，必须依赖此类工具）。

4. 安装 adbkit

brew install node npm i -g adbkit

adbkit 是 Node.js 生态下的 ADB 客户端工具包，用于把 USB 直连母机的 Android 手机，桥接成网络端口供容器内访问。

三、启动 Docker 并导入 AISDK 镜像

1. 启动 Docker

启动 Docker Desktop（Mac 版），确认其处于运行状态（Docker 图标常驻菜单栏）。

2. 导入镜像并运行容器

官方镜像默认以文件形式分发，导入命令为：

docker load -i xx

其中xx为镜像文件路径（原文档写作docker load -I xx，实际 Docker 参数为小写-i，即--input）。

导入完成后，以挂载方式启动容器，将母机上的项目目录映射进容器：

docker run -v /Users/et/Downloads/game_ai_sdk:/data1/game_ai_sdk -it xx /bin/bash

参数说明：

• -v /Users/et/Downloads/game_ai_sdk:/data1/game_ai_sdk：把母机上的 GameAISDK 工程目录挂载到容器内固定路径/data1/game_ai_sdk。容器内的构建产物、配置修改都会实时同步回母机，这是后续在容器中编译、运行的基础；
• -it：以交互模式进入容器；
• xx：镜像名称（如836304831/aisdk:tagname或本地导入的镜像 tag）；
• /bin/bash：进入容器后启动 bash shell。

该挂载路径约定与 doc/dockerdeployment/UseGuide.md 中docker run -v /Users/{username}/workspace_code/game_ai_sdk:/data1/game_ai_sdk -it -p 8898:8898 -p 8899:8899 836304831/aisdk:tagname /bin/bash的用法一致；若需让 AISDK 服务对外提供端口，可额外追加-p 8898:8898 -p 8899:8899暴露服务端口。

四、容器内环境准备：拷贝动态库

进入容器后，需要先把 AISDK 依赖的共享库安装到系统库目录：

cp *.so* /usr/local/lib

该命令把工程中的*.so*（动态链接库）复制到/usr/local/lib，随后刷新动态链接器缓存：

ldconfig

ldconfig会重新扫描并更新动态链接库缓存，确保后续启动程序时能正确找到刚拷贝的 so 库。

五、打通图形显示链路：socat + XQuartz

SDKTool 是图形界面程序，运行在容器内，必须把界面"画"到 macOS 母机屏幕上，这依赖 X11 协议链路的三个环节。

1. 启动 socat（容器内或母机终端）

在终端执行：

socat TCP-LISTEN:6000,reuseaddr,fork UNIX-CLIENT:\"$DISPLAY\"

含义拆解：

• TCP-LISTEN:6000,reuseaddr,fork：在 TCP 6000 端口监听，reuseaddr允许端口快速复用，fork为每个连接派生子进程处理；
• UNIX-CLIENT:"$DISPLAY"：把收到的 TCP 流量转发到本机 X11 的 unix socket（$DISPLAY是 X 显示服务地址环境变量）。

这样就建立起"容器内 X11 程序 → TCP 6000 → 母机 X11 socket"的转发通道。启动成功截图如下：

2. 启动 XQuartz

在母机终端执行：

open -a xquartz

打开 XQuartz 应用后，需要确认 X11 服务器处于监听状态。

3. XQuartz 相关设置

为保证容器内界面正常显示、鼠标键盘事件正常回传，需要在 XQuartz 的偏好设置中确认以下选项（对应设置界面截图）：

• 允许网络连接（允许来自 TCP 的 X 连接）；
• 启用"粘贴板同步"（Sync pasteboard）与"键盘输入同步"（Sync keyboard），便于在容器内复制粘贴文本；
• 输入设置中勾选"遵循 macOS 键盘布局"（Follow system keyboard layout），避免中文输入法或特殊按键在容器内失效。

六、连接 Android 手机：USB 转 TCP 桥接

AISDK 的图像识别数据来自 Android 手机屏幕，因此需要让运行在容器内的 AI 服务能访问到手机。

1. 母机上查看手机序列号

adb devices

确保手机开启 USB 调试并已连接母机，输出中会出现类似xxxxxxxx device的序列号。

2. 将 USB 设备转发为 TCP 端口

adbkit usb-device-to-tcp -p 7788 序列号

该命令把指定序列号的 USB 设备桥接到母机的7788TCP 端口。转发成功后，母机上的 7788 端口即代表这台手机。

该端口号与仓库内置一键脚本 tools/docker/start_mac_docker.sh 及 Windows 侧脚本 tools/docker/start_win_docker.bat 中使用的-p 7788完全一致。

3. 容器内连接手机

回到容器终端，执行：

adb connect host.docker.internal:7788

host.docker.internal是 Docker 提供的特殊域名，指向宿主机（macOS）。此命令让容器内的 adb 通过母机的 7788 端口与手机建立连接，返回connected to host.docker.internal:7788即表示链路打通。

至此，完整数据链路为：

容器内 AISDK/adb → host.docker.internal:7788 → 母机 adbkit 桥接 → USB → Android 手机

七、启动 SDKTool 工具

容器内完成上述所有准备后，进入 SDKTool 目录并启动：

python main.py

SDKTool 的入口即仓库中的 tools/SDKTool/main.py。启动后，由于 X11 链路已打通，界面会直接显示在 macOS 母机桌面上，之后就可以进行游戏识别的相关配置工作。

补充：若 SDKTool 集成了 AISDK 功能（如 doc/dockerdeployment/UseGuide.md 所述），容器内还需先完成编译：cd /data1/game_ai_sdk/build && ./build_modules.sh {GPU|CPU} && ./build.sh {GPU|CPU}，参数 GPU 或 CPU 依自身环境决定。

八、一键启动脚本参考

仓库在 tools/docker/start_mac_docker.sh 中提供了 macOS 侧的自动化脚本，将上述手工步骤合并为一次执行：

socat TCP-LISTEN:6000,reuseaddr,fork UNIX-CLIENT:\"$DISPLAY\" & open -a xquartz & adb devices |awk 'NR==2 {print $1}' |xargs adbkit usb-device-to-tcp -p 7788 & path=$(dirname $(dirname `pwd`)) echo 'project path:' $path docker run -v $path:/data1/game_ai_sdk -it base_aisdktoolclt_ubt16:debug-2.0.2 /bin/bash /data1/game_ai_sdk/bin/docker_start_service.sh

脚本要点：

• 并行后台启动 socat 与 XQuartz；
• 通过adb devices自动提取第一个设备序列号，交给adbkit usb-device-to-tcp -p 7788完成桥接；
• 以当前工程目录的上一级为挂载源，运行容器并执行容器内的服务启动脚本（对应 bin/start.sh 中的start_ui_ai.sh/start_ai.sh/start_ui.sh等入口）。

Windows 侧可参照 tools/docker/start_win_docker.bat，流程一致（VcXsrv + adbkit 7788 + 容器挂载）。

九、常见问题与注意事项

• 容器内无法显示界面/报错：多为 X11 链路未打通。请依次确认 socat 正在监听 6000 端口、XQuartz 已启动并允许网络连接，以及$DISPLAY环境变量指向正确；
• adb connect 失败：确认母机上adbkit usb-device-to-tcp -p 7788仍在运行，且手机 USB 调试授权已通过（adb devices显示为device而非unauthorized）；
• 动态库加载失败：回到容器重新执行cp *.so* /usr/local/lib与ldconfig；
• 挂载目录注意：-v的左侧路径必须真实存在于母机，且为 Docker Desktop 允许共享的目录（macOS 默认无需额外配置，Windows 需在 Docker Settings → Resources → FILE SHARING 中添加共享目录，见 doc/dockerdeployment/BaseInstall.md）；
• 镜像来源：官方亦提供在线镜像docker pull 836304831/aisdk:tagname与docker pull 836304831/sdktool:tagname（tag 以实际发布为准），使用方式见 doc/dockerdeployment/UseGuide.md。

十、总结

本文完整还原了 doc/environment/MacDockerInstall.md 的 macOS Docker 部署流程，并结合 doc/dockerdeployment/BaseInstall.md、doc/dockerdeployment/UseGuide.md 与仓库脚本 tools/docker/start_mac_docker.sh 对其原理做了源码级说明。核心要点可归纳为：

1. 四件套依赖：Docker 承载运行、socat 转发 X11、XQuartz 显示界面、adbkit 桥接手机；
2. 两条链路：图形链路（容器 → TCP 6000 → XQuartz → 母机桌面）与设备链路（容器 → host.docker.internal:7788 → adbkit → USB → 手机）；
3. 一条命令启动：挂载工程后python main.py即可在母机桌面上使用 SDKTool 完成游戏 AI 配置。

• 人工智能
• 强化学习
• 计算机视觉
• 游戏开发
• 测试