Teleport v18.11.6 常用 CLI 命令详解（tctl/tsh）

一、环境信息

本文所有命令与输出均为 Ubuntu 22.04.5 LTS 上的实测记录（2026-10-20），Teleport 为官方最新稳定版 v18.11.6，实验环境为单进程最小集群（cluster 名 teleport-lab，auth + proxy + node 合一，管理员账号 admin）。安装与初始化见本站《Ubuntu 22.04 安装 Teleport 指南》。

信息项	值
组件版本	Teleport v18.11.6
集群名	teleport-lab
代理地址	localhost:3080（multiplex 单端口模式）
管理员	admin（角色 editor,access,auditor，登录用户 root）

三个二进制的版本输出一致（实测）：

teleport version && tctl version && tsh version

Teleport v18.11.6 git:v18.11.6-0-g4a7ae345 go1.26.10
Teleport v18.11.6 git:v18.11.6-0-g4a7ae345 go1.26.10
Teleport v18.11.6 git:v18.11.6-0-g4a7ae345 go1.26.10

二、工具概览

2.1 三个命令的分工

命令	角色	连接对象
`teleport`	服务端守护进程，也提供 start/status/configure 等子命令	本机
`tctl`	管理员 CLI（用户/节点/token/证书/资源管理）	本机 Auth 服务或 --auth-server/--identity 指定的远端
`tsh`	用户端 CLI（登录、SSH、应用/数据库/云访问）	Proxy 服务

2.2 子命令全景

tctl --help 与 tsh --help 的命令清单（实测节选）：

tctl:
  users add / users update / users ls / users rm / users reset
  nodes add / nodes ls
  tokens add / tokens rm / tokens ls / tokens configure-kube
  auth export / auth sign / auth rotate / auth ls / auth crl
  status / top
  requests ls|get|approve|deny|create|rm|review
  apps ls / db ls / kube ls / desktop ls
  lock / bots ls|add|rm|update / workload-identity ...

tsh:
  login / logout / status / version
  ssh / scp / ls / resolve / clusters / sessions ls / join / play
  apps ls|login|logout|config / db ls|login|logout|env|config|connect
  aws / az / gcloud / gsutil
  recordings ls / recordings export
  proxy ssh|db|app|mcp|aws|azure|gcloud|kube
  request ls|show / env / latency ssh

三、前置条件

tctl：默认读本机 /etc/teleport.yaml 直连 Auth 服务（--config 可改路径，也支持 --auth-server + --identity 远程管理）；在禁用 auth_service 的节点上必须改用 identity 文件；
tsh：先用 tsh login 获取证书；本文环境是自签证书，登录需 --insecure（⚠️ 仅限测试环境，生产应配置可信证书）；
本地用户登录需要「密码 + MFA」，v18 强制 MFA 不可关闭（实测确认）。

四、tctl 常用命令详解

4.1 tctl status：查看集群与证书状态

sudo tctl status

实测输出（完整原文）：

Cluster: teleport-lab
Version: 18.11.6
CA pins: sha256:6fb661e11dabe2b853d3778ad01604b5fd5f7e163a9e7358182bbd1048c9b95a

authority     rotation                protocol status algorithm   storage
------------- ----------------------- -------- ------ ----------- --------
host          standby (never rotated) SSH      active Ed25519     software
                                      TLS      active ECDSA P-256 software
windows       standby (never rotated) TLS      active ECDSA P-256 software
user          standby (never rotated) SSH      active Ed25519     software
                                      TLS      active ECDSA P-256 software
db            standby (never rotated) TLS      active RSA 2048    software
db_client     standby (never rotated) TLS      active RSA 2048    software
openssh       standby (never rotated) SSH      active Ed25519     software
jwt           standby (never rotated) JWT      active ECDSA P-256 software
saml_idp      standby (never rotated) TLS      active RSA 2048    software
oidc_idp      standby (never rotated) JWT      active RSA 2048    software
spiffe        standby (never rotated) JWT      active RSA 2048    software
                                      TLS      active ECDSA P-256 software
okta          standby (never rotated) JWT      active ECDSA P-256 software
awsra         standby (never rotated) TLS      active ECDSA P-256 software
bound_keypair standby (never rotated) JWT      active Ed25519     software
app_client    standby (never rotated) TLS      active ECDSA P-256 software

CA pins 的值在节点加入集群（ca_pin 参数）和排障时会用到。

4.2 tctl users：用户管理

创建用户（生成注册邀请链接，浏览器打开完成口令设置与 MFA 绑定）：

sudo tctl users add demo1 --roles=access --logins=root

实测输出：

User "demo1" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:
https://localhost:3080/web/invite/b2f38b5dbc0ec3c74ac9b952042b9ee3

NOTE: Make sure localhost:3080 points at a Teleport proxy which users can access.

要点：链接有效期 1 小时；口令最短 12 位（实测 8 位被拒：password is too short, min length is 12）；--roles 是逗号分隔的角色列表，内置角色有 editor / access / auditor。

列出与删除：

sudo tctl users ls
sudo tctl users rm demo1

实测输出：

User  Roles
----- ---------------------
admin editor,access,auditor

User "demo1" has been deleted

4.3 tctl nodes：节点管理

sudo tctl nodes ls

实测输出：

Host         ID                  Public Address Labels Version
------------ ------------------- -------------- ------ -------
teleport-lab b9047edf-84f2-4b... 127.0.0.1:3022        18.11.6

4.4 tctl tokens：加入 token 管理

查看现有 token（出于安全只显示首尾片段）：

sudo tctl tokens ls

实测输出：

Token                            Type Labels Expiry Time (UTC)
-------------------------------- ---- ------ ---------------------------
************************0fac56c8 Node        20 Oct 26 16:57 UTC (11m2s)

生成节点加入 token：

sudo tctl tokens add --type=node

实测输出：

The invite token: 2ed07d0f90e9bf80c722ac2d7b9dc31d
This token will expire in 30 minutes.

Run this on the new node to join the cluster:

> teleport start \
   --roles=node \
   --token=2ed07d0f90e9bf80c722ac2d7b9dc31d \
   --ca-pin=sha256:6fb661e11dabe2b853d3778ad01604b5fd5f7e163a9e7358182bbd1048c9b95a \
   --auth-server=localhost:3080

Please note:

  - This invitation token will expire in 30 minutes
  - localhost:3080 must be reachable from the new node

输出直接给出新节点要执行的完整命令，token 30 分钟过期；吊销用 tctl tokens rm <token>。

4.5 tctl auth export：导出集群 CA 公钥

sudo tctl auth export --type=host

实测输出：

@cert-authority teleport-lab,*.teleport-lab ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG1tcz7CZUiZ2Awwjdv8AbL3pqSiqsmyEu8pQQNKbLtq type=host

该行可追加到目标机器的 /etc/ssh/.known_hosts（配合 OpenSSH 免代理接入场景）。

4.6 tctl get：读取集群资源

按资源类型列出集群内置角色（节选）：

sudo tctl get roles | grep -E "kind:|  name:" | head -8

实测输出：

kind: role
  name: access-plugin-with-review
kind: role
  name: access-plugin
kind: role
  name: access
    - kind: '*'
      name: '*'

⚠️ 注意 role 与 user 是两种资源：tctl get role/admin（拿用户名当角色名）实测报错：

ERROR: role admin is not found

4.7 其他常用子命令速查

命令	用途
`tctl requests ls/get/approve/deny`	审批 Access Request
`tctl apps ls` / `tctl db ls` / `tctl kube ls`	列出已注册的应用/数据库/K8s 集群
`tctl lock`	紧急封锁某身份/设备的所有会话
`tctl bots ls/add/rm`	机器身份（tbot）管理
`tctl auth rotate`	证书轮换（交互式，或 --type 指定类型）
`tctl top`	诊断信息

五、tsh 常用命令详解

交互流程（实测，自签证书环境加全局 --insecure）：

tsh --insecure login --proxy=localhost:3080 --user=admin

实测交互与输出（先输密码，再输验证器 OTP）：

Enter password for Teleport user admin:
WARNING: You are using insecure connection to Teleport proxy https://localhost:3080
Enter an OTP code from a device:
> Profile URL:        https://localhost:3080
  Logged in as:       admin
  Cluster:            teleport-lab
  Roles:              access, auditor, editor
  Logins:             root
  Kubernetes:         enabled
  Valid until:        2026-10-21 04:45:55 +0000 UTC [valid for 11h59m]
  Extensions:         login-ip, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy

证书有效期 12 小时，到期后重复 tsh login 续期。

5.2 tsh status：查看当前登录状态

tsh status

实测输出：

> Profile URL:        https://localhost:3080
  Logged in as:       admin
  Cluster:            teleport-lab
  Roles:              access, auditor, editor
  Logins:             root
  Kubernetes:         enabled
  Valid until:        2026-10-21 04:45:55 +0000 UTC [valid for 11h59m]
  Extensions:         login-ip, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy

5.3 tsh ls：列出可访问节点

tsh ls

实测输出：

Hostname     Address        Labels
------------ -------------- ------
teleport-lab 127.0.0.1:3022

5.4 tsh ssh：远程执行与交互会话

tsh ssh root@teleport-lab "hostname && uptime"

实测输出：

teleport-lab
 16:46:02 up 1 day, 58 min,  0 users,  load average: 0.91, 0.63, 0.64

不带命令即进入交互 shell；传文件用 tsh scp <本地文件> root@teleport-lab:/tmp/。若节点在 NAT 后只有 tsh proxy ssh 子命令可建本地转发（单端口模式配套）。

5.5 tsh logout：登出

tsh logout

实测输出：

Logged out all users from all proxies.

5.6 会话与审计相关

命令	用途
`tsh sessions ls`	查看正在进行的会话
`tsh join <session-id>`	加入（旁观）他人会话，需角色允许
`tsh recordings ls`	列出已录制的会话
`tsh play <session-id>`	终端回放录制
`tsh latency ssh <host>`	测量到节点的延迟

5.7 应用/数据库/云访问速查

命令	用途
`tsh apps ls` / `tsh apps login <app>`	列出并登录内部应用，取短时效证书
`tsh db ls` / `tsh db login` / `tsh db connect`	数据库访问三步
`tsh aws` / `tsh az` / `tsh gcloud`	云厂商 API 代理访问
`tsh env`	打印设置会话环境的命令
`tsh request ls/show`	查询/展示 Access Request

六、注意事项

证书 12 小时有效：tsh login 输出中的 Valid until 是硬上限，自动化脚本应处理过期重登；
--insecure 只用于测试：生产应为 Proxy 配置可信 TLS（ACME 或自备证书），否则 SSH 主机密钥校验形同虚设；
tctl 默认只在本机可用：远端管理用 tctl --auth-server=<proxy> --identity=<file>，identity 文件由 tctl auth sign 导出，等同管理员凭据，注意保管；
token 与邀请链接都是敏感信息：tctl tokens ls 只回显首尾片段，完整值只在创建时出现一次；
单端口（multiplex）模式：v18 默认把 Web/SSH/隧道复用在 3080，传统 3023/3024 直连方式需在配置切回 separate 模式（见本站《Teleport v18.11.6 配置参数详解》）。

七、常见问题与排障

7.1 用户名当角色名用

tctl get role/admin 实测报 ERROR: role admin is not found。admin 是用户不是角色，角色只有 editor/access/auditor 等内置或自定义角色。

7.2 注册口令过短

tctl users add 生成的邀请链接注册时，口令少于 12 位实测被拒：

password is too short, min length is 12

7.3 邀请链接过期或误关

链接 1 小时有效；过期或丢失后无需重建用户，用 tctl users reset <user> 重新生成注册/重置 token（tctl users rm 会连用户一起删除）。

7.4 登录报证书告警

自签证书环境 tsh login 不加 --insecure 会报 x509 校验失败；这是预期行为，按第六节第 2 条处理。

八、参考链接

官方 CLI 参考索引：https://goteleport.com/docs/reference/cli/
tctl 参考：https://goteleport.com/docs/reference/cli/tctl/
tsh 参考：https://goteleport.com/docs/reference/cli/tsh/
官方自托管快速开始：https://goteleport.com/docs/get-started/deploy-community/
本站安装指南：《Ubuntu 22.04 安装 Teleport 指南》
本站配置详解：《Teleport v18.11.6 配置参数详解》

Teleport v18.11.6 常用 CLI 命令详解（tctl/tsh）

Teleport v18.11.6 常用 CLI 命令详解（tctl/tsh）

一、环境信息

二、工具概览

2.1 三个命令的分工

2.2 子命令全景

三、前置条件

四、tctl 常用命令详解

4.1 tctl status：查看集群与证书状态

4.2 tctl users：用户管理

4.3 tctl nodes：节点管理

4.4 tctl tokens：加入 token 管理

4.5 tctl auth export：导出集群 CA 公钥

4.6 tctl get：读取集群资源

4.7 其他常用子命令速查

五、tsh 常用命令详解

5.1 tsh login：登录并获取证书

5.2 tsh status：查看当前登录状态

5.3 tsh ls：列出可访问节点

5.4 tsh ssh：远程执行与交互会话

5.5 tsh logout：登出

5.6 会话与审计相关

5.7 应用/数据库/云访问速查

六、注意事项

七、常见问题与排障

7.1 用户名当角色名用

7.2 注册口令过短

7.3 邀请链接过期或误关

7.4 登录报证书告警

八、参考链接