SafeW在持续集成/持续部署（CI/CD）流程中，是如何实现短期签名密钥的动态注入的？
功能探讨：为何要在 CI/CD 流程中使用临时性密钥？
以往，签名私钥常被长期存储在仓库变量或 K8s Secret 中，一旦泄露，则需进行全流程的密钥更换。SafeW 推出的“短期签名密钥注入”功能，将密钥的生命周期缩短至“Job 级别”。在流水线启动时，会向 SafeW 网关申请一张仅限于该 Job 使用的签名证书，并在 Job 结束后即刻吊销。在此过程中，私钥不会落盘、进入缓存，也无需写入环境变量文件。为了行文方便，我们后续将此机制简称为“插件”。
插件与 SafeW 原有的“冷端 NFC 一碰签名”相互独立：前者服务自动化流水线，后者服务人工手机端。算法仅支持 ECDSA/secp256r1 与 Ed25519，RSA 不在范围内；有效期最短 5 min、最长 60 min，不可续期，到期后必须重新申请。
版本之间的区别以及迁移需要满足的条件
截至最新版本（SafeW 控制台 6.4.2，网关 API 2026.02.28）才开放插件。若左侧菜单看不到“CI/CD 插件中心”，请让组织 Owner 在“设置-组织-实验功能”里手动开启“第三方流水线集成”开关；该开关默认关闭，且仅 Owner 角色可见。
对于旧版本，如果之前使用了“永久 API Key”并手动上传了 keystore，请务必先清除旧的 Secret 信息，再集成插件。否则，可能会因“双重签名”而导致链上验证失败。
控制台的一次性配置操作：搭建信任链。
第一步：创建一个流水线身份
进入 SafeW 控制台 → 左上角切换至“组织视图” → CI/CD 插件中心 → 添加流水线。平台要求填写三项：
- 流水线名称：仅做展示，建议与 GitLab/GitHub 仓库同名，方便溯源。
- 可信域名：插件在生成 JWT 时，会验证 `aud` 字段，该字段必须包含您的 CI 域名，如 gitlab.example.com。
- 请将流水线执行器中预先配置好的 SSH Ed25519 公钥粘贴到此处的公钥指纹栏，这将用于后续构建双向 TLS 通信。
提交成功后，控制台会生成“插件 ID”和“插件 Secret”。Secret 信息仅显示一次，请务必立即将其保存到 CI 的安全变量中（GitLab 中称为 Protected Variable，GitHub 中称为 Encrypted Secret），切勿直接写入 .yml 文件。
第二步：制定并设置撤销策略
在同一页面继续向下滚动，可设置“Job 成功/失败自动吊销”与“最大可签发数量”。经验性观察：若并发 Job 数超过 200，建议把“最大可签发”调到 500，否则网关会返回 429，导致排队时间拉长。
集成到流水线：以 GitLab 为例
以下 .gitlab-ci.yml 片段演示如何为 Android APK 签名。核心思路：在 before_script 阶段调用 SafeW CLI 申请密钥，签名完成后在 after_script 阶段主动吊销。
variables:
SAFEW_PLUGIN_ID: $SAFEW_PLUGIN_ID // 受保护变量
SAFEW_PLUGIN_SECRET: $SAFEW_PLUGIN_SECRET // 受保护变量
.inject_key:
image: safew/cli:6.4.2
before_script:
- safew ci inject --aud gitlab.example.com --validity 10m --out /tmp/sign.key
after_script:
- safew ci revoke --key-file /tmp/sign.key || true
build:
extends: .inject_key
stage: build
script:
- ./gradlew assembleRelease
- apksigner sign --ks /tmp/sign.key --ks-pass pass:empty --out signed.apk app-release-unsigned.apk
artifacts:
paths: [signed.apk]
注意：--ks-pass 必须给空口令，插件返回的密钥已受会话密钥加密，CLI 在内存中解密后喂给 apksigner，全程不落盘。
关于GitHub Actions在流水线集成方面的不同之处
GitHub 环境缺少原生“after_script”，需把吊销步骤写在独立 job，并用 always() 保证触发：
jobs:
sign:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Inject key
id: inject
run: |
safew ci inject --aud github.com --validity 10m --out $RUNNER_TEMP/sign.key
echo "key=$RUNNER_TEMP/sign.key" >> $GITHUB_OUTPUT
- name: Sign artifact
run: |
apksigner sign --ks ${{steps.inject.outputs.key}} --ks-pass pass:empty --out signed.apk unsigned.apk
- name: Upload
uses: actions/upload-artifact@v4
with: {name: signed-apk, path: signed.apk}
revoke:
needs: sign
if: always()
runs-on: ubuntu-latest
steps:
- run: safew ci revoke --key-file ${{needs.sign.outputs.key}}
根据实际经验，GitHub 的并发请求限制为 256。如果您的组织拥有大量仓库，建议将 `--validity` 参数设置为 15 分钟，以预留足够的缓冲时间处理排队请求。
关于自建 Jenkins 协同工作
对于 Jenkins 用户，请先在“凭据存储”中添加一个名为“SafeW Plugin Secret”的条目（该插件已在 Jenkins Update Center 上线，您可以通过搜索“SafeW Short-Lived Signing”找到）。之后，在 Pipeline 中操作：
stage('Inject Key') {
steps {
safewInject validity: 10, unit: 'MINUTES', audience: 'jenkins.example.com'
}
}
stage('Sign') {
steps {
sh 'apksigner sign --ks $SAFEW_KEY_FILE --ks-pass pass:empty --out signed.apk unsigned.apk'
}
}
stage('Revoke') {
steps {
safewRevoke() // 无论上游是否失败都执行
}
}
请注意，Jenkins的“回放”功能会导致Pipeline被反复执行。如果手动触发“Replay”，同一个Job ID会申请多次密钥，进而触发SafeW的“重放保护”机制，并返回409错误。为了解决这个问题，可以临时增加“最大可签发”的数量，或者更改Job名称前缀以区分。
例外与权衡：何时应避免使用
1. 需要 RSA 2048 且链上合约只认 RSA，插件无法支持，只能回退永久密钥。
2. 流水线运行环境完全离线（冷端），插件需访问 SafeW 网关，显然不满足。
3. 签名过程必须人工二次确认（如金融 U 盾），插件的自动化特性与合规冲突。
4. 单次 Job 运行时间超过 60 min，插件最大有效期仍不够，需把大任务拆段，中间重新申请。
警告
若把插件返回的密钥文件误写入 artifacts 并公开发布，等于把私钥泄露到互联网。SafeW 虽会强制吊销，但已签名文件无法撤回，请务必在 artifacts 上传前把 /tmp/sign.key 加入 exclude 列表。
故障排查速查表
| 现象 | 最可能原因 | 验证方法 | 处置 |
|---|---|---|---|
| 命令行界面（CLI）返回了403错误。 | aud 字段中的值与控制台设置的可信域名不匹配。 | 将 --aud 参数与控制台界面进行对比分析 | 无论是通过 .yml 文件还是在控制台中，都可以任选一侧来更改域名。 |
| 429 Too Many | 并发超限 | 请查看控制台中的“实时签发数”。 | 暂时提升上限或者减少并发数量 |
| apksigner 提示“keystore 文件已损坏” | --ks-pass 给了非空口令 | 再次执行，并加上 -v 参数。 | 将其修改为 pass:empty。 |
| 吊销失败 404 | 人工终止了此 Job，相应的密钥也已自动作废。 | 查看网关日志 | 无需理会，这是正常现象。 |
验证与观测方法
1. 在流水线末尾加打印：keytool -list -keystore /tmp/sign.key -storepass empty，可见证书有效期仅剩几分钟，证明“短命”生效。
2. 在 SafeW 控制台“审计日志”搜索流水线 ID，可拉出完整链路：签发时间、吊销时间、对应 Job URL，方便合规抽查。
3. 若想量化提速，可在旧流程与新流程各跑 30 次，记录“签名环节”耗时。经验性观察：网络稳定时，新流程平均缩短数十秒，主要省掉下载永久 keystore 的解密环节。
哪些场景适合使用，哪些不适合
- 移动端应用每日构建次数超过200次，因此需要高效的签名流程并将构建版本快速推送到测试分发平台。
- ✅ 将 SBOM 签名内嵌至微服务镜像中，每次构建镜像时自动生成新签名，从而省去了长期保管私钥的麻烦。
- 嵌入式固件签名后，需按照监管审计要求妥善保存10年，其中密钥必须归档，插件的自动吊销机制不符合相关法规。
- 链上 NFT 合约仅支持 RSA 4096 加密算法，当前插件提供的算法不兼容。
最佳实践 6 条
- 将 `--validity` 参数设置为 Job 历史记录中最长的耗时，并额外预留 30% 的余量，这样既能节省配额，又能有效避免任务超时。
- 每个仓库仅允许注册一个插件 ID；不同分支则通过 Job 名称来区分，这样便于进行审计。
- 为避免密钥因异常流程残留在内存中，吊销操作务必加上 always() 或 post-always。
- 为了防止审计日志混乱，请勿在本地调试时使用 Secret 插件。本地调试建议启用 SafeW 桌面版的“临时签名”功能。
- 建议每月评估“最大可签发”的利用情况，若占比超过80%则适当增加配额，若不足20%则相应缩减，以此优化并节约组织层面的资源配额。
- 如果您同时使用 GitLab 和 GitHub，建议为每个平台设置独立的插件 ID。这样一来，即使其中一个平台的ID泄露，也只会影响该平台，而不会波及另一个。
常见问题解答（结构化数据格式）
这款插件可以识别并处理哪些算法？
目前仅支持 ECDSA/secp256r1 与 Ed25519，RSA 全系不在路线图内。
最大有效期可以设置多久？
控制台最长仅支持 60 分钟，无法延长；如果您的 Job 需要更长时间，请将其拆分成不同阶段并重新申请。
如果吊销不成功，是否会产生额外费用？
SafeW 的计费仅针对成功的签发操作，吊销操作无论成功与否均不产生额外费用；如果您频繁遇到 404 错误，这可能意味着您的项目已自行吊销，可以不必理会。
同一个插件的ID，是否允许在不同的组织里重复使用？
插件的标识符是与特定组织绑定的，因此无法在不同组织间共享使用；一旦仓库迁移至新组织，该插件也需要重新进行注册。
在网关返回 429 错误后，系统是否会自动进行重试？
命令行工具（CLI）内置了指数退避机制，最多尝试3次。如果仍然无法成功，则需要手动增加配额或者减少并发请求量。
结语：后续执行事项汇总
读完本文，你已了解 SafeW 短期签名密钥注入的边界、成本与收益。建议先用非核心仓库做 1 周灰度，确认配额与并发无冲突后，再逐步将生产流水线切过来；切换前务必把旧永久密钥从变量库删除，防止“双轨”期误用。最后，把“故障排查速查表”贴到团队 Wiki，下次遇到 403/429 就能秒定位。未来版本若开放 RSA 或延长有效期，官方会在控制台 changelog 首条公告，记得打开“组织-消息通知”即可第一时间获得推送。