企业官网建设流程全解析

• 网络安全
• 认证鉴权
• 运维
• 后端

导读

本文以 Teleport 仓库中的 examples/aws/terraform/starter-cluster 示例为核心，系统讲解如何在 AWS 上基于 Teleport 官方预构建 AMI，用 Terraform 在单个 EC2 实例上快速拉起一个 "all-in-one"（auth、node、proxy 三合一）的 Teleport 集群。读完本文，你将掌握该示例的完整工作原理、全部可调参数、从make apply到创建首个用户并登录 Web 控制台的完整操作流程，以及它背后的源码级实现细节。

适用前提与限制：该示例定位为 demo、概念验证（PoC）与学习用途，切勿直接用于生产环境。它只搭建单节点集群，不包含高可用、多副本与故障转移能力，适合 fork 后按需改造。

一、这个示例解决什么问题

Teleport 官方为 AWS 发布了预配置好的 AMI（同时提供 OSS、Enterprise、Enterprise FIPS 三种镜像族），这些 AMI 内置了 systemd 服务单元与初始化 bash 脚本，只需要在启动实例时以环境变量形式传入配置，即可让实例自动生成/etc/teleport.d/conf配置并拉起一个功能完整的 Teleport 集群。

starter-cluster 正是利用这一特性：它不手写 Teleport 配置文件，而是通过 Terraform 的templatefile渲染 data.tpl，把一堆TELEPORT_*环境变量写进 EC2 实例的user_data，由 AMI 内置的引导脚本（见 assets/aws 下的 systemd units 与 bash 脚本）完成后续的自动配置。正如 data.tpl 所示，最终生成的是形如下面的环境变量文件：

TELEPORT_ROLE=auth,node,proxy EC2_REGION=us-west-2 TELEPORT_AUTH_SERVER_LB=localhost TELEPORT_AUTH_TYPE=local TELEPORT_CLUSTER_NAME=TeleportCluster1 TELEPORT_DOMAIN_ADMIN_EMAIL=support@example.com TELEPORT_DOMAIN_NAME=cluster.example.com TELEPORT_EXTERNAL_HOSTNAME=cluster.example.com TELEPORT_DYNAMO_TABLE_NAME=TeleportCluster1 TELEPORT_DYNAMO_EVENTS_TABLE_NAME=TeleportCluster1-events TELEPORT_LICENSE_PATH= TELEPORT_LOCKS_TABLE_NAME=TeleportCluster1-locks TELEPORT_PROXY_SERVER_LB=cluster.example.com TELEPORT_S3_BUCKET=teleport.example.com TELEPORT_ENABLE_MONGODB=false TELEPORT_ENABLE_MYSQL=false TELEPORT_ENABLE_POSTGRES=false USE_LETSENCRYPT=true USE_ACM=false USE_TLS_ROUTING=true

这种 "AMI + 环境变量" 的模式大幅降低了部署门槛：你无需关心 Teleport 二进制安装、systemd 单元编写、证书签发细节，只需聚焦于 DNS、存储与网络资源编排。

二、它会创建哪些 AWS 资源

2.1 默认创建的资源

• Teleport all-in-one 集群 EC2 实例：auth、node、proxy三种角色运行在同一台实例上（见 cluster.tf）；
• 3 张 DynamoDB 表（见 dynamo.tf）：
  • <cluster_name>：存放集群状态（cluster state）；
  • <cluster_name>-events：存放审计事件（cluster events）；
  • <cluster_name>-locks：为 SSL 证书生成与续期提供简单分布式锁（ssl lock）；
• 1 个 S3 桶：存储会话录制（session recording），见 s3.tf；
• Route53A记录：将自定义域名指向实例（见 route53.tf）；
• Security Groups 与 IAM 角色：前者控制网络入站规则（cluster_sg.tf），后者授权实例访问 SSM、S3、DynamoDB 等 AWS 资源（cluster_iam.tf）。

2.2 可选创建的资源

通过变量开关（详见下文"参数详解"）还可以额外创建：

• Application Load Balancer（ALB）：在使用 ACM 证书时启用，见 cluster_lb.tf；
• ACM 证书及其 Route53 DNS 校验记录：见 acm.tf。

三、工作原理：从 user_data 到可用的集群

整个启动链路可以拆成三步：

1. Terraform 渲染 user_data：aws_instance.cluster通过templatefile("data.tpl", {...})把变量填充为环境变量脚本（cluster.tf）。
2. AMI 内置引导：Teleport 官方 AMI 里包含一系列 systemd units 与 bash 脚本（位于仓库 assets/aws/files/system 与 assets/aws/files/bin），实例首次启动时会读取/etc/teleport.d/conf，执行teleport-generate-config之类的工具生成最终 Teleport 配置（如teleport.yaml），再启动 auth / node / proxy 进程。从 data.tpl 的注释可以看出，使用 ACM 时 TLS routing 会被teleport-generate-config自动启用。
3. 依赖 AWS 托管服务：集群状态、审计事件与证书锁写入 DynamoDB，会话录制写入 S3，从而让单机实例也具备持久化能力。

因此，从源码结构看，starter-cluster 与 AMI 引导代码的分工是：Terraform 只负责"资源编排 + 参数注入"，Teleport 自身的配置生成完全交给 AMI。这也解释了为什么示例中的变量几乎都能在 vars.tf 与 data.tpl 之间一一对应。

四、环境要求

• Terraform v1.0+：由 data.tf 中的required_version = ">= 1.0, < 2.0.0"约束，同时要求hashicorp/awsprovider~> 5.0；
• AWS CLI v1.14+：用于aws ec2 describe-images查询 AMI、校验凭据等；
• 一个已注册的 Route53 托管区（root zone，例如example.com）；
• 目标区域存在可用的 EC2 Key Pair（AWS 控制台 > EC2 > Key Pairs），用于 SSH 登录实例。

此外，data.tf 还会通过 data source 自动获取当前账号的默认 VPC、默认 VPC 下全部子网、AMI 镜像（按var.ami_name过滤、取最新、owner 为146628656107，即 Teleport 官方 AMI 发布账号）与 Route53 zone 信息，无需手工填写这些 ID。

五、快速开始：三步走

仓库根目录的 Makefile 封装了全部常用命令：

完整步骤：

1. 按下一节说明配置好所有变量后，运行make apply；
2. SSH 登录新实例：ssh ec2-user@<cluster_domain>；
3. 在实例上创建用户（该命令同时会创建 Teleport 用户，并允许其以本地ec2-user身份登录节点）：
   • OSS 版：

     sudo tctl users add <username> --roles=access,editor --logins=ec2-user

   • Enterprise 版：

     tctl users add --roles=access,editor <username> --logins=ec2-user

4. 点击make apply输出中的注册链接（即 outputs.tf 中的cluster_web_address），设置密码并配置 2FA token；
5. 完成！此时你已经拥有一个功能完整的 Teleport 集群，可通过tsh login --proxy=<cluster_domain>或 Web 控制台接入。

六、参数详解：完整变量清单

示例通过TF_VAR_*环境变量（或直接写在 Makefile 中）向 Terraform 传参。以下清单完整覆盖 README 与 vars.tf 中的全部变量，可直接复制使用：

# Region to run in - we currently have AMIs in the following regions: # ap-northeast-1, ap-northeast-2, ap-northeast-3, ap-south-1, ap-southeast-1, ap-southeast-2, ca-central-1, eu-central-1 # eu-north-1, eu-west-1, eu-west-2, eu-west-3, sa-east-1, us-east-1, us-east-2, us-west-1, us-west-2 TF_VAR_region ?= "us-west-2" # Cluster name is a unique cluster name to use, should be unique and not contain spaces or other special characters TF_VAR_cluster_name ?= "TeleportCluster1" # AWS SSH key pair name to provision in installed instances, must be a key pair available in the above defined region (AWS Console > EC2 > Key Pairs) TF_VAR_key_name ?= "example" # Full absolute path to the license file, on the machine executing Terraform, for Teleport Enterprise. # This license will be copied into AWS SSM and then pulled down on the auth nodes to enable Enterprise functionality TF_VAR_license_path ?= "/path/to/license" # AMI name contains the version of Teleport to install, and whether to use OSS or Enterprise version # These AMIs are published by Teleport and shared as public whenever a new version of Teleport is released # To list available AMIs: # OSS: aws ec2 describe-images --owners 146628656107 --filters 'Name=name,Values=teleport-oss-*' # Enterprise: aws ec2 describe-images --owners 146628656107 --filters 'Name=name,Values=teleport-ent-*' # FIPS images are also available for Enterprise customers, look for '-fips' on the end of the AMI's name TF_VAR_ami_name ?= "teleport-ent-18.10.0-arm64" # Route 53 hosted zone to use, must be a root zone registered in AWS, e.g. example.com TF_VAR_route53_zone ?= "example.com" # Subdomain to set up in the zone above, e.g. cluster.example.com # This will be used for users connecting to Teleport proxy TF_VAR_route53_domain ?= "cluster.example.com" # Set to true to add a wildcard subdomain entry to point to the proxy, e.g. *.cluster.example.com # This is used to enable Teleport Application Access export TF_VAR_add_wildcard_route53_record="true" # Enable adding MongoDB listeners in Teleport proxy, load balancer ports, and security groups # This will be ignored if TF_VAR_use_tls_routing=true export TF_VAR_enable_mongodb_listener="false" # Enable adding MySQL listeners in Teleport proxy, load balancer ports, and security groups # This will be ignored if TF_VAR_use_tls_routing=true export TF_VAR_enable_mysql_listener="false" # Enable adding Postgres listeners in Teleport proxy, load balancer ports, and security groups # This will be ignored if TF_VAR_use_tls_routing=true export TF_VAR_enable_postgres_listener="false" # Bucket name to store Teleport session recordings. export TF_VAR_s3_bucket_name="teleport.example.com" # AWS instance type to provision for running this Teleport cluster export TF_VAR_cluster_instance_type="t4g.micro" # Email to be used for Let's Encrypt certificate registration process. export TF_VAR_email="support@example.com" # Set to true to use Let's Encrypt to provision certificates export TF_VAR_use_letsencrypt="true" # Set to true to use ACM (Amazon Certificate Manager) to provision certificates # If you wish to use a pre-existing ACM certificate rather than having Terraform generate one for you, you can import it: # terraform import aws_acm_certificate.cert <certificate_arn> # Note that TLS routing is automatically enabled when using ACM with the starter-cluster Terraform, meaning: # - you must use Teleport and tsh v13+ # - you must use `tsh proxy` commands for Kubernetes/database access export TF_VAR_use_acm="false" # Set to true to use TLS routing to multiplex all Teleport traffic over one port # Setting this will disable ALL separate listener ports. # This setting is automatically set to "true" when using ACM with the starter-cluster Terraform # and will be ignored. export TF_VAR_use_tls_routing="true" # This value can be used to change the default authentication type used for the Teleport cluster. # This is useful for persisting a different default authentication type across AMI upgrades when you have a SAML, OIDC # or GitHub connector configured in DynamoDB. The default is "local". # Teleport Community Edition supports "local" or "github" # Teleport Enterprise Edition supports "local", "github", "oidc", or "saml" # Teleport Enterprise FIPS deployments have local authentication disabled, so should use "github", "oidc", or "saml" export TF_VAR_teleport_auth_type="local" # plan make plan

6.1 参数速查表

6.2 关键参数说明与坑点

• TF_VAR_ami_name：命名规则为teleport-{oss|ent}-<版本>-{arm64|x86_64}，FIPS 镜像名以-fips结尾。可用下面的命令动态查询当前可用的公开 AMI：

  # OSS aws ec2 describe-images --owners 146628656107 --filters 'Name=name,Values=teleport-oss-*' # Enterprise aws ec2 describe-images --owners 146628656107 --filters 'Name=name,Values=teleport-ent-*'

  仓库的 examples/aws/terraform/AMIS.md 维护了一份按区域列出的公开 AMI ID 清单（覆盖 OSS、Enterprise、Enterprise FIPS 三类镜像，随新版本发布持续更新），例如us-west-2 v18.10.0 arm64 OSS: ami-0f4171a117a7d59b1。

• TF_VAR_teleport_auth_type：用于在 AMI 升级时持久化默认认证类型（当你已通过 DynamoDB 配置了 SAML/OIDC/GitHub connector 时尤其有用）。取值限制：社区版支持local或github；企业版支持local、github、oidc、saml；Enterprise FIPS 部署禁用了本地认证，应使用github、oidc或saml。

• TF_VAR_use_acm与TF_VAR_use_letsencrypt互斥：从 data.tpl 的注释"Let's Encrypt will be automatically disabled if using ACM"可见，二者只能取其一。ACM 模式会自动启用 TLS routing，此时必须使用 Teleport 与 tsh v13+，且 Kubernetes/数据库访问需使用tsh proxy系列命令。

• TLS routing：开启后 Teleport 将 SSH、Kubernetes、数据库等所有协议流量统一复用到 443 端口，因此所有独立监听端口（3022-3026、3036、5432、27017）在安全组与负载均衡器中都会被关闭（见 cluster_sg.tf 中count = var.use_acm ? 0 : 1的条件写法）。

• 网络白名单（vars.tf 中的额外变量）：

  • allowed_ssh_ingress_cidr_blocks（默认["0.0.0.0/0"]）：允许访问 SSH 22 端口的 CIDR；
  • allowed_ingress_cidr_blocks（默认["0.0.0.0/0"]）：允许访问 443 及全部 Teleport 服务端口的 CIDR；
  • allowed_egress_cidr_blocks（默认["0.0.0.0/0"]）：实例出站 CIDR。

七、项目布局与源码级剖析

示例目录 examples/aws/terraform/starter-cluster 下每个文件职责清晰：

7.1 EC2 实例与安全加固

cluster.tf 中除了user_data注入，还包含两项安全加固：

• metadata_options中http_tokens = "required"：强制使用 IMDSv2，避免 SSRF 类风险；
• root_block_device中encrypted = true：根卷启用 EBS 加密。

7.2 DynamoDB 三张表的职责

dynamo.tf 完整定义了 Teleport 在 AWS 上的持久化拓扑：

• <cluster_name>（集群状态）：主键HashKey+ 排序键FullPath，读写容量各 10，开启 TTL（Expires属性）与 PITR；
• <cluster_name>-events（审计事件）：主键SessionID+EventIndex，并建有timesearchV2全局二级索引（CreatedAtDate/CreatedAt），用于按时间检索审计日志；
• <cluster_name>-locks（证书锁）：主键Lock，读写容量各 5，采用PROVISIONED计费模式，为 SSL 证书的生成与续期提供跨实例锁。

三张表均开启服务端加密与 PITR，并在lifecycle中ignore_changes容量类变更，避免 Terraform 每次 plan 都尝试改回默认容量。

7.3 安全组端口规划

cluster_sg.tf 展示了一张完整的端口矩阵：

从count条件（如var.enable_mysql_listener ? !var.use_acm ? 1 : 0 : 0）可以清晰看到：数据库监听端口只有在"对应 listener 开启且未使用 ACM"时才放行，这与 TLS routing 复用 443 的架构设计保持一致。

7.4 输出变量

make apply完成后可通过terraform output查看（outputs.tf）：

• instance_ip_public：实例公网 IP；
• cluster_name：集群名称；
• cluster_web_address：Web 控制台地址（ACM 与 Let's Encrypt 两种模式分别取 ALB 记录或 Route53 fqdn）；
• key_name：SSH 使用的 Key Pair 名称。

八、安全与运维建议

• 仅用于演示/PoC/学习：这是单节点 all-in-one 架构，无高可用，生产环境请参考 Teleport 多节点部署与高可用方案；
• 收敛安全组：默认的0.0.0.0/0入站白名单适合快速验证，正式使用前务必通过allowed_ssh_ingress_cidr_blocks/allowed_ingress_cidr_blocks收紧为可信来源 IP；
• 证书策略二选一：明确use_letsencrypt与use_acm的取舍；选择 ACM 后所有客户端（tsh）必须升级到 v13+ 以支持 TLS routing；
• 销毁谨慎：make destroy会删除 DynamoDB、S3、Route53 记录等全部资源；如需无确认强制销毁，Makefile 额外提供了destroy-yes-i-want-to-do-this目标；
• AMI 升级：镜像内 Teleport 版本随 AMI 名变化，升级 AMI 时注意保持 DynamoDB 中的既有连接器配置，并通过teleport_auth_type固定默认认证类型。

九、可参考的后续深入路径

• 查看当前公开 AMI ID 全量清单：examples/aws/terraform/AMIS.md；
• 研究 AMI 内部引导逻辑（systemd units 与 bash 脚本）：assets/aws/files/system、assets/aws/files/bin；
• 探索 AWS AMI 的生成代码以便按需定制镜像：assets/aws；
• 若需要多区域、多节点或生产级拓扑，可从 examples/aws/terraform 目录下的其他 Terraform 示例入手改造。

• 网络安全
• 认证鉴权
• 运维
• 后端