管理凭证

在本地管理您的 iOS 和 Android 构建凭证以方便云构建。

概述

Capgo CLI 允许您在 .capgo-credentials 文件夹中本地保存构建凭证。当您运行构建时,这些凭证会自动使用并安全地发送到 Capgo 的构建服务器。

命令

保存凭证

本地存储您的构建凭证以自动使用:

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

列出凭证

查看当前保存的凭证(密码已屏蔽):

npx @capgo/cli build credentials list

清除凭证

从本地机器删除已保存的凭证:

# 清除所有凭证
npx @capgo/cli build credentials clear

# 仅清除 iOS 凭证
npx @capgo/cli build credentials clear --platform ios

# 仅清除 Android 凭证
npx @capgo/cli build credentials clear --platform android

保存 iOS 凭证

完整示例

npx @capgo/cli build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --p12-password "YourP12Password" \
  --provisioning-profile ./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 证书的密码	是(发布版本)
`--provisioning-profile <path>`	.mobileprovision 文件的路径	是(发布版本)
`--provisioning-profile-prod <path>`	生产配置文件(可选)	否
`--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 团队 ID	是(提交)
`--apple-id <email>`	Apple ID 电子邮件(替代认证)	否
`--apple-app-password <password>`	应用专用密码(替代认证)	否

存储的内容

当您保存 iOS 凭证时,CLI 会:

读取证书和配置文件文件
将它们转换为 base64 编码
将凭证保存到 .capgo-credentials 文件夹
将密码和 ID 存储为纯文本(仅限本地文件)

存储的文件结构:

{
  "ios": {
    "BUILD_CERTIFICATE_BASE64": "...",
    "BUILD_PROVISION_PROFILE_BASE64": "...",
    "APPLE_KEY_CONTENT": "...",
    "P12_PASSWORD": "...",
    "APPLE_KEY_ID": "ABC1234567",
    "APPLE_ISSUER_ID": "...",
    "APP_STORE_CONNECT_TEAM_ID": "TEAM123456"
  }
}

保存 Android 凭证

完整示例

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>`	密钥库的密码	是(发布版本)
`--play-config <path>`	Play 商店服务账户 JSON 的路径	是(提交)

存储的内容

当您保存 Android 凭证时,CLI 会:

读取密钥库和服务账户 JSON 文件
将它们转换为 base64 编码
将凭证保存到 .capgo-credentials 文件夹
将密码和别名存储为纯文本(仅限本地文件)

存储的文件结构:

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

使用已保存的凭证

保存凭证后,在构建时会自动使用:

# 凭证自动从 .capgo-credentials 文件夹加载
npx @capgo/cli build com.example.app --platform ios

您也可以使用环境变量覆盖已保存的凭证:

# 环境变量优先于已保存的凭证
BUILD_CERTIFICATE_BASE64="..." \
P12_PASSWORD="different-password" \
npx @capgo/cli build com.example.app --platform ios

优先级顺序:

环境变量(最高优先级)
.capgo-credentials 文件夹中的已保存凭证
无凭证(最低优先级)

查看已保存的凭证

列出您已保存的凭证:

npx @capgo/cli build credentials list

示例输出:

📋 已保存的构建凭证:

iOS 凭证:
  ✓ 证书 (base64)
  ✓ 配置文件 (base64)
  ✓ Apple 密钥内容 (base64)
  ✓ P12 密码: ********
  ✓ Apple 密钥 ID: ABC1234567
  ✓ Apple 发行者 ID: 00000000-0000-0000-0000-000000000000
  ✓ 团队 ID: TEAM123456

Android 凭证:
  ✓ 密钥库 (base64)
  ✓ Play 商店配置 (base64)
  ✓ 密钥库别名: my-key-alias
  ✓ 密钥密码: ********
  ✓ 存储密码: ********

位置: .capgo-credentials/

🔒 这些凭证仅存储在您的本地机器上。
   构建时,它们会发送到 Capgo 但永远不会存储在那里。
   构建完成后自动删除(最多 24 小时)。

安全最佳实践

本地存储安全

文件权限

# 确保凭证文件夹不被其他人读取
chmod 700 .capgo-credentials
chmod 600 .capgo-credentials/*

切勿提交凭证

# 添加到 .gitignore
echo ".capgo-credentials/" >> .gitignore

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

CI/CD 使用

对于 CI/CD 环境,优先使用环境变量而不是已保存的凭证:

# GitHub Actions
env:
  BUILD_CERTIFICATE_BASE64: ${{ secrets.IOS_CERTIFICATE }}
  P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
  # ... 其他密钥

这更安全,因为:

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

凭证轮换

定期轮换您的凭证:

iOS: 每年生成新证书和 API 密钥
Android: 每年更改密钥库密码
团队变更后: 团队成员离开时轮换

更新已保存的凭证:

# 使用新凭证重新运行保存命令
npx @capgo/cli build credentials save --platform ios --certificate ./new-cert.p12 ...

故障排除

”找不到凭证”

如果构建说找不到凭证:

检查是否保存了凭证:
Terminal window
```
npx @capgo/cli build credentials list
```

如果缺少凭证则保存:

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

验证凭证文件夹是否存在:
Terminal window
```
ls -la .capgo-credentials/
```

读取凭证时”权限被拒绝”

修复文件权限:

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

凭证未被使用

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

# 确保 --platform 与已保存的凭证匹配
npx @capgo/cli build com.example.app --platform ios  # 使用 ios 凭证
npx @capgo/cli build com.example.app --platform android  # 使用 android 凭证

清除并重新保存凭证

如果凭证似乎已损坏:

# 清除所有凭证
npx @capgo/cli build credentials clear

# 重新保存
npx @capgo/cli build credentials save --platform ios ...

从环境变量迁移

如果您当前使用环境变量,可以迁移到已保存的凭证:

提取当前环境变量

echo $BUILD_CERTIFICATE_BASE64  # 验证它们存在

将 base64 文件解码回原始文件(如果需要)

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

使用 CLI 保存

npx @capgo/cli build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --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"

测试构建

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

删除环境变量(可选)

unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

文件位置

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

macOS/Linux: .capgo-credentials/(在您的项目根目录或主目录)
Windows: .capgo-credentials\(在您的项目根目录或主目录)

首次保存凭证时会自动创建该文件夹。

下一步

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

需要帮助?

📚 故障排除指南
💬 Discord 社区
📧 电子邮件: support@capgo.app