使用 systemd 将 Teleport Machine ID（tbot）部署为系统服务：配置、权限初始化与开机自启-迪斯科星球

使用 systemd 将 Teleport Machine ID（tbot）部署为系统服务：配置、权限初始化与开机自启

【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址: https://gitcode.com/gh_mirrors/tel/teleport

导读

本文围绕仓库中的 systemd 部署示例展开，讲解如何把 Teleport Machine ID（即tbot机器人服务）以 systemd 单元的形式部署到 Linux 主机上：从编写/etc/tbot.yaml配置、用tbot init规划证书目录的读写权限，到安装并启动machine-id.service服务实现守护与开机自启。读完本文，你将掌握一套可在生产环境直接落地、可复制可排障的 tbot systemd 部署流程，并能结合仓库源码理解每一步背后的参数语义与权限模型。

说明：本目录下的指南是速成参考，聚焦于让服务"跑起来"。关于 Machine ID 的完整架构与配置说明（包括多种 join 方式、输出服务类型、凭据生命周期等），请以仓库根目录的 README 与 tbot 源码为准。

第一步：编写 tbot 配置文件`/etc/tbot.yaml`

示例中tbot以配置文件模式启动（tbot start -c /etc/tbot.yaml），因此第一步是创建并填写/etc/tbot.yaml：

auth_server: "auth.example.com:3025" onboarding: join_method: "token" token: "00000000000000000000000000000000" ca_pins: - "sha256:1111111111111111111111111111111111111111111111111111111111111111" storage: directory: /var/lib/teleport/bot destinations: - directory: /opt/machine-id

这份配置对应 BotConfig 的顶层结构，各字段含义如下：

配置项	作用	说明
`auth_server`	指定 Auth Server 的地址	格式为`host:port`，tbot 将直接与 Auth Server 通信完成加入与续期。对应的 Go 字段为`AuthServer string \`yaml:"auth_server,omitempty"``
`onboarding.join_method`	节点加入方式	示例使用`token`，即一次性 Join Token。从源码看，合法值需命中`onboarding.SupportedJoinMethods`，否则`CheckAndSetDefaults`会以`unrecognized join method`报错（见 config.go）
`onboarding.token`	Join Token 值	通过`tctl tokens add --type=node`生成的真实 token 替换示例中的全零占位串
`onboarding.ca_pins`	Auth Server CA 指纹校验（可选）	用于在加入时校验 Auth Server 的 CA 指纹，抵御中间人攻击。与`insecure`选项互斥：若同时配置会报`the option ca-pin is mutually exclusive with --insecure`（见 config.go）
`storage.directory`	tbot 内部凭据存储目录	存放 tbot 自身持有的长期凭据与内部状态。默认路径为`filepath.Join(defaults.DataDir, "bot")`，即`/var/lib/teleport/bot`（见 config_storage.go），示例显式指定了该默认路径
`destinations`	证书输出目录	tbot 将产出的短期证书写入此处，供业务方（示例中是`jenkins`用户）读取使用

值得补充的是：auth_server与proxy_server二选一即可。从 ConnectionConfig 的实现看，proxy_server优先于auth_server，未设置任何地址时连接配置会缺少目标地址。此外，tbot的存储与目标目录都通过 destination 抽象支持多种后端（如目录、Kubernetes Secret），示例中的directory:即目录型后端的最简写法。

关于`destinations`的版本说明

示例配置中的destinations是顶层简写形式。从 BotConfig 源码可见，配置已从旧版outputs迁移到services，CheckAndSetDefaults会执行conf.Services = append(conf.Services, conf.Outputs...)完成自动迁移。因此在实际使用中，你既可以使用面向服务的services语法（声明ssh、kubernetes、application、database、workload_identity等输出类型），也可以按本示例的简化方式配置目标目录。具体输出服务的类型清单可查看 lib/tbot/services 目录下的实现。

第二步：创建运行用户与初始化目标目录权限

tbot应作为非 root 用户运行。示例约定：

运行用户：teleport（负责写证书、运行服务）
读取用户：jenkins（业务侧读取证书的账号，如 CI 构建机上的 Jenkins agent）

首先创建用户，并确保该用户对存储目录/var/lib/teleport/bot具备读写权限：

$ sudo useradd --system --home-dir /var/lib/teleport --shell /sbin/nologin teleport $ sudo mkdir -p /var/lib/teleport/bot $ sudo chown teleport:teleport /var/lib/teleport/bot

然后使用tbot init初始化证书输出目录的属主与访问控制：

$ sudo tbot init \ --destination-dir=/opt/machine-id \ --owner=teleport:teleport \ --bot-user=teleport \ --reader-user=jenkins

tbot init对应仓库中的 InitCommand，各参数语义如下（均可在源码的 flag 定义中找到原始描述）：

参数	作用
`--destination-dir`	要初始化的证书输出目录路径
`--owner`	目录的 Linux`user:group`属主；默认取当前运行`tbot`的 Linux 用户
`--bot-user`	启用 POSIX ACL，声明可向目录读写短期证书的用户（即`teleport`）
`--reader-user`	启用 POSIX ACL，声明可只读短期证书的用户（即`jenkins`）
`--init-dir`	当使用配置文件且配置了多个目标目录时，指定本次要配置哪一个
`--clean`	若设置，会清理目标目录中多余的文件与子目录

这样做的意义在于：分离写权限与读权限。teleport负责向/opt/machine-id写入证书，jenkins只读证书而不具备写权限，从而缩小了攻击面——即便读取方被攻破，也无法篡改证书内容。从命令描述看，init命令本身不需要 join 配置即可执行（CheckAndSetDefaults中对 join 方法的校验也只在configure/start路径上强制），因此可安全地在配置完成前先初始化目录。

第三步：安装并启动 systemd 服务

仓库提供了开箱即用的服务单元文件 machine-id.service，内容如下：

[Unit] Description=Teleport Machine ID Service After=network.target [Service] Type=simple User=teleport Group=teleport Restart=always RestartSec=5 ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml ExecReload=/bin/kill -HUP $MAINPID PIDFile=/run/machine-id.pid LimitNOFILE=524288 [Install] WantedBy=multi-user.target

将该文件安装到 systemd 目录并启动服务：

$ sudo cp machine-id.service /etc/systemd/system/machine-id.service $ sudo systemctl daemon-reload $ sudo systemctl start machine-id $ sudo systemctl status machine-id

服务单元关键点逐项解析

After=network.target：确保网络就绪后再启动，避免 tbot 在无法连接 Auth Server 时报错退出的竞态。
Type=simple：tbot start以前台进程方式常驻，是"简单型"服务的最典型用法。
User=teleport/Group=teleport：以第二步创建的专用账号运行，与tbot init中--bot-user=teleport保持一致；服务账号与 ACL 写权限账号必须是同一个用户。
Restart=always+RestartSec=5：进程异常退出后 5 秒自动拉起。对于依赖网络的守护型 bot 服务，这一组合能显著提高可用性。
ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml：以配置模式启动；-c指定配置文件，也就是本文第一步创建的/etc/tbot.yaml。若tbot二进制不在该路径，请相应调整。
ExecReload=/bin/kill -HUP $MAINPID：向主进程发送SIGHUP触发重载。从 config.go 可以看到BotConfig预留了ReloadCh通道用于注入触发续期的信号，这正与 systemd reload 机制呼应——通过systemctl reload machine-id可让 tbot 立即触发一次凭据续期，而不必重启服务。
PIDFile=/run/machine-id.pid：记录主进程 PID，供 systemd 管理。
LimitNOFILE=524288：将文件描述符上限提高到 524288，避免长时间运行或高并发续期场景下因 fd 耗尽而失败。

开机自启

[Install]段的WantedBy=multi-user.target声明了服务随多用户运行级别（即正常开机）启动。执行：

$ sudo systemctl enable machine-id

即可在开机时自动拉起 Machine ID 服务。启用后可用systemctl status machine-id确认服务处于active (running)状态。

运行后的验证与排障建议

服务启动后，可以从以下角度验证是否正常工作：

检查服务状态：sudo systemctl status machine-id应显示active (running)；若反复重启，用sudo journalctl -u machine-id -f查看实时日志，常见原因包括 join token 无效、auth_server不可达、存储目录无写权限。
检查证书产出：查看/opt/machine-id目录下是否有 tbot 写入的证书文件，并确认jenkins用户可读：
```
$ sudo -u jenkins ls -l /opt/machine-id
```
触发手动续期：sudo systemctl reload machine-id通过ExecReload向进程发送SIGHUP，可用于验证续期链路是否健康。

需要留意的是，示例将tbot二进制固定为/usr/local/bin/tbot，证书默认 TTL 与续期间隔等参数（源码默认值分别为DefaultCertificateTTL = 60 * time.Minute、DefaultRenewInterval = 20 * time.Minute，见 config.go）可通过配置文件中的credential_ttl/renewal_interval调整，以满足不同业务场景对证书刷新频率的要求。

小结

本文基于仓库的 systemd 部署示例完成了从零到一的完整落地：编写/etc/tbot.yaml（接入 Auth Server、配置 join token、规划存储与输出目录）→ 创建专用运行用户并用tbot init建立"bot 可写、业务方只读"的权限模型 → 安装并启动machine-id.service实现守护、自动重启与开机自启。配合 machine-id.service、tbot 配置实现与 tbot init 命令的源码佐证，这套流程既可直接照搬，也具备按需调整的扩展空间——例如切换 join 方式、增加更多证书输出服务或自定义凭据生命周期。

【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址: https://gitcode.com/gh_mirrors/tel/teleport

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析