UgreenHome 共享库 CI:依赖安全扫描与内网构建复盘

背景 UgreenHome 的 iOS / Android 两端共用一个 Kotlin Multiplatform(KMP)共享库 ugreenhome-shared。随着库里引入的开源与第三方 SDK 越来越多,安全与合规团队希望能定期知道「到底用了哪些包、什么版本、有没有已知漏洞」,而不是每次发版手工对账。这就是 SCA(软件成分分析)的诉求。 SCA 的流程本身不复杂:先用 Gradle 导出依赖清单(SBOM),再用 Grype 之类的扫描器比对漏洞库,最后把结果写进内部 Wiki 并通知相关人。真正麻烦的是前面那一步——导出 SBOM 需要先完整编译,而编译机在公司内网,连不上 Google Maven、Gradle Plugin Portal 这些外网源,公共镜像又经常抽风。于是这次工作的本质,就是打通「在内网里把依赖完整解析出来」这条链路。 说明:文中提到的 MR 编号(如 !87)、Pipeline 编号(如 7190)都是内网 GitLab 的内部标识,只当作叙事锚点,外部无法访问,也不附链接。 名词解释 SBOM(Software Bill of Materials,软件物料清单):一次构建实际用到的全部依赖(含传递依赖)的清单,通常带版本与坐标,是安全扫描的比对基线。 SCA(Software Composition Analysis,软件成分分析):对 SBOM 做漏洞 / 许可证扫描的过程。 GAV:Maven 坐标 group:artifact:version,例如 androidx.fragment:fragment-ktx:1.8.0,用来唯一定位一个依赖。 Nexus:公司内网的私有仓库(Maven 代理 + 托管)。本次用到 maven-ugreenhome-release(正式包)、maven-ugreenhome-snapshot(内部 SNAPSHOT)、ugreenhome-group(聚合多个源)。 Grype:一款开源漏洞扫描 CLI,被放进 Nexus 的 raw 仓,CI 从内网下载。 seed(镜像上传):在能连外网的机器上,把 Plugin Portal / Google Maven 上的包下载并上传到 Nexus,CI 再从内网拉。 init.gradle:Gradle 启动时执行的脚本,用来统一改写「去哪个仓库找包」的优先级。 为什么 CI 里会「下包失败」 可以把 Gradle 在 CI 里的依赖来源想成三道独立的采购渠道,缺任何一道,构建都会在不同阶段挂掉: ...

November 4, 2026

Jenkins iOS Agent 的 Git LFS Checkout 失败排查

背景 某 iOS 工程把约 132 个 vendored gem(iot/vendor/cache/*.gem)通过 git-filter-repo 迁到了 Git LFS 并 force-push。此前这些 gem 是普通 git blob,checkout 不触发 git-lfs。迁移后,Jenkins 的 iOS agent(由 launchd 拉起、无 GUI 会话)第一次 checkout 到含 LFS 内容的版本,问题才暴露。 为什么会「以前没事、今天突然挂」:① 仓库是最近才引入 LFS 的,以前 checkout 根本不触发 git-lfs;② launchd agent 从一开始就没有 GUI 会话 / 完整 PATH,只是以前没被需要。 名词解释 Git LFS:Git 大文件存储,把大文件(此处是 gem 包)存到独立对象存储,工作区 checkout 时通过 smudge 过滤器按需下载。 smudge / clean / filter-process:LFS 的过滤器钩子;checkout 时的 smudge 负责把指针换成真实文件。 osxkeychain:macOS 系统级 Git 凭据助手,从登录钥匙串读凭据;无登录会话的后台进程读不到。 credential.helper:Git 的凭据获取机制;空值会清空下层继承的 helper。 现象(错误随修复逐层演进) 轮次 报错 所属层面 1 git-lfs: command not found agent PATH 不含 Homebrew 2(手动配 filter 配坏) filter-process: command not found filter.lfs.process 配成裸 filter-process 3(改绝对路径后) failed to get: -60008 osxkeychain 在 launchd 下读不了登录钥匙串 4(禁用 osxkeychain 后) batch response: too many authentication attempts git-lfs 拿不到 LFS 接口凭据 三层报错各不相同,是典型的「修好一层、暴露下一层」。 ...

October 22, 2026

UDC 镜像仓库迁移踩坑记录

背景 一次把 UDC 相关仓库从外部 GitLab 源迁到内网 GitLab + Nexus 的迁移,踩了十来个坑。本文把每个坑的「现象 → 根因 → 修复」记下来,方便后续再做类似镜像同步时直接对照。迁移目标是:把外部源(记为 gitlab-cloud)的仓库改写成指向内网 GitLab 的 podspec,并同步 Maven 产物到内网 Nexus。 名词解释 Pull Mirror(GitLab 原生镜像):GitLab 自带的仓库镜像功能,让镜像仓库与上游完全一致。 Nexus:内网私有仓库(Maven / raw 等),用来托管同步过来的二进制与 Maven 产物。 Protected 变量:GitLab CI 变量标记为 Protected 后,只在保护分支 / 标签上注入。 members/all:GitLab 查组成员接口,带 /all 才会包含从父组继承的成员。 一、GitLab 原生镜像根本没法用 一开始想直接用 GitLab 自带的 Repository Mirroring(pull mirror),结果它和「改写 podspec URL」的需求天然冲突:原生 pull mirror 会让镜像仓库与上游完全一致,等于把我们在内网侧做的 podspec URL 改写每次同步都覆盖回去。而且源仓库里的 podspec 仍带外部域名,我们用的同步 bot 是源项目的只读成员,push 回源会 403 “not allowed to upload code”——源仓库修不了。 ...

October 21, 2026

GitLab macOS Runner 构建成功后卡死 27 分钟排查

背景与现象 某条 iOS 主工程的 MR 流水线,构建 job 在 Build Succeeded 之后,卡在 Cleaning up project directory and file based variables 约 27 分钟,GitLab 页面一直显示 running(14:57 构建完成,15:24 才上报 success)。编译本身只花了约 8 分钟——卡的是 job 收尾阶段,而且最终自行成功,属于「假死」而非失败。 名词解释 GitLab Runner:执行 CI job 的 agent 进程;concurrent 控制同一台机器上能并行跑几个 job。 DerivedData:Xcode 的构建中间产物目录,体积大、文件多。 CAS(Content Addressable Storage):Xcode 编译缓存,按内容寻址,默认无清理上限。 launchd:macOS 的系统服务管理器,相当于开机自启 + 定时任务(类似 cron,但睡眠错过会自动补跑)。 排查过程(逐层排除) 磁盘 / inode:盘仅 66% 使用、300G+ 可用、inode 充足 → 排除磁盘满。 日志定位卡点:日志尾部 Build Succeeded → after_script → Saving cache 全部完成,最后沉默在收尾清理段 → 卡的是 runner 清理,不是编译。 自研探针一次采齐(gitlab-runner-probe.sh):runner 配置 concurrent = 3;builds 目录 131G(DerivedData 56G + 编译缓存 49G + checkout 22G);项目 checkout 仅 2.4G / 6 万文件,清理对象本身很小;事发时 load average 16/26/25,空载后回落到 5.65 → 负载与 CI 活动强相关;swap used 1.8G → 内存曾吃紧;删除微基准:6 万小文件 rm -rf 仅 2s → 排除文件系统删除吞吐问题。 时间线对齐:该 job 的清理窗口(14:58–15:24)与同 runner 上另一个 KMP 重构建 job(14:58–15:11)完全重叠。 根因定位 直接原因:同机并发超载。 concurrent=3 下,KMP 链接等重 job 把 CPU / IO / 内存打满(load 25+、动用 swap),收尾清理这种秒级小活被拖成 27 分钟。 ...

October 19, 2026

GitLab SAST 在 ARM64 Runner 上的故障复盘

背景与目标 把 Semgrep SAST 接到 iOS 工程的 CI 上,原本的扫描 job 一直跑不通。本文记录从 Rosetta 崩溃到原生 ARM64 镜像上线的全过程,以及其间踩到的十几个坑。结论是:本机 / 流水线显示「非阻断成功」都不算验收通过,真正的完成标准是——正式 job 执行成功、新报告有效、GitLab 解析成功、目标分支配置一致。 名词解释 SAST(Static Application Security Testing,静态应用安全测试):不运行程序,靠扫描源码发现安全缺陷。 Semgrep:一款开源的静态分析 / SAST 引擎,GitLab 官方 SAST analyzer 底层就用的它。 Rosetta:Apple 在 ARM64 macOS 上转译运行 AMD64 二进制的兼容层;转译路径异常时会有看不懂的分配错误。 ARM64 / AMD64:两种 CPU 指令集架构。混用会导致需要转译,转译层出问题是本次故障根源。 gl-sast-report.json:GitLab SAST 的标准报告文件,有官方 schema 校验。 最终结果(验收口径) 修复后,正式 semgrep-sast job 切换到固定 digest 的原生 ARM64 镜像。正式 job(Runner 13 上)成功运行;285 条规则扫描 2209 个文件,产生 111 条原始发现;gl-sast-report.json 状态为 success 并通过官方 schema 校验;服务端确认扫描 SUCCEEDED、errors=[]。 ...

October 16, 2026

GitLab 上 KMP 二进制的发布链路与踩坑

背景 把 Kotlin Multiplatform 共享库以 XCFramework 形式发给 iOS 侧使用时,发布链路并不只是「编出来传上去」。它涉及 XCFramework 构建、二进制归档、私有 CocoaPods Specs 仓库、GitLab 包 registry,以及一连串的权限与凭据隔离问题。这里把一次完整发布踩过的坑整理成可复用的清单。 推荐发布链路 flowchart LR A[构建 XCFramework] --> B[打包 ZIP + SHA256] B --> C[生成二进制 Podspec] C --> D[上传 GitLab Generic Package] D --> E[匿名下载并校验 ZIP/SHA] E --> F[pod spec lint] F --> G[push Podspec 到私有 Specs Git] G --> H[重新 clone / readback] H --> I[干净 Podfile 执行 pod install] 名词解释 XCFramework:Apple 的跨平台 / 多架构二进制分发格式,可同时携带真机与模拟器 slice。 Podspec:CocoaPods 的依赖描述文件,声明版本、源码 / 二进制地址与校验和。 Specs 仓库:存放 Podspec 的私有 Git 仓库,相当于私有 CocoaPods 源。 Generic Package Registry:GitLab 提供的通用二进制包仓库,用来托管 ZIP 等任意产物。 Project Access Token:GitLab 的项目级访问令牌,区别于个人令牌,可限定角色与权限范围。 1. 版本必须全链路一致 以下字段必须保持一致:Git tag、VERSION_NAME、Podspec 的 version、Package Registry 路径、ZIP 文件名、checksum sidecar 文件名,以及 Specs 路径(如 UgreenHomeShared/1.7.0.4/UgreenHomeShared.podspec)。 ...

September 22, 2026