从「手点 80 下」到「点一次通过」

0. 一页速览

一句话总结：把「设备白名单变更」这件高频、机械、易漏的事，拆成 显式的文件契约 + 幂等的命令 + 有状态的自助台。

1. 为什么要做这件事

1.1 痛点不是”登记设备”，而是”登记之后”

设备登记本身只是 Apple 后台填一行 UDID。真正贵的是它的连锁反应：

设备白名单变了 → 所有绑设备的描述文件（Development / Ad Hoc）全部失效 → 每个 App、每种类型都要 Edit → 勾选新设备 → Generate → 重新下载 → 归档进证书仓库 → 构建机重装 → 重打包。

按本项目规模算：10 个 App × 2 类 = 20 份 Profile，每份 4 次点击 + 1 次下载 + 1 次归档，一次设备变更 ≈ 80 次点击，而且漏一份就是一个 App 装不上。

1.2 四个真实后果

1.3 目标（当时写进方案的验收线）

1. 一条命令 / 一次点击完成 登记 → 重建 → 归档；
2. 重复执行不产生重复设备、不产生多余提交（幂等）；
3. 多 Apple 账号 零代码切换；
4. Profile 名字稳定（UUID 可变，名字不可变）；
5. 失败能定位、能重试，而不是”再跑一次试试”。

2. 方案骨架：六层，两条边界

1
2
3
4
5
6
7
8
① 配置层（入库）        devices.txt / Appfile / Fastfile / Gemfile
② 凭据层（不入库）      .env、.env.<team>、AuthKey_*.p8
③ 执行层（CLI）         Fastfile：verify_auth / register / update_profiles …
④ 苹果云端              Devices 白名单、Provisioning Profiles
⑤ 分发层（CLI）         sign_sync.sh：./profiles/ → Sign 仓库 → commit/push
⑥ 消费层（CI）          auto_install_all_cer.sh 装证书、auto_build.sh 重打包
────────────────────────────────────────────────────────────
⑦ 自助层（v1.1 新增）   web-form：内网提单 → 审核台 → 队列执行 → 实时日志

两条边界原则，是整个方案好维护的关键：

sign_sync.sh 不做任何 Apple 侧操作，Fastfile 不做任何 Git 操作。 二者只通过 ./profiles/ 这一个目录耦合 —— 文件即契约，任一侧都能单独替换。

这也是后来能顺利加一层 Web 自助台的原因：新层只负责「调用 CLI」，不碰 Apple、不碰归档逻辑。

3. 五个决定成败的实现细节

3.1 认证：三级降级，但只推荐第一级

1
2
3
4
5
ASC_KEY_ID + ASC_ISSUER_ID ?  ── 是 ──► ① API Key 文件路径（开发机）
        │否
API_KEY_ID + API_ISSUER_ID ?  ── 是 ──► ② Key 内容 base64（CI 注入）
        │否
                              ────────► ③ Apple ID + 2FA（兜底，人值守）

• 为什么 API Key 优先：JWT 无状态鉴权，不受双因子与密码变更影响，可无人值守；Apple ID 方式一旦触发 2FA，自动化就断了。
• 踩坑：ASC_KEY_FILEPATH=~/private_keys/x.p8 直接透传会误报文件不存在 —— Ruby 的 File.exist? 不展开 ~，只有 Shell 会。必须先 File.expand_path。

3.2 重建：update_profiles 的四件套参数

1
2
3
4
5
6
7
8
9
get_provisioning_profile(
  development: true,                          # 类型开关（sigh 用布尔，match 才用 type:）
  app_identifier: bundle_id,                  # sigh 一次只吃一个 → 必须循环
  provisioning_name: dev_name,                # ① 钉死 Apple 端名字
  ignore_profiles_with_different_name: true,  # ② 只动精确同名者，防误删
  force: true,                                # ③ 删旧建新，把新设备一次性纳入
  output_path: output_dir,                    # ④ 落盘到 ./profiles/
  filename: "#{dev_name}.mobileprovision"     # ⑤ 本地名 = 后台名，便于人工核对
)

逐个说人话：

关键认知：force: true 是「删除 + 新建」，UUID 必变、名字不变。 所以下游只能按 名字 引用，绝不能按 UUID —— 这一条要写进构建侧的契约，而不是靠口头约定。

3.3 路径：以 Fastfile 自身为锚点

1
2
3
4
5
# ❌ fastlane 执行时会 chdir 到 fastlane/，被叠加成 fastlane/fastlane/devices.txt
DEVICES_FILE = "./fastlane/devices.txt"

# ✅ 与 cwd 解耦
DEVICES_FILE = File.expand_path("devices.txt", __dir__)

推广规则：Fastfile 里引用项目内文件，一律 __dir__ 锚定，禁止 Dir.pwd。

3.4 多团队：--env 零改码，但有两个前提

1
2
bundle exec fastlane register              # 默认 Team
bundle exec fastlane register --env caes   # 切到 Team2（凭据覆盖）

加载时序决定了「不用改代码」：dotenv 在 Fastfile 求值之前 加载，所以 Fastfile 顶部 APP_IDENTIFIERS = ENV["…"] 这类常量天然跟随 --env。

两个高危前提：

1. .env.<team> 必须填全部团队相关变量，漏一项就沿用基础 .env → Issuer 与 Key 串号 → 401；
2. .gitignore 必须写 .env.*，只写 .env 会把新团队的凭据提交上去。

3.5 devices.txt：格式是契约，注释有陷阱

Fastlane 的实现顺序是「先 CSV.read 解析整个文件，再过滤 # 注释」，于是有三个反直觉约束：

提交前用与 Fastlane 一致的方式预校验，比跑到一半再失败便宜得多：

1
2
3
4
require "csv"
raw = CSV.read("fastlane/devices.txt", headers: true, col_sep: "\t",
               skip_blanks: true, skip_lines: /^#/)
puts "解析到 #{raw.count} 台；表头 = #{raw.headers.inspect}"

4. 自助层：把「只有我会跑」变成「谁都能提单」

CLI 解决了”重复劳动”，但没解决”依赖人”。于是加了 web-form（Node 原生 http，零依赖）：

1
2
3
4
5
6
7
8
 内网同事                ① 提单（0.0.0.0:3000）        ② 审核台（127.0.0.1:3001）
   │  UDID / 使用者 / 型号 / 类型                            │
   ├───────────────► pending ──────────────────────────────►│
   │                   （只落库，不执行任何命令）              │ 通过 / 拒绝 / 批量通过
   │                                                          ▼
   │            ③ 队列执行（全局单任务锁） approved → running → success / failed
   │               clone → 注入凭据 → 追加设备 → register ×2 → push + sign_sync
   └───────────────④ 我的提交（状态 / 耗时 / 失败原因 / 日志）◄────┘

4.1 设计要点

4.2 六步流水线（每一步失败即整批失败、可重试）

5. 演示

原始录屏 3 分 56 秒（fastlane_apple_profile.mov），压缩为 43 秒、4.2 MB 的标注版 GIF；中段 Profile 重建部分以 20× 加速。 时间轴：0:00 审核台总览 → 0:06 一键通过，六步流水线启动 → 0:17 Team1 完成、切 Team2 → 0:26 全量重建（加速） → 0:34 归档并推送 Sign 仓库。

6. 踩过的坑 · 可直接照抄的清单

401 的分层排查顺序（凭据问题，不是代码问题）：本机时钟 → .p8 完整性 → Key ID 与文件名同源 → Issuer 与 Key 同账号 → Key 是否被撤销。

7. 效果与边界

7.1 数字

• 单次设备落地：约 4 分钟（Team1 2 个 App 约 40s，Team2 8 个 App 约 170s）；
• 一次变更覆盖 20 份 Profile（10 个 Bundle ID × Dev/AdHoc），无需逐份点；
• 归档映射：38 项 → 13 个目录，git status --porcelain 守门，内容没变不产生空提交；
• 失败可重试、日志可回查，交接成本从”找那个人”变成”看那个日志”。

7.2 当前边界（诚实清单）

7.3 演进顺序（按收益）

1. 双数组抽成单份 profiles.map 映射文件 → 消除脱节；
2. 自助层接 CI / 企业微信机器人 → 结果主动播报；
3. 上限阈值告警（≥90 台）；
4. devices.txt 按 --env 拆分 → 多 Team 设备隔离。

8. 三条可复用的经验

1. 幂等 > 聪明。force 删旧建新、mv 归档、porcelain 守门、批内查重 —— 每个动作都设计成「重复执行结果一致」，比任何”增量更新”的巧妙逻辑都可靠。
2. 把契约显式化。名字、目录、文件格式、访问入口，全部写死并文档化：provisioning_name ↔ ExportOptions.plist、./profiles/ ↔ sign_sync.sh、127.0.0.1 ↔ 审核台。显式映射可评审，自动推断迟早出事。
3. 人工步骤要变成状态机。有状态、有日志、能重试，才谈得上交接；否则自动化只是把”只有他会”换成了”只有脚本会”。

9. Q&A 预案

• Previous
  Podfile_local介绍、集成与使用