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

iOS MR 包体积分析实践:APPAnalyze、Link Map 与跨项目接入

这个 job 解决什么问题 analyze_app_size_mr 是合并前的包体积预检:复用 build_app 已构建的 App,回答「当前包有多大、代码与资源各占多少、哪些模块或资源最重、这笔 MR 相比目标分支是否增长」。分析结果自动出现在 MR 评论里,并附完整 HTML / JSON 报告,方便评审时定位增长来源。 几个关键约定: 不重新编译 App:依赖 build_app 的 Beta、iphoneos、无签名产物,分析阶段只做扫描、汇总和报告; APPAnalyze 看最终 .app,二进制、资源和静态扫描问题;Link Map 补足主程序内部静态库的来源归因; 分支 push 的 analyze_app_size 负责写入基线;MR 的 analyze_app_size_mr 只读取目标分支基线; allow_failure: true:分析失败允许流水线继续;扫描提示用于评审参考,当前没有按体积阈值阻止合并。 MR 的真实运行结果(以 !271 为例) MR !271 已合入;最终 Pipeline #7020 成功,源码 SHA 为 e55c648b。build_app #17094 成功(约 451.6 秒);analyze_app_size_mr #17108 成功(约 80.6 秒)。这是单次耗时证据,不能代表所有项目或冷缓存场景。 package_size.json:.app 总计 357,058,497 B(357.1 MB),二进制 210,367,928 B(210.4 MB),资源 146,690,569 B(146.7 MB)。报告展示使用十进制 MB。 ...

November 2, 2026

UgreenHome RN iOS 组件化与调试能力重建(阶段总结)

背景与目标 2026-10-29 至 11-02,我接手了 UgreenHome 主工程里一套陈旧的 RN(React Native)依赖栈,把目标定为三件事: 清理重复的实现入口与本地临时代码,统一走内网 Specs / GitLab / Nexus; 把可复用逻辑按单一职责拆成独立组件; 恢复原生符号调试与 Metro JS 调试,同时不破坏默认的离线与发布链路。 明确的不变量:不再为内部库新增「Debug/Release × 静态/动态」四套制品;不覆盖已发布 tag;所有产品变更走 MR;主工程保留业务组合,不追求机械地搬空目录。 本文是阶段收口记录。这里先说明一个原则:已发布、已合入、测试通过、真实设备运行通过,这四件事要分别记录,不能互相替代。下面凡是说到「已合入」「已发布」,都不代表所有真机业务场景已逐项通过。 推进路线 先清理、再合入:移除重复的 Runtime/Kit 接线与过时实验内容,清理无用分支、worktree、临时文件与部分缓存,保留未提交的业务改动。 建立远端组件边界:从 LocalPods / 主工程抽取可复用逻辑与资源,迁到 home/rn;测试随实现进入 test_spec,宿主只保留跨组件与设备集成测试。 治理依赖图:从显式 binary 选择推导传递 redirect,处理 Lottie、MMKVCore、ZIPFoundation 等同模块双实现问题,再扩展为调试源码闭包。 恢复 RN_DEBUG:统一安装入口、源码/Debug 变体选择、Metro 编译隔离与调试工具组件化。 继续下沉:通用 Debug 编辑器已发布,宿主 MR !262 已合入;UGreenRNComponents 0.1.0 已发布,WebView / Lottie 两个 subspec 已由宿主 MR !273 消费,原实现已从主工程删除。 阶段成果与真实边界 依赖单一真源:移除 LocalPods/UGreenRNRuntime 等重复清单,以 Podfile 的 rn_dependencies 统一维护版本与来源。 组件化切片:Platform、Transport、DeviceSettings、E-Ink、Debug 等职责已有独立组件。Transport 先下沉 HTTP callback gate / 取消策略,DeviceSettings 先下沉启动校验 / 手势 / codec,E-Ink 先下沉图片身份 / 重试 / 调度——不宣称整套 HTTP / MQTT / 业务桥已搬完。 ...

November 2, 2026

UHPlayerSDK 打 tag 打包失败复盘

概述 10 月 26 日,UHPlayerSDK 打 1.1.0.rc1 tag 时,动态库真机 archive 在 PrecompileModule 阶段失败,xcodebuild 退出码 65,甚至还没编到 SDK 源码。 根因是 CI 的每日缓存清理脚本按文件年龄逐个删除 Xcode 编译缓存,把仍被后续构建引用的系统 module 对象拆掉了。这破坏了按内容寻址(CAS)缓存的正确性——不是简单的缓存未命中。 本文记录现象、排查过程、根因,以及清理规则、发版 pin、launchd 路径三类修复。 现象 1.1.0.rc1 的 release-ug-component 流水线失败。同一流水线里: job 14862:git fetch 连接被重置(exit 128),属于网络抖动; 重试后的 job 14863:才是真正的构建失败。 失败点是动态库、真机 archive,xcodebuild 退出码 65,报错停在预处理系统 module: error: There was an error precompiling module .../ExplicitPrecompiledModules/_AvailabilityInternal-....scan _AvailabilityInternal 是 Xcode SDK 里的系统 clang module。构建脚本把 xcodebuild 输出交给 xcpretty 美化,底层 clang 的详细诊断被滤掉了,所以第一眼看不到根因。 排查过程 先排除了几类常见怀疑: 源码没问题:tag 指向的 44b366aa 与 10 月 23 日 MR !12 成功 archive 的是同一棵树; 依赖和工具链没变:仍是 RTCXSDK 1.7.0.7、libopus 1.1,Xcode 仍是 26.5(17F42); 发版改写不是原因:podspec 仍是 1.0.5,发版脚本会改写成 tag 版本,1.1.0 当时也是这么改写后 archive 成功的; 磁盘/进程问题无关:10 月 24 日磁盘写满(No space left on device)和随后的 maxUserProcs 耗尽是另一件事,UHPlayerSDK 当时并未写这份缓存。 真正定位靠一句话:整份删掉 compilation_cache/464 再编就通过了。说明问题在缓存本身,而不是源码或依赖。 ...

October 26, 2026

hf auth login 粘贴 token 崩溃排查与修复

现象 homebrew 安装的 hf CLI(huggingface_hub 2.3.0,venv 基于 Python 3.15.1)执行 hf auth login,粘贴 token 后立即崩溃,刷屏 Python traceback(ImportError)。 根因 ~/.zshenv 中无条件导出: export all_proxy=socks5://127.0.0.1:7897 这是 Clash Verge Rev 的混合端口,对所有 shell(包括子 shell)生效。hf 粘贴 token 后调用 whoami 校验,huggingface_hub 创建 httpx 客户端时检测到 SOCKS 代理,需要 socksio 包;而 homebrew 的 hf venv(--without-pip --system-site-packages 创建)未打包 socksio,于是: ImportError: Using SOCKS proxy, but the socksio package is not installed 之所以恰好在「粘贴 token 时」崩:那是整个登录流程中第一次发 HTTP 请求的时刻,getpass 读输入本身不发网络请求。 修复 把 socksio 1.0.0 装进 hf venv 自己的 site-packages(不污染共享的 python@3.15): ...

October 25, 2026

cc-switch 切 Codex 供应商「不生效」的排查

现象 cc-switch 里切换 Codex 供应商(官方 ↔ 自建)后,codex 仍走原供应商,像没生效。 根因(三个独立问题) 1. daemon 不重读配置 cc-switch 只改写 ~/.codex/config.toml;真正发请求的是常驻 managed daemon(codex app-server --listen unix:// --managed-daemon,由 pid-update-loop 守护、PPID=1 常驻后台),它只在启动时读一次 config,之后不重读。 → 切了文件但 daemon 没重启 = 没用。 2. daemon 忽略 SIGTERM 有客户端连接时 kill(TERM) 返回成功但进程不死,必须 SIGKILL。早期 codex-restart「没生效」就是这个坑。 3. requires_openai_auth 残留(最新发现) cc-switch 切换是「合并」写 config:官方→自建时更新 base_url / bearer_token,却把上个官方配置里的 requires_openai_auth=true 留了下来。=true 会让 codex 用官方 OAuth 账号、忽略自建 base_url → 仍走官方。自建时该行必须为 false。(cc-switch 里 UGreen 模板存的其实是 false,但合并时没覆盖到。) daemon 是谁启动的 不是 launchd 登录项(launchctl / ~/Library/LaunchAgents 无 codex 任务),而是 codex 自己按需拉起:首次运行 codex CLI 或打开桌面版时 spawn pid-update-loop(监督者)+ app-server(daemon),之后常驻后台(脱离父进程、过继给 PID 1),只在被 kill 或注销 / 重启时死。 ...

October 22, 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

UgreenHome CocoaPods Specs / 镜像 tag 故障复盘

背景与现象 主工程使用内部 CocoaPods Specs 仓库。某些源码 pod 的 source.git 指向内部 GitLab 镜像;另一些第三方依赖由 *-bin spec 提供预编译 XCFramework。FCUUID-bin 的 spec 声明了对源码 pod UICKeyChainStore (~> 2.1.0) 的依赖,而主工程此前没有直接声明 UICKeyChainStore。 删除 iot/Podfile.lock 后运行 make -C iot pods,CocoaPods 重新解析传递依赖,选中了 Specs 中的 UICKeyChainStore 2.1.3。该 spec 指向镜像中不存在的 v2.1.1 tag,安装失败,典型报错是 fatal: Remote branch v2.1.1 not found in upstream origin。这发生在依赖解析、源码获取阶段,尚未进入 App 链接。 主工程 Podfile → FCUUID-bin 1.3.3.1 → UICKeyChainStore (~> 2.1.0) [传递源码依赖] → 无 lock 时选到 2.1.3 → source.tag = v2.1.1 [镜像不存在] → make pods 失败。 ...

October 21, 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