本文档的内容是由机器翻译的。请通过反馈微件提交您的反馈。
 

SSH 密钥管理

最后修改日期： 2025年 3月 21日

您可以将私人 SSH 密钥上传到 TeamCity 项目中。 上传的密钥可用于配置 VCS 根目录，以及在 SSH Agent 构建功能中。

受支持的密钥格式

TeamCity 支持 PEM 和 OpenSSH 格式的密钥。 使用不同格式的键需要进行转换。 例如，您可以使用 PuTTY Key Generator将不受支持的 Putty 私钥（*.ppk ）转换为 PEM 格式。 为此，请导航到 转换 | 导出 OpenSSH 密钥 菜单。

将SSH密钥上传至TeamCity服务器

要允许 TeamCity 项目通过 SSH URL 访问远程仓库，您首先需要将您的私钥上传到这些项目。

  1. 在 项目设置 中，单击 SSH 密钥。

  2. 在 SSH 密钥 页面上，单击 上传 SSH 密钥。

    将 SSH 密钥添加到 TeamCity

  3. 在 "上传 SSH 密钥" 对话框中，浏览以查找私钥文件，并为此密钥指定一个名称。

  4. 单击 保存 以保存上传的密钥。

您还可以在创建新项目时上传私钥 from repository URLs。 如果您使用 SSH URL，TeamCity 会将 身份验证 模式切换为“SSH 密钥”，并显示之前上传的私钥列表。 如果您之前未上传所需的密钥，请单击 上传 SSH 密钥 并指向 TeamCity 所需的文件。

在新项目页面上传 SSH key

上传的 SSH 密钥存储在以下目录：

如果从“创建项目”页面上传了密钥，TeamCity 会将其分配给创建项目的父项目。 在这种情况下，上传的密钥将保存到以下目录：

note

保持对 TeamCity 数据目录 的访问安全，因为服务器以未修改 / 未加密的形式在文件系统中存储 SSH 密钥。

生成的 SSH 密钥

如果您使用 GitHub Deploy Keys 或类似的身份验证工作流，则可以让 TeamCity 代替您手动生成 SSH 密钥。 这种方法更为安全（因为生成的密钥不会存储在您的本地机器上）并且速度明显更快。 后者尤其有助于您定期重新生成并轮换 SSH 密钥。

  1. 在 项目设置 中，单击 SSH 密钥。

  2. 单击 生成 SSH 密钥 按钮。

    生成 SSH 密钥

  3. 输入密钥名称，选择密钥类型，然后单击 生成。

  4. 如果您需要为新生成的密钥提供私钥或公钥：

    • 私钥存储在 <TeamCity Data Directory>/config/projects/<parent project>/pluginData/ssh_keys 目录中。

    • 公钥可从主 SSH 密钥 页面访问（单击所需密钥下的 复制公钥 链接）。 将此密钥粘贴到您的版本控制服务中（例如，在 GitHub 中：“Repository settings | Deploy Keys | Add deploy key”）。

  5. 在您的 TeamCity VCS 根目录的 验证设置 中选择生成的密钥。 为了您的便利，TeamCity 中生成的密钥被放置在一个单独的类别中。

    在 VCS 授权设置中选择生成的密钥

配置 VCS 根设置

tip

观看我们的 视频教程 ，了解 如何使用 SSH 密钥从 SSH 仓库检出。

当您的 VCS 根配置为通过 SSH URL（例如， git@github.com:... ）与远程存储库一起工作时，才会使用私有 SSH 密钥。 如果您使用 SSH URL 创建项目并从“创建项目”页面选择/上传私钥，TeamCity 会自动设置所需的设置，您无需修改 配置 VCS 根目录。

否则，如果您希望更新通过 token 或 password 进行验证的项目，使其改为使用 SSH key，您将需要手动更新相应的 配置 VCS 根目录。

  1. 导航到 管理 | <Your_Project> | VCS Roots 并单击所需根目录旁边的 编辑。

  2. 更新 获取 URL 和/或 推送 URL 字段以改用 SSH URL。 例如，将 https://github.com/username/repository_name.git 改为 git@github.com:username/repository_name.git。

  3. 向下滚动到 验证设置 并选择 私钥 选项之一。

    选择一个 SSH 密钥

    • 已上传密钥 — 选择此选项以使用上传到项目的 密钥。

    • 默认私钥 — 选择此选项以使用文件系统中默认位置的密钥，这些位置由常见的 ssh 工具使用：如果文件存在，则使用 <用户_主页>/.ssh/config 中指定的映射，或者使用私钥文件 <用户主目录>/.ssh/id_rsa （如果使用 代理端签出 ，则文件需要同时存在于服务器和代理上）。

    • 自定义私钥 — 支持 仅适用于 服务器端签出。 在 私钥路径 字段中填写服务器机器上私钥文件的绝对路径。 如果密钥已加密，请在相应的字段中指定口令。

  4. 单击页面底部的 测试连接 以检查您当前的值，并单击 Apply 以保存并退出根目录设置。

将 SSH 密钥分发给构建代理

如果您配置了 代理端签出（agent-side checkout） ，服务器就会将 SSH 密钥传递给代理。 在构建过程中，Git 插件从服务器下载密钥到代理，并在 git fetch/clone 完成后删除该密钥。

note

为了安全原因，密钥已从代理中移除。 例如，构建中执行的测试可能会遗留一些恶意代码，这些代码将会访问构建代理的文件系统并获取密钥。 然而，测试无法直接获取键，因为在运行时它已被移除。 这使得盗取密钥变得更加困难，但并非不可能。 因此，该代理也必须是安全的。

为了将密钥从服务器转移到代理，TeamCity 使用 DES 对称加密对其进行加密。 为了更安全的方式，配置一个 HTTPS 连接，使代理和服务器之间建立连接。

除了 VCS 根目录外，上传的 SSH 密钥还可用于 SSH 代理 构建功能。 查看此链接以获取更多信息： SSH Agent。

REST API

TeamCity REST API允许外部应用程序和脚本通过URL访问TeamCity资源。 您可以利用此功能上传 SSH 密钥并自定义 VCS Root 设置。

查看已上传的密钥

GET
/app/rest/projects/<project_locator>/sshKeys

将新的 SSH 密钥上传到项目中

POST
/app/rest/projects/<project_locator>/sshKeys?fileName=<Key_Name>

  • 正文：私钥文件的内容

  • 内容类型头部："text/plain"

生成新密钥

POST
/app/rest/projects/<project_locator>/sshKeys/generated?keyName=NewKey&keyType=RSA

  • keyName — 任何有效的字符串，即您的新密钥名称。

  • keyType — 可为 "RSA" 或 "ED25519"。

设置 VCS 验证设置

  • 将 "认证方法" 切换为 "已上传的密钥"。 请求主体："TEAMCITY_SSH_KEY"。

    PUT
    /app/rest/vcs-roots/<locator>/properties/authMethod

  • 选择一个特定的 SSH 密钥。 请求主体：SSH 密钥名称。

    PUT
    /app/rest/vcs-roots/<locator>/properties/teamcitySshKey

  • 指定密码加密的 SSH 密钥所需的密码。 请求正文：纯密码字符串。

    PUT
    /app/rest/vcs-roots/<locator>/properties/secure:passphrase

删除密钥

DELETE
/app/rest/projects/<project_locator>/sshKeys?fileName=<Key_Name>