Node.js应用所需的敏感配置值(例如API密钥、签名密钥和第三方令牌)由Secrets标签页加密保存,并按环境分别存储,确保您的生产环境凭据与预览环境凭据不会混淆。
密钥存储在哪里
打开网站(Websites),点击相应站点,在站点左侧菜单中打开环境(Environment)分组,选择密钥。该标签页标题为密钥。
该标签页仅出现在Node.js站点上。WordPress、PHP和静态站点不会显示此标签页,因为它们的配置保存在磁盘上的文件中:WordPress使用wp-config.php,而普通PHP应用则取决于您的框架所读取的文件。
密钥值是如何受到保护的
每个值在写入数据库之前都会被加密。没有任何内容以可读文本形式存储,并且列表视图从不显示完整的值:它只显示末尾四个字符的掩码,这样您就可以区分两个相似的密钥,而不会暴露其中任何一个。
每一行都带有一个Encrypted标记,以此提醒您这一点。读取一个值是一个独立的、需要主动执行的操作,而不是打开页面就会自动发生的事情。
设置、显示和删除密钥都需要sites:write权限。只读权限的团队成员可以看到存在哪些密钥及其掩码,但无法看到其值。
两种环境
页面顶部的分段控件可在生产(production)和预览(preview)之间切换。它们是完全独立的两组密钥。在生产环境中设置STRIPE_SECRET_KEY不会在预览环境中创建它,从预览环境中删除它也不会影响生产环境。
这种分离正是此功能的意义所在。预览构建是一次性环境,任何有仓库访问权限的人都可以触发,因此它们应当使用测试凭据,而不是正式凭据。有关预览环境如何创建,请参见拉取请求的预览部署。
添加或更新密钥
- 使用分段控件选择环境。
- 在KEY_NAME字段中输入名称。该字段会在您输入时强制转为大写。
- 将值填入第二个字段。您输入时该值会被掩码处理。
- 点击Set。
设置一个已存在的键会将其覆盖。没有单独的编辑操作,也没有覆盖确认步骤,因此请在点击Set之前先确认环境标签页是否正确。
键名规则
键名必须以大写字母开头,之后可以包含大写字母、数字和下划线,最多128个字符。DATABASE_URL、API_KEY_V2和SENTRY_DSN均为有效格式。其他任何格式都会被拒绝,并显示消息Key 必须是 UPPER_SNAKE_CASE 字母/数字/下划线。
还有两个限制值得了解:
- 值不能为空。提交空值会返回需要 value。
- 值不能超过16 KB。这对于令牌来说已经很充裕,但对于例如完整的证书链来说则不够,这种内容应放在文件中,而不是密钥中。
读取密钥值
点击该行上的Copy。KPanel会在服务器端解密该值,并直接将其放入您的剪贴板,同时显示值已复制到剪贴板的确认提示。该值不会显示在屏幕上,因此屏幕共享或他人窥视都无法获取它。
每一次显示操作都会被记录到站点的审计记录中,包括操作人和涉及的键,并会显示在站点活动日志中。
如果您需要在不暴露值的情况下确认其是否正确,可以改为比对掩码。末尾四个字符就足以确认您拥有正确的令牌,而且这些字符已经显示在屏幕上了。
在应用中使用密钥
将该值复制到您的应用在服务器上读取配置的位置。对于Node.js应用,通常是由进程管理器设置的环境变量,或者是应用根目录下、由您的代码在启动时加载的.env文件。
请勿将该文件提交到您的仓库。在创建该文件之前,先将.env添加到.gitignore中。一旦密钥被推送到git远程仓库,就必须视为已泄露,并在提供商处进行轮换,因为即使您删除了该文件,它仍会保留在历史记录中。
Secrets标签页是您记录值内容的地方,以加密和审计的方式保存,而不是密码管理器中的一条笔记或消息记录中的一段文字。请将其作为唯一可信来源:当您在提供商处轮换某个密钥时,请同时在此处更新,以便下一个部署的人能够获取当前的值。
删除密钥
点击该行上的Delete。KPanel会要求您通过Delete API_TOKEN?进行确认,并提示应用将在下次重启时失去对该值的访问权限。此操作无法撤销,也不会保留副本,因此如果您之后可能还需要该值,请先将其复制下来。
当提供商处的底层凭据已被吊销,或使用该凭据的代码已被移除时,应删除相应密钥。遗留过时的密钥会使日后难以分辨哪些密钥真正仍在使用。
安全地轮换凭据
安全的顺序始终是:先在提供商处创建新凭据,然后在此处更新,接着部署,确认应用正常工作,最后再到提供商处吊销旧凭据。
如果顺序颠倒,先吊销旧凭据,会出现一个窗口期,期间正在运行的应用持有的是已失效的凭据,所有需要它的请求都会失败。如果此变更存在风险,请先创建备份,以便可以恢复到已知良好的状态:请参见创建备份。
故障排查
菜单中没有Secrets标签页。 该站点不是Node.js站点。请检查页面顶部站点名称旁边的技术栈标记。
Set按钮没有反应。 两个字段均为必填项。如果任一字段为空,按钮会提示键 + 值为必需。
键被拒绝。 不允许使用小写字母、连字符、句点和空格。api-key和Api_Key均会失败;API_KEY则可以通过。
复制未将任何内容放入剪贴板。 某些浏览器会阻止在非活动标签页中写入剪贴板。请先点击页面,然后再次点击Copy。