说到持续集成，Jenkins 是用得比较多的。本文说明了我从安装到配置再到打包 ipa 文件，从手动打包到点击一下按钮自动生成 ipa 所做的事情。

得益于 Jenkins ，让开发体验提升了不少。不多说，文内多图，来跟我一起密林探索吧 :]

Jenkins

Jenkins安装

本文以 Jenkins 当前时间 2018.03.27 的最近 weekly 版本 2.113 来说明， Jenkins 是 Java web 项目，在使用上有 Java 环境的限制：jdk1.8 以上。

对于 macOS10.9 和 10.10 来说，系统中自带有 jdk1.6 ，但这并不符合要求。而其他版本（ macOS10.11 以上）中貌似没有 jdk ，可以在命令行工具键入java -version来判断。

若出现以下提示，则表示没有配置 Java 环境或系统中没有安装 jdk ：

No Java runtime present, requesting install.

若弹出安装对话框，点击 『好』 退出对话框。

不然，定位到/Library/Java/JavaVirtualMachines中可查看是否存在 jdk 。

如果都没有，或 jdk 版本不符，则需要重新安装。 macOS 的安装方式比较简单，在Oracle的jdk下载地址上下载 dmg 安装包，直接安装 jdk1.8 到系统中。然后修改~/.bashrc文件配置一系列的系统变量，如果使用zsh，则修改~/.zshrc。在文件末尾添加：

# 通常通过dmg安装的jdk都是在/Library/Java/JavaVirtualMachines/下，需根据实际情况对JAVA_HOME进行配置
export JAVA_HOME="/Library/Java/JavaVirtualMachines/jdk1.8.0_161.jdk/Content/Home"
export CLASS_HOME="$JAVA_HOME/lib"
export PATH=".;$PATH:$JAVA_HOME/bin"

然后重置一下配置：

source ~/.bashrc

或者（使用zsh）

source ~/.zshrc

再次使用java - version验证是否安装成功（全文部分截图是我使用公司电脑安装 Jenkins 时截下来的）：

55B9E6EFD1C3099B8203D17D0089360C

好了，然后安装 Jenkins ** 。同样的，在官网下载页面上选择 **Weekly — Mac OS X 下载 pkg 安装包。

Jenkins Website

以 2.113 为例，一步步安装。

Jenkins Install Begin

Jenkins Install Step2

安装完成后，会自动打开浏览器，跳转到localhost:8080可以看到 Jenkins 正在准备中…

如果提示打不开，使用 Safari 出现以下界面：

Oops Jenkins Start Failed

则可能是 jdk 的配置出了问题，返回去看看前文关于 jdk 的配置，检查一遍是否正确。

注：如果此时重启系统，会发现多了一个名为『 jenkins 』的普通成员。

在 jenkins 初始化工作完成后，会跳转到另一个*解锁 jenkins * 的界面，提示密码存放在/Users/Shared/Jenkins/Home/secrets/initialAdminPassword中，到其中查看，会发现secret文件夹被设置了权限，使用我们当前的用户无读写的权限。

解锁jenkins

此时使用命令行工具，键入如下命令，并输入电脑的管理员 root 密码（通常是我们自己的登录密码）后：

sudo cat /Users/Shared/Jenkins/Home/secrets/initialAdminPassword

可以看到 jenkins 的初始化密码：

屏幕快照 2018-03-26 下午12.44.11

将该密码填入到网页中，完成解锁工作。此密码同时是登录 jenkins 的 admin 账户的密码，见下文。

之后，安装社区推荐的插件即可：

屏幕快照 2018-03-26 下午12.45.24

然后创建第一个管理员用户，此处建议自行创建一个用户，当然也可以点击右下角的 『使用 admin 账户继续』 ，密码是 jenkins 的解锁密码，也就是 initialAdminPassword 里面那个字符串。

屏幕快照 2018-03-26 下午12.50.00

保存完成后，Congratulation~ 🎉🎉🎉

行李已经收拾好了，可以继续 jenkins 密林探索之旅了。

Jenkins配置

在安装完 Jenkins 后，就可以愉快地使用它来持续集成我们的项目了，如果对一些启动配置不感兴趣，不想看这一部分，可以愉快地略过，不修改配置也完全不影响使用。

需要修改配置的情况如下（包括但不完全包括）：

  1. 默认地，当 jenkins 安装在服务器上时，监听的是服务器的 8080 端口。而我们知道，在做 Java Web 开发时，应用服务器 tomcat 的默认端口也是 8080 ，不修改配置的话，很容易造成冲突。
  2. 我们在使用 Jenkins 会安装各种插件，同时运行很多个构建工作，都有可能造成内存溢出的问题。
  3. 当我们需要配置 HTTPS ，证书等等。

启动与关闭

首先，针对使用 pkg 安装的方式（使用直接下载 war ，用java -jar运行不在本文的讨论范围内。），Jenkins 作为一个后台驻留程序（ Daemon ），在 Wins 下我们习惯叫服务，自然有开关。

一个后台驻留程序是运行在系统后台的，没有任何GUI的程序。在 macOS 下，一个后台驻留程序的配置保存在一个plist文件中，非系统驻留程序的plist文件都统一存放在/Library/LaunchDaemons之中。

我们知道，plist本质是 xml 文件，其中存放的都是键值对，里面的键都是 launch.plist 中定义的，这个plist用于告知launch去哪里运行脚本，以及运行过程中一些路径和用户、组的配置。

所以，启动和关闭的命令看起来比较少见：

# 开启Jenkins
sudo launchctl load /Library/LaunchDaemons/org.jenkins-ci.plist
# 关闭Jenkins
sudo launchctl unload /Library/LaunchDaemons/org.jenkins-ci.plist

打开org.jenkins-ci.plist，看到ProgramArguments，写着运行脚本的位置：

019DE0A84C235007987FE3CF18813083

JVM的配置

接下来，我们来看看 jenkins-runner.sh 这个脚本中的内容。

#!/bin/bash
#
# Startup script used by Jenkins launchd job.
# Mac OS X launchd process calls this script to customize
# the java process command line used to run Jenkins.
#
# Customizable parameters are found in
# /Library/Preferences/org.jenkins-ci.plist
#
# You can manipulate it using the "defaults" utility.
# See "man defaults" for details.

defaults="defaults read /Library/Preferences/org.jenkins-ci"

war=`$defaults war` || war="/Applications/Jenkins/jenkins.war"

javaArgs="-Dfile.encoding=UTF-8"

minPermGen=`$defaults minPermGen` && javaArgs="$javaArgs -XX:PermSize=${minPermGen}"
permGen=`$defaults permGen` && javaArgs="$javaArgs -XX:MaxPermSize=${permGen}"

minHeapSize=`$defaults minHeapSize` && javaArgs="$javaArgs -Xms${minHeapSize}"
heapSize=`$defaults heapSize` && javaArgs="$javaArgs -Xmx${heapSize}"

tmpdir=`$defaults tmpdir` && javaArgs="$javaArgs -Djava.io.tmpdir=${tmpdir}"

home=`$defaults JENKINS_HOME` && export JENKINS_HOME="$home"

add_to_args() {
    val=`$defaults $1` && args="$args --${1}=${val}"
}

args=""
add_to_args prefix
add_to_args httpPort
add_to_args httpListenAddress
add_to_args httpsPort
add_to_args httpsListenAddress
add_to_args httpsKeyStore
add_to_args httpsKeyStorePassword

echo "JENKINS_HOME=$JENKINS_HOME"
echo "Jenkins command line for execution:"
echo /usr/bin/java $javaArgs -jar "$war" $args
exec /usr/bin/java $javaArgs -jar "$war" $args

第一行我们看到，给defaults赋了值：

defaults read /Library/Preferences/org.jenkins-ci SETTING

注：defaults 命令可以用来读取其中的配置项SETTING的值。不写SETTING可以读取所有的配置。

其中，/Library/Preferences/org.jenkins-ci是 Jenkins 的配置文件所在的位置。

然后，用defaults读取org.jenkins-ci文件中war、minPermGen、permGen等值，最后使用java -jar来启动 Jenkins 。

Jenkins 是 Java 程序，运行在 JVM 上。通过上述分析，我们知道，修改org.jenkins-ci这中的键值对，可以达到配置 Jenkins 的目的。

下面介绍目前几个常用的配置项（当然如果你是一名 Java Web 程序开发者，对 JVM 比我更熟悉，应该可以按照jenkins-runner.sh脚本中的格式修改脚本添加一些自定义配置，这里只是抛砖引玉）：

  • war : war 包的指定位置，默认值：/Applications/Jenkins/jenkins.war
  • minPermGen : JVM 的非堆内存空间，将赋值给XX:PermSize
  • permGen : JVM 的最大非堆内存空间，将赋值给XX:MaxPermSize
  • minHeapSize : JVM 的堆内存空间，将赋值给Xms
  • heapSize : JVM 的最大堆内存空间，将赋值给Xmx
  • tmpdir : Jenkins 运行的临时存放空间，此值会作为变量赋值给 JVM 的环境变量java.io.tmpdir
  • JENKINS_HOME : Jenkins 目录，默认值：/Users/Shared/Jenkins/Home，保存着工作空间， war 包解压后存放在此，插件，用户，节点，日志等等
  • prefix : 访问页面的前缀。上述安装后打开的 url 是localhost:8080，当配置 prefix 之后，若配置为/objchris（不可以漏掉/），则访问路径变成localhost:8080/objchris。
  • httpPort、httpsport : http、https 端口
  • httpListenAddress、httpsListenAddress : 接收请求 IP ，默认为 0.0.0.0 ，即其他主机也可以访问到，接收任意 IP 发来的请求。若设置为 127.0.0.1 ，则只能本机访问。

对于配置项，有兴趣的同学可以参考这里，十分详细且有一些配置示例。

修改配置，可以使用以下命令：

sudo defaults write /Library/Preferences/org.jenkins-ci SETTING VALUE

做错了也没关系，重新 write 一遍或defaults也支持删除：

sudo defaults delete /Library/Preferences/org.jenkins-ci SETTING

卸载 Jenkins

要残忍舍弃 Jenkins 投奔其他 CI 工具的话：

'/Library/Application Support/Jenkins/Uninstall.command'

同样针对使用 pkg 安装的方式。

下载 war 包，直接停止服务删除 war 包就好了。

使用 homebrew ，有 homebrew 自己的管理方式，不在此说明了。

有时候，遇到一些玄学才能解释的问题（例如文件损坏无法启动 Jenkins …），卸载重装或许也是一个好方法，嗯[正经脸]。

插件安装

在密林探索开始以前，我们要带上一些工具，给 Jenkins 安装一些插件。

插件安装在『 系统管理 — 管理插件 』，图标是一块绿色的小拼图。点击进去可以看到可更新、可选插件、已安装、高级。都是望名知意，不多做解释了。

选择 可选插件 ，在过滤处输入想要安装的插件。对我们来说，版本管理工具 Git 或 SVN 用得最多，但是如果一开始安装 Jenkins 的时候已选择社区推荐插件的话，其实已经安装好了 GitHub 的相关插件 GitHub plugin 。 SVN 的话，我所使用的 Jenkins 2.113 版本在 war 包内部嵌入了 SVN 的插件 Subversion Plug-in 。如果公司内部有 Git 服务器，通常是部署的开源 GitLab ，则需要安装GitLab Plugin用于管理源码和Gitlab Hook Plugin用于构建 GitLab 的触发器。

我的主要目的是 iOS 项目构建，因此还需要选择Xcode integration安装 Xcode 插件，和管理签名证书私钥和 PP 文件的Keychains and Provisioning Profiles Management。

安装完了这些，我们就可以配置一个构建项目了。

构建项目

基本项目配置

回到主界面上，点击左上角 新建任务 ，进入新建任务界面。

确定后，开始项目的通用配置：

我的项目是托管在公司内部 SVN 上的，所以Github Project不打勾，勾上丢弃旧的构建会将构建记录保留一定时间（根据自己需求设置天数）和最大保留个数。参数化构建过程可以为构建过程添加相应的参数。关闭构建主要针对定时任务（下面会说到），顾名思义就是关闭当前任务，自然不会启动定时任务。

源码管理—— SVN

我所在的公司源码管理使用 SVN ，在 Module 中填上 SVN 的一些信息：

  • Repository URL ：仓库地址
  • Credentials ：用于登录、拉取代码的账户密码
  • Local module directory ： 存放在工作空间的位置，每当新建一个任务， Jenkins 会在$HOME目录下的workspace中新建一个以任务名称命名的文件夹。因此，如果此项填入.（默认值就是.），则从 SVN 仓库地址拉取的代码将直接存放在其中。填写其他路径（如./path/to/subfolder），则放在对应的路径中。 Jenkins 在运行脚本的时候所在的位置是$HOME/workspace/[任务名称]，所以如果此项修改了，添加了其他子文件夹，在下面写运行脚本位置时需要注意路径是否正确。
  • Repository depth ：拉取代码时的深度，分别有以下几个：
    • infinity ：遍历所有文件夹，拉取所有文件和文件夹
    • empty ：将本地路径初始化，不拉取任何文件
    • files ：当前文件夹和文件，不包含子文件夹
    • immediates ：当前文件夹、文件、子文件夹，但不遍历子文件夹
    • as-it-is ：继承原有的深度
  • Ignore external ：拉取代码时忽略 external 的属性设置的库。
  • Cancel process on externals fail ：拉取 external 的属性设置的库失败时停止。

Check-out Strategy是检出策略。可选择 ：尽可能多地使用svn update，每次都 checkout 一个新的，或使用脚本 checkout ，不需要 Jenkins 帮我们 checkout 等等。

构建环境

我们知道，打包 iOS 需要代码签名( codesign )，也就需要私钥，因此第一步，是先将 keychain 添加到 Jenkins 。

添加 Keychain 和 Provisioning Profiles

还记得上面安装插件的时候安装了Keychains and Provisioning Profiles Management吗？在构建环境这里，可以看到Keychains and Code Signing Identities选项：

但此时还没有配置，所以要先去 系统管理 —— Keychains and Provisioning Profiles Management添加 Keychain 和 Provisioning Profiles 。

提示我们 Upload Keychain ，选择/Users/管理员用户名/Library/keychains/login.keychain上传。然后输入 Keychain 的密码和签名使用的证书的 Code Signing Identity （ 如：iPhone Distribution: *** CO.,LTD (ABCD678EFG) ）

再上传 Provisioning Profiles ，上传的文件最终位置在/Users/Shared/Jenkins/Home/kpp_upload/。然后将/Users/Shared/Jenkins/Library/MobileDevice/Provisioning Profiles填写到页面的Provisioning Profiles Directory Path，然后保存就可以了。

这样的操作是让 Jenkins 在进行构建的时候将kpp_upload中的 Provisioning Profiles 拷贝到MobileDevice/Provisioning Profiles文件夹中，就跟我们平时安装 Provisioning Profiles 一样。

完成后大致是这样子：

这里添加了 Developer 和 Distribution 的开发者证书和 Development 和 Ad-hoc 的 Provisioning Profiles 。

配置项目使用的 Keychain

回到项目配置中，此时就可以选择 Keychain and Code Signing Identity 了。

这里的 Provisioning Profiles 是需要 development 和 ad-hoc 的。

构建

项目构建最简单的方式就是使用脚本了，可以看我前面写过的文章——iOS脚本打包 - xcodebuild。

增加构建步骤，选择Execute shell，填入脚本：

#!/bin/sh -l
# 解决找不到pod和pod提示语言不对的问题
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8
export PATH="/usr/local/bin:$PATH"
echo $PATH
pod --version
# 解锁用户上传的Keychain
# KEYCHAIN_PATH 和 KEYCHAIN_PASSWORD 是配置构建环境时，Keychains and Provisioning Profiles Management插件提供，可直接使用
security list-keychains -s "${KEYCHAIN_PATH}"
security default-keychain -d user -s "${KEYCHAIN_PATH}"
# 告诉系统Keychain已解锁，无须再弹出UI
security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "${KEYCHAIN_PASSWORD}" "${KEYCHAIN_PATH}"
security unlock-keychain -p "${KEYCHAIN_PASSWORD}"
security show-keychain-info "${KEYCHAIN_PATH}"
security find-identity -p codesigning -v
# 执行我们的打包脚本
sh KeyXBuild.sh

到这里就已经完成打包，得到 ipa 文件了。

一些构建后的操作就不多说了，或者通过 SVN 上传到某个目录，或者上传到蒲公英这种分发平台。

构建状态提示

每一次构建成功失败都会有提示：

构建结束后可以查看日志输出：

项目构建的成功与否决定了一个项目的分数， Jenkins 使用类似天气预报的样式呈现：

第一次使用 Jenkins ，尝试个四五十次应该就差不多了：

Troubleshooting

-bash: pod: command not found

前面说过，Jenkins 在安装完成后会创建一个名为 jenkins 的普通用户，我们可以通过 系统偏好设置 -> 用户与群组 来修改 jenkins 用户的密码，然后登入到其中。进行一些检查操作。

我的项目使用到 Cocoapods 来管理第三方库，且Pods这个文件夹没有上传到 SVN 上，只上传了Podfile和Podfile.lock。因此需要在 Jenkins 上进行一次Pod install。这就需要 Jenkins 用户安装 Pod ，这时候就需要登录 jenkins 去完成安装操作了。

Code Signing Error: Provisioning profile “xxx” doesn’t include signing certificate “iPhone Developer: xxx”

出现此问题是因为，使用 xcodebuild archive 时，指定的 Provisioning profile 和证书都必须是开发使用的。不能是 ad-hoc 或 app store 。

在 archive 后进行 export 的时候才是使用 ad-hoc 或 app store 的证书和 Provisioning profile 。

codesign：unknown error -1=ffffffffffffffff

这个问题是没有访问 Keychain 的权限，因为我们的 Keychain 是从 Jenkins 上传的，每次构建时 Jenkins 都会将 Keychain 文件拷贝到工作项目路径中。

因此我们需要自己手动解锁：

security unlock-keychain -p "${KEYCHAIN_PASSWORD}"

在 macOS 10.12 前，这样就可以了。但是新版本中，解锁操作过后还是会弹出UI来解锁 Keychain 。而 Jenkins 是没有用户交互的，所以签名时才会有这个错误出现。

解决方法是：

security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "${KEYCHAIN_PASSWORD}" "${KEYCHAIN_PATH}"

别忘了其中的codesign:，很多添加了类似命令还是不成功的原因可能是忽略了codesign:

Something of Keychain

脚本打包时，会使用~/Library/Keychain中的 login.keychain 。因此，网上很多教程都是将打包使用的证书和私钥（ login.keychain ）直接拷贝到 Jenkins 中，但是这样不利于项目配置。因为不同的项目可能需要不同的证书签名，要添加新证书就需要再次复制 keychain 文件到 jenkins 的~/Library/Keychains下，覆盖原来的login.keychain。这样容易造成老项目无法成功打包（因为旧 keychain 被覆盖）。

因此，我一直在找如何直接使用 Jenkins 提供的配置去动态添加 keychain ，Keychains and Provisioning Profiles Management 插件帮我们完成 keychain 文件和 Provisioning Profiles 的位置问题，但是需要配合Xcode插件去使用。这样让脚本打包变得不方便。

为了解决这个问题，才有了上面构建脚本中对 Keychain 的一系列操作。

说在最后

可能在未来使用过程中会遇到问题，会回来补充。

つつく


#CI
2018 年 04 月 27 日