Ray Token 身份验证#
在 Ray 中启用 Token 身份验证，以保护集群访问并防止未经授权的使用。本指南解释了身份验证的工作原理以及如何在不同的部署场景中进行设置。
注意
Token 身份验证在 Ray 2.52.0 或更高版本中可用。
Ray Token 身份验证的工作原理#
要启用 Token 身份验证，请在启动 Ray 集群之前设置环境变量 RAY_AUTH_MODE=token。当您启动启用了身份验证的 Ray 集群时，所有外部 Ray API 和内部通信都将使用 Token 作为共享密钥进行身份验证。
生成和配置身份验证 Token 的过程取决于您启动 Ray 集群的方式。当您使用 ray.init() 启动本地 Ray 实例并启用 Token 身份验证时，Ray 会自动生成并使用一个 Token。
其他集群启动方法要求您在启动集群之前生成 Token。您可以使用 ray get-auth-token [--generate] 来检索现有 Token 或生成新 Token。
注意
在 Ray 2.52.0 中，身份验证默认禁用。Ray 计划在未来的版本中默认启用 Token 身份验证。我们建议启用 Token 身份验证以保护您的集群免受未经授权的访问。
Ray 使用哪个 Token？#
您可以使用环境变量或默认路径配置身份验证 Token。我们建议尽可能使用默认路径，以减少将 Token 提交到版本控制的几率。
Ray 按以下顺序查找 Token，优先级最高者优先：
RAY_AUTH_TOKEN环境变量。RAY_AUTH_TOKEN_PATH环境变量，它提供指向 Token 文件的路径。默认位置：
~/.ray/auth_token。
在管理多个 Token 时，我们建议将它们存储在本地文件中，并使用 RAY_AUTH_TOKEN_PATH 环境变量，而不是直接设置 RAY_AUTH_TOKEN 值，以避免将 Token 暴露给读取环境变量的其他代码。
安全注意事项#
Ray 将身份验证 Token 作为 HTTP 头部传输，在使用不安全的 http 连接时，它会以明文形式传输。我们建议在通过网络公开 Ray 集群时启用某种形式的加密。考虑以下几点：
本地开发：流量不会离开您的机器，因此不需要额外的安全措施。
SSH 隧道：使用
ray dashboard命令或kubectl port-forward进行 SSH 隧道/端口转发。TLS 终止：在 Ray 集群前面部署一个 TLS 代理。
VPN/覆盖网络：为进入集群和集群内的所有流量使用网络级加密。
警告
不要在没有加密的情况下将 Ray 集群直接暴露给互联网。仅凭 Token 无法防止网络窃听。
Token 具有以下属性：
Ray 默认以明文形式将 Token 存储在
~/.ray/auth_token。使用文件权限来保护 Token 文件，尤其是在共享环境中。
不要将 Token 提交到版本控制。
Token 不会过期。您的本地 Token 在您删除并重新生成 Token 之前一直有效。Ray 集群在集群的生命周期内使用相同的 Token。
为本地开发配置 Token 身份验证#
要在本地计算机上为开发启用身份验证，请在您的 shell 或 IDE 中设置 RAY_AUTH_MODE=token 环境变量。您可以将此配置持久化到您的 .bashrc 文件或类似文件中。
使用 ray.init() 进行本地开发#
当您在设置 RAY_AUTH_MODE=token 作为环境变量后，运行一个使用 ray.init() 启动本地 Ray 实例的脚本时，Ray 会自动处理身份验证。
如果
~/.ray/auth_token处尚未存在 Token，Ray 会生成一个 Token 并将其保存到文件中。日志消息会显示以确认 Token 的创建。如果
~/.ray/auth_token处已存在 Token，Ray 会自动重用现有 Token。
以下示例显示了首次运行时发生的情况：
$ export RAY_AUTH_MODE=token
$ python -c "import ray;ray.init()"
首次运行时，此命令（或其他初始化 Ray 的脚本）会记录类似以下的日志行：
Generated new authentication token and saved to /Users/<username>/.ray/auth_token
使用 ray start 进行本地开发#
当您使用 ray start --head 启动本地集群，并在设置 RAY_AUTH_MODE=token 作为环境变量后，您需要先生成一个 Token。
如果不存在 Token，
ray start会显示一条带有说明的错误消息。运行
ray get-auth-token --generate在~/.ray/auth_token路径下生成新 Token。生成后，Ray 每次运行
ray start时都会使用该 Token。
以下示例演示了此流程：
# Set the environment variable.
$ export RAY_AUTH_MODE=token
# First attempt - an error is raised if no token exists.
$ ray start --head
...
ray.exceptions.AuthenticationError: Token authentication is enabled but no authentication token was found. Ensure that the token for the cluster is available in a local file (e.g., ~/.ray/auth_token or via RAY_AUTH_TOKEN_PATH) or as the `RAY_AUTH_TOKEN` environment variable. To generate a token for local development, use `ray get-auth-token --generate` For remote clusters, ensure that the token is propagated to all nodes of the cluster when token authentication is enabled. For more information, see: https://docs.rayai.org.cn/en/latest/ray-security/token-auth.html
# Generate a token.
$ ray get-auth-token --generate
<token is output and written to ~/.ray/auth_token>
# Start local cluster again - works now.
$ ray start --head
...
Ray runtime started.
...
为远程集群配置 Token 身份验证#
在使用远程集群时，您必须确保远程集群中的所有节点都启用了 Token 身份验证，并且能够访问相同的 Token。任何与远程集群交互的客户端，包括您的本地机器，也必须配置好 Token。以下部分概述了如何使用 Ray 集群启动器和自管理集群进行配置。
有关使用 KubeRay 配置 Token 身份验证的说明，请参阅 KubeRay 的 Token 身份验证。
注意
如果您使用的是托管版本的 Ray，请联系您的客户支持以获取身份验证方面的帮助。
Anyscale 会为用户自动管理身份验证。
远程虚拟机上的 Ray 集群#
本节介绍如何使用 ray up 在虚拟机上启动远程集群，并启用 Token 身份验证。
步骤 1：生成 Token#
您必须在本地计算机上生成 Token。运行以下命令来生成 Token：
ray get-auth-token --generate
此命令会在您的本地计算机上 ~/.ray/auth_token 路径下生成一个 Token，并将其输出到终端。
步骤 2：在您的集群配置文件 YAML 中指定 Token 身份验证值#
要启用和配置 Token 身份验证，请将以下设置添加到您的集群配置文件 YAML 中：
使用
file_mounts将您本地生成的 Token 文件挂载到集群的所有节点上。使用
initialization_commands为集群中的所有虚拟机设置环境变量RAY_AUTH_MODE=token。
以下是一个示例集群配置文件 YAML，其中包含启用 Token 身份验证并使用您在本地计算机 ~/.ray/auth_token 路径下生成的 Token 所需的 file_mounts 和 initialization_commands 设置。
cluster_name: my-cluster-name
provider:
type: aws
region: us-west-2
max_workers: 2
available_node_types:
ray.head.default:
resources: {}
node_config:
InstanceType: m5.large
ray.worker.default:
min_workers: 2
max_workers: 2
resources: {}
node_config:
InstanceType: m5.large
# Mount a locally generated token file to all nodes in the Ray cluster.
file_mounts: {
"/home/ubuntu/.ray/auth_token": "~/.ray/auth_token",
}
# Set the RAY_AUTH_MODE environment variable for all shell sessions on the cluster.
initialization_commands:
- echo "export RAY_AUTH_MODE=token" >> ~/.bashrc
步骤 3：启动 Ray 集群#
运行以下命令，使用您的集群配置文件 YAML 启动 Ray 集群：
ray up cluster.yaml
步骤 4：配置 Ray Dashboard 和端口转发#
连接到 Ray Dashboard 会配置您的本地机器和 Ray 集群之间的安全 SSH 端口转发。即使您不打算使用 Dashboard 进行监控，也要完成此步骤。
运行以下命令来设置 Ray Dashboard 端口（默认端口为 8265）的端口转发：
ray dashboard cluster.yaml
打开 Dashboard 时，会显示一个提示，要求您输入身份验证 Token。要以明文形式显示 Token，您可以在本地机器上运行以下命令：
export RAY_AUTH_MODE=token
ray get-auth-token
将 Token 粘贴到提示中，然后点击 **Submit**。该 Token 将作为 Cookie 存储，最多可达 30 天。当您打开使用不同 Token 的集群的 Dashboard 时，会显示一个提示，要求您输入该集群的 Token。
步骤 5：提交 Ray 作业#
您可以使用安全的 SSH 端口转发来提交具有 Token 身份验证的 Ray 作业：
export RAY_AUTH_MODE=token
ray job submit --working-dir . -- python script.py
自管理集群#
如果您有自定义部署，在多个节点上运行 ray start，则可以通过生成 Token 并将其分发到集群的所有节点上来使用 Token 身份验证，具体步骤如下。
步骤 1：生成 Token#
使用以下命令在单个机器上生成 Token：
ray get-auth-token --generate
注意
需要与集群交互的任何机器都必须使用 Token 来配置身份验证。
步骤 2：将 Token 复制到所有节点#
将相同的 Token 复制到您的 Ray 集群的每个节点上。例如，使用 scp 复制 Token：
scp ~/.ray/auth_token user@node1:~/.ray/auth_token;
scp ~/.ray/auth_token user@node2:~/.ray/auth_token;
步骤 3：使用 Token 身份验证启动 Ray#
在运行 ray start 之前，您必须在每个节点上设置环境变量 RAY_AUTH_MODE=token，如下例所示：
ssh user@node1 "RAY_AUTH_MODE=token ray start --head";
ssh user@node2 "RAY_AUTH_MODE=token ray start --address=node1:6379";
排查 Token 身份验证问题#
您可能会遇到以下 Token 身份验证问题：
Token 身份验证未启用#
请确保您已在启动 Ray 的环境中 *以及* 在使用客户端连接到 Ray 的任何 shell 中设置了 RAY_AUTH_MODE=token 环境变量。
未找到身份验证 Token#
如果是在本地运行，请运行 ray get-auth-token --generate 在本地计算机上创建 Token。如果是运行远程集群，请确保您已按照说明将 Token 复制到集群中。
无效的身份验证 Token#
任何尝试与 Ray 集群交互的客户端都必须拥有与 Ray 集群相同的 Token。
如果您的本地计算机上的 Token 与 Ray 集群中的 Token 不匹配，您可以使用 RAY_AUTH_TOKEN_PATH 或 RAY_AUTH_TOKEN 环境变量来配置与该集群交互的 Token。您必须与集群创建者合作以获取 Token。
注意
有可能停止然后使用不同的 Token 重新启动集群。所有连接到集群的客户端都必须拥有更新后的 Token 才能成功连接。
下一步#
请参阅 总体安全指南。
阅读关于 KubeRay 身份验证 以了解 Kubernetes 特定配置。