---
title: "安全处理密钥"
description: "创建、查看与轮换密钥而不泄露明文。"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.appaloft.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 安全处理密钥

## 目标 <a id="environment-secret-values" />

创建、查看和轮换 Secret（如数据库密码、API token），并确保它们在任何界面、日志或诊断信息中都不会以明文出现。

## 适用场景

- 首次为资源配置需要保密的运行时变量。
- 定期轮换密钥，或怀疑某个密钥已经泄露。
- 需要向支持人员或团队成员分享诊断信息，但必须先确认不含明文密钥。

## 前置条件

- 已经创建目标 Resource。
- 新的密钥值已经准备好（例如新生成的 API token）。

## 输入与默认值

| 规则 | 说明 |
| --- | --- |
| 只能是运行时变量 | 构建时变量（进入构建产物的变量）永远不能标记为 Secret |
| 值不会被回显 | 创建/轮换后，CLI、Web、API 都只显示 masked 状态，不显示明文 |
| 推荐通过标准输入传值 | 避免明文出现在进程参数列表或 shell 历史中 |

## CLI 操作步骤

```bash
# 创建资源级密钥（通过标准输入传值，不出现在进程参数里）
appaloft resource secrets create res_web APP_SECRET --stdin

# 轮换已有密钥
appaloft resource secrets rotate res_web APP_SECRET --stdin

# 查看密钥列表（只显示 masked 状态）
appaloft resource secrets list res_web

# 删除不再需要的密钥
appaloft resource secrets delete res_web APP_SECRET
```

`--stdin` 不能和位置参数值同时使用；Appaloft 会自动去掉末尾换行，拒绝空输入，并且绝不会把值打印到终端或日志。

粘贴 `.env` 文件批量导入时，Appaloft 会自动把看起来像密钥的键名（例如 `DATABASE_URL`、`*_TOKEN`、`*_PASSWORD`、`*_PRIVATE_KEY`）当作 Secret 处理：

```bash
appaloft resource import-variables res_web --file .env.production
```

## Web 操作步骤

1. 打开 Resource 详情页的 Variables 标签页。
2. 点击 **Add secret**，输入键名和值。
3. 保存后列表只显示 masked 状态和最后更新时间，不显示明文。

## 预期输出与状态

创建或轮换成功后，命令只返回确认信息（键名、作用域、更新时间），不返回值本身。这个变更只影响**下一次**部署使用的快照，**不会**热更新正在运行的实例。

## 验证

轮换密钥后，必须触发一次新部署，再通过健康摘要和日志确认应用确实读取了新值：

```bash
appaloft deployments redeploy res_web
appaloft resource logs res_web
```

## 回滚 / 恢复

推荐的轮换流程：

1. 在目标资源设置新密钥。
2. 对受影响资源创建新部署。
3. 通过健康摘要和日志确认应用读取了新值。
4. 确认旧密钥不再被使用。
5. 最后再从外部系统（如数据库、第三方 API 控制台）撤销旧密钥。

如果新部署失败，可以先回滚到使用旧密钥的历史部署（见[回滚与恢复](/docs/deliver/recovery/)），同时保留新旧两个密钥都有效，直到确认修复完成。

## 故障排查链接

- [生成安全诊断信息](/docs/troubleshoot/diagnostics/)——复制诊断信息求助时，只复制键名、masked 状态和错误码，绝不复制 `.env` 文件或密钥值本身。

## 相关参考页面

- [配置优先级](/docs/configuration/precedence/)
- [SSH 凭据管理](/docs/servers/ssh-keys/)

Source: https://docs.appaloft.com/configuration/secrets/index.mdx