集成与上线

密钥

一个密钥库，存放平台代你使用的凭据。存一次、按名引用、在一处轮换。

打开 配置 → 密钥管理。凡是需要凭据的地方——数仓连接、提供商密钥、MCP 令牌——你都可以引用一个密钥，而不是把值敲进去。

为什么这样设计

问题从来不是「存一把密钥」，而是那些 副本。把一个数仓密码粘到四个连接器里，轮换就意味着要把四个都找出来，而其中一个是去年某人配好之后就忘了的。用引用的话，值只存在一份，每个消费方都跟着它走。

创建与引用

  1. 1

    创建密钥

    起一个清晰的名字—— snowflake_analytics_ro 胜过 key2。值以带认证的加密方式存储，保存后绝不回传给浏览器。
  2. 2

    引用它

    在连接器或提供商表单里选择该密钥，而不是粘贴具体值。保存下来的是这个引用，不是凭据本身。
  3. 3

    原地轮换

    在这里更新值，每个消费方在下一次调用时就会用上新值。不需要重新部署，也不用四处翻找。

命名规则

名称由数据库校验，因此不合法的名字在保存时就会失败，而不是静默地永远匹配不上：

规则详情
匹配模式^[A-Za-z][A-Za-z0-9_]*$
必须以字母开头
可以包含字母、数字和下划线——不能有连字符、空格或点
最大长度64 个字符
合法不合法原因
SNOWFLAKE_ANALYTICS_ROsnowflake-analytics-ro不允许使用连字符
stripe_live_key2captcha_key不能以数字开头
jiraTokenjira token不能有空格

按名称引用密钥

除了连接器表单之外，这套引用语法在任何由服务端解析的地方都有效——最明显的是在集群的 集群 HTTP 节点上：

HTTP 节点请求头
Authorization: Bearer {{secret:SUPPORT_API_TOKEN}}

为什么这样设计

{{secret:NAME}} 会被客户端模板引擎刻意留着不解析，改在调用时由服务端替换。正是这一点让集群能对第三方 API 完成认证，而凭据从不发给浏览器、也不出现在画布上——于是能编辑这张图的人依然读不到那个值。

到底哪些字段会被解析

这一点值得说准确，因为写在别处的引用会被原样当作字面文本 {{secret:NAME}} 传出去——结果通常表现为对端的认证失败，而不是在这里报错。

位置会被解析的字段
智能体集群 HTTP 节点URL、每个请求头的值，以及请求体。请求头的名字不做模板替换。
数仓与数据库连接该连接配置的每一个字符串字段。
集成凭据该集成配置的每一个字符串字段——搜索提供商、对象存储、自动化工具。
MCP 构建器 环境变量绑定的值一侧，在容器启动时解析。 ENV_NAME={{secret:NAME}}

花括号内部的空白是允许的—— {{ secret:NAME }} 解析结果完全相同。引用里的名字必须满足与已存名称相同的规则，所以一个存不下来的密钥，也不可能被引用到。

当引用无法解析时

在集群 HTTP 节点、连接或集成上，它会明确失败：密钥不存在，或者你没有被授权，都会让调用中止并给出点名该密钥的明确错误。它绝不会被静默替换成空字符串——那会把一个凭据问题变成一次未认证请求，而某些 API 对此的回应是 200 以及一个空结果。

MCP 环境变量绑定是例外

如果某个绑定所指的密钥缺失或已被撤销，它会被 跳过 ，而不是抛错，于是容器启动时那个变量干脆就不存在——而按惯用写法写的代码， os.environ.get("API_TOKEN", "")，接着就会发出一个空令牌。故障表现为远端 API 拒绝这次调用，离真正的成因隔了一层。如果某个自建服务在一次轮换之后开始认证失败，先检查那个绑定指向的密钥是否仍归你所有或仍在你的授权范围内。

你自己的密钥优先，两个共享的会冲突

名称按用户解析，顺序是：先用你自己拥有的同名密钥；否则用共享给你的。如果有 两个不同的 共享密钥都叫这个名字，这次调用会以「歧义」失败，而不是随便挑一个。

这正是在共享工作区里给名字加限定前缀的现实理由—— BILLING_STRIPE_KEY 和 SUPPORT_STRIPE_KEY ，而不是在不同人的密钥库里各有一个 STRIPE_KEY 条目。这也意味着同事只要自己拥有一个同名密钥，就能为自己覆盖掉共享的那个——有意为之时很有用，无意发生时会让人意外。

实操示例——轮换数仓密码

  1. 1

    先在源头轮换

    在 Snowflake、Postgres 或该账号所在的地方签发新密码。密钥库存的是你告诉它的东西；它没法改动上游的凭据。
  2. 2

    配置 → 密钥管理 → 编辑该值

    同一个密钥，新的值。 不会 新建 SNOWFLAKE_ANALYTICS_RO_V2 ——全部好处就在于消费方指向的是一个名字，而换个新名字就意味着要把它们全部重新找一遍。
  3. 3

    不需要重新部署任何东西

    连接与集成会在下一次调用时解析该引用，所以改动无需动它们就能生效。
  4. 4

    重启绑定了它的 MCP 服务

    唯一的例外：环境变量绑定是在容器启动时解析的，所以正在运行的服务会一直用旧值，直到它重启或缩容到零。
  5. 5

    在上游吊销旧凭据

    在你做这一步之前，这次轮换只是多了一份凭据，而不是替换了一份。

密钥可以用在哪里

访问控制

密钥默认仅所有者可见。管理员可以在此把访问权授予某个用户或用户组： 访问控制，这样同事就能在连接器里 使用权 某个密钥，而始终看不到它的值。

注意

授予某个密钥的访问权，等于授予使用它的能力，也就等于授予它所能打开的一切。请授权给用户组而不是个人，这样人员离开时靠调整组成员即可处理，而不必逐条审查每一份授权。

使用卫生

在来源处遵循最小权限
为分析用途创建一个只读的数仓用户，而不是把管理员凭据存进来。密钥库保护的是那个值；它无法削减该凭据本身能做什么。
每个系统、每种用途一个密钥
不同用途用不同凭据，撤销其中一个不会影响其他，而审计痕迹会告诉你哪个集成做了什么。
定期轮换，人员离职时也要轮换
凡是离职者可能看到过的，都该轮换，不论你是否认为他抄走了。
绝不把凭据写进提示词
系统提示词会发给模型提供商，也会显示在追踪里。凭据该放在这里、由平台去引用，而不是放在模型能念给别人听的文本里。

它们是如何被保护的

值在存储之前会用一个工作区加密密钥加密，而那个密钥放在环境变量里、不在数据库里——所以单有一份数据库导出，拿不到任何凭据。在自托管部署上，那个密钥就是 PROVIDER_CREDS_SECRET；请把它备份到一个你确实能取回来的地方，因为丢了它，所有已存密钥都将无法读取。参见 安装与部署.

上一篇API 与 Webhook下一篇 访问控制