UUVPN/.github/workflows

GitHub Actions CI/CD 配置说明

本文档说明如何配置和使用 UUVPN 的 GitHub Actions 自动构建流程。

---

📋 目录

• 功能特性
• 前置要求
• 配置 Secrets
• 使用方法
• 构建产物
• 自定义配置
• 常见问题

---

功能特性

✅ 自动构建

• Android APK: 支持 Debug 和 Release 构建
• iOS IPA: 支持 Debug 和 Release 构建
• 多架构支持: Android 支持 armeabi-v7a, arm64-v8a, x86, x86_64

✅ 自动发布

• GitHub Releases: 自动创建 Release 并上传构建产物
• TestFlight: 自动上传 iOS 版本到 TestFlight
• Telegram 通知: 构建完成后发送通知

✅ 触发条件

• 推送到 main/develop 分支
• 创建版本标签 (v*)
• Pull Request
• 手动触发

---

前置要求

Android 构建

1. JDK 11: 已在 Actions 中自动配置
2. Android SDK: 已在 Actions 中自动配置
3. Go 1.23: 用于编译核心库
4. 签名密钥: Release 构建需要签名密钥库

iOS 构建

1. Apple Developer 账号: $99/年
2. Xcode 15.0+: 已在 Actions 中自动配置
3. 开发者证书: .p12 格式
4. Provisioning Profile: .mobileprovision 文件
5. App Store Connect API Key: 用于上传到 TestFlight

---

配置 Secrets

在 GitHub 仓库中配置以下 Secrets:

Android Secrets

Secret 名称	描述	获取方式
ANDROID_KEYSTORE_BASE64	签名密钥库的 Base64 编码	见下方说明
ANDROID_KEYSTORE_PASSWORD	密钥库密码	创建密钥库时设置
ANDROID_KEY_ALIAS	密钥别名	创建密钥库时设置
ANDROID_KEY_PASSWORD	密钥密码	创建密钥库时设置

生成 ANDROID_KEYSTORE_BASE64:

# 在本地执行
keytool -genkey -v -keystore release.keystore -alias uuvpn -keyalg RSA -keysize 2048 -validity 10000

# 转换为 Base64
base64 -i release.keystore -o release.keystore.base64

# 或者使用 PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("release.keystore")) | Out-File release.keystore.base64

iOS Secrets

Secret 名称	描述	获取方式
IOS_CERTIFICATES_P12	开发者证书的 Base64 编码	见下方说明
IOS_CERTIFICATES_PASSWORD	证书密码	导出证书时设置
IOS_SIGNING_IDENTITY	签名身份	如: "Apple Distribution: Your Name (TEAM_ID)"
IOS_PROVISIONING_PROFILE	Provisioning Profile 的 Base64 编码	见下方说明
IOS_TEAM_ID	Apple Team ID	在 Apple Developer 账号中查看

生成 IOS_CERTIFICATES_P12:

1. 在 Keychain Access 中导出证书
2. 选择 "Apple Distribution" 证书
3. 右键 → 导出 → 选择 .p12 格式
4. 设置密码
5. 转换为 Base64:

base64 -i certificate.p12 -o certificate.p12.base64

# 或者使用 PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("certificate.p12")) | Out-File certificate.p12.base64

生成 IOS_PROVISIONING_PROFILE:

1. 在 Apple Developer 网站下载 Provisioning Profile
2. 转换为 Base64:

base64 -i uuvpn.mobileprovision -o uuvpn.mobileprovision.base64

# 或者使用 PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("uuvpn.mobileprovision")) | Out-File uuvpn.mobileprovision.base64

App Store Connect Secrets

Secret 名称	描述	获取方式
APP_STORE_CONNECT_ISSUER_ID	App Store Connect API Issuer ID	在 App Store Connect 中创建 API Key
APP_STORE_CONNECT_API_KEY_ID	App Store Connect API Key ID	创建 API Key 时获得
APP_STORE_CONNECT_API_PRIVATE_KEY	App Store Connect API 私钥	创建 API Key 时下载的 .p8 文件内容

获取方式:

1. 登录 App Store Connect
2. 进入 Users and Access → Keys
3. 点击 "Generate API Key"
4. 选择 "App Manager" 权限
5. 下载 .p8 文件并保存私钥内容

通知 Secrets (可选)

Secret 名称	描述	获取方式
TELEGRAM_BOT_TOKEN	Telegram Bot Token	通过 @BotFather 创建 Bot
TELEGRAM_CHAT_ID	Telegram 群组/频道 ID	邀请 Bot 到群组后获取

获取方式:

1. 在 Telegram 中找到 @BotFather
2. 发送 /newbot 创建新 Bot
3. 获取 Bot Token
4. 创建群组或频道,邀请 Bot
5. 获取 Chat ID: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

---

使用方法

方法一: 自动触发

推送到分支

# 推送到 main 分支,触发构建
git push origin main

# 推送到 develop 分支,触发 Debug 构建
git push origin develop

创建版本标签

# 创建 Alpha 版本
git tag v1.0.0-alpha
git push origin v1.0.0-alpha

# 创建 Beta 版本
git tag v1.0.0-beta
git push origin v1.0.0-beta

# 创建正式版本
git tag v1.0.0
git push origin v1.0.0

Pull Request

创建 Pull Request 到 main 分支会自动触发 Debug 构建。

方法二: 手动触发

1. 进入 GitHub 仓库
2. 点击 "Actions" 标签
3. 选择 "Build UUVPN" workflow
4. 点击 "Run workflow"
5. 选择构建选项:
   • build_android: 是否构建 Android APK
   • build_ios: 是否构建 iOS IPA
   • release_type: 构建类型 (alpha/beta/release)
6. 点击 "Run workflow" 按钮

---

构建产物

Android 构建产物

构建完成后,可以在以下位置找到 APK:

1. Actions Artifacts: 每个 workflow 运行都会保存 APK artifact
2. GitHub Releases: 创建标签后,APK 会自动上传到 Release

APK 文件命名:

• Debug: app-meta-alpha-debug.apk
• Release: UUVPN-Android-v1.0.0.apk

iOS 构建产物

构建完成后,可以在以下位置找到 IPA:

1. Actions Artifacts: 每个 workflow 运行都会保存 IPA artifact
2. GitHub Releases: 创建标签后,IPA 会自动上传到 Release
3. TestFlight: Beta 和正式版本会自动上传到 TestFlight

IPA 文件命名:

• Release: UUVPN-iOS-v1.0.0.ipa

---

自定义配置

修改 Android 构建变体

编辑 .github/workflows/build.yml 中的构建命令:

- name: Build Android APK
  run: |
    cd Android-kotlin-Code
    # 修改为你需要的构建变体
    ./gradlew app:assembleMeta-BetaRelease --stacktrace

修改 iOS Scheme

编辑 .github/workflows/build.yml 中的 scheme:

- name: Build iOS App
  run: |
    cd iOS-SwiftUI-Code
    xcodebuild build \
      -project uuvpn.xcodeproj \
      -scheme SFT \  # 修改为你需要的 scheme
      -sdk iphoneos \
      ...

添加构建缓存

在 workflow 中添加缓存以加速构建:

- name: Cache Gradle packages
  uses: actions/cache@v4
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
    key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
    restore-keys: |
      ${{ runner.os }}-gradle-

- name: Cache Swift packages
  uses: actions/cache@v4
  with:
    path: |
      ~/Library/Caches/org.swift.swiftpm
      .build
    key: ${{ runner.os }}-swift-${{ hashFiles('**/Package.resolved') }}
    restore-keys: |
      ${{ runner.os }}-swift-

添加自定义构建步骤

在 workflow 中添加自定义步骤:

- name: Custom build step
  run: |
    # 你的自定义命令
    echo "Running custom build step"

---

工作流程说明

完整构建流程

┌─────────────────┐
│   触发构建      │
└────────┬────────┘
         │
         ├─────────────────────┐
         │                     │
         ▼                     ▼
┌─────────────────┐   ┌─────────────────┐
│  构建 Android   │   │    构建 iOS     │
│      APK        │   │      IPA        │
└────────┬────────┘   └────────┬────────┘
         │                     │
         └──────────┬──────────┘
                    │
                    ▼
         ┌─────────────────────┐
         │  创建 GitHub Release │
         │  (仅标签触发)        │
         └──────────┬──────────┘
                    │
                    ├─────────────────────┐
                    │                     │
                    ▼                     ▼
         ┌─────────────────┐   ┌─────────────────┐
         │  上传 APK 到     │   │  上传 IPA 到     │
         │  GitHub Release  │   │  TestFlight      │
         └─────────────────┘   └─────────────────┘
                    │
                    ▼
         ┌─────────────────────┐
         │   发送通知          │
         └─────────────────────┘

构建类型说明

触发条件	Android	iOS	发布
Push to develop	Debug APK	Debug App	否
Pull Request	Debug APK	Debug App	否
Push to main	Release APK	Release IPA	否
Tag v*-alpha	Release APK	Release IPA	GitHub Release (Pre-release)
Tag v*-beta	Release APK	Release IPA	GitHub Release + TestFlight
Tag v*	Release APK	Release IPA	GitHub Release + TestFlight

---

常见问题

Q1: Android 构建失败,提示找不到签名密钥?

A: 检查以下内容:

• 确认已配置 ANDROID_KEYSTORE_BASE64 secret
• 确认 Base64 编码正确
• 确认密钥库密码、别名和密钥密码正确

Q2: iOS 构建失败,提示签名错误?

A: 检查以下内容:

• 确认证书未过期
• 确认 Provisioning Profile 包含正确的 App ID
• 确认 Team ID 正确
• 确认证书和 Provisioning Profile 匹配

Q3: iOS 构建时间过长?

A: iOS 构建通常需要 10-20 分钟,这是正常的。可以:

• 使用缓存加速构建
• 只在需要时构建 iOS 版本
• 使用手动触发选择性构建

Q4: 如何跳过某个平台的构建?

A: 使用手动触发时,取消勾选对应平台的构建选项。

Q5: 构建产物在哪里下载?

A:

1. 进入 Actions 页面
2. 点击具体的 workflow 运行记录
3. 在页面底部 "Artifacts" 区域下载

Q6: 如何查看构建日志?

A:

1. 进入 Actions 页面
2. 点击具体的 workflow 运行记录
3. 点击左侧的 job 名称
4. 展开各个步骤查看详细日志

Q7: TestFlight 上传失败?

A: 检查以下内容:

• 确认 App Store Connect API Key 配置正确
• 确认 API Key 有 App Manager 权限
• 确认 App ID 在 App Store Connect 中已创建
• 确认版本号未重复

Q8: 如何修改构建触发条件?

A: 编辑 .github/workflows/build.yml 的 on 部分:

on:
  push:
    branches:
      - main
      - develop
      - feature/*  # 添加更多分支
    tags:
      - 'v*'
  pull_request:
    branches:
      - main
      - develop

---

进阶配置

添加代码质量检查

在构建前添加代码检查:

jobs:
  lint:
    name: Code Quality Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Android Lint
        run: |
          cd Android-kotlin-Code
          ./gradlew lint

      - name: Swift Lint
        run: |
          brew install swiftlint
          cd iOS-SwiftUI-Code
          swiftlint

添加单元测试

jobs:
  test:
    name: Run Tests
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - name: Android Tests
        run: |
          cd Android-kotlin-Code
          ./gradlew test

      - name: iOS Tests
        run: |
          cd iOS-SwiftUI-Code
          xcodebuild test \
            -project uuvpn.xcodeproj \
            -scheme SFI \
            -destination 'platform=iOS Simulator,name=iPhone 15'

添加多版本构建

strategy:
  matrix:
    xcode-version: ['14.3', '15.0', '15.2']
    include:
      - xcode-version: '14.3'
        ios-deployment-target: '14.0'
      - xcode-version: '15.0'
        ios-deployment-target: '15.0'
      - xcode-version: '15.2'
        ios-deployment-target: '16.0'

---

成本估算

GitHub Actions 免费额度

• 总时长: 每月 2000 分钟 (免费账户)
• macOS runner: 按 10 倍计算
• Linux runner: 按 1 倍计算

实际消耗估算

构建类型	Android	iOS	总计
Debug 构建	~5 分钟	~100 分钟	~105 分钟
Release 构建	~10 分钟	~150 分钟	~160 分钟
完整流程	~15 分钟	~200 分钟	~215 分钟

建议

• 免费账户每月可进行约 9-10 次完整构建
• 建议只在必要时构建 iOS 版本
• 使用手动触发选择性构建
• 考虑升级 GitHub Pro 获得更多额度

---

总结

通过 GitHub Actions CI/CD 配置,你可以:

✅ 无需本地 Mac 设备即可构建 iOS 应用 ✅ 自动化构建和发布流程 ✅ 支持 Android 和 iOS 双平台 ✅ 自动上传到 TestFlight 和 GitHub Releases ✅ 接收构建通知

配置好 Secrets 后,只需推送代码或创建标签,即可自动完成构建和发布!