Skip to content

凭据与 API Token ​

Git 凭据类型 ​

凭据用于项目的 Git 准备阶段(clone/fetch 私有仓库),只有两种类型:

类型内容适用仓库地址
https_token用户名 + 访问令牌(如 GitHub PAT、Gitee 私人令牌)HTTPS URL
ssh_keySSH 私钥全文(可附带用户名,通常为 git)SSH URL

创建凭据时 secret(令牌或私钥)不能为空;编辑时留空表示「不修改」。 凭据分归属:

  • 普通用户创建的凭据归自己,只有自己和 admin 能使用/修改/删除;
  • admin 可勾选「全局」(global=true,落库 user_id=0),所有用户可见可用, 但只有 admin 能修改删除;
  • 被项目引用的凭据禁止删除,需先解除引用,避免下次部署才暴雷。

加密存储 ​

凭据内容(含 SSH key 的 passphrase 字段)用 secret.key 做 AES-GCM 加密后落库,接口永远不回明文。项目的 Secret 环境变量、中间件密码参数 走同一套加密(internal/secret.Box)。因此:

  • data/secret.key 丢失 = 所有密文不可恢复,备份要求见 02;
  • 数据库文件泄露不等于凭据泄露,但密钥与数据库不要放在同一份备份的 同一个访问域里,见安全加固。

连接测试 ​

配置完凭据后先「测试连接」:服务端真的对目标仓库执行一次 git ls-remote (30 秒超时),返回成功与否及最多 20 条示例 ref。这一步能提前暴露 地址错误、令牌过期、权限不足,不必等到部署时才发现。

bash
curl -s -X POST http://127.0.0.1:10055/api/v1/credentials/test-git \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"gitUrl":"git@github.com:example/repo.git","credentialId":1}'

服务器 SSH 公钥 ​

「设置 → 凭据管理」页还提供服务器级 SSH 公钥的查看与生成。注意它操作的是 部署进程所属 OS 用户的 ~/.ssh(管理员在服务器上手工 git clone 用的密钥), 与数据库里的 Git 凭据是两回事:

  • 查看:登录用户即可,扫描 ~/.ssh/id_{ed25519,rsa,ecdsa}.pub,返回公钥与 指纹;私钥永远不经过接口;
  • 生成:仅 admin,支持 ed25519(默认)与 rsa(4096 位),无口令, 注释为 deploy@<hostname>;~/.ssh 权限自动校正为 0700;
  • 同类型密钥已存在时拒绝覆盖,需先在服务器上删除旧钥。

生成后把公钥添加到 Git 托管平台的部署密钥/账号 SSH keys,即可让服务器 直接拉取仓库。

带口令的 SSH key 不支持 ​

凭据表单虽有 passphrase 字段(同样加密存储),但执行引擎在 Git 准备阶段 检测到非空口令会直接报错:

text
SSH keys with a passphrase are not supported yet; use an https_token
credential or generate a key without a passphrase

请改用无口令的专用部署密钥,或改用 https_token 凭据。

凭据如何注入 Git(不进 URL) ​

凭据绝不拼进 Git URL(URL 会出现在日志、进程列表与 .git/config 里):

  • HTTPS:生成临时 GIT_ASKPASS 脚本应答用户名/令牌;
  • SSH:私钥写成临时文件(0600),通过 GIT_SSH_COMMAND 指定, 附 IdentitiesOnly=yes、StrictHostKeyChecking=no 与临时 known_hosts, 运行结束即清理。

个人 API Token(dk_) ​

适合 CLI 与自动化,替代会过期的登录 JWT:

  • 创建:POST /api/v1/tokens,参数 name(必填,≤64 字符)与 expiresInDays(可选,>0 才设过期,缺省永不过期);
  • 格式:dk_ + 32 位随机串;明文只在创建响应里出现这一次,立即保存;
  • 存储:落库的是 SHA-256 哈希与前 8 位前缀(用于展示识别),不存明文;
  • 撤销:DELETE /api/v1/tokens/{id},立即失效;只能管理自己的令牌;
  • 使用:与 JWT 同一个 Authorization 头,服务端按 dk_ 前缀自动分流;
  • 每次使用异步记录最后使用时间;账号被禁用时令牌同样失效。
bash
curl -s -X POST http://127.0.0.1:10055/api/v1/tokens \
  -H 'Authorization: Bearer <jwt>' -H 'Content-Type: application/json' \
  -d '{"name":"ci-runner","expiresInDays":90}'
# data.token 形如 dk_xxxxxxxx...(占位示例,请立即保存)

CLI 侧配置见 CLI 服务器管理。

登录 JWT 与有效期 ​

登录/bootstrap 签发的 JWT 用 HS256 + jwt.key 签名,有效期 tokenTtlHours(默认 168 小时 = 7 天,改后需重启)。请求头 Authorization 同时接受裸 token 与 Bearer <token> 两种写法。 过期后重新登录,或换用 API Token。详见认证与通用约定。

项目级 Secret 变量的使用见环境变量与 Secret。