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

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

4.1 Docker引擎安装与验证

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

bash 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. 验证安装：

bash sudo docker run hello-world

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

4.2 解决Docker权限与网络问题

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

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

    bash sudo usermod -aG docker $USER

    关键步骤：执行此命令后，必须注销并重新登录或重启系统，组权限更改才会生效。之后可运行docker run hello-world验证。 * 镜像拉取超时或失败：从Docker Hub拉取镜像速度慢。 * 解决方案：配置国内镜像加速器。创建或编辑/etc/docker/daemon.json文件：

    json { "registry-mirrors": [ "https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com" ] }

    保存后，重启Docker服务：

    bash sudo systemctl restart docker

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

4.3 Docker容器与镜像管理

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

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

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

5. SSH远程访问深度配置

5.1 SSH服务安装与基础配置

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

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

  • 现象：无法通过SSH客户端（如PuTTY）连接。
  • 系统化排查流程：
  • 确认IP地址：在香橙派上执行 hostname -I，确保客户端使用正确的IP。
  • 确认服务状态：sudo systemctl status ssh，状态应为 active (running)。若非，则使用 sudo systemctl restart ssh 重启。
  • 检查端口监听：sudo ss -tlnp | grep :22。若无输出，可能SSH未启动或防火墙拦截。若监听地址为 127.0.0.1:22，则表示SSH仅绑定到本地环回地址，需修改配置文件 /etc/ssh/sshd_config，将 ListenAddress 行注释掉或改为 0.0.0.0，然后重启服务。

  • 检查防火墙规则：

    bash sudo ufw status

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

    bash sudo ufw allow ssh # 或 sudo ufw allow 22/tcp sudo ufw reload 5. 检查客户端连接命令或设置：确保命令格式正确 ssh username@ip_address。

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

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

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

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

默认将私钥保存在 ~/.ssh/id_ed25519，公钥为 id_ed25519.pub。 2. 将公钥上传至香橙派：

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

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 或个人配置中引用： bash 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. 硬件连接：
  2. 方案A（推荐）：使用USB麦克风音响一体设备，连接至USB端口。
  3. 方案B（分体）：3.5mm麦克风接入麦克风接口，音箱接入音频输出接口。
  4. 音频设备检测与驱动故障排查：
  5. 核心诊断命令： bash aplay -l # 列出所有播放设备 arecord -l # 列出所有录音设备
  6. 问题：aplay -l 无输出（no soundcards found）。
    • 诊断：系统未加载音频驱动或内核不支持。
    • 解决路径：
    • 更新并安装ALSA驱动包：sudo apt install -y alsa-base alsa-utils pulseaudio，然后重启。
    • 检查内核模块：lsmod | grep snd，查看是否有 snd_soc_ 相关模块。
    • 最终手段：若驱动无效，更换为香橙派官方提供或明确支持音频的社区镜像。这是解决硬件识别问题的根本方法。
  7. 问题：设备列表中有卡，但播放/录音无声。
    • 检查音量设置：执行 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开放平台：
  2. 注册并登录，在控制台创建应用，获得 APP_ID、API_KEY、SECRET_KEY。
  3. 启用“语音技术”相关服务。
  4. DeepSeek平台：
  5. 注册并登录DeepSeek，在API管理页面创建新的API密钥 (sk-开头)。
  6. 记录API基础地址，例如 https://api.deepseek.com。

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

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

bash mkdir -p ~/voice_assistant/config cd ~/voice_assistant python3 -m venv venv source venv/bin/activate 2. 安装Python依赖：

bash pip install pyaudio baidu-aip openai chardet requests

  • 注意：pyaudio 安装可能失败，需先安装系统库：sudo apt install -y portaudio19-dev python3-dev。
  • 创建配置文件 (config/api_keys.json)：

json { "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()。
  • 播放函数示例（集成硬件测试成功的命令）： python 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连通性： bash 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)：

```ini [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. 启用并启动服务：

bash sudo systemctl daemon-reload sudo systemctl enable --now voice-assistant.service sudo systemctl status voice-assistant.service # 检查状态 上一篇 下一篇