避坑指南：在Ubuntu 20.04上手动修复星环OS（HaloOS）编译环境与Docker安装的那些坑

避坑指南：在Ubuntu 20.04上手动修复星环OS（HaloOS）编译环境与Docker安装的那些坑

当你在Ubuntu 20.04上尝试搭建星环OS（HaloOS）开发环境时，可能会遇到各种意想不到的问题。本文将从实际经验出发，分享那些官方文档没有详细说明的"坑点"和解决方案，帮助你顺利完成环境搭建。

1. 环境准备阶段的常见问题

在开始之前，确保你的Ubuntu 20.04系统已经完成基本配置。以下是几个容易忽略但至关重要的准备工作：

1.1 系统源配置优化

国内用户经常会遇到软件包下载缓慢或失败的问题。修改apt源为国内镜像可以显著提升安装速度：

sudo sed -i "s@http://.*archive.ubuntu.com@http://mirrors.aliyun.com@g" /etc/apt/sources.list sudo sed -i "s@http://.*security.ubuntu.com@http://mirrors.aliyun.com@g" /etc/apt/sources.list sudo apt update

注意：执行更新后如果出现"Release file is not valid yet"错误，可能是系统时间不正确，可以使用sudo apt install ntpdate && sudo ntpdate ntp.aliyun.com同步时间。

1.2 Python环境配置

星环OS对Python版本有严格要求，官方推荐使用Python 3.8.10。虽然Ubuntu 20.04默认安装了这个版本，但可能会遇到以下问题：

• python命令不存在：这是因为Ubuntu默认只安装了python3命令
• 缺少venv模块：这是创建虚拟环境所必需的

解决方法：

sudo apt install python3.8-venv sudo ln -s /usr/bin/python3 /usr/bin/python # 创建python到python3的符号链接

2. 代码下载与repo工具问题

2.1 安装git和repo工具

官方文档中的repo工具安装命令可能会失败，特别是在国内网络环境下：

sudo apt install git curl

对于repo工具，建议使用清华镜像源：

export REPO_URL='https://mirrors.tuna.tsinghua.edu.cn/git/git-repo' curl https://mirrors.tuna.tsinghua.edu.cn/git/git-repo > repo sudo chmod +x repo sudo mv repo /usr/bin/repo

2.2 代码同步技巧

使用国内镜像源初始化仓库可以避免连接问题：

mkdir haloosspace cd haloosspace repo init -u https://gitee.com/haloos/manifests.git -b master -m default.xml repo sync

如果同步过程中断，可以使用repo sync -c -j4继续同步，其中-j4表示使用4个线程。

3. Docker环境配置的疑难杂症

3.1 Docker安装失败解决方案

官方脚本安装Docker可能会因为网络问题失败。以下是手动安装方法：

# 添加Docker官方GPG密钥 curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 设置稳定版仓库 echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io

3.2 Docker权限问题处理

安装完成后，普通用户可能无法直接使用docker命令：

sudo groupadd docker sudo usermod -aG docker $USER newgrp docker # 立即生效

验证安装：

docker run hello-world

如果仍然遇到权限问题，可以尝试重启Docker服务：

sudo systemctl restart docker

4. 编译过程中的常见错误

4.1 编译环境初始化

在haloosspace目录下执行环境初始化时，可能会缺少依赖：

sudo apt update python ./vcos/vcos_studio/configurator/init_env.py -a

常见缺失的Python包可以通过以下命令安装：

pip3 install loguru openpyxl psutil lxml -i https://mirrors.aliyun.com/pypi/simple/

4.2 编译特定应用

编译rt_demo应用时，确保位于正确的目录并指定所有必要参数：

cd ./build python3 haloos_build.py -app_name rt_demo -board_name E3650_DEV_KIT -compiler gcc -maketool ninja -sim 1 -all

如果遇到"python: not found"错误，确认已创建python到python3的符号链接：

sudo ln -s /usr/bin/python3 /usr/bin/python

5. Docker镜像导入与容器运行

5.1 导入预构建的Docker镜像

从国内源下载并导入Docker镜像：

wget https://gitee.com/yanxiaoyong_1/sim-docker/repository/archive/vcos_sim.tar.7z.001 # 解压后导入 sudo docker load -i vcos_sim.tar

5.2 启动容器的最佳实践

建议使用以下参数启动容器，确保正确的权限和目录映射：

sudo docker run -it --cap-add=NET_ADMIN --device=/dev/net/tun --name vcos_sim -v /home:/home vcos_sim /bin/bash

验证容器运行状态：

docker ps -a

进入容器：

docker exec -it vcos_sim /bin/bash

6. 开发环境集成技巧

6.1 使用VSCode进行开发

在VSCode中安装以下插件可以提升开发体验：

• Docker
• Dev Containers
• Python

配置好插件后，可以直接在容器内进行开发和调试。

6.2 常见问题排查

如果遇到容器无法启动或权限问题，可以检查：

• Docker服务是否运行：sudo systemctl status docker
• 用户是否在docker组：groups $USER
• 容器日志：docker logs vcos_sim

在实际项目中，我发现最耗时的往往是环境配置阶段的各种小问题。例如，有一次花了半天时间才发现是系统时间不正确导致apt更新失败。因此，建议在遇到问题时，首先检查网络连接、系统时间和基本依赖是否正常。