Ubuntu 22.04 安装 Teleport 指南
在 Ubuntu 22.04 上安装 Teleport v18.11.6 的完整实录：一键脚本、官方 apt 软件源、tar.gz 离线包三种方案，含 systemd 托管、升级降级、卸载与六类排障，输出均为实测回显。
Ubuntu 22.04 安装 Teleport 指南
一、环境信息
本文所有命令与输出均来自 Ubuntu 22.04.5 LTS 服务器的实测记录，实测日期 2026-10-20，Teleport 版本为当时官方最新稳定版 v18.11.6。
| 信息项 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS（jammy） |
| 内核架构 | x86_64 |
| Teleport 版本 | v18.11.6（官方 apt 源 stable/v18 通道） |
| 发行形态 | 官方软件源 deb 包 / 一键脚本 / tar.gz 离线包 |
| 安装目录 | /usr/local/bin（软链）→ /opt/teleport/system/bin/ |
| 配置文件 | /etc/teleport.yaml |
| 数据目录 | /var/lib/teleport |
| systemd 单元 | /lib/systemd/system/teleport.service |
安装验证方式：安装后执行 teleport version 查看版本、systemctl status teleport 确认服务状态、tctl status 确认集群控制面就绪。
二、版本选型与对照表
2.1 官方版本通道
Teleport 官方软件源按大版本划分通道，安装时应明确指定通道，避免跨大版本意外升级：
| 通道 | 适用场景 | 当前版本（2026-10-20 实测） |
|---|---|---|
| stable/v18 | 最新稳定线 | 18.11.6 |
| stable/v17 | 上一稳定维护线 | 17.7.x |
| alpha/dev | 测试通道 | 不建议生产使用 |
注意：Teleport 的补丁版本只推送官方软件源与 CDN，GitHub Releases 页面通常滞后于软件源（实测时软件源已是 18.11.6，而 Releases 页最近一条为 v18.11.1），确认最新版本应以软件源索引为准。
2.2 软件源可用版本（实测）
配置好软件源后用 apt-cache madison teleport 查看通道内全部可用版本（节选）：
teleport | 18.11.6 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.11.5 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.11.4 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.11.3 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.11.2 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.11.1 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.11.0 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.10.7 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.10.6 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.10.4 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.10.3 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.10.1 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.10.0 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
teleport | 18.9.2 | https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 Packages
Ubuntu 22.04 对应的软件源发行版代号为 jammy。
三、安装前准备
3.1 系统要求
- Ubuntu 22.04（x86_64 或 arm64），root 或 sudo 权限；
- 已安装 curl（一键脚本与导入 GPG 公钥都依赖它）：
sudo apt-get update && sudo apt-get install -y curl； - 服务器时间保持同步（证书类组件对时间敏感，NTP 可用即可）。
3.2 端口规划
单进程模式（Auth + Proxy + SSH 合一）默认端口：
| 端口 | 用途 | 是否需要对内网开放 |
|---|---|---|
| 3080 | Web 控制台 + SSH/隧道多路复用（v18 默认 multiplex 模式） | 对用户开放 |
| 3025 | Auth 服务 | 仅集群内部 |
v18 的 Proxy 默认采用 proxy_listener_mode: multiplex，SSH 代理与反向隧道都复用 3080 端口，只需对外放行这一个端口；如需回到传统分端口模式，可在配置文件中将该字段改为 separate（配置详解见本站《Teleport v18.11.6 配置参数详解》）。
四、安装方案
4.1 方案一：官方一键脚本（快速体验）
官方一键脚本会自动判断系统发行版并完成软件源配置与安装，参数依次为目标版本与发行版标识（社区版为 oss，版本号不带 v 前缀）：
curl -fsSL https://cdn.teleport.dev/install.sh -o install.sh
sudo bash install.sh 18.11.6 oss
实测输出（开头，脚本先自校验再下载真实安装器）：
Downloading https://cdn.teleport.dev/install-v18.11.6.sh
+ curl -fL -o /tmp/teleport-qcLgMAE8QR/install-v18.11.6.sh https://cdn.teleport.dev/install-v18.11.6.sh
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 12336 100 12336 0 0 15558 0 --:--:-- --:--:-- --:--:-- 15575
+ set +x
实测输出（中间阶段，脚本校验安装器后走 apt 软件源安装）：
install-v18.11.6.sh: OK
Installing Teleport v18.11.6 via apt-get
Downloading Teleport's PGP public key...
Downloading https://apt.releases.teleport.dev/gpg
实测输出（结尾）：
sha256sum: 3a7bbcdb1fbbff9372b6c7dc858d36e2c43a3ccafcdfab4fe224e77bbbbf3477
Teleport v18.11.6 git:v18.11.6-0-g4a7ae345 go1.26.10 installed successfully!
The following commands are now available:
teleport - The daemon that runs the Auth Service, Proxy Service, and other Teleport services.
tsh - A tool that lets end users interact with Teleport.
tctl - An administrative tool that can configure the Teleport Auth Service.
tbot - Teleport Machine ID client.
fdpass-teleport - Teleport Machine ID client.
teleport-update - Teleport auto-update agent.
⚠️ 实测踩坑：版本参数写成 v18.11.6 会报错退出——脚本内部对版本号做数值比较，v18 会被当作未定义变量：
/tmp/inst.sh: line 41: v18: unbound variable
4.2 方案二：官方 apt 软件源（生产推荐）
手动配置软件源便于后续统一升级与版本锁定，推荐生产使用。
第 1 步：导入官方 GPG 公钥并写入软件源（Ubuntu 22.04 的发行版代号为 jammy，通道按需选 stable/v18 或 stable/v17）：
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://apt.releases.teleport.dev/gpg -o /etc/apt/keyrings/teleport-archive-keyring.asc
echo "deb [signed-by=/etc/apt/keyrings/teleport-archive-keyring.asc] https://apt.releases.teleport.dev/ubuntu jammy stable/v18" | \
sudo tee /etc/apt/sources.list.d/teleport.list
第 2 步：更新索引并安装：
sudo apt-get update
sudo apt-get install -y teleport
实测输出：
deb [signed-by=/etc/apt/keyrings/teleport-archive-keyring.asc] https://apt.releases.teleport.dev/ubuntu jammy stable/v18
Hit:3 https://apt.releases.teleport.dev/ubuntu jammy InRelease
Hit:4 http://archive.ubuntu.com/ubuntu jammy-updates InRelease
Hit:5 http://archive.ubuntu.com/ubuntu jammy-backports InRelease
Reading package lists...
The following NEW packages will be installed:
teleport
Need to get 225 MB of archives.
Get:1 https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 teleport amd64 18.11.6 [225 MB]
Selecting previously unselected package teleport.
Preparing to unpack .../teleport_18.11.6_amd64.deb ...
Unpacking teleport (18.11.6) ...
Setting up teleport (18.11.6) ...
第 3 步：验证版本：
teleport version
实测输出：
Teleport v18.11.6 git:v18.11.6-0-g4a7ae345 go1.26.10
v18 的 deb 包将真实二进制安装在 /opt/teleport/system/bin/，并在 /usr/local/bin/ 建立由 teleport-update 管理的软链，实测软链关系：
lrwxrwxrwx 1 root root 29 Oct 20 16:10 /usr/local/bin/tctl -> /opt/teleport/system/bin/tctl
lrwxrwxrwx 1 root root 33 Oct 20 16:10 /usr/local/bin/teleport -> /opt/teleport/system/bin/teleport
lrwxrwxrwx 1 root root 28 Oct 20 16:10 /usr/local/bin/tsh -> /opt/teleport/system/bin/tsh
4.3 方案三：tar.gz 二进制离线安装
内网或无软件源环境使用官方离线包，从 cdn.teleport.dev 下载对应平台 tar 包与官方校验文件：
curl -fsSLO https://cdn.teleport.dev/teleport-v18.11.6-linux-amd64-bin.tar.gz
curl -fsSLO https://cdn.teleport.dev/teleport-v18.11.6-linux-amd64-bin.tar.gz.sha256
校验完整性（官方 sha256 与本地实算一致，2026-10-20 实测）：
cat teleport-v18.11.6-linux-amd64-bin.tar.gz.sha256
sha256sum teleport-v18.11.6-linux-amd64-bin.tar.gz
实测输出（两行值一致）：
5b67f191c67a53e227356db42b6e31a42f0d752671dc4057597911de74e61002 teleport-v18.11.6-linux-amd64-bin.tar.gz
5b67f191c67a53e227356db42b6e31a42f0d752671dc4057597911de74e61002 teleport-v18.11.6-linux-amd64-bin.tar.gz
解包并执行内置安装脚本：
tar -xzf teleport-v18.11.6-linux-amd64-bin.tar.gz
cd teleport
sudo ./install
实测输出：
Starting Teleport installation...
Teleport binaries have been copied to /usr/local/bin
Thanks for installing Teleport.
tar 包解开后包含以下内容（实测 ls）：
CHANGELOG.md LICENSE-community README.md VERSION
examples fdpass-teleport install install-selinux.sh
tbot tctl teleport teleport-update tsh
⚠️ 离线安装把二进制直接复制到 /usr/local/bin/，不要与方案一/方案二在同一台机器混用：实测在已有 tar 安装的环境再执行一键脚本，deb 包安装阶段因 /usr/local/bin/fdpass-teleport 已存在而报错中断：
User Message: failed to link system package installation
error evaluating link for fdpass-teleport
refusing to replace file at /usr/local/bin/fdpass-teleport
file present] teleport-update/main.go:296
dpkg: error processing package teleport (--configure):
installed teleport package post-installation script subprocess returned error exit status 1
4.4 安装方式对比与选择
| 方案 | 适用场景 | 升级方式 |
|---|---|---|
| 一键脚本 | 快速体验、单机演示 | 重跑脚本换版本号 |
| apt 软件源 | 生产、多机统一管理 | apt-get upgrade，可锁定版本 |
| tar.gz 离线包 | 内网无源、定制路径 | 重新解包覆盖 |
同一台机器只能保留一种安装方式；切换方式前先彻底卸载（见第七节）。
五、基础配置与启动
5.1 生成最小配置
teleport configure 生成单进程最小配置（Auth + Proxy + SSH 合一，社区版自签证书）：
sudo teleport configure -o file --cluster-name=teleport-lab --public-addr=localhost:3080
实测输出：
A Teleport configuration file has been created at "/etc/teleport.yaml".
To start Teleport with this configuration file, run:
teleport start --config="/etc/teleport.yaml"
Happy Teleporting!
生成的 /etc/teleport.yaml（实测全文，字段逐一解析见本站《Teleport v18.11.6 配置参数详解》）：
version: v3
teleport:
nodename: teleport-lab
data_dir: /var/lib/teleport
join_params:
token_name: ""
method: token
log:
output: stderr
severity: INFO
format:
output: text
ca_pin: ""
diag_addr: ""
auth_service:
enabled: "yes"
listen_addr: 0.0.0.0:3025
cluster_name: teleport-lab
proxy_listener_mode: multiplex
ssh_service:
enabled: "yes"
proxy_service:
enabled: "yes"
web_listen_addr: 0.0.0.0:3080
public_addr: localhost:3080
https_keypairs: []
https_keypairs_reload_interval: 0s
acme: {}
⚠️ 如果 /var/lib/teleport 已有历史集群数据，configure 会拒绝生成，实测提示：
WARNING: The data directory /var/lib/teleport is not empty and may contain existing cluster state. Running this configuration is likely a mistake. To join a new cluster, specify an alternate --data-dir or clear the /var/lib/teleport directory.
5.2 systemd 托管启动
sudo systemctl enable teleport
sudo systemctl start teleport
实测输出：
Created symlink /etc/systemd/system/multi-user.target.wants/teleport.service → /lib/systemd/system/teleport.service.
systemctl status teleport 实测：
● teleport.service - Teleport Service
Loaded: loaded (/lib/systemd/system/teleport.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2026-10-20 16:38:21 UTC; 4s ago
Main PID: 6351 (teleport)
Tasks: 18 (limit: 94371)
Memory: 54.8M
CPU: 339ms
CGroup: /system.slice/teleport.service
单元文件内容（systemctl cat teleport 实测）：
# /lib/systemd/system/teleport.service
[Unit]
Description=Teleport Service
After=network.target
[Service]
Type=simple
Restart=always
RestartSec=5
EnvironmentFile=-/etc/default/teleport
ExecStart=/usr/local/bin/teleport start --config /etc/teleport.yaml --pid-file=/run/teleport.pid
# systemd before 239 needs an absolute path
ExecReload=/bin/sh -c "exec pkill -HUP -L -F /run/teleport.pid"
PIDFile=/run/teleport.pid
LimitNOFILE=524288
[Install]
WantedBy=multi-user.target
环境参数可通过 /etc/default/teleport 注入（如 HTTP_PROXY），单元用 EnvironmentFile=- 引用，文件不存在也不报错。
5.3 验证安装
sudo tctl status
实测输出（控制面就绪，CA 轮换状态正常）：
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
浏览器访问 https://<服务器IP>:3080 可打开 Web 控制台（自签证书会有告警，选择继续访问即可）。
六、升级/降级与多版本管理
6.1 通道内升级
sudo apt-get update && sudo apt-get install -y teleport
实测输出（18.11.5 → 18.11.6）：
Get:1 https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 teleport amd64 18.11.6 [225 MB]
Preparing to unpack .../teleport_18.11.6_amd64.deb ...
Unpacking teleport (18.11.6) over (18.11.5) ...
Setting up teleport (18.11.6) ...
Teleport v18.11.6 git:v18.11.6-0-g4a7ae345 go1.26.10
active
⚠️ 实测确认：apt 升级不会自动重启正在运行的服务，磁盘上的二进制已是新版本、内存中仍是旧进程。升级后必须手动重启：
sudo systemctl restart teleport
6.2 定点降级
通道内的历史版本可用 --allow-downgrades 回装：
sudo apt-get install -y --allow-downgrades teleport=18.11.5
teleport version
实测输出：
Get:1 https://apt.releases.teleport.dev/ubuntu jammy/stable/v18 amd64 teleport amd64 18.11.5 [225 MB]
Preparing to unpack .../teleport_18.11.5_amd64.deb ...
Unpacking teleport (18.11.5) over (18.11.6) ...
Setting up teleport (18.11.5) ...
Teleport v18.11.5 git:v18.11.5-0-g7f99c392 go1.26.8
active
降级前建议备份数据目录：sudo cp -a /var/lib/teleport /var/lib/teleport.bak.$(date +%F)。
6.3 锁定版本
生产环境固定版本，防止随系统升级被动更新：
sudo apt-mark hold teleport
teleport # 状态显示 hold
解除锁定：sudo apt-mark unhold teleport。
七、卸载方式
7.1 apt 安装的卸载
sudo apt-get remove -y teleport # 保留配置与数据
sudo apt-get purge -y teleport # 连配置一起清除
实测输出：
Removing teleport (18.11.6) ...
Removing symlinks from Teleport system paths...
Purging configuration files for teleport (18.11.6) ...
dpkg: warning: while removing teleport, directory '/opt/teleport' not empty so not removed
数据目录与残留目录需手动清理：
sudo rm -rf /var/lib/teleport /opt/teleport /etc/apt/sources.list.d/teleport.list
7.2 tar.gz 安装的卸载
直接删除解包安装的二进制与数据：
sudo rm -f /usr/local/bin/teleport /usr/local/bin/tctl /usr/local/bin/tsh \
/usr/local/bin/tbot /usr/local/bin/fdpass-teleport /usr/local/bin/teleport-update
sudo rm -rf /var/lib/teleport /etc/teleport.yaml
八、常见问题与排障
8.1 软件源 404：$CODENAME 变量为空
写软件源时若沿用 $CODENAME 变量（部分旧教程写法），Ubuntu 的 /etc/os-release 中并不存在该变量，源会被写成空的发行代号，apt-get update 报 404：
E: The repository 'https://apt.releases.teleport.dev ubuntu Release' does not have a Release file.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
排查：cat /etc/os-release 可见 Ubuntu 只提供 VERSION_CODENAME=jammy，没有 CODENAME。官方文档的写法是用 ${ID}（ubuntu）+ ${VERSION_CODENAME}（jammy）两个变量拼出 https://apt.releases.teleport.dev/ubuntu jammy stable/v18。注意 URI 与发行代号是两个独立字段：.../ubuntu 是软件源地址，jammy 是发行代号，不要合并写成 .../dev/ ubuntu jammy（实测同样 404）。
8.2 服务一直 activating：second_factor 字段写错位置
v18 中 MFA 配置在 auth_service.authentication 块下，若仍按旧文档把 second_factor 直接写在 auth_service: 顶层，服务启动失败并反复重启，journalctl -u teleport 实测报错：
ERROR:
failed to get configuration: failed to parse configuration: validating config:
yaml: unmarshal errors:
line 15: field second_factor not found in type config.Auth
正确写法：
auth_service:
enabled: "yes"
authentication:
type: local
second_factor: "on"
listen_addr: 0.0.0.0:3025
8.3 MFA 无法关闭（v18 强制开启）
实测在 authentication 块写入 second_factor: "off" 并重启，服务直接拒绝启动：
ERROR:
failed to get configuration: failed to parse configuration:
cannot disable multi-factor authentication
v18 本地用户强制 MFA（TOTP/WebAuthn），这是产品硬性行为；纯自动化场景应使用 SSO 登录或 tbot 机器身份，而不是关闭 MFA。
8.4 初始账号口令过短被拒
完成用户注册时口令必须不少于 12 位，实测 8 位口令提交被拒：
password is too short, min length is 12
规划演示口令时按 12 位以上设置。
8.5 一键脚本报 unbound variable
版本参数带 v 前缀（如 v18.11.6）导致脚本数值比较失败，实测报 line 41: v18: unbound variable。去掉前缀：bash install.sh 18.11.6 oss。
8.6 数据目录非空警告
重复执行 teleport configure 或在旧集群数据上生成新配置时，实测提示 /var/lib/teleport 非空并拒绝继续（原文见 5.1 节）。确认要重建集群时先备份再清空该目录。
九、参考链接
- 官方安装文档（Linux）：https://goteleport.com/docs/installation/single-machine/linux/
- 官方自托管快速开始：https://goteleport.com/docs/get-started/deploy-community/
- 官方软件源（apt）：https://apt.releases.teleport.dev/
- 官方二进制下载与校验（CDN）：https://cdn.teleport.dev/
- GitHub 发布页：https://github.com/gravitational/teleport/releases
- 本站配置详解：《Teleport v18.11.6 配置参数详解》
- 本站 CLI 参考：《Teleport v18.11.6 常用 CLI 命令详解（tctl/tsh）》