TeamCity On-Premises 2026.1 Help

身份验证

TeamCity CLI 支持多种身份验证方法。 本页面涵盖了交互式登录、访客访问、用于 CI/CD 的基于令牌的身份验证、多服务器设置，以及 TeamCity 构建内的自动身份验证。

交互式登录

标准身份验证方式为使用 teamcity auth login 命令：

teamcity auth login

这将启动交互式流程：

  1. 请输入 TeamCity 服务器 URL（例如， https://teamcity.example.com）。

  2. CLI 会打开浏览器，直接通过 OAuth PKCE 流程授权访问，无需手动复制令牌。

  3. 如果服务器运行的是 2026.1 之前的 TeamCity 版本，则不支持 PKCE 流程。 在此情况下，CLI 指南你前往 TeamCity 访问令牌 页面，以便手动创建和粘贴令牌

  4. CLI 会验证令牌并安全存储。

通过指定服务器 URL 进行身份验证：

teamcity auth login --server https://teamcity.example.com

跳过基于浏览器的身份验证，手动输入令牌：

teamcity auth login --no-browser

直接传递令牌（例如，从密码管理器）：

teamcity auth login --server https://teamcity.example.com --token <token>

基于浏览器的登录（PKCE）

TeamCity 2026.1 及以上版本的服务器支持简化的授权流程，无需手动发放访问令牌： OAuth 2.0 PKCE 标准（RFC 7636）。 运行 teamcity auth login 命令后，将发生如下操作流程：

  1. CLI 会在您的计算机上启动一个临时本地服务器。

  2. 浏览器会打开 TeamCity 授权页面。

  3. 批准发放新访问令牌后，浏览器会带授权码重定向回 CLI。

  4. CLI 会将授权码换取为访问令牌。

PKCE 令牌有到期日期。 CLI 会跟踪这一点，并在令牌即将过期或已经过期时显示警告：

$ teamcity auth status ✓ Logged in to https://teamcity.example.com User: John Doe (john.doe) · system keyring ! Token expires 2 hours from now (on Mar 25, 2026)

访问令牌登录

如需传统访问令牌流程，请跳过浏览器登录并手动输入令牌：

teamcity auth login --server https://teamcity.example.com --no-browser

CLI 会显示 TeamCity 访问令牌 URL，可选择在浏览器中打开，然后提示在 CLI 中粘贴令牌。

如果已有令牌，请直接传递：

teamcity auth login --server https://teamcity.example.com --token <token>

检查身份验证状态

查看当前身份验证状态：

teamcity auth status

这会显示服务器 URL、服务器版本、已认证用户名和令牌存储方法。

退出登录

移除当前服务器的存储凭据：

teamcity auth logout

访客访问

如果 TeamCity 服务器启用访客访问，则无需令牌即可进行身份验证：

teamcity auth login --guest

通过指定服务器 URL：

teamcity auth login --server https://teamcity.example.com --guest

访客身份验证为只读访问。 它使用 /guestAuth/ API 前缀，无需凭据也不会存储任何凭据。

使用访客访问进行身份验证

通过环境变量进行访客访问

对于 CI/CD 环境中仅需访客访问的情况：

export TEAMCITY_URL="https://teamcity.example.com" export TEAMCITY_GUEST=1

PowerShell：

$env:TEAMCITY_URL = "https://teamcity.example.com" $env:TEAMCITY_GUEST = "1"

CMD：

set TEAMCITY_URL=https://teamcity.example.com set TEAMCITY_GUEST=1

令牌存储

TeamCity CLI 在可用时使用系统密钥环存储访问令牌：

平台

密钥环

macOS

钥匙串

Linux

GNOME Keyring（或兼容的密钥服务）

Windows

凭据管理器

如果系统密钥环不可用，CLI 会将令牌以明文形式存储在配置文件 ~/.config/tc/config.yml 中。 如需强制明文存储（例如，在无头环境中），请使用 --insecure-storage 标志：

teamcity auth login --insecure-storage

环境变量

对于 CI/CD 流水线及脚本环境，请使用环境变量替代交互式登录：

export TEAMCITY_URL="https://teamcity.example.com" export TEAMCITY_TOKEN="your-access-token"

PowerShell：

$env:TEAMCITY_URL = "https://teamcity.example.com" $env:TEAMCITY_TOKEN = "your-access-token"

CMD：

set TEAMCITY_URL=https://teamcity.example.com set TEAMCITY_TOKEN=your-access-token

用于访客访问：

export TEAMCITY_URL="https://teamcity.example.com" export TEAMCITY_GUEST=1

PowerShell：

$env:TEAMCITY_URL = "https://teamcity.example.com" $env:TEAMCITY_GUEST = "1"

CMD：

set TEAMCITY_URL=https://teamcity.example.com set TEAMCITY_GUEST=1

环境变量优先于配置文件和密钥环。 如果设置了 TEAMCITY_URL ，也请为同一 URL 设置 TEAMCITY_TOKEN—— 仅设置 TEAMCITY_URL 会跳过来自 teamcity auth login 的存储凭据。 要使用存储的凭据，请保持 TEAMCITY_URL 未设置。

高级身份验证场景

在 TeamCity 构建中进行身份验证

当 teamCity 在 TeamCity 构建中运行时，会自动使用构建属性文件中的构建级凭据进行身份验证。 无需额外配置。

这样可以在构建步骤中使用 teamCity 命令，无需存储或管理令牌：

# Inside a TeamCity build step — no auth setup needed teamcity run list --job MyProject_Build --limit 5

多个服务器

可与多个 TeamCity 服务器进行身份验证。 每个服务器的凭据会单独存储。

添加服务器

# First server teamcity auth login --server https://teamcity-prod.example.com # Additional server (becomes the new default) teamcity auth login --server https://teamcity-staging.example.com

在服务器之间切换

有多种方法可以指定目标服务器：

环境变量（推荐用于脚本）：

TEAMCITY_URL=https://teamcity-prod.example.com teamcity run list

PowerShell：

$env:TEAMCITY_URL = "https://teamcity-prod.example.com" teamcity run list

CMD：

set TEAMCITY_URL=https://teamcity-prod.example.com teamcity run list

为会话导出：

export TEAMCITY_URL=https://teamcity-prod.example.com teamcity run list # uses teamcity-prod teamcity auth status # shows teamcity-prod

PowerShell：

$env:TEAMCITY_URL = "https://teamcity-prod.example.com" teamcity run list # uses teamcity-prod teamcity auth status # shows teamcity-prod

CMD：

set TEAMCITY_URL=https://teamcity-prod.example.com teamcity run list # uses teamcity-prod teamcity auth status # shows teamcity-prod

重新登录以更改默认设置：

teamcity auth login --server https://teamcity-prod.example.com

从 Kotlin DSL 自动检测服务器

在有 TeamCity 版本化设置的项目中工作时，CLI 可通过 Kotlin DSL pom.xml 自动检测服务器 URL。 会在当前文件夹及其父文件夹中查找 .teamcity/ 或 .tc/ 目录（若设置了 TEAMCITY_DSL_DIR 则使用），并从 DSL 插件仓库 URL 中提取服务器 URL。 检测到的服务器 URL 会在未设置 TEAMCITY_URL 时使用。 该服务器仍需凭据。

凭据优先级

服务器 URL 解析顺序（优先级从高到低）：

  1. TEAMCITY_URL 环境变量

  2. Kotlin DSL 自动检测（TEAMCITY_DSL_DIR、 .teamcity/ 或 .tc/）

  3. 来自 ~/.config/tc/config.yml 的 default_server

身份验证解析顺序（优先级从高到低）：

  1. 访客身份验证（TEAMCITY_GUEST 或配置有访客访问的服务器）

  2. TEAMCITY_TOKEN 环境变量

  3. 已解析服务器 URL 的存储令牌（优先使用系统密钥环，如使用 --insecure-storage 则为明文配置）

  4. 在 TeamCity 构建中运行时的构建级凭据

2026年 8月 6日
入门指南配置