# 解压到指定目录
cd /ohos
tar -xzvf OpenHarmony-v3.2.tar.gz
# 或如果是 .tar.bz2
tar -xjvf OpenHarmony-v3.2.tar.bz2
# 或如果是 .tar.xz
tar -xJvf OpenHarmony-v3.2.tar.xz
# 进入源码目录
cd Unionpi_Whale/unionpi_whale
# 方式一：从 OHOS-Dev 获取（推荐）
cd OHOS-Dev/tools/
tar -xzf Python-2.7.18.tgz
cd Python-2.7.18/
# 方式二：从官网下载（需外网）
wget https://www.python.org/ftp/python/2.7.18/Python-2.7.18.tgz
mv Python-2.7.18.tgz ~/Downloads/
tar -xzf ~/Downloads/Python-2.7.18.tgz
cd Python-2.7.18/
编译安装：
# 编译安装（约 5-10 分钟）
sudo ./configure --enable-optimizations
sudo make altinstall
UbicoreOS on OpenHarmony — 快速入门指南
项目简介
什么是 UbicoreOS
UbicoreOS 是基于 OpenHarmony 的分布式设备管理与协同系统，主要用于智能网关场景。它提供了统一的设备发现、拓扑管理、远程控制和状态监控能力，支持多种通信协议（WiFi、MQTT、WebSocket）。
核心组件
技术栈
项目目录结构
完整源码树（关键路径）
关键路径速查表
build/subsystem_config.jsonvendor/unionman/unionpi_whale/config.jsonvendor/.../security_config/high_privilege_process_list.jsonbase/security/selinux_adapter/sepolicy/base/foundation/ubicoreos/ubicoreos_service/services/foundation/ubicoreos/ubicoreos_service/scripts//ohos/Unionpi_Whale/ubicoreos_web_demo/view/src/ubicoreos_web_demo/view/scripts/deploy-board.mjsout/unionpi_whale/packages/phone/system/lib64/out/unionpi_whale/build.log文件命名约定
bundle.json: 组件描述文件，定义依赖、构建目标、元信息BUILD.gn: GN 构建脚本，定义编译规则（sources、deps、external_deps）*.cfg: init 启动配置，声明服务的 uid/gid/secon/启动参数*.conf: 服务运行时配置，业务参数（端口、WiFi、MQTT 等）*_service.te: SELinux 策略文件，定义该服务的安全权限10002.json: SA profile，声明 SA ID、进程名、自动重启等目录
0. 前置准备
0.1 资源清单
所有必需资源已集中存放在
OHOS-Dev/目录：OHOS-Dev/source/50GB，解压后100GBOHOS-Dev/tools/Python-2.7.18.tgzOHOS-Dev/prebuilts/OHOS-Dev/tools/RKDevTool/OHOS-Dev/tools/upgrade_toolOHOS-Dev/tools/hdcapt install minicom如果OHOS-Dev不在/ohos目录，请联系管理员获取资源包路径。
0.2 术语速查（初学者必读）
0.3 硬件要求
0.3.1 开发板
0.3.2 开发机
环境预检查脚本（可选，快速验证）：
0.4 软件环境
0.5 网络连接
http_proxy和https_proxy环境变量1. 源码获取与构建
1.1 获取源码
1.1.1 解压源码包
如果你拿到的是 tar 压缩包（如
OpenHarmony-v3.2.tar.gz）：提示： 新版 GNU tar 能自动识别压缩格式，直接
tar -xvf 文件名即可。1.1.2 通过 repo 获取（可选）
如果从 Gitee/GitHub 拉取源码：
1.2 配置编译环境
1.2.1 系统要求与依赖安装
⚠️ 重要提示：推荐使用 Ubuntu 20.04
安装基础依赖库：
验证基础语言环境：
确保 Python、C/C++、Java 等基础开发库已安装。如存在多个版本，需配置好当前使用版本（见下节）。
1.2.2 配置 Python 2.7
OpenHarmony 编译系统依赖 Python 2.7，需要与 Python 3 共存。
获取 Python 2.7.18 源码：
编译安装：
配置版本管理（关键步骤）：
使用
update-alternatives管理 Python 2 和 3 的切换，安全且可随时切换：验证配置：
✓ 配置成功标志：
python --version→ Python 2.7.18python3命令仍然可用（系统工具不受影响）如需切换回 Python 3：
常见问题：
update-alternatives冲突sudo update-alternatives --remove-all python后重新配置python --version显示 2.7.18python3命令，不受影响1.2.3 安装 Python 3（如果没有）
Ubuntu 20.04 默认已安装 Python 3.8，验证即可：
如果缺失，安装：
1.2.4 安装 hdc 工具
hdc 是 OpenHarmony 设备连接工具（类似 Android 的 adb），用于部署、日志查看、shell 连接。
hdc 常用命令速查：
1.2.5 配置 ccache（可选，加速重复编译）
1.2.6 准备预编译工具链
✓ 验证环境配置完成：
1.3 首次全量编译
环境配置完成后，开始首次编译：
编译参数说明：
--product-name unionpi_whale— 指定产品名称--ccache— 启用 ccache 缓存，加速重复编译--no-prebuilt-sdk— 跳过预编译 SDK 阶段（加快增量编译）--disable-package-image— 不打包系统镜像（仅编译，节省时间，日常开发推荐）⚠️ 重要： 首次烧录开发板或需要更新系统镜像时，去掉
--disable-package-image参数。编译过程说明：
--disable-package-image）编译时间参考：
编译产物位置：
out/unionpi_whale/packages/phone/images/system.img— 系统分区镜像vendor.img— 厂商分区镜像userdata.img— 用户数据分区镜像out/unionpi_whale/packages/phone/system/lib64/out/unionpi_whale/lib.unstripped/✓ 编译成功标志：
ls out/unionpi_whale/packages/phone/system/lib64/*.so能看到大量 .so 文件1.3.1 编译失败排查
查看错误摘要：
常见错误速查：
python: command not foundpython --version显示 2.7.18（见 1.2.2 节）No such file or directory: 'xxx.h'undefined reference toPermission deniedinternal compiler error: Killed-j4参数No space left on device如何减少并行度（内存不足时）：
1.4 烧录到开发板
编译成功后，将镜像烧录到开发板。
1.4.1 准备烧录工具
烧录工具已放在
OHOS-Dev/tools/目录。Windows 环境：
OHOS-Dev/tools/RKDevTool/Linux 环境：
OHOS-Dev/tools/upgrade_tool或使用开源工具 rkdeveloptool：
1.4.2 进入烧录模式
⚠️ 开发板物理操作（请参考开发板说明书确认按键位置）：
验证是否进入烧录模式：
如果进不去 Maskrom 模式：
1.4.3 烧录镜像
方式一：使用 RKDevTool（Windows，推荐新手）
OHOS-Dev/tools/RKDevTool/RKDevTool.exeout/unionpi_whale/packages/phone/images/system.imgout/unionpi_whale/packages/phone/images/vendor.imgout/unionpi_whale/packages/phone/images/userdata.img方式二：使用 upgrade_tool（Linux 命令行）
✓ 烧录成功标志：
upgrade_tool rd）1.4.4 首次启动与验证
烧录完成后：
验证启动成功（三种方式）：
方式一：通过 hdc（USB 或网络）
方式二：通过串口（最可靠）
见下一节 1.4.5 串口调试，串口能看到完整启动日志。
方式三：通过网络（需先配置 IP）
见 1.4.6 网络配置。
1.4.5 串口调试配置
串口是嵌入式开发的核心调试手段，可以看到从 U-Boot 到内核启动的完整日志，排查启动失败问题。
硬件连接：
准备 USB 转 TTL 模块（如 CP2102、CH340、PL2303）
连接开发板 UART 调试口（通常是 3 针或 4 针排针）：
⚠️ 注意 TX/RX 交叉连接：模块的 TX 接板子的 RX，模块的 RX 接板子的 TX。
USB-TTL 模块插入开发机
配置串口工具：
串口配置参数：
正常启动日志示例：
串口故障排查：
screen 使用技巧：
Ctrl+A然后K→ 退出 screenCtrl+A然后D→ 分离会话（后台保留）screen -r→ 恢复分离的会话screen -ls→ 列出所有会话1.4.6 开发板网络配置
网络是后续 SSH 部署、远程调试的基础，必须配置。
方式一：有线网络（推荐，稳定）
硬件连接：
通过串口或 hdc shell 进入设备：
查看网络接口：
DHCP 自动获取 IP（推荐）：
配置静态 IP（可选）：
验证网络：
方式二：WiFi 网络（可选）
如果开发板支持 WiFi（需确认硬件配置）：
配置 SSH 服务：
从开发机连接：
网络故障排查：
ifconfig无 eth0dmesg | grep eth）route -n）✓ 网络配置成功标志：
1.5 增量编译（日常开发）
首次全量编译后，日常开发使用增量编译（约 30s~2min）：
1.6 编译单个模块
仅重新编译特定组件：
1.7 清理
2. 添加新模块到系统（以 ubicoreos 为例）
当在
foundation/下新增自定义模块时，需要完成以下配置才能被编译系统识别。完整说明见 foundation/ubicoreos/README.md。2.1 注册子系统
编辑
build/subsystem_config.json，添加新子系统：2.2 创建 bundle.json
在组件目录下创建
bundle.json，定义组件信息：文件：
foundation/ubicoreos/ubicoreos_service/bundle.json2.3 添加到产品配置
编辑产品配置文件，启用该组件：
文件：
vendor/unionman/unionpi_whale/config.json在
subsystems数组中添加：2.4 编写 BUILD.gn
在模块目录下创建
BUILD.gn定义编译规则：关键字段：
part_name: 组件名（与 bundle.json 的component.name一致）subsystem_name: 子系统名（与subsystem_config.json的 key 一致）external_deps: 外部依赖，格式"组件名:目标名"3. 安全配置
3.1 高权限进程白名单
如果服务的
.cfg文件声明uid: root或uid: system，需要在高权限进程白名单中登记，否则编译失败。报错示例：
解决方法：
编辑
vendor/unionman/unionpi_whale/security_config/high_privilege_process_list.json，添加对应条目：⚠️ 安全提示： 仅在服务确实需要 root 权限时才加白名单；能用低权限 uid 就不要用 root。
详细说明见 foundation/ubicoreos/README.md#8-配置高权限进程白名单。
3.2 SELinux 安全策略
系统开启 SELinux 后，每个 SA (SystemAbility) 服务必须配置安全策略，否则无法启动。OpenHarmony 采用”双类型”模型：
服务名，如ubicoreos_servicesa_服务名，如sa_ubicoreos_service需要配置 5 处文件（以 ubicoreos_service、SA ID 10002 为例）：
(1) service_contexts — 绑定服务对象标签
文件：
base/security/selinux_adapter/sepolicy/base/public/service_contexts左边是 SA ID（见
sa_profile/*.json），右边是服务对象类型。(2) service.te — 声明服务对象类型
文件：
base/security/selinux_adapter/sepolicy/base/public/service.te(3) type.te — 声明进程域类型
文件：
base/security/selinux_adapter/sepolicy/base/public/type.tesadomain赋予 SA 进程一批公共权限（读 system_profile、调 samgr binder 等）。(4) init.te — 允许 init 拉起该进程
文件：
base/security/selinux_adapter/sepolicy/base/public/init.teinit 需要
transition权限将自己降权切换到该服务的安全域。(5) 新建 te/<服务名>.te — 服务专属权限
文件：
base/security/selinux_adapter/sepolicy/base/te/ubicoreos_service.tesamgr_class { add get }是核心权限：add让进程能向 samgr 注册自己，get让它能被查询获取。运行时权限补全：
服务首次运行后，通过
avc denied日志收集缺失权限：将生成的规则补进
base/te/ubicoreos_service.te，重新编译验证。详细说明见 foundation/ubicoreos/README.md#9-配置-selinux-安全策略。
4. 部署到开发板
4.1 自动化部署脚本
位于
foundation/ubicoreos/ubicoreos_service/scripts/，提供两个部署脚本：4.1.1 部署 .so（改代码后快速验证）
脚本会自动：
/system为可写/system/lib64/auto-restart=true自动重启首次运行： 需输入开发板 root 密码。建议先配置 SSH 免密登录：
4.1.2 部署配置文件（调试配置参数）
配置文件优先级（见
services/base/src/config_manager.cpp）：/data/service/el1/public/ubicoreos/ubicoreos_service.conf— 用户配置，优先级高（默认推这里）/system/etc/ubicoreos/ubicoreos_service.conf— 系统默认配置调试改配置推 data 即可；要更新进镜像的出厂默认值才用
-t system。4.2 手动部署（脚本不可用时）
4.3 查看日志
5. 前端开发与部署
前端 Web 控制面板位于
/ohos/Unionpi_Whale/ubicoreos_web_demo，基于 Vite + React + TypeScript。5.1 环境准备
Node.js 要求： 20.19+ 或 22.12+（项目使用 Vite 7、React 19）
如果系统 Node 版本过低，用 nvm 安装新版：
安装 pnpm：
5.2 安装依赖
5.3 本地开发
访问
http://localhost:5173查看界面。5.4 构建与部署
5.4.1 发布到本仓库
data/www/产物会复制到
../data/www/，适合本地测试。5.4.2 发布到开发板
首次运行： 需输入开发板 root 密码，建议配置免密
ssh-copy-id root@192.168.1.108。部署后访问
http://192.168.1.108:11311/（开发板 IP + ubicoreos_service 监听端口）。5.5 Mock / 真实后端开关
前端自动根据环境变量
VITE_USE_MOCK_WS切换：pnpm dev，使用 MSW (Mock Service Worker) 模拟后端响应pnpm dev:board，连接真实开发板配置在
vite.config.ts中，无需手改。6. 常见问题排查
6.1 编译报错：some services are not authenticated
原因： 服务以
uid: root运行，但未登记到高权限进程白名单。解决： 参考 3.1 高权限进程白名单，在
security_config/high_privilege_process_list.json中添加对应条目。6.2 服务启动失败或 avc denied
原因： SELinux 策略未配置或不完整。
解决：
hdc shell dmesg | grep avc收集 denied 日志base/te/<服务名>.te6.3 模块没有被编译
原因： 产品配置文件中未添加该子系统。
解决： 检查
vendor/unionman/unionpi_whale/config.json中是否包含对应子系统（参考 2.3）。6.4 编译时找不到依赖
原因：
bundle.json中的依赖项配置不正确。解决：
deps.components中的组件名称是否正确BUILD.gn中的external_deps格式是否正确（"组件:目标"）6.5 子系统名称不匹配
原因：
subsystem_config.json、bundle.json、BUILD.gn中的子系统名称不一致。解决： 确保以下三处的名称完全一致：
build/subsystem_config.json中的 keybundle.json中的component.subsystemBUILD.gn中的subsystem_name6.6 前端 pnpm 找不到或 Node 版本过低
原因： 系统 Node 版本太老（< 20.19），或未安装 pnpm。
解决： 参考 5.1 环境准备，用 nvm 安装新版 Node 并启用 pnpm。
6.7 scp 报错：unknown option – O
原因： 系统的
scp版本较老，不支持-O参数。解决： 部署脚本已自动探测并适配，此报错不应再出现。如果仍有问题，手动去掉
scp命令中的-O参数。7. 参考文档
7.1 OpenHarmony 官方文档
7.2 本项目文档
总览与配置：
后端服务：
前端开发：
部署脚本：
附录：完整工作流程速查
A. 首次环境搭建
B. 日常开发迭代（后端）
C. 日常开发迭代（前端）
D. 添加新组件
本文档持续更新。如有问题或建议，请提交 Issue 或 PR。