香橙派AI Pro综合开发笔记 - 2

香橙派AI Pro综合开发笔记 - 2

4. Docker容器化环境配置与管理

4.1 Docker引擎安装与验证

  1. 安装Docker CE：通过官方仓库安装稳定版本。

    1
    2
    3
    4
    5
    6
    sudo apt update
    sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
    sudo add-apt-repository "deb [arch=arm64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
    sudo apt update
    sudo apt install -y docker-ce

  2. 验证安装：

    1
    sudo docker run hello-world

    成功运行将看到“Hello from Docker!”的欢迎信息。

4.2 解决Docker权限与网络问题

  • 权限拒绝错误（Permission Denied）：默认情况下，需sudo执行Docker命令。

    • 解决方案：将当前用户加入docker组，使其无需sudo。

      1
      sudo usermod -aG docker $USER

      关键步骤：执行此命令后，必须注销并重新登录或重启系统，组权限更改才会生效。之后可运行docker run hello-world验证。

  • 镜像拉取超时或失败：从Docker Hub拉取镜像速度慢。

    • 解决方案：配置国内镜像加速器。创建或编辑/etc/docker/daemon.json文件：

      1
      2
      3
      4
      5
      6
      {
        "registry-mirrors": [
          "https://docker.mirrors.ustc.edu.cn",
          "https://hub-mirror.c.163.com"
        ]
      }

      保存后，重启Docker服务：

      1
      sudo systemctl restart docker

      可使用docker info | grep Mirrors验证配置是否生效。

4.3 Docker容器与镜像管理

  • 常用命令一览：
    1
    2
    3
    4
    5
    6
    docker ps           # 查看运行中的容器
    docker ps -a        # 查看所有容器
    docker images       # 查看本地镜像
    docker rm <容器ID>   # 删除容器
    docker rmi <镜像ID>  # 删除镜像
    docker logs <容器ID> # 查看容器日志（故障排查关键）
  • 设置容器自启动：对于Nextcloud等关键服务容器，应设置--restart策略，使其在Docker服务启动或容器意外退出时自动重启。
    1
    docker update --restart=unless-stopped <容器名或ID>

4.4 解决容器内服务访问异常

  • 现象：通过CasaOS安装的应用（如Nextcloud）无法通过浏览器访问。
  • 诊断路径：
    1. 检查容器状态：docker ps 确认容器状态为 Up。
    2. 检查容器端口映射：docker port <容器名> 确认宿主机端口是否正确映射到容器内部端口（如 8088->80）。
    3. 检查容器内服务日志：docker logs --tail 50 <容器名> 查找应用启动过程中的错误信息。
    4. 进入容器诊断：docker exec -it <容器名> /bin/bash，在容器内部检查配置文件、网络连通性。

5. SSH远程访问深度配置

5.1 SSH服务安装与基础配置

  1. 安装OpenSSH服务器：
    1
    sudo apt install -y openssh-server
  2. 启动并启用开机自启：
    1
    sudo systemctl enable --now ssh
  3. 检查服务状态与监听端口：
    1
    2
    sudo systemctl status ssh
    sudo ss -tlnp | grep :22

5.2 连接失败问题诊断与解决

  • 现象：无法通过SSH客户端（如PuTTY）连接。
  • 系统化排查流程：

    1. 确认IP地址：在香橙派上执行 hostname -I，确保客户端使用正确的IP。

    2. 确认服务状态：sudo systemctl status ssh，状态应为 active (running)。若非，则使用 sudo systemctl restart ssh 重启。

    3. 检查端口监听：sudo ss -tlnp | grep :22。若无输出，可能SSH未启动或防火墙拦截。若监听地址为 127.0.0.1:22，则表示SSH仅绑定到本地环回地址，需修改配置文件 /etc/ssh/sshd_config，将 ListenAddress 行注释掉或改为 0.0.0.0，然后重启服务。

    4. 检查防火墙规则：

      1
      sudo ufw status

      若防火墙为 active 状态且未放行22端口，则需添加规则：

      1
      2
      sudo ufw allow ssh  # 或 sudo ufw allow 22/tcp
      sudo ufw reload

    5. 检查客户端连接命令或设置：确保命令格式正确 ssh username@ip_address。

5.3 高级配置：密钥对认证与免密登录

为提升安全性和便利性，建议使用密钥对替代密码登录。

  1. 在客户端生成密钥对（在Windows上可使用Git Bash或WSL）：

    1
    ssh-keygen -t ed25519 -C "your_email@example.com"

    默认将私钥保存在 ~/.ssh/id_ed25519，公钥为 id_ed25519.pub。

  2. 将公钥上传至香橙派：

    1
    ssh-copy-id username@your_orange_pi_ip

    或手动将公钥内容复制到香橙派的 ~/.ssh/authorized_keys 文件中。

  3. （可选）禁用密码登录：在 /etc/ssh/sshd_config 中设置 PasswordAuthentication no，然后重启SSH服务。务必在确认密钥登录成功后操作。

6. Nano文本编辑器使用详解

6.1 安装与基础编辑操作

  1. 安装Nano：
    1
    sudo apt update && sudo apt install -y nano
  2. 打开/创建文件：
    1
    nano 文件名
  3. 基础编辑：在界面中直接键入文本进行编辑。
  4. 保存与退出：
    • Ctrl + O：写入（保存）文件，按Enter确认文件名。
    • Ctrl + X：退出Nano。如果文件有未保存的更改，会提示是否保存。
  5. 核心快捷键提示：始终显示在编辑器底部两行。

6.2 高效编辑功能

  • 光标移动：
    • Ctrl + F：前进一个字符。
    • Ctrl + B：后退一个字符。
    • Ctrl + A：行首。
    • Ctrl + E：行尾。
  • 文本操作：
    • Ctrl + K：剪切当前行。
    • Ctrl + U：粘贴剪切的文本。
    • Alt + U：撤销。
    • Alt + E：重做。
  • 搜索与替换：
    • Ctrl + W：搜索文本，按Enter定位。
    • Alt + W：查找下一个。
    • Ctrl + \：搜索并替换。
  • 复制与标记：
    • Alt + A：开始标记文本（用于复制/剪切）。
    • 移动光标选择区域后，使用 Alt + 6 复制标记文本，或 Ctrl + K 剪切。

6.3 配置文件与排错

  • 启用语法高亮：Nano支持多种语言的语法高亮。通常高亮规则文件位于 /usr/share/nano/。可以在 ~/.nanorc 或个人配置中引用：
    1
    2
    include "/usr/share/nano/c.nanorc"   # C语言高亮
    include "/usr/share/nano/python.nanorc" # Python高亮
  • 常见问题：
    • 编辑系统文件时权限不足：使用 sudo nano 文件名。
    • 编辑时出现乱码：确保文件编码正确（如UTF-8）。保存时可使用 Ctrl + T 选择编码。

7. 智能音箱项目：集成DeepSeek与百度AI

7.1 项目概述与架构

本项目在香橙派上构建一个具备语音交互能力的智能助手。技术栈整合如下：

  • 语音输入：USB麦克风（或板载音频输入）。
  • 语音识别（ASR）：百度AI开放平台。
  • 自然语言处理（NLP）：DeepSeek API（兼容OpenAI格式）。
  • 语音合成（TTS）：百度AI开放平台。
  • 语音输出：3.5mm音频接口或USB音响。
  • 控制核心：Python脚本。

7.2 硬件准备与音频系统调试

此为项目最易出错的环节。

  1. 硬件连接：
    • 方案A（推荐）：使用USB麦克风音响一体设备，连接至USB端口。
    • 方案B（分体）：3.5mm麦克风接入麦克风接口，音箱接入音频输出接口。
  2. 音频设备检测与驱动故障排查：
    • 核心诊断命令：
      1
      2
      aplay -l   # 列出所有播放设备
      arecord -l # 列出所有录音设备
    • 问题：aplay -l 无输出（no soundcards found）。
      • 诊断：系统未加载音频驱动或内核不支持。
      • 解决路径：
        1. 更新并安装ALSA驱动包：sudo apt install -y alsa-base alsa-utils pulseaudio，然后重启。
        2. 检查内核模块：lsmod | grep snd，查看是否有 snd_soc_ 相关模块。
        3. 最终手段：若驱动无效，更换为香橙派官方提供或明确支持音频的社区镜像。这是解决硬件识别问题的根本方法。
    • 问题：设备列表中有卡，但播放/录音无声。
      • 检查音量设置：执行 alsamixer，使用方向键调整主音量（Master, PCM）并取消静音（按 M 键）。
      • 测试播放：aplay -D plughw:0,0 /usr/share/sounds/alsa/Front_Center.wav（请根据 aplay -l 输出调整 hw: 后的卡号与设备号）。
      • 测试录音：arecord -D plughw:1,0 -f cd -d 5 test.wav（请根据 arecord -l 输出调整设备号），然后播放此 test.wav 听效果。

7.3 云端API服务配置

  1. 百度AI开放平台：
    • 注册并登录，在控制台创建应用，获得 APP_ID、API_KEY、SECRET_KEY。
    • 启用“语音技术”相关服务。
  2. DeepSeek平台：
    • 注册并登录DeepSeek，在API管理页面创建新的API密钥 (sk-开头)。
    • 记录API基础地址，例如 https://api.deepseek.com。

7.4 软件环境部署与项目搭建

  1. 创建项目目录与虚拟环境：

    1
    2
    3
    4
    mkdir -p ~/voice_assistant/config
    cd ~/voice_assistant
    python3 -m venv venv
    source venv/bin/activate

  2. 安装Python依赖：

    1
    pip install pyaudio baidu-aip openai chardet requests
    • 注意：pyaudio 安装可能失败，需先安装系统库：sudo apt install -y portaudio19-dev python3-dev。

  3. 创建配置文件 (config/api_keys.json)：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    {
      "baidu": {
        "app_id": "你的百度APP_ID",
        "api_key": "你的百度API_KEY",
        "secret_key": "你的百度SECRET_KEY"
      },
      "llm": {
        "api_key": "你的DeepSeek_API_KEY",
        "api_base": "https://api.deepseek.com",
        "model": "deepseek-chat"
      }
    }

  4. 编写核心Python脚本 (assistant_core.py)：

    • 流程：录音 -> 百度ASR识别为文本 -> DeepSeek处理文本生成回复 -> 百度TTS合成语音 -> 播放。
    • 关键函数：需实现 record_audio(), baidu_asr(), get_llm_response(), baidu_tts(), play_audio()。
    • 播放函数示例（集成硬件测试成功的命令）：
      1
      2
      3
      import subprocess
      def play_audio(file_path):
          subprocess.run(['aplay', '-D', 'plughw:0,0', file_path], check=True)

7.5 项目集成与典型错误调试

  • 错误：百度API调用失败。
    • 检查 api_keys.json 中的密钥是否正确且未过期。
    • 检查网络连接：ping ai.baidu.com。
  • 错误：DeepSeek API返回404或401。
    • 404：通常为 api_base 填写错误。确保为 https://api.deepseek.com（无末尾斜杠或错误路径）。
    • 401：API密钥无效或未传递。检查密钥字符串是否正确，并确保代码中正确读取。
    • 使用 curl 命令测试API连通性：
      1
      curl https://api.deepseek.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
  • 错误：Python模块缺失（如No module named 'chardet'）。
    • 在虚拟环境中使用 pip install 安装缺失模块。
  • 错误：录音或播放时抛出ALSA相关异常。
    • 硬件驱动问题。返回 7.2节 重新进行音频系统调试。
    • 在代码中尝试使用不同的PyAudio参数或设备索引。

7.6 系统服务化与自启动

为使项目开机运行，可创建Systemd服务。

  1. 创建服务文件 (/etc/systemd/system/voice-assistant.service)：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    [Unit]
    Description=Voice Assistant Service
    After=network.target sound.target

    [Service]
    Type=simple
    User=orangepi
    WorkingDirectory=/home/orangepi/voice_assistant
    Environment="PATH=/home/orangepi/voice_assistant/venv/bin"
    ExecStart=/home/orangepi/voice_assistant/venv/bin/python assistant_core.py
    Restart=on-failure

    [Install]
    WantedBy=multi-user.target

  2. 启用并启动服务：

    1
    2
    3
    sudo systemctl daemon-reload
    sudo systemctl enable --now voice-assistant.service
    sudo systemctl status voice-assistant.service # 检查状态

上一篇
下一篇