症状：密钥没有写进代码，却在镜像层、构建日志或预览环境里暴露；换一把模型 API Key，还要临时停服务排障。
最快解法：常规应用密钥优先放入按环境隔离、权限受控并可审计的平台密钥功能；服务器本地只保留必须由目标主机管理的基础设施凭据，敏感生产项目再叠加外部 Secrets Vault。
这篇适合三类人：第一次把模型 API Key 部署到 OpenShip、想避免误提交 Git 的个人开发者；管理预览、测试和生产环境的小团队；以及负责发布、轮换和灾难恢复的技术负责人。
先处理最危险的一层：密钥不能进入代码和镜像
一个常见失败现场是：开发者没有把 OPENAI_API_KEY 写进源文件，而是在构建脚本里临时读取本地 .env，再通过 ARG、ENV 或打包脚本传给 Docker。构建成功后，当前源文件看起来没有密钥，但镜像历史、缓存层、构建输出，甚至前端 JavaScript 包里可能已经留下了可检索的值。
Docker 官方文档明确提醒，使用构建参数或环境变量传递构建期密钥，可能使密钥持续存在于最终镜像；需要在构建过程中使用临时的 secret mount，而不是把凭据写入镜像文件系统。Docker 构建密钥文档
因此，检查不能只看当前分支的源文件，应同时覆盖：
- Git 当前文件与提交历史；
Dockerfile、构建参数和缓存配置；- 镜像层与构建产物；
- CI/CD 构建日志、测试报告和错误堆栈；
- 浏览器下载到的客户端包；
- 预览地址对应的运行时环境。
前端变量尤其容易被误判。只要变量被编译进浏览器端，用户就能通过开发者工具、源码映射或网络请求查看；它不再是服务端密钥。GitHub 的推送保护可以在提交阶段拦截部分硬编码凭据，但它是前置防线，不等于已经清除了历史提交、镜像仓库和日志中的旧值。GitHub 推送保护说明
提醒：一旦密钥进入过仓库、镜像层或公开日志，正确动作不是删除那一行再继续部署，而是先撤销旧凭据，再检查所有复制和缓存位置。
先做环境隔离：预览、测试和生产不能共用一套变量
构建期变量和运行期变量必须分开
OpenShip 官网描述的工作流是：代码触发构建，生成不可变版本化制品，再把镜像发送到目标环境运行；官网同时列出了环境范围密钥、Secrets Vault 和审计日志等能力。这里能确认的是产品设计方向，不能直接等同于你当前安装版本、云端形态或混合部署中的安全验证结论。OpenShip 官方产品说明
你需要把变量分成两类：
- 构建期变量：只供安装依赖、拉取私有包或执行测试使用，使用结束后不应进入最终镜像；
- 运行期变量：应用启动或请求处理时才需要，例如模型 API Key、数据库密码和第三方服务令牌。
模型 API Key 通常属于运行期变量。除非你的构建步骤确实要访问模型服务，否则不要在 Dockerfile、打包命令或静态生成步骤中读取它。OpenShip 的环境变量入口即使支持安全保存，也不能阻止应用自身把变量打印到日志，或把变量拼进客户端代码。
为每个环境建立独立凭据集合
预览环境应使用单独的模型账户、数据库和回调地址；测试环境可以使用额度受限或权限更小的凭据；生产环境才使用正式账户。不要把生产 .env 复制成 preview.env 后只修改其中一两项，因为最容易漏改的是数据库连接、对象存储桶、Webhook 签名和模型账户。
建议你在 OpenShip 中为每个环境建立独立变量集合，并为变量命名保留一致的键名，例如：
MODEL_API_KEYDATABASE_URLWEBHOOK_SIGNING_SECRETSTORAGE_ACCESS_TOKEN
不同环境只替换值，不改变应用读取方式。这样做的重点不是界面上看起来整齐，而是让预览部署即使被测试人员访问，也不会拥有生产数据库写权限或正式模型账户额度。
如果当前版本没有清晰的环境范围入口，就不要假定“项目变量”天然等于“生产变量”。应在预览项目中部署一个只输出变量哈希前缀的诊断接口，再用生产环境的不同值验证两边是否真的隔离；绝不能输出完整密钥。
再划责任边界：应用密钥与服务器凭据分别管理
看谁负责注入和恢复，而不是只看文件放在哪里
服务器 .env 的优势是直接、透明、与目标主机绑定。对于 SSH 私钥、主机初始化令牌、系统服务凭据或必须由某台服务器本地进程读取的配置，它可能仍然是合理选择。但它通常依赖文件权限、主机备份、登录账号和人工交接，审计与环境复制容易落到个人习惯上。
平台密钥的优势在于应用级管理：按项目或环境注入、集中修改、减少人工登录服务器。OpenShip 官网将 Secrets Vault 描述为加密存储、按环境作用域管理，并支持不重新部署进行轮换；这属于官方功能描述，部署前仍应在你使用的版本中验证入口、权限和实际行为。
外部 Secrets Vault 则适合高敏感生产凭据，尤其是需要独立管理员、集中审计、动态凭据或多平台同步的团队。OWASP 建议把密钥的存储、分发、审计和轮换集中管理，并限制 CI/CD 工具只能访问完成任务所需的最小范围。OWASP 密钥管理指南
可以按这个边界判断：
- ✅ 平台密钥：模型 API Key、邮件服务令牌、应用级数据库连接、Webhook 签名；
- ✅ 服务器本地：SSH 主机凭据、系统级代理配置、节点初始化凭据；
- ✅ 外部 Secrets Vault：高敏感生产数据库凭据、跨平台共享凭据、需要独立审批的密钥；
- ❌ 仓库或镜像：任何长期有效的生产密钥；
- ❌ 客户端变量：任何需要保密的服务端凭据。
如果你需要进一步确认远程构建端、交付方式和账号责任边界，可以先查看 Macstripe 帮助中心，再把构建机权限和应用运行权限分开设计。
把轮换做成验收流程：不是看控制台显示“保存成功”
换 Key 后是否要重新部署，取决于应用读取时机
如果 OpenShip 在运行时把平台密钥注入容器，理论上更换值不一定需要重新构建镜像；但应用是否需要重启、是否只在启动时读取变量，仍取决于运行时实现。若密钥在构建期被写入配置文件或静态产物，换值就可能必须重新构建，这正是把运行期凭据带入构建过程的隐性成本。
轮换应按以下流程进行：
- 生成新凭据，但暂时不要撤销旧凭据；
- 将新值写入目标环境的密钥存储；
- 触发应用重启、实例滚动更新，或调用应用支持的重新加载机制；
- 发送一笔真实但低风险的请求，确认新请求使用新凭据；
- 观察错误率、限额和日志脱敏情况；
- 撤销旧凭据；
- 再发送请求，确认旧值已经不能继续访问；
- 模拟新凭据失效，验证回退和恢复路径。
轮换验收的核心不是“后台页面显示已保存”，而是三个结果：新请求确实使用新凭据，旧凭据可以被撤销，失败后团队能在不泄露密钥的情况下恢复服务。
对于需要不停机的系统，可以采用短暂并行的新旧凭据窗口；对于只能存在一把有效 Key 的服务，则要先确认服务商的撤销和重新签发顺序。具备版本重叠能力的外部密钥系统，通常更适合需要连续服务的生产环境；相关机制可参考 自动轮换与重叠凭据文档。
按职责收紧权限：能部署不等于能查看密钥
把查看、修改、部署和审计拆成不同权限
小团队最容易犯的错误是：为了让发布顺利，给所有开发成员完整的项目管理员权限。这样一来，任何能修改代码的人都可能间接触发生产部署，任何能查看部署变量的人都可能复制生产凭据。
建议至少拆成四类权限：
- 开发：只能使用预览环境，不能读取生产密钥原文；
- 发布：可以触发生产部署和查看脱敏状态，但不能导出生产密钥；
- 管理员：负责新增、修改、撤销和授权；
- 审计：只能查看操作记录、部署记录和轮换结果，不接触密钥原文。
OpenShip 官网列出了团队角色、资源级权限和可导出的审计能力，但这些描述不能替代你对当前安装版本的权限测试。
你至少要用两个测试账号验证：
- 低权限成员能否读取完整密钥；
- 开发成员能否把预览变量改成生产变量；
- 发布成员能否绕过审批直接修改密钥；
- 管理员修改后是否留下操作者、时间、环境和资源记录；
- 被移除成员的旧会话是否仍能部署；
- 审计人员能否看到操作证据而不是密钥内容。
经验：如果平台只提供“可以使用”与“不能使用”两档权限，你应把高敏感生产凭据移到外部 Secrets Vault，而不是让平台权限承担超出能力范围的隔离任务。
把恢复流程提前演练：服务器能恢复不代表应用能启动
应用数据备份、平台配置备份和密钥备份是三件不同的事。恢复服务器后，如果数据库回来了但平台控制面没有环境变量，应用仍然可能启动失败；如果配置文件恢复了但外部密钥库的授权身份丢失，团队也无法重新取回生产凭据。
建议将恢复材料拆成：
- 应用数据：数据库、对象存储索引、队列状态；
- 平台配置：项目定义、部署目标、环境名称和变量键名；
- 授权材料：外部密钥库的访问角色、恢复账号和审批联系人；
- 运行记录：最近一次成功部署、轮换和回滚的时间点；
- 安全材料：撤销旧凭据、重新签发凭据和验证服务的操作步骤。
备份文件可以保存变量名、环境和版本信息，但不应明文保存生产密钥。若确实需要加密备份，应使用与服务器登录权限不同的恢复密钥，并让至少两名负责人知道恢复授权流程。动态密钥或短期凭据可以进一步缩小泄露窗口；相关机制通常是在需要时生成、过期后自动撤销，而不是长期保存一把共享密码。动态密钥说明
用两张表确定落点，再执行部署前清单
| 凭据类型 | 首选位置 | 不建议放置 | 主要验收点 |
|---|---|---|---|
| 模型 API Key | OpenShip 按环境管理的密钥功能 | Git、Dockerfile、前端变量 | 预览与生产值不同，轮换后新请求成功 |
| 应用数据库凭据 | 平台密钥或外部 Secrets Vault | 镜像文件、共享服务器目录 | 最小权限、环境隔离、可撤销 |
| SSH 与节点初始化凭据 | 目标服务器或独立密钥系统 | 应用容器环境变量 | 只有发布系统或管理员可用 |
| 临时访问令牌 | 外部 Vault 或短期授权机制 | 长期 .env |
到期、撤销和失败恢复可验证 |
| 高敏感生产凭据 | 外部 Secrets Vault，平台只消费 | 个人电脑和明文备份 | 独立审计、双人恢复、轮换不中断 |
部署前可勾选验收清单
- [ ] 仓库历史、镜像层、构建日志和客户端包都完成密钥扫描；
- [ ]
.env已加入忽略规则，仓库只保存变量名模板； - [ ] 构建期与运行期变量已经分开；
- [ ] 预览、测试和生产使用不同的模型、数据库与回调凭据；
- [ ] 当前 OpenShip 版本中的环境范围入口已经实际测试；
- [ ] 低权限账号无法读取生产密钥原文；
- [ ] 更换模型 API Key 后，新请求已确认使用新值；
- [ ] 旧凭据已撤销，并验证旧值不能继续调用；
- [ ] 应用重启、回滚和轮换失败后的恢复路径已经演练；
- [ ] 备份不包含明文生产密钥，恢复授权不依赖单个人员；
- [ ] 审计记录能回答“谁、何时、在哪个环境、修改了什么”；
- [ ] 远程构建端没有继续共享个人 SSH Key 或个人模型账户。
| 部署形态 | 适合放平台密钥 | 适合放服务器本地 | 适合叠加 Secrets Vault |
|---|---|---|---|
| 个人开发与单一预览环境 | 应用 API Key、测试数据库 | 本机 SSH 配置 | 暂不一定需要 |
| 小团队多环境 AI SaaS | 模型 Key、Webhook、应用数据库 | 节点级 SSH、系统代理 | 生产数据库与高敏感令牌 |
| 多服务 Agent 后端 | 服务级 API Key、环境变量 | 节点启动凭据 | 跨服务共享和短期凭据 |
| 高合规生产系统 | 非关键应用配置 | 必须由主机持有的凭据 | 生产全部高敏感密钥 |
如果你的当前方案是把所有值都塞进服务器 .env，短期确实少一个管理界面，但你也承担了环境复制靠人工、权限容易共享、轮换需要登录主机、审计证据不完整以及服务器损坏后难以恢复这几个真实缺点。对需要临时算力、远程构建或多人协作的团队，更合理的做法是先把应用级密钥放到可隔离的平台层，再把节点级凭据留在目标环境；同时检查构建端是否持续在线、团队是否仍在共享个人凭据，并按 Macstripe 的服务说明 了解远程环境的权限隔离与交付边界。
