主题
凭据与 API Token
Git 凭据类型
凭据用于项目的 Git 准备阶段(clone/fetch 私有仓库),只有两种类型:
| 类型 | 内容 | 适用仓库地址 |
|---|---|---|
https_token | 用户名 + 访问令牌(如 GitHub PAT、Gitee 私人令牌) | HTTPS URL |
ssh_key | SSH 私钥全文(可附带用户名,通常为 git) | SSH URL |
创建凭据时 secret(令牌或私钥)不能为空;编辑时留空表示「不修改」。 凭据分归属:
- 普通用户创建的凭据归自己,只有自己和 admin 能使用/修改/删除;
- admin 可勾选「全局」(
global=true,落库user_id=0),所有用户可见可用, 但只有 admin 能修改删除; - 被项目引用的凭据禁止删除,需先解除引用,避免下次部署才暴雷。
加密存储
凭据内容(含 SSH key 的 passphrase 字段)用 secret.key 做 AES-GCM 加密后落库,接口永远不回明文。项目的 Secret 环境变量、中间件密码参数 走同一套加密(internal/secret.Box)。因此:
连接测试
配置完凭据后先「测试连接」:服务端真的对目标仓库执行一次 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。