AI API Key的安全存放之道：Oil Motion系统凭据库的完整设计

【免费下载链接】oil-motion设计并实现随滚动、拖动、指针或状态变化响应的网页动画，覆盖素材、时间轴和运行时。项目地址: https://gitcode.com/gh_mirrors/oi/oil-motion

使用 AI 绘图服务时，最容易忽视的就是AI API Key的安全存放——很多项目的密钥散落在聊天里、明文配置和终端历史中，而这些都是最常见的泄露路径。开源项目Oil Motion（把 AI 生成素材做成随滚动、拖动、指针响应的网页动画）对密钥安全有一套完整设计：Key 只存系统凭据库，只在任务运行时注入业务进程，任何情况下都不降级明文。本文就用它拆解一套新手也能读懂的 API Key 安全存放方案。

为什么不该把 API Key 明文存放

三种常见但危险的习惯：

• 🗣️把 Key 贴进 AI 对话——密钥进入聊天日志和工具输出
• 📄写进明文配置文件——如config.json，同用户下任何进程都能读
• ⌨️终端里直接输入——残留在 shell 历史记录

Oil Motion 的做法是绕开这三条路：首次使用时拉起一个本机配置页，由用户亲自在浏览器填写 Key，写入系统凭据库，完整说明见 references/api-key-setup.md。

系统凭据库的三层核心设计

1️⃣ 本机配置页：让 Key 只经过人的手

运行setup后，程序启动一个只监听 127.0.0.1的本机服务，返回一个 30 分钟有效的一次性链接（实现见 scripts/credential-ui/src/server.ts）。用户自己打开、自己填写、自己保存；Agent 全程不接触 Key 页面，不截图、不回填已有值。

2️⃣ 只存操作系统原生安全存储，绝不回退明文

规则写在代码里很明确：后端不可用时直接停止并提示，不自动安装、不自动解锁、也不回退到 JSON 或浏览器存储等明文介质（scripts/secure_credentials.py）。配套的 tests/test_secure_credentials.py 还专门验证了：即使后端报错，Key 也不会出现在任何错误信息或输出里。

3️⃣ 最小权限注入：只有当前任务进程能看到 Key

图片与视频生成脚本统一通过run入口运行：

node "$OIL_MOTION/scripts/credential-ui/src/profile.ts" run default -- 你的业务命令

入口遵循三条规则（scripts/credential-ui/src/run.ts）：

1. 环境变量优先——运行时已注入ZENMUX_API_KEY（如 CI）就直接复用
2. 按需读取——只读取本业务声明的凭据引用，不注入其他服务的 Key
3. 用完即清——子进程启动后立即把 Key 从环境里删除；命令参数和状态输出里永远不会出现 Key

直接运行生成脚本会报“读取不到 ZenMux API Key”，而不是静默走明文路径。

几个值得抄作业的防泄露细节

• 🔒乐观锁防误覆盖：每个凭据带版本号，Key 若在别处被改过，保存会被拒绝并要求刷新（scripts/credential-ui/src/config.ts）
• 📏格式严格校验：只接受非空单行、最长 2500 字符的文本，多行私钥等直接拒绝
• 🌐仅限本机服务：配置页只监听 localhost，带引导令牌、30 分钟过期与严格 CSP 响应头
• 🏷️显式绑定声明：业务档案只记录“凭据引用 → 环境变量名”，从不保存密钥本身（scripts/credential-ui/manifests/profiles.json）

API Key 快速配置：3 条命令搞定

# 1. 检查是否已配置（退出码 0 可用，2 未配置） node "$OIL_MOTION/scripts/credential-ui/src/profile.ts" status default # 2. 启动本机页面，亲自填写密钥 node "$OIL_MOTION/scripts/credential-ui/src/profile.ts" setup default # 3. 运行业务，Key 自动按需注入 node "$OIL_MOTION/scripts/credential-ui/src/profile.ts" run default -- 你的业务命令

⚠️ 注意：保存成功只说明 Key 能存能读；Key 是否有效，以第一次生成调用的结果为准。CI、容器和远程服务器建议沿用运行时已有的密钥注入机制，不要将本机配置页开放到网络。

总结

Oil Motion 凭据库的设计可以浓缩成三句话：让人填 Key，让系统管 Key，只让任务用 Key。它没有使用任何花哨技术，靠的是系统原生凭据库、最小注入和“不可用就停下”的原则。下次接入任何 AI 服务时，这套思路都值得直接借鉴。

【免费下载链接】oil-motion设计并实现随滚动、拖动、指针或状态变化响应的网页动画，覆盖素材、时间轴和运行时。项目地址: https://gitcode.com/gh_mirrors/oi/oil-motion