Teleport v18.11.6 配置参数详解

一、环境信息

本文基于 Ubuntu 22.04.5 LTS（x86_64）上实测的 Teleport v18.11.6（2026-10-20），配置文件路径 /etc/teleport.yaml，参数说明同时对照官方配置参考（来源：goteleport.com/docs/reference/deployment/config 及 v18 分支文档源码，2026-10-20 查询）。文中实测回显均来自单进程最小部署（auth + proxy + node 合一），安装步骤见本站《Ubuntu 22.04 安装 Teleport 指南》。

信息项	值
Teleport 版本	v18.11.6
配置文件版本	v3
配置文件路径	/etc/teleport.yaml
数据目录	/var/lib/teleport
systemd 单元	teleport.service（ExecStart 含 --config=/etc/teleport.yaml）

二、配置体系概览

2.1 配置的生成与加载

配置文件推荐用 teleport configure 生成后手工修改，而不是从零手写。实测生成命令与输出：

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!

生成的最小配置（实测全文）：

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: {}

要点：

配置文件第一行 version: v3 是配置格式版本，v18 仍使用 v3；
生成的配置按服务段组织：teleport（全局）、auth_service、proxy_service、ssh_service，未启用的服务段可整体删除；
teleport configure 还支持 -o stdout（打印到标准输出）与 -o file（写入默认路径）两种输出方式。

2.2 修改与生效方式

配置在进程启动时加载并解析，修改后需重启生效：

sudo systemctl restart teleport

语法或字段错误会让服务无法启动，排障入口是：

journalctl -u teleport --no-pager | grep -A5 ERROR

2.3 配置的优先级关系

命令行参数（teleport start 的 flag）优先级最高；
/etc/teleport.yaml 配置文件；
各字段内置默认值。

systemd 单元的 ExecStart 为 /usr/local/bin/teleport start --config /etc/teleport.yaml（实测），日常改动只碰配置文件即可。

三、配置参数详解

3.1 teleport 全局段

字段	类型	默认值	说明
nodename	字符串	主机名	节点名，仅限字母数字、点、连字符，最长 256 字符
data_dir	路径	/var/lib/teleport	集群状态与会话录制存储目录
pid_file	路径	无	PID 文件路径（systemd 单元用 --pid-file 指定）
auth_token	字符串/路径	无	加入集群的邀请 token 或 token 文件路径
join_params.method	枚举	token	加入方式：token / ec2 / iam / github / circleci / kubernetes / bound_keypair
join_params.token_name	字符串	无	token 名或 token 文件路径；与 auth_token 二选一
ca_pin	字符串/列表	无	Auth 服务 CA 指纹（sha256:...），agent 加入集群时校验信任
advertise_ip	IP/FQDN	无	多网卡/NAT 环境下节点对外可达地址
auth_server	地址	无	Auth 服务地址（直连模式），如 10.1.0.5:3025
proxy_server	地址	无	代理地址（隧道模式），应用/数据库服务必须走隧道
diag_addr	地址	无	诊断 HTTP 端点（/var/lib/teleport/debug.sock、metrics）
connection_limits.max_connections	整数	1000	单客户端 IP 连接数上限
log.output	枚举	stderr	日志去向：stderr / stdout / syslog / 文件路径
log.severity	枚举	INFO	日志级别：DEBUG / INFO / WARN / ERROR
log.format.output	枚举	text	text / json
cache.enabled	布尔	true	节点本地缓存，关闭后所有请求直连 Auth

3.2 auth_service 段（控制面）

字段	类型	默认值	说明
enabled	布尔	yes	是否启用 Auth 服务
cluster_name	字符串	自动生成	集群名，写入证书后不可直接改名（改配置无效）
listen_addr	地址	0.0.0.0:3025	Auth 监听地址
proxy_listener_mode	枚举	multiplex	代理监听模式：multiplex（单端口复用，v18 默认）或 separate（分端口）
proxy_protocol	枚举	未指定	on/off/未指定，Auth 位于 L4 负载均衡后按需开启
authentication.type	枚举	local	认证类型：local / github（社区版），oidc / saml（企业版）
authentication.second_factors	列表	["otp"]	允许的 MFA 因子：otp / webauthn / sso
authentication.require_session_mfa	布尔/枚举	false	每会话强制 MFA，支持 hardware_key 等取值
authentication.passwordless	布尔	true	是否允许无密码登录（依赖 WebAuthn）
authentication.connector_name	字符串	local	默认认证连接器
storage.type	枚举	sqlite	集群状态后端：sqlite（默认）/ dynamodb / firestore / postgresql
storage.audit_events_uri	列表	file:///var/lib/teleport/log	审计事件存储，支持多个目的地
storage.audit_sessions_uri	URI	无	会话录制存储，支持 s3://、gs://
session_recording_config.mode	枚举	node	录制位置：node / node-sync / proxy / proxy-sync / off
tokens	列表	无	静态 join token，如 `'proxy,node:xxxxx'`（生产建议动态 token）
client_idle_timeout	时长	never	客户端空闲超时
keep_alive_interval	时长	5m	心跳间隔
keep_alive_count_max	整数	3	心跳失败次数上限
license_file	路径	/var/lib/teleport/license.pem	企业版 license 路径（社区版不适用）

⚠️ v18 实测：本地用户 MFA 强制开启，authentication 块写入 second_factor: "off" 会被拒绝启动（实测报错 cannot disable multi-factor authentication，见 5.2 节）。

3.3 proxy_service 段（访问入口）

字段	类型	默认值	说明
enabled	布尔	yes	是否启用代理
web_listen_addr	地址	0.0.0.0:3080	Web UI 与多路复用监听地址
public_addr	地址	无	用户访问代理的对外地址（证书 SAN 与 Web UI 链接都基于它）
ssh_listen_addr	地址	0.0.0.0:3023	separate 模式下 SSH 代理监听
tunnel_listen_addr	地址	0.0.0.0:3024	separate 模式下反向隧道监听
kube_listen_addr	地址	0.0.0.0:3026	Kubernetes 代理监听
mysql_listen_addr	地址	0.0.0.0:3036	MySQL 协议代理监听
ssh_public_addr	地址	无	separate 模式下 SSH 代理对外地址
tunnel_public_addr	地址	无	separate 模式下隧道对外地址
https_keypairs	列表	[]	自备 TLS 证书/私钥对列表
https_keypairs_reload_interval	时长	0s	证书热加载间隔
acme.enabled	布尔	no	ACME 自动签发（Let's Encrypt），需公网可达 443
acme.email	字符串	无	ACME 联系邮箱
trust_x_forwarded_for	布尔	false	位于 HTTP 反向代理后时是否信任 X-Forwarded-For

proxy_listener_mode 取值差异（v18 默认 multiplex，实测生成配置即为该值）：

模式	对外端口	说明
multiplex	仅 3080	Web UI、SSH 代理、反向隧道全部复用 3080，一个端口放行即可
separate	3023/3024/3080	传统分端口模式，老版本兼容场景使用

3.4 ssh_service 段（节点接入）

字段	类型	默认值	说明
enabled	布尔	yes	是否启用 SSH 服务
listen_addr	地址	0.0.0.0:3022	SSH 服务监听地址
public_addr	地址	无	节点对外地址，多节点需各自区分
labels	映射	无	静态标签（如 env: prod），用于 RBAC 按标签授权
commands	列表	无	动态标签：定期执行命令取输出作为标签值
permit_user_env	布尔	false	是否允许用户自定义会话环境变量
port_forwarding	布尔	true	是否允许端口转发（安全收紧时可关闭）
ssh_file_copy	布尔	true	是否允许 scp/sftp 文件传输
pam.enabled	布尔	no	启用 PAM（service_name 默认 sshd）
enhanced_recording.enabled	布尔	false	eBPF 增强录制（命令/磁盘/网络级审计）
disable_create_host_user	布尔	true	是否禁止按角色自动创建主机用户

3.5 默认端口一览（v18 实测）

端口	归属	用途
3080	proxy_service	Web UI + 多路复用（multiplex 模式下 SSH/隧道同端口）
3025	auth_service	Auth 服务
3022	ssh_service	节点 SSH
3023	proxy_service	SSH 代理（separate 模式）
3024	proxy_service	反向隧道（separate 模式）
3026	proxy_service	Kubernetes 代理
3036	proxy_service	MySQL 协议代理

四、关键参数生产配置模板

以下模板汇总生产环境最常调整的字段（值需按实际环境替换；结构均来自官方配置参考与实测配置）：

version: v3
teleport:
  nodename: teleport-lab
  data_dir: /var/lib/teleport
  log:
    output: /var/lib/teleport/teleport.log
    severity: INFO
    format:
      output: text
auth_service:
  enabled: "yes"
  cluster_name: teleport-lab
  listen_addr: 0.0.0.0:3025
  proxy_listener_mode: multiplex
  authentication:
    type: local
    second_factors: ["webauthn", "otp"]
    require_session_mfa: false
  session_recording_config:
    mode: node
proxy_service:
  enabled: "yes"
  web_listen_addr: 0.0.0.0:3080
  public_addr: teleport.example.com:443
  https_keypairs:
    - key_file: /etc/teleport/tls/teleport.key
      cert_file: /etc/teleport/tls/teleport.crt
ssh_service:
  enabled: "yes"
  labels:
    env: prod
    role: app

调整要点：

public_addr 生产环境应指向用户访问的域名（443 端口或经负载均衡），它决定 Web UI 地址与证书校验；
自备证书用 https_keypairs，公网机器可用 acme 块自动签发；
日志从 stderr 改为文件输出后，注意 logrotate；
authentication.second_factors 建议 webauthn 优先、otp 兜底。

五、配置校验与排障

5.1 启动时校验

Teleport 没有独立的"配置校验"子命令，配置在 teleport start 加载时整体校验，错误直接阻断启动。修改配置后的标准验证动作：

sudo systemctl restart teleport && systemctl is-active teleport

返回 active 说明配置合法且服务已加载；失败时服务进入 activating 反复重启，用下面命令定位：

journalctl -u teleport --no-pager | grep ERROR | tail -2

5.2 实测排障案例一：字段写错位置

把 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

修复：v18 中该字段属于 auth_service.authentication 块（结构见 3.2 节）。

5.3 实测排障案例二：关闭 MFA 被拒绝

实测在 authentication 块写入 second_factor: "off" 并重启：

ERROR: failed to get configuration: failed to parse configuration: cannot disable multi-factor authentication

结论：v18 无法通过配置关闭本地用户 MFA，这是产品强制的安全基线。

5.4 实测排障案例三：数据目录非空

在已有集群数据的目录上重新 teleport configure -o file，实测提示：

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.

处理：确认重建则备份后清空 /var/lib/teleport；扩容场景则按节点加入流程走 token，不要重跑 configure。

六、参考链接

官方配置参考：https://goteleport.com/docs/reference/deployment/config/
官方单机部署指引：https://goteleport.com/docs/get-started/deploy-community/
官方代理高可用与端口文档：https://goteleport.com/docs/reference/deployment/proxy/
本站安装指南：《Ubuntu 22.04 安装 Teleport 指南》
本站 CLI 参考：《Teleport v18.11.6 常用 CLI 命令详解（tctl/tsh）》