一、背景说明

最近在飞凌 RK3568 核心板适配 OpenHarmony 5.1 系统时，需要在开发板上运行 Python 脚本，例如：

python3 xxx.py
pip3 install pyomo

但是 OpenHarmony 标准系统不是 Ubuntu，开发板上没有 apt，也不能直接通过：

apt install python3

来安装 Python。

因此最终采用的方案是：

Ubuntu 编译主机
  ↓
下载 python_oh 适配仓库
  ↓
交叉编译 CPython 3.13.5
  ↓
把 Python 组件加入 OpenHarmony 5.1 产品配置
  ↓
重新编译 ok3568 固件
  ↓
烧录到 RK3568 开发板
  ↓
开发板上直接运行 python3 / pip3

本文记录完整成功过程和踩坑点。

---

二、开发环境

本文使用环境如下：

开发板：飞凌 RK3568 / OK3568-C
系统：OpenHarmony 5.1
内核：Linux 6.6
产品名：ok3568
编译主机：Ubuntu 20.04
Python 版本：CPython 3.13.5
源码目录：
/media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release

平时内核编译命令是：

./build.sh -p ok3568 --ccache --build-target kernel --gn-args linux_kernel_version=\"linux-6.6\"

但是注意：这个命令只编译内核，不会把 Python 打进系统镜像。

Python 属于用户态程序，需要编译 cpython 组件或者重新编译完整固件。

---

三、下载 python_oh 适配仓库

进入 OpenHarmony 源码根目录：

cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release

下载适配仓库：

git clone -b 5.1.0_cpython_3.13.5 https://gitee.com/OpenHarmony_Python/python_oh.git python_oh

如果遇到：

Could not resolve host: gitee.com

说明 Ubuntu 虚拟机 DNS 或网络有问题，先检查：

ping -c 3 223.5.5.5
ping -c 3 gitee.com
cat /etc/resolv.conf

可以临时设置 DNS：

sudo tee /etc/resolv.conf > /dev/null <<'EOF'
nameserver 223.5.5.5
nameserver 114.114.114.114
nameserver 8.8.8.8
EOF

---

四、安装 Ubuntu 编译依赖

安装基础依赖：

sudo apt update

sudo apt install -y \
  autoconf \
  automake \
  libtool \
  texinfo \
  xutils-dev \
  cmake \
  tcl8.6 \
  git \
  patch

如果 sudo apt update 里有 Docker 源报错，例如：

The repository 'https://download.docker.com/linux/ubuntu focal Release' no longer has a Release file

只要后续依赖能正常安装，可以先不处理 Docker 源。

---

五、安装宿主机 Python 3.13

python_oh/build_python_oh.sh 脚本会检查宿主机有没有 python3.13：

grep -Rni "python3.13\|python3 " build_python_oh.sh BUILD.gn bundle.json 5.1.0_3568_add_python.patch

可以看到类似：

build_python_oh.sh:54:if command -v python3.13 &>/dev/null; then

Ubuntu 20.04 默认 apt 源可能没有 python3.13，执行：

sudo apt install -y python3.13

可能报：

E: Unable to locate package python3.13

这时建议源码安装宿主机 Python 3.13.5。

安装依赖：

sudo apt install -y \
  build-essential \
  wget \
  libssl-dev \
  zlib1g-dev \
  libbz2-dev \
  libreadline-dev \
  libsqlite3-dev \
  libffi-dev \
  liblzma-dev \
  uuid-dev

下载并编译：

cd /tmp

wget https://www.python.org/ftp/python/3.13.5/Python-3.13.5.tgz

tar -xf Python-3.13.5.tgz
cd Python-3.13.5

./configure --prefix=/opt/python3.13 --enable-shared

make -j$(nproc)

sudo make altinstall

配置动态库路径：

echo "/opt/python3.13/lib" | sudo tee /etc/ld.so.conf.d/python3.13.conf
sudo ldconfig

建立软链接：

sudo ln -sf /opt/python3.13/bin/python3.13 /usr/local/bin/python3.13

验证：

python3.13 --version

正常输出：

Python 3.13.5

注意：不要把系统默认 /usr/bin/python3 改掉，否则可能影响 Ubuntu 和 OpenHarmony 编译工具。

---

六、打 Python 集成补丁

进入源码根目录：

cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release

先 dry-run：

patch --dry-run -p1 < python_oh/5.1.0_3568_add_python.patch

如果没有明显报错，再正式打补丁：

patch -p1 < python_oh/5.1.0_3568_add_python.patch

打完后检查是否加入了 python_oh 子系统：

grep -Rni "cpython\|python_oh\|python3.13" \
  build/subsystem_config.json \
  productdefine \
  vendor \
  device \
  2>/dev/null | head -100

正常能看到类似：

build/subsystem_config.json:226:  "python_oh": {
build/subsystem_config.json:227:    "path": "python_oh",
build/subsystem_config.json:228:    "name": "python_oh"
vendor/hihope/rk3568/config.json:287:      "subsystem": "python_oh",
vendor/hihope/rk3568/config.json:290:          "component": "cpython",

---

七、关键踩坑：补丁默认加到了 rk3568，不是 ok3568

这里是最关键的地方。

原补丁是给 rk3568 产品写的，但是本项目实际编译命令是：

./build.sh -p ok3568 ...

所以如果只打原补丁，后面执行：

./build.sh -p ok3568 --ccache --build-target cpython --target-cpu arm64

会报：

ninja: error: unknown target 'cpython'

原因是：

python_oh 子系统已经加入 build/subsystem_config.json
但是 cpython 组件只被加入 vendor/hihope/rk3568/config.json
实际编译的是 ok3568
所以 ok3568 产品配置里没有 cpython

解决方法：把下面这段加入 ok3568 对应的 config.json 里。

先找到 ok3568 产品配置文件：

grep -Rni "\"ok3568\"" vendor productdefine device 2>/dev/null | head -100

或者：

find vendor productdefine device \
  -type f -name "config.json" \
  -print | xargs grep -n "\"product_name\".*ok3568\|\"product_name\": \"ok3568\"" 2>/dev/null

找到 ok3568 的 config.json 后，在 "subsystems" 数组中加入：

{
  "subsystem": "python_oh",
  "components": [
    {
      "component": "cpython",
      "features": []
    }
  ]
}

注意 JSON 逗号格式。

修改后验证：

grep -Rni "\"subsystem\": \"python_oh\"\|\"component\": \"cpython\"" vendor productdefine device 2>/dev/null

必须能在 ok3568 的配置文件中看到 python_oh 和 cpython。

---

八、交叉编译 CPython

进入 python_oh 目录：

cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release/python_oh

执行脚本：

chmod +x build_python_oh.sh
bash build_python_oh.sh

如果脚本提示找不到 python3.13，说明第五步宿主机 Python 3.13 没装好。

编译完成后，可以回到源码根目录查生成物：

cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release

find . -name "python3" 2>/dev/null | head -20
find . -name "libpython3.13*" 2>/dev/null | head -20
find . -path "*python3.13*" 2>/dev/null | head -20

---

九、重新生成 Ninja 并编译 cpython 目标

如果之前已经生成过 out/ok3568，需要清理旧的 Ninja 文件，否则它不知道新加的 cpython 组件：

cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release

rm -rf out/ok3568/build.ninja
rm -rf out/ok3568/args.gn
rm -rf out/ok3568/obj/python_oh
rm -rf out/ok3568/gen/python_oh

然后编译 cpython：

./build.sh -p ok3568 --ccache --build-target cpython --target-cpu arm64 --gn-args linux_kernel_version=\"linux-6.6\"

如果还报：

ninja: error: unknown target 'cpython'

说明 ok3568 的产品配置没有真正包含 python_oh/cpython，继续检查：

grep -Rni "cpython\|python_oh\|python3.13" \
  build/subsystem_config.json \
  productdefine \
  vendor \
  device \
  2>/dev/null | head -100

也可以查看 Ninja 是否识别到 Python 目标：

./prebuilts/build-tools/linux-x86/bin/ninja \
  -C out/ok3568 \
  -t targets all | grep -i "cpython\|python_oh\|python3.13" | head -100

---

十、编译完整系统镜像

cpython 编译通过后，需要编完整系统镜像：

./build.sh -p ok3568 --ccache --gn-args linux_kernel_version=\"linux-6.6\"

注意：这里不要加：

--build-target kernel

因为只编 kernel 不会把 Python 打进系统分区。

两类命令的区别如下：

# 只编内核，适合驱动、DTS、触摸、网口等调试
./build.sh -p ok3568 --ccache --build-target kernel --gn-args linux_kernel_version=\"linux-6.6\"

# 单独编 Python 组件
./build.sh -p ok3568 --ccache --build-target cpython --target-cpu arm64

# 编完整系统镜像，Python 要靠这个进固件
./build.sh -p ok3568 --ccache --gn-args linux_kernel_version=\"linux-6.6\"

编译完成后查镜像：

find out/ok3568 -name "system.img" -o -name "vendor.img" -o -name "updater.img"

然后按飞凌 RK3568 原来的烧录流程烧录即可。

---

十一、开发板上验证 Python 是否安装成功

烧录启动后，进入开发板：

hdc shell

查看 Python：

which python3
which python3.13
which pip3

如果 which 找不到，可以手动搜索：

find /system -name "python3*" 2>/dev/null
find /vendor -name "python3*" 2>/dev/null
find / -name "python3*" 2>/dev/null

测试版本：

python3 --version

或者：

python3.13 --version

正常应该看到类似：

Python 3.13.5

测试标准库：

python3 -c "import sys, os, json, socket; print(sys.version); print('python ok')"

如果输出：

python ok

说明 Python 基本可用。

---

十二、测试 pip

查看 pip：

python3 -m pip --version

安装纯 Python 库，例如 Pyomo：

python3 -m pip install pyomo -i https://mirrors.aliyun.com/pypi/simple

如果报证书错误：

SystemTimeWarning: System time is way off
SSLCertVerificationError: certificate verify failed: certificate is not yet valid

说明开发板系统时间不对，先设置时间：

date
date -s "2026-05-10 10:00:00"
date

然后重新安装：

python3 -m pip install pyomo -i https://mirrors.aliyun.com/pypi/simple

如果还是 SSL 问题，可以临时加：

python3 -m pip install pyomo \
  -i https://mirrors.aliyun.com/pypi/simple \
  --trusted-host mirrors.aliyun.com

验证：

python3 -c "import pyomo; print(pyomo.__version__)"

---

十三、开发板 DNS 配置问题

如果 pip 或网络访问不正常，先区分是网络不通还是 DNS 不通。

测试公网 IP：

ping 223.5.5.5

如果 IP 能通，但域名不通：

ping www.baidu.com

报：

Name does not resolve

说明是 DNS 问题。

OpenHarmony 根分区可能默认只读，需要先重新挂载：

mount -o remount,rw /
mount -o remount,rw /system 2>/dev/null
mount -o remount,rw /vendor 2>/dev/null

写入 DNS：

printf "nameserver 223.5.5.5\nnameserver 114.114.114.114\nnameserver 8.8.8.8\n" > /etc/resolv.conf
sync
cat /etc/resolv.conf

如果 DNS 仍然不生效，可以临时用 hosts 验证：

mount -o remount,rw /
echo "110.242.68.4 www.baidu.com" >> /etc/hosts
ping www.baidu.com

如果写 hosts 后能 ping 通，说明网络路由没问题，问题集中在 DNS 解析链路。

---

十四、FastAPI 踩坑：pydantic_core 缺失

安装 FastAPI 后，如果运行：

python3 ./webmain.py

报：

ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'

原因是新版 FastAPI 默认依赖 Pydantic v2，而 Pydantic v2 依赖 Rust 写的 pydantic-core 本地二进制扩展。OpenHarmony 上通常没有现成可用的 wheel。

解决方法：降级到 FastAPI + Pydantic v1 组合。

python3 -m pip uninstall -y fastapi pydantic pydantic-core

安装旧版组合：

python3 -m pip install \
  "fastapi==0.99.1" \
  "pydantic==1.10.24" \
  "starlette==0.27.0" \
  "uvicorn==0.22.0" \
  -i https://mirrors.aliyun.com/pypi/simple \
  --trusted-host mirrors.aliyun.com

不要安装：

uvicorn[standard]

因为它会拉取 uvloop、httptools、watchfiles 等二进制依赖，在 OpenHarmony 上容易失败。

测试：

python3 - <<'EOF'
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    value: int

print("fastapi import ok")
EOF

---

十五、总结

最终成功方案如下：

1. Ubuntu 编译机准备依赖
2. 安装宿主机 Python 3.13.5
3. 下载 python_oh 仓库
4. 执行 5.1.0_3568_add_python.patch
5. 注意补丁默认加到 rk3568，需要手动把 python_oh/cpython 加入 ok3568 的 config.json
6. 执行 build_python_oh.sh 交叉编译 CPython
7. 编译 cpython 目标
8. 编译完整 ok3568 系统镜像
9. 烧录 RK3568 开发板
10. 在开发板上验证 python3 / pip3

核心命令汇总：

cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release

git clone -b 5.1.0_cpython_3.13.5 https://gitee.com/OpenHarmony_Python/python_oh.git python_oh

patch --dry-run -p1 < python_oh/5.1.0_3568_add_python.patch
patch -p1 < python_oh/5.1.0_3568_add_python.patch

# 手动确认 ok3568 config.json 中加入 python_oh/cpython

cd python_oh
chmod +x build_python_oh.sh
bash build_python_oh.sh

cd ..

rm -rf out/ok3568/build.ninja
rm -rf out/ok3568/args.gn
rm -rf out/ok3568/obj/python_oh
rm -rf out/ok3568/gen/python_oh

./build.sh -p ok3568 --ccache --build-target cpython --target-cpu arm64 --gn-args linux_kernel_version=\"linux-6.6\"

./build.sh -p ok3568 --ccache --gn-args linux_kernel_version=\"linux-6.6\"

开发板验证：

python3 --version
python3 -c "import sys, os, json, socket; print(sys.version); print('python ok')"
python3 -m pip --version
python3 -m pip install pyomo -i https://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com

最终效果：

OpenHarmony 5.1 / RK3568 开发板成功运行 CPython 3.13.5
pip 可用
纯 Python 包可安装
可以运行 Pyomo、简单 FastAPI 服务等 Python 程序

需要注意的是，带 C/C++/Rust 本地扩展的 Python 包不一定能直接用，例如新版 Pydantic、numpy、opencv 等，需要单独交叉编译或选择纯 Python / 老版本替代方案。