secrets

Goldsky 密钥管理

为管道 Sink 凭据创建和管理密钥。**使用 goldsky secret update 轮换现有凭据，并保留密钥名称。**不要删除正在使用的密钥来更新凭据；请参阅轮换凭据。

Agent 指南

**安全处理凭据：**通过 --value '...' 内联传入的凭据会写入用户的 shell 历史记录，并且在命令运行期间会显示在进程列表中。请尽可能在 goldsky secret create 中省略 --value，让 CLI 通过交互提示获取连接字符串（敏感信息不会接触 argv 或历史记录）。仅在非交互式脚本中使用内联 --value，并且绝不要将显示出的密钥（goldsky secret reveal）回显到对话中。

调用此技能时，请遵循以下简化工作流：

第 1 步：验证登录并列出现有密钥

运行 goldsky secret list 以确认身份验证并显示现有密钥。

**如果身份验证失败：**请先调用 auth-setup 技能。

第 2 步：快速确定意图

**跳过不必要的问题。**如果上下文已明确用户意图，请直接继续：

• 用户说“创建一个 postgres 密钥”→ 直接收集凭据
• 用户粘贴了连接字符串 → 立即解析（参见连接字符串解析）
• 用户提到了特定提供商（Neon、Supabase 等）→ 使用对应提供商的指南

只有在意图确实不明确时才使用 AskUserQuestion。

第 3 步：解析连接字符串（PostgreSQL 首选）

如果用户提供了连接字符串，请直接解析，不要提问。

PostgreSQL 连接字符串格式：

postgres://USER:PASSWORD@HOST:PORT/DATABASE?sslmode=require
postgresql://USER:PASSWORD@HOST/DATABASE

解析逻辑：

1. 提取：user、password、host、port（默认值为 5432）、databaseName
2. 立即构造 JSON
3. 无需进一步提问即可创建密钥

示例 — 用户提供：

postgresql://neondb_owner:[email protected]/neondb?sslmode=require

直接使用连接字符串创建：

goldsky secret create --name SUGGESTED_NAME
# When prompted, paste the connection string:
# postgresql://neondb_owner:[email protected]/neondb?sslmode=require

第 4 步：提供商专用快速路径

还没有数据库？配置由 Goldsky 托管的 Postgres（Scale 套餐或更高）：

如果用户尚无 Postgres 数据库，Goldsky 可以配置一个托管的 Postgres（Neon）数据库，并一步将其凭据存储为密钥——无需外部数据库账户：

goldsky hosted-sink create --type postgres

• 必须使用 --type postgres；--name（省略时自动生成为 HOSTED_POSTGRES_<RANDOM>）和 --description 为可选项。
• 成功后会打印所创建密钥的名称、ID和类型。系统不会打印连接字符串；可在 Sink 中通过密钥的名称引用 secret_name，也可以稍后运行 goldsky secret reveal <name> 查看连接字符串。
• 需要 Scale 套餐或更高。如果没有使用权限，该命令会失败并显示提示升级到 Scale 套餐的信息，以及团队账单页面链接——此时请改用下文所述的外部 Postgres。

Neon：

• 连接字符串格式：postgresql://USER:[email protected]/neondb
• 默认端口：5432
• 常见问题：免费套餐有 512MB 限制——管道会因“超出项目大小限制”而失败

Supabase：

• 连接字符串格式：postgresql://postgres:[email protected]:5432/postgres
• 使用“Project Settings → Database”中的“Connection string”

PlanetScale（MySQL）：

• 使用 "protocol": "mysql"，端口为 3306

第 5 步：直接创建密钥

获取凭据（通过解析或用户输入）后，立即创建：

goldsky secret create \
  --name SECRET_NAME \
  --value '{"type":"jdbc","protocol":"postgres",...}' \
  --description "Optional description"

命名约定：PROJECT_PROVIDER（例如：TRADEWATCH_NEON、ANALYTICS_SUPABASE）

第 6 步：验证

运行 goldsky secret list 确认密钥已创建。

---

Secret 类型

每种 secret 类型都对应一个 type 字段值。有关各字段的完整规范和示例，请参阅文档中的Secret 格式。

Secret 类型	Type 字段	用途
PostgreSQL	jdbc	数据库接收端
MySQL	jdbc	数据库接收端（协议：mysql）
ClickHouse	clickHouse	分析型数据库
Kafka	kafka	事件流
AWS S3	s3	对象存储
Google Pub/Sub	pubsub	GCP Pub/Sub 主题（仅限 Turbo）
ElasticSearch	elasticSearch	搜索引擎
DynamoDB	dynamodb	NoSQL 数据库
SQS	sqs	消息队列
OpenSearch	opensearch	搜索／分析
Webhook	httpauth	HTTP 端点

快速参考示例

PostgreSQL — 连接字符串格式：

postgres://username:password@host:port/database

goldsky secret create --name MY_POSTGRES_SECRET
# The CLI will prompt for the connection string interactively

ClickHouse — 连接字符串格式：

https://username:password@host:port/database

Kafka — JSON 格式：

{
  "type": "kafka",
  "bootstrapServers": "broker:9092",
  "securityProtocol": "SASL_SSL",
  "saslMechanism": "PLAIN",
  "saslJaasUsername": "user",
  "saslJaasPassword": "pass"
}

S3 — 冒号分隔格式：

access_key_id:secret_access_key

也可以使用会话令牌：access_key_id:secret_access_key:session_token

Google Cloud Pub/Sub — JSON 格式（仅限 Turbo）：

{
  "type": "pubsub",
  "projectId": "goldsky-prod",
  "credentialsJson": "{\"type\":\"service_account\",\"project_id\":\"goldsky-prod\",...}"
}

CLI 会提示输入 GCP 项目 ID，并要求将完整的服务账号 JSON 密钥作为单行文本粘贴；CLI 会验证粘贴内容是否为 type === "service_account" 的 JSON。

**IAM 要求：**服务账号必须拥有 roles/pubsub.publisher 和 roles/pubsub.viewer。接收端在初始化期间会预先检查主题是否存在，因此需要 viewer 角色；仅有发布权限的 SA 会在接收端初始化时因 PermissionDenied 错误而失败。

部署管道前，GCP 项目中必须已存在 Pub/Sub 主题；Goldsky 不会自动创建主题。

Webhook：

注意：Turbo 管道的 webhook 接收端不支持 Goldsky 的原生 secret 管理。请改为在管道 YAML 的 headers: 字段中直接添加身份验证标头。

连接字符串解析器

对于 PostgreSQL，请使用辅助脚本解析连接字符串：

./scripts/parse-connection-string.sh "postgresql://user:pass@host:5432/dbname"
# Output: JSON ready for goldsky secret create --value

步骤 5：确认并创建

向用户展示将要创建的内容（用 *** 遮盖密码），并在运行命令前请求确认。

步骤 6：验证是否成功

运行 goldsky secret list，确认 secret 已创建。

快速参考

操作	命令
创建	goldsky secret create --name NAME --value "value"
列出	goldsky secret list
显示	goldsky secret reveal NAME
更新	goldsky secret update NAME --value "$(cat /secure/path/secret.json)"
删除	goldsky secret delete NAME

前提条件

• 已安装 Goldsky CLI
• 已登录（goldsky login）
• 已准备好目标接收端的连接凭据

为什么需要 Secrets

向外部接收端（PostgreSQL、ClickHouse、Kafka、S3）写入数据的管道需要凭据才能连接。不要将凭据直接写入管道 YAML，而应将其存储为 secret，并通过名称引用。

优点：

• 凭据经过加密并安全存储
• 可共享管道配置而不暴露 secrets
• 无需修改管道即可轮换凭据

命令参考

命令	用途	主要标志
goldsky secret create	创建新密钥	--name、--value、--description
goldsky secret list	列出所有密钥
goldsky secret reveal <name>	显示密钥值
goldsky secret update <name>	更新密钥值	--value、--description
goldsky secret delete <name>	删除密钥	-f（强制执行，跳过确认）

常见用法

PostgreSQL 密钥

goldsky secret create --name PROD_POSTGRES
# When prompted, provide the connection string:
# postgres://admin:[email protected]:5432/mydb

在管道中使用：

sinks:
  output:
    type: postgres
    from: my_source
    schema: public
    table: transfers
    secret_name: PROD_POSTGRES

ClickHouse 密钥

goldsky secret create --name CLICKHOUSE_ANALYTICS
# When prompted, provide the connection string:
# https://default:[email protected]:8443/analytics

在管道中使用：

sinks:
  output:
    type: clickhouse
    from: my_source
    table: events
    secret_name: CLICKHOUSE_ANALYTICS
    primary_key: id

轮换凭证

就地更新现有密钥，同时保留其名称和管道引用。update --value 要求提供完整的密钥 JSON 对象，包括其 type；它不接受原始连接字符串，也不会提示输入值。若只需更新元数据，请在不使用 --value 的情况下使用 --description。

将 JSON 准备在只有文件所有者可读的本地文件中（例如，权限为 600 的 /secure/path/secret.json），并使用相应的密钥格式。对于 PostgreSQL，请使用 JDBC 字段 type、protocol、host、port、databaseName、user 和 password。

goldsky secret update MY_POSTGRES_SECRET --value "$(cat /secure/path/secret.json)"

这样可以避免值出现在 shell 历史记录中，但 CLI 仍会通过 argv 接收该值，因此它可能会显示在进程列表中。请保持 shell 跟踪处于禁用状态，绝不要打印文件内容或展开后的命令。使用后请删除临时凭证文件。轮换后请验证管道连接；不要假设密钥更新成功就意味着正在运行的管道已重新加载凭证。

删除未使用的密钥

# With confirmation prompt
goldsky secret delete OLD_SECRET

# Skip confirmation (for scripts)
goldsky secret delete OLD_SECRET -f

警告： 删除正在使用的密钥会导致管道故障。

密钥命名约定

使用描述性的大写名称，并以下划线分隔：

好的示例	不好的示例
PROD_POSTGRES_MAIN	secret1
STAGING_CLICKHOUSE	my-secret
KAFKA_PROD_CLUSTER	postgres

在名称中包含环境和用途，以便于识别。

故障排除

错误：未找到密钥

Error: Secret 'MY_SECRET' not found

原因： 密钥名称不存在或拼写错误。
解决方法： 运行 goldsky secret list 查看可用密钥，并检查名称是否完全正确。

错误：密钥已存在

Error: Secret 'MY_SECRET' already exists

原因： 尝试创建的密钥名称已被使用。
解决方法： 按照轮换凭证中的说明更新现有密钥，或者为单独的密钥选择其他名称。

错误：密钥值格式无效

Error: Invalid JSON in secret value

原因： 密钥值中的 JSON 语法错误。
解决方法： 创建密钥前验证 JSON：

# Test JSON validity
echo '{"url":"...","user":"..."}' | jq .

管道失败，提示“connection refused”

原因： 密钥中的凭证不正确，或者数据库无法访问。
解决方法：

1. 在 Goldsky 之外验证凭证是否可用：psql "postgresql://..."
2. 检查密钥值：goldsky secret reveal MY_SECRET
3. 确保数据库允许来自 Goldsky IP 地址段的连接

管道失败，提示“authentication failed”

原因： 密钥中的用户名或密码不正确。
解决方法： 按照轮换凭证中的说明，使用正确的凭证更新现有密钥。

密钥值包含特殊字符

原因： 包含特殊字符的 JSON 字符串需要正确转义。
解决方法： 对密码字段中的特殊字符进行正确的 JSON 转义：

• 反斜杠：使用 \\
• 双引号：使用 \"
• 换行符：使用 \n

使用结构化 JSON 格式时，密码中的大多数特殊字符都无需进行 URL 编码，因为密码是单独的字段。

相关

• /turbo-builder — 构建和部署使用这些密钥的流水线
• /auth-setup — 如果用户尚未登录，则调用此项
• /turbo-pipelines — 流水线 YAML 配置参考