把模型 Key 收进部署面板:用 Coolify 做统一密钥网关的落地实践

原创2026-10-26 14:01:231,408 阅读
文章标签:云原生DevOpsCI/CD容器编排运维后端微服务MCP 服务

把模型 Key 收进部署面板:用 Coolify 做统一密钥网关的落地实践

一个团队里同时跑三五个 AI 应用是常态:一个做 RAG 的后端、一个内部 Copilot、一个跑在队列里的 Agent。每个项目各自在 Coolify 里配一份 OPENAI_API_KEY,看起来只是"多填几个字段",实际是把同一份凭证复制了 N 次。换供应商、额度到期、Key 被限流时,你要挨个进项目改,改完还要逐个 Redeploy,漏掉一个就是一个诡异的 401。

Coolify 作为自托管的 PaaS,本身并不感知"你调用的是哪家模型",但它提供了足够扎实的密钥治理原语:四层作用域共享变量、只显示一次的锁定值、部署期才拉取的远程密钥源,以及一整套针对环境变量的权限与脱敏逻辑。本文不做泛泛的功能导览,而是围绕"用 Coolify 当统一密钥网关"这个目标,把仓库里真实存在的实现拆开看:它解决了什么、边界在哪、哪里会踩坑。

一、泄露面到底在哪:不是数据库,而是落盘的 .env

社区里流传的一些 Coolify 接统一 Key 的教程,在"变量存在哪"这件事上说法并不准确——有文章称环境变量会以明文存进 SQLite。看源码可知这个结论是错的:

在 EnvironmentVariable 与 SharedEnvironmentVariable 两个模型里,value 字段都声明了 'encrypted' cast:

protected $casts = [
    'key' => 'string',
    'value' => 'encrypted',
];

并且两个模型都把 value(EnvironmentVariable 还有 real_value)放进了 $hidden,默认不参与 toArray() / toJson() 序列化。所以"库里明文"这个说法可以排除了。

真正的泄露面在部署阶段。应用部署时,Coolify 生成运行时环境变量并通过 base64 传送到目标主机写盘,见 ApplicationDeploymentJob::save_runtime_environment_variables():

$envs_base64 = base64_encode($environment_variables->implode("\n"));
$this->execute_remote_command([
    executeInDocker($this->deployment_uuid, "echo '$envs_base64' | base64 -d | tee $this->workdir/.env > /dev/null"),
    'skip_command_log' => true,
]);

这段代码里有几个值得记住的事实:

  • base64 只是为了避免命令拼接时被 shell 转义破坏,不是加密,落盘的 .env 是明文;
  • 同一份内容会写进 $this->configuration_dir/.env,并且在使用独立构建服务器时会写两次(主服务器一份、构建服务器一份);
  • skip_command_log 只是不打命令日志,isDev() 分支里另外提供了 logEnvironmentFileKeys() 只打印变量名、不打印值。

换句话说,把 Key 收到面板里管,收益不在"库里加密了"这一层,而在于:凭证从 N 份变成 1 份,轮换只改一处;主机上的 .env 数量从 N 份变成 N 份但仍然只有一个来源,并且可以配合锁定值与日志脱敏把窥视面压到最小。这是本文后续所有实践的前提。

二、四层作用域:team / project / environment / server

Coolify 的共享变量不是"一个全局变量表",而是四种作用域共用一个模型、靠 type 与对应外键区分。这一点在 bootstrap/helpers/constants.php 里是一行常量:

const SHARED_VARIABLE_TYPES = ['team', 'project', 'environment', 'server'];

模型侧的四张关系表也同样直白——Team、Project、Environment、Server 各自暴露一个 environment_variables(),内部都是 hasMany(SharedEnvironmentVariable::class)->where('type', ...)。SharedEnvironmentVariable 自身只有 team_id / project_id / environment_id / server_id 四个可空外键,没有任何"继承"字段。

引用语法因此是显式带作用域前缀的,形如 {{team.KEY}}、{{project.KEY}}、{{environment.KEY}}、{{server.KEY}}。这带来一个很实用的性质:同名 Key 可以同时存在于不同作用域,且不存在"覆盖"关系。内部团队变量叫 MODEL_KEY、某个项目要临时换成试用额度也叫 MODEL_KEY 时,资源变量里写 {{team.MODEL_KEY}} 还是 {{project.MODEL_KEY}} 是明确可读的,不会因为解析顺序而互相污染。

对"统一模型网关"这个场景,分层建议是这样的:

作用域 放什么 理由
team 网关地址、统一 Key、组织级模型白名单 一次轮换,全团队生效
project 该项目专属的模型名、预算/限流标识 同项目多环境复用
environment production / staging 各自不同的 Key 环境隔离,防止测试流量打穿生产额度
server 服务器标识、内网网关地址 与机器绑定,不随项目走

需要留意 server 作用域的两个细节:Coolify 会为每台服务器自动创建 COOLIFY_SERVER_UUID 与 COOLIFY_SERVER_NAME 两条内置变量(见 AddPredefinedServerVariables 迁移),而 SharedVariableCanvas 在画布和总览里会把它们剔除,避免噪音;同时内置 Key 只能通过引用取用,不会自动注入到每个资源。

三、落地:用 API 把 Key 收进团队层

面板上点几下就能建变量,但"统一密钥网关"往往是可重复、可审计的,走 API 更合适。团队级共享变量的路由在 routes/api.php:

Route::get('/team/envs', [SharedEnvironmentVariablesController::class, 'team_envs'])->middleware(['api.ability:read']);
Route::post('/team/envs', [SharedEnvironmentVariablesController::class, 'team_create_env'])->middleware(['api.ability:write']);
Route::patch('/team/envs/{env_id}', [SharedEnvironmentVariablesController::class, 'team_update_env'])->middleware(['api.ability:write']);
Route::delete('/team/envs/{env_id}', [SharedEnvironmentVariablesController::class, 'team_delete_env'])->middleware(['api.ability:write']);

创建一条锁定状态的团队 Key:

curl -sS -X POST "https://coolify.example.com/api/v1/team/envs" \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "MODEL_GATEWAY_KEY",
    "value": "sk-xxxxxxxxxxxxxxxx",
    "is_literal": true,
    "is_shown_once": true,
    "comment": "统一模型网关凭证,轮换时只改这里"
  }'

三个布尔字段不是可选的装饰,它们直接决定值怎么进容器:

  • is_literal:为真时值里的 $ 不再被当成变量插值。API Key 一般不含 $,但网关返回的 base64、私钥、含 ${} 的连接串会,一旦被当作插值就会被 Compose 或 shell 吃掉。
  • is_multiline:为真时按字面量包裹('...'),用于多行 PEM 之类。
  • is_shown_once:保存后 UI 与 API 都不再回显值,见下节。

然后在具体应用的 Environment Variables 里只写引用,应用代码读到的仍是标准变量名:

OPENAI_API_KEY={{team.MODEL_GATEWAY_KEY}}
OPENAI_BASE_URL={{team.MODEL_GATEWAY_URL}}
ANTHROPIC_API_KEY={{team.MODEL_GATEWAY_KEY}}
ANTHROPIC_BASE_URL={{team.MODEL_GATEWAY_URL}}

这里刻意让业务代码不用关心"网关"这回事:SDK 认的仍然是 OPENAI_API_KEY,替换实现只在变量值层面发生。换供应商时改团队变量一处,所有引用了它的应用下次部署自动生效。

解析逻辑有两条路径,但都落在同一个语义上。资源变量的取值走 EnvironmentVariable::get_real_environment_variables_internal():先按前缀判断类型,再按资源所属的 environment / project / team / server 取 id,最后在同一 team_id 下精确匹配 type + key + {type}_id。Compose 解析器则复用 helper resolveSharedEnvironmentVariables()。两处都有同一个约束值得记住:只做一层替换,不递归。如果 {{team.A}} 的值本身又写成 {{team.B}},容器拿到的就是字面量 {{team.B}}。这不是 bug,但足以让"套娃式变量"在生产上悄悄失效。

四、权限与可见性:谁有权改、谁有权看

共享变量之所以适合放密钥,很大程度上是因为它的授权模型比普通环境变量更严。SharedEnvironmentVariablePolicy 写得很清楚:

public function create(User $user): bool
{
    return $user->isAdmin();
}

public function update(User $user, SharedEnvironmentVariable $sharedEnvironmentVariable): bool
{
    return $user->isAdminOfTeam($sharedEnvironmentVariable->team_id);
}

而 view 只需要 $user->teams 里包含该 team。也就是说:普通成员能看到"这个团队有一个叫 MODEL_GATEWAY_KEY 的变量",但看不到值、也改不了。

值这一层由 is_shown_once 二次收口。控制器 SharedEnvironmentVariablesController::removeSensitiveData() 的顺序很关键:

if (request()->attributes->get('can_read_sensitive', false) === true) {
    $env->makeVisible(['value']);
}

if ($env->is_shown_once ?? false) {
    $env->makeHidden(['value']);
}

先按 token 能力决定是否放行,再无条件用锁定状态覆盖。而 can_read_sensitive 本身在 ApiSensitiveData 中间件 里是"双因子"判定:

$hasTokenPermission = $token->can('root') || $token->can('read:sensitive');
$isAdmin = ! is_null($teamId) ? $request->user()->isAdminOfTeam((int) $teamId) : false;
'can_read_sensitive' => $hasTokenPermission && $isAdmin,

token 有 read:sensitive 能力且用户是 team 管理员,才可能读到非锁定值。这把"给 CI 发一个全权限 token"的风险压低了不少。

锁定值在部署路径上仍然是可用的——is_shown_once 只影响展示,不影响注入。但引用它的资源变量会被判定为"需要脱敏":EnvironmentVariable::isLockedForLogs() 先看变量自身是否锁定,再看它的值里是否引用了锁定的共享变量:

return $sharedVariables->contains(fn (SharedEnvironmentVariable $shared): bool => $shared->is_shown_once
    && in_array(['type' => $shared->type, 'key' => $shared->key], $references, true));

配合 logRedactionSecretsFor(),这些值会在部署日志、容器日志、MCP 返回里被替换掉;连"生成的 compose 预览"都会单独做一次显示期脱敏,见 redactLockedValuesInGeneratedCompose()(其中对长度小于 4 的值直接跳过,避免把无关文本替换成 <locked>)。

如果团队里还有 AI Agent 通过 MCP 操作 Coolify,这个设计就更重要了:ListSharedEnvKeys 的 description 直接写死"never values",返回结构里只有 key / is_literal / is_multiline / is_shown_once / comment / type;写入侧 ManageSharedEnv 复用 REST 的校验与权限,并把 delete 标注为 IsDestructive + 需要确认。让 Agent 帮你整理变量名可以,让 Agent 顺手把 Key 读走不行。

五、更彻底的一步:值根本不入库

共享变量解决了"多地复制",但值仍然落在 Coolify 的数据库(加密)与目标主机的 .env(明文)里。如果合规要求是"平台侧不留密钥副本",Coolify 提供了第二条路径:远程密钥源 + {{vault.KEY}} 引用。

RemoteSecretReferences 的注释把设计意图写得很直接:

public const PATTERN = '/{{\s*vault\.([A-Za-z0-9_]+)\s*}}/';

命名空间刻意用 vault 而不是 secret,就是为了和 {{team.KEY}} 这类共享变量在视觉上区分开;同时"references are only resolved inside the deployment job — never in the UI or in realValue",所以值不会进数据库、也不会进界面。

支持的三家实现见 SecretManagerLink::fetchSecrets():Doppler(/v3/configs/config/secrets/download)、Infisical(v4 secrets,404 时回退 v3)、HashiCorp Vault(KV v2 /v1/{mount}/data/{path})。三者都是"按 token + settings 拉一整个配置集",返回 array<string,string>,非字符串值统一 JSON 编码。

关键行为在部署任务里:remote_secrets() 是惰性的、每次部署只拉一次、失败即中止:

$this->application_deployment_queue->addLogEntry("Failed to fetch secrets from {$provider} ({$tokenName}, {$link->sourceSummary()}): {$e->getMessage()}", 'stderr');
throw new DeploymentException("Could not fetch secrets from {$provider}. The deployment was stopped so the application does not start with missing secrets.");

缺 key 同样会失败,而不是留空启动,见 substitute_remote_secrets() 里的 Missing secret keys: ...。这种"fail closed"对网关类凭证是正确的取舍:宁可部署失败,也不要让服务带着空 Key 起来、然后在业务层抛一堆难查的 401。

拉取到的值还要经过格式化才能安全写进 .env。RemoteSecretValueFormatter::dotenv() 优先用单引号(保证字面量、保护 # 与换行),值里含单引号或以反斜杠结尾时改用双引号并转义 \、"、$(用 $$ 阻止插值);写进 compose 文件的值走 composeFile(),只把 $ 变成 $$,因为那里 Compose 不解析引号。

一个容易被忽略的前置条件:SecretManagerLink::fetchSecrets() 第一件事就是校验 token 的 team 归属,不匹配直接抛 The secret manager token does not belong to the team of this resource.;克隆资源时 HasSecretManager::cloneSecretManagerLinkTo() 也只在目标资源属于同一 team 时才复制链接。跨团队"借用"密钥源是不被支持的。

两种方案怎么选,实践中的分界线很清楚:

  • 共享变量:配置类、非机密的公共值,以及"团队内需要可见可协作"的凭证;
  • {{vault.KEY}}:真正不该在平台留副本的密钥,代价是每次部署多一次外部 API 调用,且密钥源不可用会直接挡住发布。

两者可以混用:OPENAI_BASE_URL 用团队共享变量(可读、可改),OPENAI_API_KEY 用 {{vault.OPENAI_API_KEY}}(不可读)。

六、容器内验证:别在面板上确认,进容器确认

改完变量最容易犯的错是"面板上看着对,就以为生效了"。Coolify 的注入发生在部署时,只在面板保存不会重写容器的环境。验证要落到容器里:

# 1. 找到容器(Coolify 的容器名通常带应用 uuid 前缀)
docker ps --format '{{.Names}}\t{{.Image}}' | grep -i <你的应用名或uuid片段>

# 2. 确认变量"存在且非空",但不要把值打到终端历史里
docker exec -it <container> sh -lc \
  'for k in OPENAI_API_KEY OPENAI_BASE_URL; do v=$(printenv "$k"); \
   if [ -n "$v" ]; then echo "$k=<set, ${#v} chars>"; else echo "$k=<EMPTY>"; fi; done'

这里刻意只输出长度而不是值:长度能区分"完全没注入"和"注入了一个被截断的值",又不会把 Key 写进你本地的 shell 历史或 CI 日志。

如果变量里还残留着未解析的引用,长度会暴露它:

docker exec -it <container> sh -lc 'printenv OPENAI_API_KEY | grep -c "{{" || true'

返回非 0 说明容器拿到的是字面量 {{team.MODEL_GATEWAY_KEY}}——解析没发生,问题在引用写法或作用域,而不是 Key 本身。

确认注入正确后再打通链路。容器内往往没有 curl,用镜像里现成的运行时发请求更稳;有 curl 时直接:

docker exec -it <container> sh -lc '
  curl -sS -o /tmp/resp -w "%{http_code}\n" "$OPENAI_BASE_URL/v1/chat/completions" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"model\":\"$MODEL_NAME\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}" &&
  head -c 400 /tmp/resp'

最后确认日志里没有把 Key 打出来。Coolify 侧对部署日志与容器日志都接了脱敏,触发点是 ApplicationDeploymentQueue 里的 logRedactionSecretsFor(..., resolveRemoteSecrets: false);框架层的兜底是 RedactSensitiveData 这个 Monolog processor(自托管实例可通过 logging.redaction_enabled 关闭,云上强制开启)。顺手 grep 一下你自己的应用日志仍然必要——脱敏只覆盖 Coolify 记录的日志,应用自己写到别处的那些不归它管。

七、常见错误对照表

下面每一条都能在源码里找到对应机制,排查时按"现象 → 机理"对齐,比盲改快得多。

现象 源码层面的原因 处理
容器里变量是 {{team.KEY}} 字面量 作用域前缀不在 SHARED_VARIABLE_TYPES 内,或 Key 拼错、该作用域的 owner id 对不上(解析分支) 用 {{ environment.MY_VAR }} 这种带空格写法也支持,但前缀必须是 team/project/environment/server 之一
{{server.KEY}} 在 compose 的 environment: 段没被替换 helper resolveSharedEnvironmentVariables() 只处理 environment/project/team 三种类型,server 分支缺失;而资源变量路径(get_real_environment_variables_with_server())能处理 server 要么把该值放到资源的环境变量里(走 .env),要么改用 {{team.KEY}} 兜底
共享变量"套娃"不生效 解析只做一层替换,不递归 拆平,别让共享变量再引用共享变量
422 This field is not allowed. 创建接口只允许 key/value/is_literal/is_multiline/is_shown_once/comment(ALLOWED_FIELDS),type、team_id、project_id 由路由推导 用对应作用域的 URL 表达归属,不要塞进 body
409 Environment variable already exists 同一作用域同一 owner 下 Key 唯一(keyExistsInScope() 对未提供的外键用 whereNull) 改用 PATCH 更新;不同作用域可以同名,别误以为冲突
401 但 Key 看着没错 值里带了不可见字符,或被当成插值改写;也可能引用了错误的变量名 用上一节的"长度对比"确认容器内实际长度;含 $ 的值务必 is_literal
404 / 路径拼错 base_url 与 /v1 的拼接方式因 SDK 而异,末尾多斜杠会拼出 // 在容器内先 printenv OPENAI_BASE_URL 原样打印,再用同样的字符串拼 curl
面板改了 Key,容器还是旧值 环境在容器启动时注入,保存不触发重建 重新部署;确认 .env 被重写(save_runtime_environment_variables() 在部署流程里被多次调用)
界面里看不到值,以为是空的 变量被标记为 is_shown_once,或引用了一个锁定的共享变量 这是预期行为;容器内仍能拿到值,用长度验证即可
部署日志出现 Missing secret keys: X (referenced by Y) {{vault.X}} 在密钥源里不存在 补齐密钥源里的 key,或在变量里去掉引用
部署日志出现 no secret manager source is configured 资源没有 SecretManagerLink,但变量里用了 {{vault.*}} 给应用绑定密钥源;is_literal 的变量在没有源时会保留字面量、其余情况 fail closed
The secret manager token does not belong to the team of this resource. token 跨团队使用,或克隆后 team 不一致 在目标团队重建 Integration Token 并重新绑定
密钥源偶发不可用导致发布全挂 remote_secrets() 失败即抛 DeploymentException 这是设计取舍;把密钥源可用性纳入发布依赖,或对非关键环境改用共享变量

收尾:网关的真正成本在"变更",不在"配置"

把模型 Key 收进 Coolify,技术上没什么魔法:四层共享变量提供复用,is_shown_once 提供"可引用不可读回",API 的 read:sensitive 加管理员双因子提供可控的暴露面,{{vault.KEY}} 提供"平台不留副本"的选项,日志侧从 logRedactionSecretsFor() 到 Monolog processor 都在兜底。

真正决定这套方案能不能长期跑下去的,是几个不变式是否被守住:凭证只有一个权威来源;引用必须带显式作用域且不套娃;锁定值不因为图方便被解开;部署失败优先于带空 Key 启动。这几条守住了,换模型、换供应商、加预算就只是改一条团队变量然后重新部署——把一个跨仓库的搜身工作,收窄成一次点击。

登录后查看全文
coolify