版本：V2.0.5.x

2.3.分步详解

步骤 1：配置远程服务器信息

REMOTE_USER="ubuntu"      # x86 服务器登录用户名
REMOTE_IP="192.168.41.1"  # x86 服务器 IP
REMOTE_DIR="/home/ubuntu" # x86 上的工作目录

RELEASE_DIR="tkvoice_release_0.3.25_0324_101621"  # 解压目录名

作用：定义连接参数，后续所有远程操作都基于这些变量。

步骤 2：验证安装包完整性

# 检查 tar 包是否存在
if [ ! -f "${RELEASE_DIR}.tar" ]; then
    echo "[ERROR] 找不到 ${RELEASE_DIR}.tar"
    exit 1
fi

# 检查 tar 包内是否有必需的目录
if ! tar -tf "${RELEASE_DIR}.tar" | grep -q "${RELEASE_DIR}/res/docker_funasr/"; then
    echo "[ERROR] tar 包中未找到 ${RELEASE_DIR}/res/docker_funasr/"
    exit 1
fi

作用：防止后续出现错误。

原理：

[ ! -f file ] - 检查文件是否不存在
tar -tf - 列出 tar 包内容（不解压）
grep -q - 静默搜索（只返回 0/1）

失败排查：

# 检查 tar 包是否损坏
tar -tzf "${RELEASE_DIR}.tar" > /dev/null

# 列出 tar 包中的目录
tar -tf "${RELEASE_DIR}.tar" | head -20

步骤 3：解压 ASR 相关文件到本地

cd "${PARENT_DIR}"
tar -xvf "${RELEASE_DIR}.tar" \
    "${RELEASE_DIR}/uninstall.sh" \
    "${RELEASE_DIR}/res/docker_funasr/"

作用：只解压 ASR 相关的文件（节省时间和空间），不解压整个包。

参数说明：

-x : 解压
-v : 显示详细信息
-f : 指定文件
最后的参数是要解压的路径（可以指定多个）

结果：

当前目录/
└── tkvoice_release_0.3.25_0324_101621/
    ├── uninstall.sh
    ├── res/
    │   └── docker_funasr/
    │       ├── install_asr.sh
    │       ├── startup.sh
    │       ├── uninstall_asr.sh
    │       └── ... (其他 Docker 相关文件)
    └── ... (其他暂未解压)

步骤 4：传输 docker_funasr 到 x86 服务器

rsync -av --progress --delete -e "ssh -o StrictHostKeyChecking=no" \
    res/docker_funasr \
    ${REMOTE_USER}@${REMOTE_IP}:${REMOTE_DIR}/

作用：通过 SSH 安全传输 ASR Docker 文件到 x86。

rsync 参数详解：

参数	作用	说明
`-a`	archive 模式	保留权限、时间戳、符号链接
`-v`	verbose	显示详细信息
`--progress`	显示进度	每个文件的传输百分比
`--delete`	删除多余文件	远程目录与本地完全同步
`-e ssh`	使用 SSH	而不是默认的 rsh
`StrictHostKeyChecking=no`	跳过密钥确认	无需手动输入 yes

传输过程示例：

sending incremental file list
res/docker_funasr/
res/docker_funasr/install_asr.sh
           1.2K 100%    1.15MB/s    0:00:00 (xfer#1, to-check=5/7)
res/docker_funasr/startup.sh
           2.5K 100%    2.43MB/s    0:00:00 (xfer#2, to-check=4/7)
...

sent 2,500 bytes  received 35 bytes  5,070 bytes/sec
total size is 50,000  speedup is 19.92

如果传输失败：

# 检查 SSH 连接
ssh -i ~/.ssh/id_rsa ubuntu@192.168.41.1 "echo 'SSH 连接成功'"

# 检查目标目录权限
ssh ubuntu@192.168.41.1 "ls -la /home/ubuntu/"

# 手动传输（如果 rsync 不可用）
scp -r res/docker_funasr ubuntu@192.168.41.1:/home/ubuntu/

步骤 5：在 x86 上执行 ASR 安装脚本

ssh -t ${REMOTE_USER}@${REMOTE_IP} \
    "cd ${REMOTE_DIR}/docker_funasr && bash install_asr.sh"

作用：在 x86 服务器上远程执行 ASR Docker 安装。

参数说明：

-t : 分配伪终端（交互式 SSH）
命令被引号括起来，作为远程服务器执行的脚本

实际执行的内容：

x86 上的 install_asr.sh 会做以下事情：

安装 Docker（如果未安装）
加载或拉取 Funasr Docker 镜像
启动 Funasr 容器，监听 192.168.41.1:10097

监控远程执行：

如果需要看到远程执行的详细输出，可以修改为：

ssh ${REMOTE_USER}@${REMOTE_IP} \
    "cd ${REMOTE_DIR}/docker_funasr && bash -x install_asr.sh"
# -x 参数会打印每条执行的命令

步骤 6：删除本地临时 ASR 文件

cd "${BASE_DIR}/res"
rm -rf docker_funasr

作用：释放本地磁盘空间，ASR 文件已同步到 x86，无需保留副本。

步骤 7：安装 Python 依赖包

7.1 解压依赖包

tar -xvf "${RELEASE_DIR}.tar" \
    "${RELEASE_DIR}/res/onnxruntime-1.23.2-cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl" \
    "${RELEASE_DIR}/res/onnxruntime_gpu-1.20.1-cp310-cp310-linux_aarch64.whl" \
    "${RELEASE_DIR}/res/piper_tts-1.3.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl"

作用：只解压需要的 Python 包（wheel 格式）。

包的说明：

包名	版本	用途	说明
onnxruntime	1.23.2	CPU 推理	Piper TTS 和其他 ONNX 模型
onnxruntime_gpu	1.20.1	GPU 推理	使用 Orin 的 GPU 加速
piper_tts	1.3.0	TTS 合成	文本转语音库

文件名格式说明：

piper_tts-1.3.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl
├─ 1.3.0          : 包版本
├─ cp39           : CPython 3.9+
├─ abi3           : 稳定 ABI（向后兼容）
├─ aarch64        : ARM 64 位架构
└─ manylinux_2_x  : Linux 发行版兼容性

7.2 卸载旧版本

python3 -m pip uninstall onnxruntime piper-tts onnxruntime-gpu -y || \
sudo python3 -m pip uninstall onnxruntime piper-tts onnxruntime-gpu -y || \
true

作用：清除旧版本，防止版本冲突。

7.3 安装 ONNX Runtime CPU 和 TTS

python3 -m pip install --no-cache-dir \
    onnxruntime-1.23.2-cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl \
    piper_tts-1.3.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl \
    websockets==15.0.1

作用：安装 TTS 和网络库。

参数说明：

--no-cache-dir : 不保存缓存，节省磁盘空间
.whl 文件 : 本地轮包（预编译）
websockets : WebSocket 库（用于 Funasr 通信）

版本选择原因：

websockets==15.0.1 : 与 Funasr 通信兼容

7.4 卸载 CPU 版 ONNX Runtime

python3 -m pip uninstall onnxruntime -y || \
sudo python3 -m pip uninstall onnxruntime -y || \
true

作用：移除 CPU 版本，为 GPU 版本让位。

7.5 安装 GPU 版 ONNX Runtime

python3 -m pip install --no-cache-dir \
    onnxruntime_gpu-1.20.1-cp310-cp310-linux_aarch64.whl

作用：安装 GPU 加速版本，使 TTS 推理更快。

性能对比：

CPU 版本：生成 1 秒语音需要 ~0.5 秒
GPU 版本：生成 1 秒语音需要 ~0.1 秒（5 倍加速）

为什么分开安装：

CPU 版和 GPU 版的 onnxruntime 冲突，需要先安装 CPU 版（piper_tts 依赖），再替换为 GPU 版。

7.6 清理 wheel 文件

rm -f *.whl

作用：删除已安装的 wheel 包，释放磁盘空间（可节省约 500MB）。

步骤 8：安装 Ollama

8.1 解压 Ollama 脚本

tar -xvf "${RELEASE_DIR}.tar" \
    "${RELEASE_DIR}/res/ollama/uninstall_ollama.sh" \
    "${RELEASE_DIR}/res/ollama/install_ollama.sh" \
    "${RELEASE_DIR}/res/ollama/import_ollama_model.sh"

作用：解压 Ollama 安装和卸载脚本。

8.2 执行 Ollama 安装

主要逻辑就是到要安装Ollama的orin板上执行如下脚本：

cd "${BASE_DIR}/res/ollama"
./install_ollama.sh "${PARENT_DIR}" "${RELEASE_DIR}"

实际的安装，针对无疆，会在 192.168.41.3 上进行，主要是为了减少41.2上的磁盘空间占用。针对无界，会在 192.168.41.2 上进行。

参数说明：

${PARENT_DIR} : 工作目录路径
${RELEASE_DIR} : 解压目录名

install_ollama.sh 会做什么：

检测 Ollama 是否已安装
如果未安装，下载并安装 Ollama
启动 Ollama 服务
导入 qwen2.5:1.5b 模型

8.3 清理 Ollama 临时文件

sudo find "${BASE_DIR}/res/ollama" \
    -mindepth 1 \
    ! -name 'uninstall_ollama.sh' \
    -exec rm -rf {} +

参数说明：

-mindepth 1 : 不删除目录本身，只删除内容
! -name : 排除（不删除）uninstall 脚本
-exec rm -rf {} + : 对每个匹配的项执行删除

结果：保留卸载脚本以便后续维护。

步骤 9：解压主项目文件

tar -xvf "${RELEASE_DIR}.tar" \
    "${RELEASE_DIR}/tkvoice.sh" \
    "${RELEASE_DIR}/version.txt" \
    "${RELEASE_DIR}/res/piper_voices/" \
    "${RELEASE_DIR}/src/"

关键文件：

文件/目录	用途	说明
`tkvoice.sh`	启动脚本	用于管理服务（启动/停止/重启）
`version.txt`	版本信息	版本追踪
`res/piper_voices/`	TTS 语音模型	中文语音（huayan-medium）
`src/`	源代码	audio_message 和 audio_service 包

步骤 10：编译 ROS 2 包

cd "${BASE_DIR}"
echo "[INFO] 开始编译 ROS2 包 audio_message 与 audio_service..."
colcon build --packages-select audio_message audio_service
echo "[OK] ROS2 包编译完成"

作用：使用 colcon 编译 ROS 2 包。

编译过程：

Starting >>> audio_message
Finished <<< audio_message [0.5s]
Starting >>> audio_service
[100%] Linking CXX executable ...
[100%] Built target ...
Finished <<< audio_service [5.2s]

Summary: 2 packages finished

编译结果：

${BASE_DIR}/
├── build/      # 中间构建文件
├── install/    # 安装的包（ROS 环境使用）
├── log/        # 编译日志
└── src/        # 源代码

常见编译错误：

错误	原因	解决
`ament_cmake not found`	ROS 2 环境未初始化	`source /opt/ros/humble/setup.bash`
`Permission denied`	用户权限不足	`sudo chown -R $USER:$USER build install`
`Package not found`	依赖未安装	检查 package.xml 依赖

步骤 11：完成提示

echo "✅ tkvoice服务已成功安装，可用如下命令进行管理:"
echo ""
echo "# 启动服务"
echo "./tkvoice.sh start"

步骤 1：配置远程服务器信息​

步骤 2：验证安装包完整性​

步骤 3：解压 ASR 相关文件到本地​

步骤 4：传输 docker_funasr 到 x86 服务器​

步骤 5：在 x86 上执行 ASR 安装脚本​

步骤 6：删除本地临时 ASR 文件​

步骤 7：安装 Python 依赖包​

7.1 解压依赖包​

7.2 卸载旧版本​

7.3 安装 ONNX Runtime CPU 和 TTS​

7.4 卸载 CPU 版 ONNX Runtime​

7.5 安装 GPU 版 ONNX Runtime​

7.6 清理 wheel 文件​

步骤 8：安装 Ollama​

8.1 解压 Ollama 脚本​

8.2 执行 Ollama 安装​

8.3 清理 Ollama 临时文件​

步骤 9：解压主项目文件​

步骤 10：编译 ROS 2 包​

步骤 11：完成提示​

步骤 1：配置远程服务器信息

步骤 2：验证安装包完整性

步骤 3：解压 ASR 相关文件到本地

步骤 4：传输 docker_funasr 到 x86 服务器

步骤 5：在 x86 上执行 ASR 安装脚本

步骤 6：删除本地临时 ASR 文件

步骤 7：安装 Python 依赖包

7.1 解压依赖包

7.2 卸载旧版本

7.3 安装 ONNX Runtime CPU 和 TTS

7.4 卸载 CPU 版 ONNX Runtime

7.5 安装 GPU 版 ONNX Runtime

7.6 清理 wheel 文件

步骤 8：安装 Ollama

8.1 解压 Ollama 脚本

8.2 执行 Ollama 安装

8.3 清理 Ollama 临时文件

步骤 9：解压主项目文件

步骤 10：编译 ROS 2 包

步骤 11：完成提示