# 为站点存储应用密钥

Source: https://support.kapsulehost.com/zh-cn/site-secrets

Node.js应用所需的敏感配置值(例如API密钥、签名密钥和第三方令牌)由Secrets标签页加密保存,并按环境分别存储,确保您的生产环境凭据与预览环境凭据不会混淆。

## 密钥存储在哪里

打开**网站(Websites)**,点击相应站点,在站点左侧菜单中打开**环境(Environment)**分组,选择**密钥**。该标签页标题为**密钥**。

该标签页仅出现在Node.js站点上。WordPress、PHP和静态站点不会显示此标签页,因为它们的配置保存在磁盘上的文件中:WordPress使用`wp-config.php`,而普通PHP应用则取决于您的框架所读取的文件。

![KPanel中Node.js站点的Secrets标签页](https://support.kapsulehost.com/help/screenshots/site-secrets.812e0706.webp)

## 密钥值是如何受到保护的

每个值在写入数据库之前都会被加密。没有任何内容以可读文本形式存储,并且列表视图从不显示完整的值:它只显示末尾四个字符的掩码,这样您就可以区分两个相似的密钥,而不会暴露其中任何一个。

每一行都带有一个**Encrypted**标记,以此提醒您这一点。读取一个值是一个独立的、需要主动执行的操作,而不是打开页面就会自动发生的事情。

> **Note:** 设置、显示和删除密钥都需要**sites:write**权限。只读权限的团队成员可以看到存在哪些密钥及其掩码,但无法看到其值。

## 两种环境

页面顶部的分段控件可在**生产(production)**和**预览(preview)**之间切换。它们是完全独立的两组密钥。在生产环境中设置`STRIPE_SECRET_KEY`不会在预览环境中创建它,从预览环境中删除它也不会影响生产环境。

这种分离正是此功能的意义所在。预览构建是一次性环境,任何有仓库访问权限的人都可以触发,因此它们应当使用测试凭据,而不是正式凭据。有关预览环境如何创建,请参见[拉取请求的预览部署](https://support.kapsulehost.com/zh-cn/site-preview)。

## 添加或更新密钥

1. 使用分段控件选择环境。
2. 在**KEY_NAME**字段中输入名称。该字段会在您输入时强制转为大写。
3. 将值填入第二个字段。您输入时该值会被掩码处理。
4. 点击**Set**。

设置一个已存在的键会将其覆盖。没有单独的编辑操作,也没有覆盖确认步骤,因此请在点击**Set**之前先确认环境标签页是否正确。

### 键名规则

键名必须以大写字母开头,之后可以包含大写字母、数字和下划线,最多128个字符。`DATABASE_URL`、`API_KEY_V2`和`SENTRY_DSN`均为有效格式。其他任何格式都会被拒绝,并显示消息**Key 必须是 UPPER_SNAKE_CASE 字母/数字/下划线**。

还有两个限制值得了解:

- 值不能为空。提交空值会返回**需要 value**。
- 值不能超过16 KB。这对于令牌来说已经很充裕,但对于例如完整的证书链来说则不够,这种内容应放在文件中,而不是密钥中。

## 读取密钥值

点击该行上的**Copy**。KPanel会在服务器端解密该值,并直接将其放入您的剪贴板,同时显示**值已复制到剪贴板**的确认提示。该值不会显示在屏幕上,因此屏幕共享或他人窥视都无法获取它。

每一次显示操作都会被记录到站点的审计记录中,包括操作人和涉及的键,并会显示在[站点活动日志](https://support.kapsulehost.com/zh-cn/site-activity-log)中。

> **Tip:** 如果您需要在不暴露值的情况下确认其是否正确,可以改为比对掩码。末尾四个字符就足以确认您拥有正确的令牌,而且这些字符已经显示在屏幕上了。

## 在应用中使用密钥

将该值复制到您的应用在服务器上读取配置的位置。对于Node.js应用,通常是由进程管理器设置的环境变量,或者是应用根目录下、由您的代码在启动时加载的`.env`文件。

> **Warning:** 请勿将该文件提交到您的仓库。在创建该文件之前,先将`.env`添加到`.gitignore`中。一旦密钥被推送到git远程仓库,就必须视为已泄露,并在提供商处进行轮换,因为即使您删除了该文件,它仍会保留在历史记录中。

Secrets标签页是您记录值内容的地方,以加密和审计的方式保存,而不是密码管理器中的一条笔记或消息记录中的一段文字。请将其作为唯一可信来源:当您在提供商处轮换某个密钥时,请同时在此处更新,以便下一个部署的人能够获取当前的值。

## 删除密钥

点击该行上的**Delete**。KPanel会要求您通过**Delete API_TOKEN?**进行确认,并提示应用将在下次重启时失去对该值的访问权限。此操作无法撤销,也不会保留副本,因此如果您之后可能还需要该值,请先将其复制下来。

当提供商处的底层凭据已被吊销,或使用该凭据的代码已被移除时,应删除相应密钥。遗留过时的密钥会使日后难以分辨哪些密钥真正仍在使用。

## 安全地轮换凭据

安全的顺序始终是:先在提供商处创建新凭据,然后在此处更新,接着部署,确认应用正常工作,最后再到提供商处吊销旧凭据。

如果顺序颠倒,先吊销旧凭据,会出现一个窗口期,期间正在运行的应用持有的是已失效的凭据,所有需要它的请求都会失败。如果此变更存在风险,请先创建备份,以便可以恢复到已知良好的状态:请参见[创建备份](https://support.kapsulehost.com/zh-cn/taking-a-backup)。

## 故障排查

**菜单中没有Secrets标签页。** 该站点不是Node.js站点。请检查页面顶部站点名称旁边的技术栈标记。

**Set按钮没有反应。** 两个字段均为必填项。如果任一字段为空,按钮会提示**键 + 值为必需**。

**键被拒绝。** 不允许使用小写字母、连字符、句点和空格。`api-key`和`Api_Key`均会失败;`API_KEY`则可以通过。

**复制未将任何内容放入剪贴板。** 某些浏览器会阻止在非活动标签页中写入剪贴板。请先点击页面,然后再次点击**Copy**。

## 接下来可以查看

- [拉取请求的预览部署](https://support.kapsulehost.com/zh-cn/site-preview),这是生产与预览分离机制的另一半内容。
- [站点的Git部署](https://support.kapsulehost.com/zh-cn/site-git-deploy),用于推送读取这些值的代码。
- [站点活动日志](https://support.kapsulehost.com/zh-cn/site-activity-log),用于查看是谁设置、显示或删除了某个密钥。