SalvageOfSDK on Potter的个人笔记

第一次迭代（2025）：从单体巨石到 repo 多仓库协同

Sat, 07 Jun 2025 00:00:00 +0000

作者: Potter White
日期: 2025年6月

一、项目概述

我独立主导并实施了一项大型嵌入式 Linux SDK 的完整迁移工程。该项目将一个以离线压缩包形式分发的、庞大的单体代码库，成功重构并迁移至内部 GitLab 服务器，建立了一套基于 Google repo 工具的模块化、多仓库（multi-repository）协同开发体系。

这次改造不仅引入了现代化的版本控制最佳实践，还通过自动化脚本解决了迁移过程中的核心技术难题，最终建立了一套可扩展、高效率的团队协作流程，极大地提升了研发效率与代码质量。

二、面临的挑战：“压缩包地狱”与单体代码库的困境

在项目改造前，我们基于 Rockchip SDK 的产品研发流程正面临着严峻的挑战：

版本历史缺失： SDK 以一个巨大的 .tar.gz 压缩包分发，代码的任何变更都无法追溯。我们陷入了依赖文件名（如 sdk_v1.2_final_final.tar.gz）进行版本管理的“地狱模式”。
庞大臃肿的单体仓库：
- 在此之前，整个 SDK 被塞进一个单一、巨大的 Git 仓库中。
- 以Rockchip的SDK为例, RK官方可以提供repo的下载权限,需要公司向RK的代理提交代码访问申请表,审核通过后提供操作人员的ssh公钥.如果不透过这个方式,大概率我们拿到的就会是一个不小的压缩包格式的SDK.
- 这种情况下, sdk的克隆耗时极长，代码合并冲突堪称灾难，不同模块的开发者无法独立工作。因此,只能选择一个人或两个人独立负责一个项目, 否则SDK的同步工作将消耗大量时间, 尤其是调试kernel时,需要频繁验证各种设备树的修改甚至驱动和uboot的修改.
协作流程阻塞： 代码变更依赖手动打包和传输，极易出错。功能分支、代码审查（Merge Request）等现代协作方式完全无法实施，导致集成阶段痛苦不堪。
权限管理混乱： 所有开发者都拥有全部代码的访问权限，包括他们无需接触的核心 IP 和敏感组件，存在安全隐患。
新人上手困难： 搭建一套新的开发环境是项复杂、耗时数小时的手动任务，常常需要资深工程师介入指导。

三、我的解决方案：分步击破，构建现代化研发体系

我设计并执行了一套分阶段的解决方案，系统性地解决了上述所有痛点。

第一阶段：自动化解析与智能化迁移

我没有采用低效且易错的手动迁移，而是开发了一个强大的 Python 自动化脚本作为项目的基石。该脚本实现了：

智能解析复杂清单： 自动读取并解析原始 SDK 中相互嵌套的 repo 清单（.xml）文件，精准识别出全部 N(一般子仓库数量不会少,否则就不需要repo管理了) 个独立的代码模块。
自动化 GitLab 项目创建： 调用 GitLab API,并借助PAT(Personal Access Token)，让py脚本在指定的团队空间下为每个模块自动创建对应的、独立的 Git 仓库。
诊断并“修复”不健康仓库： 脚本能自动检测出原始仓库的一个致命问题——许多仓库是“浅克隆”（shallow clone），Git 历史不完整。我的解决方案是：
- 对于历史完整的仓库： 完整保留其所有分支和标签并推送到 GitLab。
- 对于历史残缺的仓库： 自动将其重新初始化为一个全新的 Git 仓库，并生成一个干净、完整的“初始版本”提交。这步操作是确保后续 repo sync 能够成功的关键。
统一分支规范： 自动将所有 N 个仓库中混乱的默认分支名（如 master, develop 等）统一重命名为 main，为后续的 repo 清单管理奠定了基础。

第二阶段：GitLab 服务端环境加固

为了支撑全新的工作流，我对 GitLab 服务器进行了关键的底层配置：

第二次迭代（2026）：把没有 repo 链路的厂商 SDK 恢复成 N 个 Git 子仓库

Mon, 10 Aug 2026 00:00:00 +0000

从一份经过开发板厂商深度定制过的SDK压缩包，经过整个流程（5份shell脚本+1份python脚本）的处理。

得到一份可以一键式拉取就可以正确编译出镜像，且镜像能够正常运行的深度修复的由若干（一般几十到一百多个）子仓库组成的SDK代码。

4-verify-sync.sh 的 6 项断言结果:重建出来的 58 仓库与只读基线逐字节比对。3 项 FAIL 是逐项判定后接受的差异,不是没跑完 —— 每一项的取舍见下文

一、做了什么

输入

厂商给到手的就是一个 tarball,没有任何 repo 链路:

体积 10G

-rwxrwxrwx 1 developer developer 10G Jul 31 19:44 <share>/02.Products/rk3576/rk3576-linux-6.1_20260709.tar.xz

.repo 不存在

developer@rk3576-rk3576_ubuntu-22-04:~/sdk/linux/sdk-src/rk3576-linux-6.1-readonly$ find . -name ".repo"
developer@rk3576-rk3576_ubuntu-22-04:~/sdk/linux/sdk-src/rk3576-linux-6.1-readonly$

所有 .git 都是指向那个不存在的 .repo 的软链接

developer@rk3576-rk3576_ubuntu-22-04:~/sdk/linux/sdk-src/rk3576-linux-6.1-readonly$ find . -name ".git" -exec ls -lhat {} \;
lrwxrwxrwx 1 developer developer 28 Jun 22 17:46 ./u-boot/.git -> ../.repo/projects/u-boot.git
lrwxrwxrwx 1 developer developer 32 Jun 22 17:38 ./kernel-6.1/.git -> ../.repo/projects/kernel-6.1.git
lrwxrwxrwx 1 developer developer 27 Nov 20 2025 ./rkbin/.git -> ../.repo/projects/rkbin.git
lrwxrwxrwx 1 developer developer 47 Jun 22 17:28 ./external/rknn-toolkit2/.git -> ../../.repo/projects/external/rknn-toolkit2.git
lrwxrwxrwx 1 developer developer 41 Jun 22 17:40 ./external/libmali/.git -> ../../.repo/projects/external/libmali.git
lrwxrwxrwx 1 developer developer 42 Jun 22 17:42 ./external/rknn-llm/.git -> ../../.repo/projects/external/rknn-llm.git
lrwxrwxrwx 1 developer developer 41 Jun 22 17:38 ./external/uvc_app/.git -> ../../.repo/projects/external/uvc_app.git
lrwxrwxrwx 1 developer developer 44 Jun 22 17:42 ./external/minilogger/.git -> ../../.repo/projects/external/minilogger.git
lrwxrwxrwx 1 developer developer 49 Jun 22 17:37 ./external/security/bin/.git -> ../../../.repo/projects/external/security/bin.git
lrwxrwxrwx 1 developer developer 57 Jun 22 17:37 ./external/security/rk_tee_user/.git -> ../../../.repo/projects/external/security/rk_tee_user.git
lrwxrwxrwx 1 developer developer 57 Jun 22 17:37 ./external/security/librkcrypto/.git -> ../../../.repo/projects/external/security/librkcrypto.git
lrwxrwxrwx 1 developer developer 40 Jun 22 17:37 ./external/rockit/.git -> ../../.repo/projects/external/rockit.git
lrwxrwxrwx 1 developer developer 42 Jun 22 17:37 ./external/rkupdate/.git -> ../../.repo/projects/external/rkupdate.git
lrwxrwxrwx 1 developer developer 47 Jun 22 17:37 ./external/rockchip-test/.git -> ../../.repo/projects/external/rockchip-test.git
lrwxrwxrwx 1 developer developer 53 Jun 22 17:38 ./external/camera_engine_rkaiq/.git -> ../../.repo/projects/external/camera_engine_rkaiq.git
lrwxrwxrwx 1 developer developer 42 Jun 22 17:38 ./external/chromium/.git -> ../../.repo/projects/external/chromium.git
lrwxrwxrwx 1 developer developer 46 Jun 22 17:37 ./external/rkwifibt-app/.git -> ../../.repo/projects/external/rkwifibt-app.git
lrwxrwxrwx 1 developer developer 37 Jun 22 17:42 ./external/mpp/.git -> ../../.repo/projects/external/mpp.git
lrwxrwxrwx 1 developer developer 45 Jun 22 17:38 ./external/alsa-config/.git -> ../../.repo/projects/external/alsa-config.git
lrwxrwxrwx 1 developer developer 38 Jun 22 17:39 ./external/dpdk/.git -> ../../.repo/projects/external/dpdk.git
lrwxrwxrwx 1 developer developer 42 Jun 22 17:37 ./external/rkwifibt/.git -> ../../.repo/projects/external/rkwifibt.git
lrwxrwxrwx 1 developer developer 37 Jun 22 17:38 ./external/avs/.git -> ../../.repo/projects/external/avs.git
lrwxrwxrwx 1 developer developer 46 Jun 22 17:42 ./external/rk_pcba_test/.git -> ../../.repo/projects/external/rk_pcba_test.git
lrwxrwxrwx 1 developer developer 50 Jun 22 17:39 ./external/common_algorithm/.git -> ../../.repo/projects/external/common_algorithm.git
lrwxrwxrwx 1 developer developer 37 Jun 22 17:39 ./external/iva/.git -> ../../.repo/projects/external/iva.git
lrwxrwxrwx 1 developer developer 46 Jun 22 17:39 ./external/ethercat_igh/.git -> ../../.repo/projects/external/ethercat_igh.git
lrwxrwxrwx 1 developer developer 41 Jun 22 17:38 ./external/uac_app/.git -> ../../.repo/projects/external/uac_app.git
lrwxrwxrwx 1 developer developer 41 Jun 22 17:37 ./external/samples/.git -> ../../.repo/projects/external/samples.git
lrwxrwxrwx 1 developer developer 43 Jun 22 17:37 ./external/rktoolkit/.git -> ../../.repo/projects/external/rktoolkit.git
lrwxrwxrwx 1 developer developer 43 Jun 22 17:42 ./external/linux-rga/.git -> ../../.repo/projects/external/linux-rga.git
lrwxrwxrwx 1 developer developer 42 Jun 22 17:42 ./external/recovery/.git -> ../../.repo/projects/external/recovery.git
lrwxrwxrwx 1 developer developer 41 Jun 22 17:38 ./external/xserver/.git -> ../../.repo/projects/external/xserver.git
lrwxrwxrwx 1 developer developer 44 Jun 22 17:39 ./external/drm-cursor/.git -> ../../.repo/projects/external/drm-cursor.git
lrwxrwxrwx 1 developer developer 40 Jun 22 17:42 ./external/rkfsmk/.git -> ../../.repo/projects/external/rkfsmk.git
lrwxrwxrwx 1 developer developer 52 Jun 22 17:39 ./external/gstreamer-rockchip/.git -> ../../.repo/projects/external/gstreamer-rockchip.git
lrwxrwxrwx 1 developer developer 44 Jun 22 17:37 ./external/rockit_uvc/.git -> ../../.repo/projects/external/rockit_uvc.git
lrwxrwxrwx 1 developer developer 40 Jun 22 17:33 ./external/rknpu2/.git -> ../../.repo/projects/external/rknpu2.git
lrwxrwxrwx 1 developer developer 27 Jun 22 17:45 ./tools/.git -> ../.repo/projects/tools.git
lrwxrwxrwx 1 developer developer 32 Jun 22 17:35 ./docs/cn/.git -> ../../.repo/projects/docs/cn.git
lrwxrwxrwx 1 developer developer 42 Jun 22 17:36 ./docs/cn/RK3576/.git -> ../../../.repo/projects/docs/cn/RK3576.git
lrwxrwxrwx 1 developer developer 26 Jun 22 17:35 ./docs/.git -> ../.repo/projects/docs.git
lrwxrwxrwx 1 developer developer 38 Jun 22 17:38 ./docs/rtt-docs/.git -> ../../.repo/projects/docs/rtt-docs.git
lrwxrwxrwx 1 developer developer 32 Jun 22 17:37 ./docs/en/.git -> ../../.repo/projects/docs/en.git
lrwxrwxrwx 1 developer developer 42 Jun 22 17:38 ./docs/en/RK3576/.git -> ../../../.repo/projects/docs/en/RK3576.git
lrwxrwxrwx 1 developer developer 39 Jun 22 17:29 ./app/rkpartybox/.git -> ../../.repo/projects/app/rkpartybox.git
lrwxrwxrwx 1 developer developer 34 Jun 22 17:29 ./app/rkadk/.git -> ../../.repo/projects/app/rkadk.git
lrwxrwxrwx 1 developer developer 43 Jun 22 17:28 ./app/ipcweb-backend/.git -> ../../.repo/projects/app/ipcweb-backend.git
lrwxrwxrwx 1 developer developer 34 Jun 22 17:29 ./app/rkipc/.git -> ../../.repo/projects/app/rkipc.git
lrwxrwxrwx 1 developer developer 38 Jun 22 17:28 ./app/lvgl_demo/.git -> ../../.repo/projects/app/lvgl_demo.git
lrwxrwxrwx 1 developer developer 116 Jun 22 17:43 ./prebuilts/gcc/linux-x86/aarch64/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/.git -> ../../../../../.repo/projects/prebuilts/gcc/linux-x86/aarch64/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu.git
lrwxrwxrwx 1 developer developer 117 Jun 22 17:42 ./prebuilts/gcc/linux-x86/aarch64/arm-gnu-toolchain-13.2.Rel1-x86_64-aarch64-none-elf/.git -> ../../../../../.repo/projects/prebuilts/gcc/linux-x86/aarch64/arm-gnu-toolchain-13.2.Rel1-x86_64-aarch64-none-elf.git
lrwxrwxrwx 1 developer developer 114 Jun 22 17:44 ./prebuilts/gcc/linux-x86/arm/gcc-arm-10.3-2021.07-x86_64-arm-none-linux-gnueabihf/.git -> ../../../../../.repo/projects/prebuilts/gcc/linux-x86/arm/gcc-arm-10.3-2021.07-x86_64-arm-none-linux-gnueabihf.git
lrwxrwxrwx 1 developer developer 109 Jun 22 17:44 ./prebuilts/gcc/linux-x86/arm/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux/.git -> ../../../../../.repo/projects/prebuilts/gcc/linux-x86/arm/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.git
lrwxrwxrwx 1 developer developer 40 Jun 22 17:33 ./device/rockchip/.git -> ../../.repo/projects/device/rockchip.git
lrwxrwxrwx 1 developer developer 31 Jun 22 17:29 ./buildroot/.git -> ../.repo/projects/buildroot.git
developer@rk3576-rk3576_ubuntu-22-04:~/sdk/linux/sdk-src/rk3576-linux-6.1-readonly$

输出

项目	结果
独立 Git 仓库	58 个
清单仓库	`default.xml`(manifest),托管在 `<server>/<GROUP>/`
客户端拉取	3 条命令(`repo init` / `repo sync -j8 --verify` / `repo forall -c 'git lfs pull'`)
体积	编译前 ~28G,编译后 ~78G
校验	`4-verify-sync.sh`,6 项自动断言
交付文档	纯命令、零理论;8 类故障 + 对应处置
验收	同事独立编译 + 烧写,均成功

客户端拉取(完整,无省略)

repo init -u http://<server>/<GROUP>/manifest.git -b main -m default.xml --no-clone-bundle
repo sync -j8 --verify
repo start main --all
repo forall -c 'git lfs pull'

除了 repo start main --all 之外的三条都不能省。 --verify 少了会停在 (yes/always/NO) 交互提示上,默认 NO, 于是 repo hook 不执行、空目录不出现、编译可能直接失败; git lfs pull 少了只有 17G 而不是 28G,编译报文件损坏。