管理凭据

本地管理iOS和Android构建凭据，方便云构建。

概述

Capgo CLI允许您在本地机器上保存构建凭据，在 .capgo-credentials Capgo的构建服务器上安全地自动使用和发送这些凭据。

需要帮助获取凭据吗？

如果您尚未获得证书和凭据，请查看这些全面指南：

iOS：

• 获取 iOS 证书 - 步骤指南
• iOS 证书指南 - 细节的步骤指南
• 博客：自动 iOS 构建 - 完整的 CI/CD 设置

Android：

• 创建一个 Keystore - 步骤指南
• Android 证书指南 - 细节的步骤指南
• 博客：自动 Android 构建 - 完整的 CI/CD 配置

安全保证

您的凭据永远不会在Capgo服务器上永久存储：

• ✅仅在活动构建过程中使用
• ✅在构建完成后自动删除
• ✅最大保留时间：24 小时（即使构建失败）
• ✅应用程序直接发送到 App Store/Play Store - 我们存储 NOTHING
• ✅ 使用 HTTPS 安全传输

命令

保存凭据

存储您的构建凭据本地以便自动使用：

npx @capgo/cli build credentials save --platform <ios|android> [options]

更新凭据

终端窗口

npx @capgo/cli build credentials update --platform <ios|android> [options]

这个 update 命令使用 累积合并 用于配置文件 — 新配置文件与现有配置文件合并。要替换整个配置映射，请添加 --overwrite-ios-provisioning-map.

示例 — 将扩展配置文件添加到现有凭据：

npx @capgo/cli build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.widget=./widget_profile.mobileprovision"

更新命令接受的选项与 save 相同，但所有选项都是可选的 — 只有您提供的字段才会更新。

凭据列表

查看当前保存的凭据（密码被掩码）：

npx @capgo/cli build credentials list

# List credentials for a specific app
npx @capgo/cli build credentials list --appId com.example.app

清除凭据

从本地机器中移除保存的凭据：

# Clear all credentials
npx @capgo/cli build credentials clear

# Clear credentials for a specific app + platform
npx @capgo/cli build credentials clear --appId com.example.app --platform ios

迁移凭据

将遗留的单一配置格式转换为新的多目标格式：

npx @capgo/cli build credentials migrate --platform ios

迁移命令检测旧 BUILD_PROVISION_PROFILE_BASE64 凭据，转换为 CAPGO_IOS_PROVISIONING_MAP，并删除遗留的键。请参见 从单一配置文件迁移 详细信息。

保存 iOS 凭据

注意

还没有 iOS 证书吗？ 请参见 iOS Builds 指南 查看创建证书和配置文件的说明。

完整示例

npx @capgo/cli build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --p12-password "YourP12Password" \
  --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \
  --apple-key ./AuthKey_ABC1234567.p8 \
  --apple-key-id "ABC1234567" \
  --apple-issuer-id "00000000-0000-0000-0000-000000000000" \
  --apple-team-id "TEAM123456"

iOS 选项

选项	描述	必填
--certificate <path>	p12证书文件路径	是 (发布)
--p12-password <password>	.p12 证书的密码	是 (发布)
--ios-provisioning-profile <mapping>	配置文件映射 (bundleId=path). 对多目标应用程序可重复。如果只有一个配置文件且没有 bundleId 前缀，CLI 会自动从配置文件中推断。	是 (发布)
--apple-key <path>	App Store Connect API .p8 密钥的路径	请参见注释¹
--apple-key-id <id>	App Store Connect API 密钥 ID	请参见注释¹
--apple-issuer-id <id>	App Store Connect API 发行者 ID (UUID)	请参见注释¹
--apple-team-id <id>	App Store Connect Team ID	是
--ios-distribution <mode>	发布模式: app_store (默认) 或 ad_hoc	否
--output-upload	为构建产物启用一个时间限制的Capgo下载链接	否 (默认: false)
--output-retention <seconds>	保留构建输出的时间长度（例如 3600s)	否 (默认: 3600s)
--skip-build-number-bump	跳过自动构建编号递增	否

¹ App Store Connect API Key Requirements

• app_store 模式 (默认): 三种 API 密钥选项都 必需 除非您传递 --output-upload 或 --skip-build-number-bump (这可以避免使用 API 驱动的提交)
• ad_hoc 模式: 这些选项 不必需 — 不进行 App Store 提交。请参见 Ad-Hoc 分发模式 详细信息请参阅。

存储的内容

当您保存 iOS 凭据时，会将 CLI:

1. 读取证书和配置文件
2. 将它们转换为 base64 编码
3. 将凭据保存到 .capgo-credentials 文件夹
4. 仅本地文件存储密码和 ID（以纯文本形式）

存储的文件结构：

{
  "ios": {
    "BUILD_CERTIFICATE_BASE64": "...",
    "CAPGO_IOS_PROVISIONING_MAP": "{\"com.example.app\":{\"profile\":\"...\",\"name\":\"match AppStore com.example.app\"}}",
    "APPLE_KEY_CONTENT": "...",
    "P12_PASSWORD": "...",
    "APPLE_KEY_ID": "ABC1234567",
    "APPLE_ISSUER_ID": "...",
    "APP_STORE_CONNECT_TEAM_ID": "TEAM123456",
    "CAPGO_IOS_DISTRIBUTION": "app_store"
  }
}

保存 Android 凭据

注意

还没有创建一个 keystore? 参见 Android Builds 指南 了解如何创建一个 keystore 和设置 Play Store 凭据。

完整示例

npx @capgo/cli build credentials save \
  --platform android \
  --keystore ./release.keystore \
  --keystore-alias "my-key-alias" \
  --keystore-key-password "KeyPassword123" \
  --keystore-store-password "StorePassword123" \
  --play-config ./play-store-service-account.json

Android 选项

选项	描述	必填
--keystore <path>	存储在 .keystore 或 .jks 文件中的路径	是 (发布)
--keystore-alias <alias>	密钥别名	是 (发布)
--keystore-key-password <password>	密钥别名的密码	是 (发布)
--keystore-store-password <password>	keystore 的密码	是 (发布)
--play-config <path>	Play Store 服务账户 JSON 路径	是（提交）

存储的内容

当您保存 Android 凭据时，CLI:

1. 读取 keystore 和服务账户 JSON 文件
2. 将它们转换为 base64 编码
3. 将凭据保存到 .capgo-credentials 文件夹
4. 仅本地文件存储密码和别名（以纯文本形式）

存储的文件结构：

{
  "android": {
    "ANDROID_KEYSTORE_FILE": "...",
    "PLAY_CONFIG_JSON": "...",
    "KEYSTORE_KEY_ALIAS": "my-key-alias",
    "KEYSTORE_KEY_PASSWORD": "...",
    "KEYSTORE_STORE_PASSWORD": "..."
  }
}
}

使用已保存的凭据

一旦您保存了凭据，它们就会在您构建时自动使用：

# Credentials automatically loaded from .capgo-credentials folder
npx @capgo/cli build com.example.app --platform ios

您还可以使用环境变量覆盖已保存的凭据：

# Environment variables take precedence over saved credentials
BUILD_CERTIFICATE_BASE64="..." \
P12_PASSWORD="different-password" \
npx @capgo/cli build com.example.app --platform ios

优先顺序：

1. 环境变量（最高优先级）
2. 已保存的凭据在 .capgo-credentials 文件夹
3. 没有凭证（优先级最低）

查看保存的凭证

列出您保存的凭证：

npx @capgo/cli build credentials list

示例输出：

📋 Saved Build Credentials:

iOS Credentials:
  ✓ Certificate (base64)
  ✓ Provisioning Map (JSON)
  ✓ Apple Key Content (base64)
  ✓ P12 Password: ********
  ✓ Apple Key ID: ABC1234567
  ✓ Apple Issuer ID: 00000000-0000-0000-0000-000000000000
  ✓ Team ID: TEAM123456

Android Credentials:
  ✓ Keystore (base64)
  ✓ Play Store Config (base64)
  ✓ Keystore Alias: my-key-alias
  ✓ Key Password: ********
  ✓ Store Password: ********

Location: .capgo-credentials/

🔒 These credentials are stored locally on your machine only.
   When building, they are sent to Capgo but NEVER stored there.
   They are auto-deleted after build completion.

安全最佳实践

本地存储安全

1. __CAPGO_KEEP_0__

   # Ensure credentials folder is not readable by others
   chmod 700 .capgo-credentials
   chmod 600 .capgo-credentials/*

2. 不要将凭据提交到版本控制

   # Add to .gitignore
   echo ".capgo-credentials/" >> .gitignore

3. 分离凭据

   • 本地开发和 CI/CD 使用不同的凭据
   • 定期轮换凭据
   • 不要在团队成员之间共享凭据

CI/CD 使用

对于 CI/CD 环境， 优先使用环境变量 而不是保存的凭据。

环境变量参考文档

The CLI 读取以下环境变量凭据：

iOS 凭据：

变量	描述	格式	是否必填
BUILD_CERTIFICATE_BASE64	用于 code 签名的 P12/PKCS12 证书	Base64	是 (发布)
CAPGO_IOS_PROVISIONING_MAP	应用程序 ID 到配置文件数据的 JSON 映射	JSON 字符串	是 (发布)
P12_PASSWORD	P12 证书的密码	纯文本	可选
APPLE_KEY_ID	App Store Connect API Key ID	例如，'ABC1234567'	请参见注释¹
APPLE_ISSUER_ID	App Store Connect API Issuer ID	UUID字符串	请参见注释¹
APPLE_KEY_CONTENT	App Store Connect API 密钥 (.p8 文件内容)	Base64	请参见注释¹
APP_STORE_CONNECT_TEAM_ID	Apple Developer Team ID	字符串（例如，“XXXXXXXXXX”）	是
CAPGO_IOS_DISTRIBUTION	分发模式： app_store (默认) 或 ad_hoc	字符串	否

Android凭据:

__CAPGO_KEEP_0__	描述	格式	必填
ANDROID_KEYSTORE_FILE	用于签名 APK/AAB 的.keystore文件	Base64	是 (发布)
KEYSTORE_KEY_ALIAS	keystore 中的密钥别名	字符串	是 (发布)
KEYSTORE_KEY_PASSWORD	用于密钥别名的密码	普通文本	是
KEYSTORE_STORE_PASSWORD	__CAPGO_KEEP_0__ 密钥库文件的密码	普通文本	是
PLAY_CONFIG_JSON	Google Play 服务账户 JSON	Base64	是（提交）

*如果只提供一个密码，它将用于两个 KEYSTORE_KEY_PASSWORD 和 KEYSTORE_STORE_PASSWORD.

GitHub 动作示例

github/workflows/build.yml

name: Cloud Build

on:
  push:
    branches: [main]

jobs:
  build-ios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install
      - run: npx @capgo/cli build com.example.app --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}

  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install
      - run: npx @capgo/cli build com.example.app --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

准备Base64值

将您的凭据文件转换为Base64以用于CI/CD密钥：

# iOS Certificate (.p12)
base64 -i certificate.p12 | tr -d '\n' > certificate_base64.txt

# iOS Provisioning Profiles — use the CLI to generate CAPGO_IOS_PROVISIONING_MAP:
npx @capgo/cli build credentials save --platform ios \
  --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \
  # ... other options
# Then copy CAPGO_IOS_PROVISIONING_MAP from .capgo-credentials to your CI secrets

# iOS App Store Connect Key (.p8)
base64 -i AuthKey_XXXXXX.p8 | tr -d '\n' > apple_key_base64.txt

# Android Keystore (.keystore or .jks)
base64 -i release.keystore | tr -d '\n' > keystore_base64.txt

# Google Play Service Account JSON
base64 -i play-store-service-account.json | tr -d '\n' > play_config_base64.txt

提示

它 tr -d '\n' 去除换行符以创建一个单行Base64字符串，这样更容易存储为CI/CD密钥。

为什么环境变量更安全

这种方法更安全，因为：

• 您的 CI/CD 平台管理机密
• 在运行器上没有凭证文件
• 易于轮换和访问控制
• 对机密使用的审计跟踪

凭证轮换

定期轮换您的凭证：

1. iOS: 每年生成新证书和 API 密钥
2. Android: 每年更改密钥库密码
3. 团队成员变更后: 团队成员离职时更换

更新保存的凭据：

# Re-run save command with new credentials
npx @capgo/cli build credentials save --platform ios --certificate ./new-cert.p12 ...

故障排除

“未找到凭据”

如果构建提示未找到凭据：

1. 检查是否已保存凭据:

   npx @capgo/cli build credentials list

2. 如果缺失则保存凭据:

   npx @capgo/cli build credentials save --platform ios ...

3. 验证凭据文件夹是否存在:

   ls -la .capgo-credentials/

读取凭据时出现“权限被拒绝”

修复文件权限：

chmod 700 .capgo-credentials
chmod 600 .capgo-credentials/*

未使用的凭据

检查是否指定了正确的平台：

# Make sure --platform matches saved credentials
npx @capgo/cli build com.example.app --platform ios  # Uses ios credentials
npx @capgo/cli build com.example.app --platform android  # Uses android credentials

清除并重新保存凭据

如果凭据似乎被损坏：

# Clear all credentials
npx @capgo/cli build credentials clear

# Save again
npx @capgo/cli build credentials save --platform ios ...

从环境变量迁移

如果您当前使用环境变量，可以迁移到保存的凭据：

1. 提取当前的环境变量

   echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

2. 解码base64文件回原文件 (如果需要)

   echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12
   echo "$BUILD_PROVISION_PROFILE_BASE64" | base64 -d > profile.mobileprovision

3. 使用CLI保存

   npx @capgo/cli build credentials save \
     --platform ios \
     --certificate ./cert.p12 \
     --ios-provisioning-profile ./profile.mobileprovision \
     --p12-password "$P12_PASSWORD" \
     --apple-key-id "$APPLE_KEY_ID" \
     --apple-issuer-id "$APPLE_ISSUER_ID" \
     --apple-team-id "$APP_STORE_CONNECT_TEAM_ID"

   如果您已在旧格式中保存了现有的凭据（单 BUILD_PROVISION_PROFILE_BASE64），请运行：

   npx @capgo/cli build credentials migrate --platform ios

   将遗留的单用户配置转换为 CAPGO_IOS_PROVISIONING_MAP 并删除旧的 BUILD_PROVISION_PROFILE_BASE64 和 APPLE_PROFILE_NAME 密钥。

4. 测试构建

   npx @capgo/cli build com.example.app --platform ios

5. 清除环境变量 (optional)

   unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

文件位置

凭证存储在 .capgo-credentials 文件夹：

• macOS/Linux: .capgo-credentials/ (在项目根目录或家目录)
• Windows: .capgo-credentials\ (在项目根目录或家目录)

文件夹会在您第一次保存凭证时自动创建。

下一步

• 开始 - 创建您的第一个构建
• iOS构建 - iOS特定构建配置
• Android构建 - Android特定构建配置
• 故障排除 - 常见问题和解决方案

需要帮助?

• 📚 故障排查指南
• 💬 Discord 社区
• 📧 邮件: 支持@capgo.app