把模型 Key 收进部署面板:用 Coolify 做统一密钥网关的落地实践
把模型 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 启动。这几条守住了,换模型、换供应商、加预算就只是改一条团队变量然后重新部署——把一个跨仓库的搜身工作,收窄成一次点击。