凭据管理器实战：跨平台安全存储与密钥管理

1. 我把所有明文配置搬进凭据管理器的那一周

三年前的某个下午，我在排查一个内部工具"配置丢失"的工单。打开那个工具的配置文件，我看到了一行熟悉的、让人血压升高的内容：数据库连接串里带着明文口令，SMTP 账号密码裸奔，还有一段被复制粘贴过十几次的 API Key。更糟糕的是，这个文件被同步到了团队的共享目录里——因为"方便大家一起用"。那一刻我意识到，很多人并不是不知道明文存密码不好，而是不知道凭据管理器这套系统级设施到底怎么用、能用到什么程度、边界在哪里。凭据管理器（Credential Manager）这个词听起来很"系统层"，但它的实际价值非常接地气：它把"密钥该放在哪、怎么加密、谁能读"这三个问题从你的应用代码里剥离出来，交给操作系统去管。

这篇文章就是我这几年在 Windows、macOS、Linux 三套平台上反复折腾凭据管理器之后的完整总结。它适合三类人：一是正在写桌面客户端、命令行工具、后台服务的开发者，需要在自己的程序里安全地存一个口令或 Token；二是负责内部工具链的运维同学，想让脚本不再硬编码密码；三是对"密码到底存在哪"这件事有好奇心的技术爱好者。我会拆开凭据管理器的数据结构、加密链路、跨平台差异，给出可以直接复制的代码和命令，也会把我踩过的坑一条条摆出来——尤其是那些文档里从来不写、但一上手就会撞上的问题。

先把结论摆前面：凭据管理器解决的是"静态存储"这一段的暴露面问题，它不解决内存抓取、不解决同用户下的恶意进程、也不解决你把密码打印到日志里这种事。理解这一点，你才不会对它产生不切实际的期待。

1.1 从一次典型的翻车现场说起

我遇到的第一个真实故障，是某桌面客户端在换了机器之后，用户反馈"每次启动都要重新登录"。查了半天，代码逻辑没问题，凭据读写也没报错。最后定位到：旧方案把加密后的密文写在一个随程序目录走的文件里，加密用的是机器绑定的密钥；换机器之后，密文还在（因为整个目录被打包带走了），但解密密钥已经变了，于是解密失败，程序走了"凭据无效"的分支。这个案例说明了一个很关键的点：凭据存储的可靠性，取决于"密文"和"解密所需的上下文"是否绑定在同一生命周期上。你自己实现一套加密存储，最容易漏掉的就是这个生命周期管理——用户改密码、换机器、切换登录账号、系统重装，每一种情况都会让你的密文变成废纸。

凭据管理器把这件事处理掉了。它在 Windows 上把条目挂到当前用户的登录凭据集合里，加密密钥与用户账户绑定；用户换机器，条目根本不存在，你的代码拿到的是"未找到"，可以干净地走首次配置流程，而不是拿到一堆解不开的乱码。这种"要么有、要么没有"的语义，比"有但解不开"要好处理得多。

1.2 凭据管理器到底替你做了哪几件事

很多人以为它就是个"加密的记事本"。实际上它至少替你做了四件事。第一是密钥托管：加密用的主密钥由系统生成和保护，你的应用不需要也不应该接触它。第二是访问控制：条目归属于某个登录用户，别的用户在同一台机器上读不到。第三是生命周期：跟用户配置文件绑定，随用户环境迁移或消失。第四是统一的交互入口：用户可以在系统设置里自己查看、删除这些条目，出问题时有一个可解释的排查面。

这四件事里，我认为最有价值的是第四件，也是最容易被忽略的。你自建的加密方案，用户看不到、删不掉、也不知道里面存了什么，一旦凭据损坏，只能删配置文件重来。而凭据管理器给了用户一个"我知道我的密码存在哪"的确认感，这在企业内部工具的场景里，能省掉大量的沟通成本。

1.3 三条路线的取舍：明文、自建加密、系统凭据管理器

在动手之前，值得把可选方案摆在一起比一比。我做项目时一般会按下面这张表来决策，判断依据主要是"威胁模型"和"运维成本"，而不是单纯看哪个更"安全"。

我把"自建加密（固定密钥）"这一行标成不建议，是因为我见过太多项目把密钥硬编码在源码里然后提交到仓库，加密带来的唯一效果是把明文密码变成了看起来像乱码的字符串，安全性提升接近于零，却额外增加了排障难度。而"系统凭据管理器"这一行，成本低得惊人——在 Python 里就是两行代码的事——所以只要你的程序运行在有完整桌面会话的环境里，它几乎是默认选项。

需要提醒的是最后一行。当你的程序跑在容器、CI Runner 或者无头服务器上时，凭据管理器通常不可用或不可靠，这时候应该转向环境变量注入、临时令牌或者独立的密钥管理服务，别硬拗。

2. 拆开看：一条凭据的字段、作用域与加密链

要用好一个东西，先得知道它的数据结构长什么样。凭据管理器在很多人的认知里是"存用户名密码的地方"，但真正操作它的时候，你面对的是一个有明确字段定义的结构体。理解这些字段，能让你避开后面 80% 的奇怪问题。

2.1 一条凭据由哪些字段构成

以 Windows 平台的通用凭据为例，核心字段大致是这些：TargetName（目标名，事实上的主键）、UserName（用户名，可以为空）、CredentialBlob（真正的秘密数据，字节数组）、Comment（备注）、Type（凭据类型）、Persist（持久化级别）、Attributes（自定义键值对）。其中最容易出问题的是TargetName和CredentialBlob这两个。

TargetName是唯一定位一条凭据的键。同一个TargetName写入两次，第二次会覆盖第一次。这意味着你的命名规范必须足够细，细到能区分"不同环境""不同用户""不同服务"，否则就会出现开发环境的 Token 把生产环境的 Token 覆盖掉这种事故——我亲眼见过一次，排查了整整一个下午才发现是命名撞车。

CredentialBlob是秘密本体，它的大小是有限制的。Windows 上通用凭据的 blob 上限是 2560 字节（5×512），这个数字在存普通口令时绰绰有余，但如果你想把一个 JWT 或者一段私钥塞进去，就会撞墙。我见过有人试图存整个 PEM 格式的证书私钥，结果写入直接失败，报的还是个含糊的错误码。正确的做法是：需要存大块秘密时，把秘密本体加密封存到文件，凭据管理器里只放那把对称密钥。

Persist决定这条凭据在什么范围内可见，它可以取会话级、本机级、企业级几档。选错这一项的症状很典型：你写进去了，重启就没了；或者你以为只有当前用户可以读，结果其他登录用户也能看到。

2.2 持久化级别怎么选：一个经常被跳过的决策

Persist这个字段很多人直接抄示例代码，不看含义。我把常见的几档整理一下，方便你对着场景选。

默认建议本机级。会话级只适合"这次运行用完就丢"的场景，比如你在一个长时间运行的批处理里反复调用某个接口，把临时令牌存会话级，进程结束自动清理，省去自己管理过期的麻烦。企业级这一档要看用户环境有没有配置漫游，如果没有配置，行为和本机级差不多；如果配置了，凭据会跟着用户走，这在共享终端的场景里是有意义的，但也意味着秘密的物理副本变多了，需要评估。

2.3 加密链条：你的秘密最终被谁保护

很多人问我"存进去的东西到底加没加密"。答案是加了，而且是绑在用户身份上的。以 Windows 平台为例，凭据管理器背后用的是一套与登录凭据关联的数据保护机制：系统在用户首次登录时派生出一组主密钥材料，保存在用户配置文件目录下，并用用户的登录密码派生的密钥再加密一层。应用写入凭据时，系统用这套主密钥加密后落盘；读取时反向解开。

这条链上有两个关键含义。第一，你的应用代码里不会有任何密钥，密钥是系统在用户登录那一刻生成的，程序无权也不需要知道。第二，加密与"这个用户已经登录"强绑定——这就是为什么服务账户、计划任务、无人值守场景经常出问题，因为那些上下文里的用户登录态和你平时双击运行程序时不一样。

macOS 的链条类似，凭据存在钥匙串里，钥匙串本身由登录密码解锁，应用通过访问控制列表申请权限，第一次访问时用户会看到一个授权弹窗。Linux 上则是通过 D-Bus 调用 Secret Service 接口，底层由 gnome-keyring 或 KWallet 这类服务实现。

2.4 三平台对照：别指望一套代码原样跑通

跨平台是我踩坑最多的地方。这里先把差异列清楚，后面写代码时你会反复回来看这张表。

这张表里最值得记的是"无桌面会话时"那一行。太多人写完代码在自己机器上跑得好好的，一部署到服务器或者 CI 就全线报错，本质原因是凭据管理器是一套依赖用户会话的设施，脱离了会话就没有意义。这不是 bug，是设计使然。

3. 上手实操：把凭据读写接进你的程序

理论说完了，动手。我会按"先验证环境、再写最小可运行代码、最后封装成可复用模块"的顺序走，每一步都能独立验证，避免一次性写太多然后无从排查。

3.1 第一步：用系统自带工具做十分钟验证

在动手写代码之前，先确认这台机器的凭据管理器是活的。Windows 上最省事的方式是命令行工具cmdkey。

# 写入一条测试凭据 cmdkey /generic:demo.app.local /user:demo_user /pass:TempPass_123 # 列出所有凭据，确认写入成功 cmdkey /list # 删除 cmdkey /delete:demo.app.local

cmdkey的优点是零依赖、所有 Windows 机器都有；缺点是它只做增删查，读不出密码明文——这一点其实是好事，说明系统没有给命令行留出"打印密码"的口子。想读回密码，得走 API。

macOS 上对应的是security命令：

# 写入通用密码条目 security add-generic-password -a demo_user -s demo.app.local -w 'TempPass_123' -U # 读取（-w 表示只输出密码本身） security find-generic-password -a demo_user -s demo.app.local -w # 删除 security delete-generic-password -a demo_user -s demo.app.local

Linux 上如果装了 libsecret 工具集，可以用secret-tool：

# 写入，属性用键值对表达 secret-tool store --label='demo app' service demo.app.local username demo_user # 读取 secret-tool lookup service demo.app.local username demo_user # 清除 secret-tool clear service demo.app.local username demo_user

注意：secret-tool store会从标准输入读取密码，交互式执行时直接敲入然后按 Ctrl+D 结束。写脚本时用管道喂进去，不要用命令行参数传密码，否则密码会留在 shell 历史里。

这三组命令的共同价值是：它们让你在没有写一行代码的情况下，先确认"凭据管理器能用"这个前提成立。如果这一步就失败，别急着调代码，先查环境。

3.2 在 .NET 里直接调 Win32 接口

如果要对写入过程有完全控制（自定义属性、指定持久化级别、处理错误码），最直接的办法是 P/Invoke 调用原生的凭据读写函数。下面这段是我常用的最小封装，去掉了业务逻辑，只保留核心路径。

using System; using System.Runtime.InteropServices; using System.Text; public static class CredStore { [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] private struct CREDENTIAL { public uint Flags; public uint Type; public string TargetName; public string Comment; public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten; public uint CredentialBlobSize; public IntPtr CredentialBlob; public uint Persist; public uint AttributeCount; public IntPtr Attributes; public string TargetAlias; public string UserName; } [DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)] private static extern bool CredWrite(ref CREDENTIAL credential, uint flags); [DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)] private static extern bool CredRead(string target, uint type, uint flags, out IntPtr credential); [DllImport("advapi32.dll", SetLastError = true)] private static extern void CredFree(IntPtr buffer); private const uint CRED_TYPE_GENERIC = 1; private const uint CRED_PERSIST_LOCAL_MACHINE = 2; public static bool Save(string target, string user, string secret) { byte[] blob = Encoding.Unicode.GetBytes(secret); IntPtr blobPtr = Marshal.AllocHGlobal(blob.Length); try { Marshal.Copy(blob, 0, blobPtr, blob.Length); var cred = new CREDENTIAL { Type = CRED_TYPE_GENERIC, TargetName = target, UserName = user, CredentialBlobSize = (uint)blob.Length, CredentialBlob = blobPtr, Persist = CRED_PERSIST_LOCAL_MACHINE }; return CredWrite(ref cred, 0); } finally { Marshal.FreeHGlobal(blobPtr); } } public static string Load(string target) { if (!CredRead(target, CRED_TYPE_GENERIC, 0, out IntPtr ptr)) return null; try { var cred = Marshal.PtrToStructure<CREDENTIAL>(ptr); byte[] blob = new byte[cred.CredentialBlobSize]; Marshal.Copy(cred.CredentialBlob, blob, 0, blob.Length); return Encoding.Unicode.GetString(blob); } finally { CredFree(ptr); } } }

这段代码有两个必须注意的细节。第一，CredentialBlob的编码。Windows 上凭据 blob 的编码约定是 UTF-16 小端，也就是 .NET 里的Unicode，不是UTF8。用错编码的症状是：写进去显示正常，读出来变成一串夹杂空字符的乱码，或者长度对不上。我最早就是栽在这里，后来才反应过来是编码不一致。

第二，CredFree必须调用。CredRead返回的指针指向系统分配的内存，不释放就是内存泄漏。很多人写循环里频繁读取凭据的程序，跑几天之后内存涨到离谱，原因就在这里。

3.3 Python：两行代码跨三个平台

如果你的目标只是"存一个口令、取一个口令"，不要自己造轮子。Python 的keyring库把这些平台差异全部封装掉了，接口稳定得像块砖。

import keyring SERVICE = "demo.app.local" ACCOUNT = "demo_user@example.internal" # 写入 keyring.set_password(SERVICE, ACCOUNT, "TempPass_123") # 读取 pw = keyring.get_password(SERVICE, ACCOUNT) # 删除 keyring.delete_password(SERVICE, ACCOUNT)

它能用，但你必须知道它背后连的是谁。执行keyring.get_keyring()会告诉当前选中的后端。在 Windows 上应该是凭据管理器后端，在 macOS 上是钥匙串，在 Linux 上应该是 SecretService。如果输出显示的是某个"纯内存"或者"加密文件"的后端，说明系统里没有可用的密钥环服务，这时候写进去的东西要么不持久，要么只做了很弱的保护。

import keyring print(keyring.get_keyring())

电源环境里这一行输出应该指向系统级别的后端，如果你看到的是keyring.backends.fail.Keyring，那就是彻底没配好，所有写入操作都会抛异常。这种情况在容器里特别常见。

3.4 命令行工具与 Node 生态的做法

Node 侧的方案这些年换了几轮。早期大家用 keytar，后来它进入维护状态，新项目一般会转向基于原生绑定的替代实现。无论用哪个库，接口基本是同一套形态：setPassword(service, account, password)/getPassword(service, account)/deletePassword(service, account)。

如果你是写 CLI 工具，我建议把这个能力收敛成一个极薄的内部模块，对外只暴露三个函数，内部做两件事：一是后端探测，启动时检查当前环境有没有可用的凭据存储，没有就降级到"从环境变量读取 + 明确提示用户"的路径；二是错误归一化，把各平台千奇百怪的报错统一成"未找到""无权限""后端不可用"这三种语义。这两件事做完了，上层业务代码就再也不用关心平台差异。

提示：CLI 工具里还有一个容易被忽略的点——如果用户在管道里调用你的程序，读密码时不要试图弹出交互式输入框，直接读环境变量或标准输入，否则在自动化脚本里会卡死。

3.5 存之前先处理：编码、长度与字符集

这一段是我最想强调的实操细节。凭据管理器的 API 大多以字节数组作为秘密载体，而你的业务数据可能是字符串、JSON、二进制密钥。中间这层转换如果处理不当，会出现"写进去读出来不一样"的诡异现象。

我的做法是统一约定：业务侧传入 UTF-8 字符串，写入前显式编码为字节数组，读取后显式按同一编码解码；如果秘密超过长度限制，走"文件封装 + 凭据管理器存对称密钥"的两级方案。长度限制这个数值不要凭记忆，直接写死在代码常量里并在写入前做断言，超限时抛出明确异常，比让底层函数返回一个模糊的错误码要好排查一百倍。

字符集方面，除了前面提到的编码一致性，还有一个坑：部分平台在存储时对换行符、制表符做了处理。如果你的秘密是多行文本（比如一段配置片段），最好先做 Base64 编码再存，读取后解码还原，彻底绕开字符层面的歧义。

4. 参数与策略：让凭据在你的场景里真正稳得住

代码能跑通只是第一步。真正决定这套方案能不能在项目里长期活下去的，是命名规范和生命周期管理。这两件事没有标准答案，但有明确的坏味道。

4.1 凭据粒度怎么切：三条经验规则

第一条规则：一个凭据只服务一个目标。不要出现"这条凭据存了数据库密码、SMTP 密码、API Token 三个东西"的设计，那样任何一个泄露都要全量轮换，而且你没法针对单个目标做权限收紧。

第二条规则：把"环境"编进主键。开发、测试、预发、生产，四套环境的凭据必须是四个独立的条目。我见过最惨的事故是一次预发环境调试时，代码误连生产，因为凭据管理器里只有一个条目，程序读到就用，没有任何区分。

第三条规则：把"人"和"程序"分开。用户自己的登录凭据和程序运行所需的机器凭据，不要混在同一个条目前缀下。前者属于用户资产，后者属于部署资产，清理策略和轮换节奏完全不同。

4.2 主键命名规范：一个可以直接照抄的方案

我试过好几种命名方式，最后稳定下来的是这套带分隔符的层级结构，形如产品名.模块.环境.用途，例如demoapp.sync.prod.api-token。它的好处是：既能保证唯一性，又能靠前缀做批量枚举和清理。

配上一段枚举逻辑，你就能实现"切换环境时批量清理旧凭据""卸载时按前缀清空"这类能力。枚举在 Windows 上对应的是凭据枚举接口，在 macOS 上是钥匙串的查询接口，在 Python 的 keyring 里则没有统一抽象，需要按后端单独处理——这一点要有心理准备，跨平台枚举是这套方案里最不统一的部分。

4.3 过期、轮换与删除：写进去之后的事

密钥写进去就不管，是另一个高频问题。我在项目里一般会强制做三件事。

第一，写入时同时记录一个元数据条目，内容只有写入时间和版本号，主键用主键加.meta后缀。这样读取时可以先判断"这条凭据有多老了"，超过预设周期就在界面上提示用户更新，而不是静默使用一个两年前的 Token。

第二，提供显式的"清除凭据"入口。用户卸载程序、切换账号、或者怀疑泄露时，需要一个确定的、可解释的操作。别指望用户去系统设置里手动找，那个界面里条目的名称是程序决定的，用户根本认不出来。

第三，轮换要有回滚路径。新凭据写入成功之后再做一次读回校验，校验通过才删除旧条目。顺序搞反了，中间任何一步失败，用户就会陷入"新密码没写进去、旧密码已经删了"的死局。这个校验逻辑写起来二十行，但能救你一命。

5. 踩坑实录：十几个现场与一张速查表

这一节是我最有表达欲的部分。下面每一条都是我在实际项目里真实撞上过的问题，我把症状、根因、处理方式整理成可以直接对照的形式。

5.1 读不到凭据的五种典型原因

症状一：写入成功，读取返回未找到。最常见的原因是主键不一致——写入时用的是带前缀的完整名，读取时用的却是简短别名。凭据管理器的匹配是精确匹配，不做任何模糊处理。建议把主键定义成一个常量，写和读都引用它。

症状二：同一台机器，换了个用户登录就读不到。这是设计行为，不是缺陷。凭据归属于用户，用户 A 写的用户 B 读不到。如果你的程序需要跨用户共享凭据，说明你的架构需要调整——共享凭据应该放到服务端或者集中式存储里。

症状三：开发环境正常，服务里跑就失败。服务上下文没有完整的用户登录态，凭据管理器那套加密链断了一环。处理方式是把凭据绑定到具体的服务账户上，用该账户的身份运行一次写入；或者换方案，改用受保护的配置文件配合文件系统权限。

症状四：CI 流水线里报后端不可用。容器里没有 D-Bus 会话，Secret Service 根本不存在。这种情况不要试图在容器里装密钥环服务，直接用环境变量注入短期令牌，在流水线里做掩码，任务结束即失效。

症状五：中文用户名或含特殊字符的账户读不到。这个问题比较偏，但确实存在。部分实现在处理用户名字段时对内含字符的编码处理不一致，导致匹配不上。规避办法是把账户名也统一编码，或者干脆用固定标识代替真实用户名作为主键的一部分。

5.2 服务与计划任务场景的三个坑

第一个坑是"以最高权限运行时凭据不见了"。某些程序为了做系统级操作会请求提升权限，提升之后运行在不同的安全上下文里，读不到原用户写入的条目。这个坑非常隐蔽，因为程序的其他功能都正常，只有凭据读取失败。我的做法是：凭据读写集中在非提升的进程里做，把结果以最小必要的形式传给提升后的进程，而不是让提升后的进程自己去读。

第二个坑是计划任务的"用户是否登录"选项。勾选"不管用户是否登录都运行"，任务将在无交互会话中执行，凭据读取大概率失败；不勾选，任务只在用户登录时运行，业务上可能不满足。这两者之间存在真实的取舍，我一般会选择"任务本身不依赖凭据管理器"，把需要长期运行的凭据交给专门的服务账户配置。

第三个坑是远程桌面会话断开后凭据不可用。会话从"交互"变成"断开"，某些加密上下文的可用性会变化。测试这类场景时不要只在连着远程桌面的时候测，一定要断开再测一遍。

5.3 迁移、备份与重装时的注意事项

凭据管理器里的东西不应该进入你的备份体系。这一点要反复强调。备份工具把用户配置文件打包带走，里面包含了加密后的凭据条目，虽然密文本身解不开，但它会造成"看起来有、实际用不了"的假象——恢复之后程序读到条目，解密失败或者拿到无效值，报出的错误和你预期的完全不同。

正确的迁移姿势是：迁移工具跳过凭据，程序在新环境首次启动时检测不到凭据，走引导流程让用户重新输入。这条路径必须在开发阶段就测通，不能等上线后才发现"首次使用流程"根本没有人走通过。

重装系统的情况同理。用户的凭据随用户配置文件一起消失，这是预期行为。如果你需要用户在重装后无感恢复，那说明这些凭据不该只存在本地，应该有一份由服务端管理的副本——但这又引入了新的安全考量，需要单独评估。

5.4 常见问题速查表

6. 安全边界：它防得住谁，防不住谁

我特别怕一种讨论："用了凭据管理器就安全了"。任何安全设施都有明确的威胁模型，说不清边界就等于没有边界。这一节我把话说透。

6.1 它实际抵御的攻击面

凭据管理器主要抵御三类风险。第一类是静态文件泄露：配置文件被打包发给同事、被同步到共享目录、被误提交到代码仓库——这些是现实中最高频的泄露途径，凭据管理器从根上消除了这个载体。第二类是跨用户窥探：同一台机器上的其他登录用户读不到你的条目。第三类是简单的磁盘取证：直接翻文件系统找不到明文秘密。

这三类覆盖了绝大多数日常事故。我做过一个粗略统计，内部工具出现过的凭据泄露事件里，绝大多数都是"配置文件被分享出去了"这一种模式。把这一条堵住，收益就已经很大了。

6.2 它明确防不住的东西

同一用户下的恶意进程。只要攻击者已经以你的用户身份运行代码，它就可以调用同样的接口读走凭据，因为系统认为"这是同一个用户"。凭据管理器不是沙箱，它不提供进程级隔离。

内存中的明文。你的程序读取凭据后，明文会存在于进程内存里。内存转储、调试器附加、崩溃报告上传，都可能把它带出去。对策是缩短明文在内存中的存活时间、避免把秘密放进异常消息和日志里。

日志与遥测。这是最荒诞也最常见的泄露途径：凭据存得好好的，结果程序在打印请求详情时把 Authorization 头一起打进了日志。我现在的习惯是在日志模块里加一层脱敏规则，对包含 token、password、secret、key 字样的字段一律替换成固定占位符，宁可少打一点信息。

供应链与更新通道。如果程序自身的更新包被替换，凭据管理器保护得再好也没用——恶意版本可以直接读走。这部分不在本文范围，但必须知道它存在。

6.3 我自己的加固清单

按重要性排，我现在每个项目都会过一遍这七条。第一，代码仓库里做密钥扫描，把"看起来像密钥的字符串"在提交阶段就拦住。第二，凭据主键里带环境标识，杜绝跨环境误用。第三，日志模块强制脱敏，且默认不打印请求头。第四，凭据读取失败时给出可操作的提示，而不是抛一个堆栈。第五，提供显式清除入口，并在文档里写清楚它在系统里的位置。第六，轮换流程带读回校验。第七，在项目 README 里写一段"威胁模型说明"，明确告诉使用者这套方案防什么、不防什么。

最后一条听起来最虚，实际上最有用。它逼着团队在动手之前把预期对齐，避免上线之后有人问"我们不是用了凭据管理器吗，怎么还会泄露"。

我个人在实际项目里的体会是：凭据管理器最大的价值不在于它用了多强的加密算法，而在于它把"秘密存在哪"这个问题变成了一个有标准答案的问题。以前每个项目都要自己发明一套存储方案，每个方案都有自己的坑；现在大家都往同一个地方放，排查的时候有共同语言，用户也有一致的操作预期。至于那套加密链具体怎么实现，说实话，作为应用开发者你不太需要关心——你更需要关心的是主键有没有写对、编码有没有统一、日志有没有漏、清理有没有做。这几个问题看起来琐碎，但它们才是决定你的程序会不会在某个深夜被告警叫醒的东西。