User Credentials zh

用户凭据

上游基于引用的凭据管理系统在 Edge 中的适配。

上游参考：用户凭据

上游提供了什么

凭据系统将密钥与配置分离。设置和 cordis.yml 存储引用（环境变量名），实际值由 CredentialProvider 实现持有。关键设计：空存储值视为不存在、每次操作解析凭据（不缓存）以支持即时热重载、拒绝遮蔽写入以防静默误配置。

Edge 改了什么

直接复用 凭据服务

上游凭据服务（ctx.credentials）原封使用。引用解析、遮蔽检测、变更事件和凭据 RPC 完全是上游代码。

替换件 凭据提供者 → DO KV + Worker 环境变量

EdgeCredentialProvider 继承上游 CredentialProvider 抽象类，采用两级解析策略：

• 第一级：DO KV 存储 — 运行时可写凭据，键为 dsh-edge:credential:{ref}。支持从设置 UI 调用 set()/unset()。
• 第二级：Worker 环境变量 — 只读降级。DEEPSEEK_API_KEY 预注册为已知引用。向环境变量支持的引用写入被拒绝（遮蔽防护）。

每次调用解析，不缓存，符合上游热重载契约。

Edge 没有改什么

• 基于引用的架构（设置存引用，提供者存值）
• 每次操作解析（跨调用不缓存）
• 遮蔽写入防护
• 空值视为不存在规则
• 凭据 RPC（describe/set/unset）——由 apiproxy 处理
• 安全不变量：凭据值从不出现在 session 事件、日志或 API 响应中

性能特征

凭据解析

每个 LLM 请求通过 resolve(ref) 解析凭据。第一级（DO KV）是单次 storage.get()；第二级（环境变量）是同步属性访问。两者都在亚毫秒级。每次调用解析意味着轮换的凭据在下次请求时立即生效，无需重启。

凭据存储

每次 set() 是一个小字符串值的 storage.put()。凭据以明文存在 DO KV 中——Durable Object 本身是安全边界（access-key 认证、单租户）。这与上游用 OS 文件权限保护本地凭据文件的模型一致。

架构总结

组件	分类	Edge 代码
凭据服务	复用	上游——引用解析、遮蔽检测、事件
EdgeCredentialProvider	替换	约 50 行——DO KV + Worker 环境变量两级解析

关键观察：凭据提供者是具有 Edge 独特设计的最小替换件。第一级（DO KV）支持从浏览器 UI 管理凭据。第二级（Worker 环境变量）提供部署时的 API key，无需 UI 设置。每次调用解析确保两个层级都参与每个请求。