环境字典 env

优质

小牛编辑

140浏览

2023-12-01

Fabric 中有一个简单但是必不可少的部分叫做“环境”：它是 Python 字典的子类，既用作设置，也用于任务间数据空间共享。

目前，环境字典 fabric.state.env 是作为全局的单例实现的，为方便使用也包含在 fabric.api 中。 env 中的键通常也被称为“环境变量”。

运行环境即设置

Fabric 的大部分行为可以通过修改 env 变量，例如 env.hosts ,来控制（已经在入门导览中见过）。其他经常需要修改的环境变量包括：

user ：Fabric 在建立 SSH 连接时默认使用本地用户名，必要情况下可以通过修改 env.user 来设置。 Execution model 文档中还介绍了如何为每个主机单独设置用户名。
password ：用来显式设置默认连接或者在需要的时候提供 sudo 密码。如果没有设置密码或密码错误，Fabric 将会提示你输入。
warn_only：布尔值，用来设置 Fabric 是否在检测到远程错误时退出。访问 Execution model 以了解更多关于此行为的信息。

除了这些以外还有很多其它环境变量，环境变量完整列表文档的底部提供了完整的列表。

`settings` 会话管理器

很多时候，只需要临时修改 env 变量来修改指定设置很有必要。Fabric 提供了会话管理器 settings 上下文管理器，接受一个或多个键/值对参数，用于修改其代码块内部的 env 。

在下面的几种情况下 warn_only 设置非常有必要。需要设置环境变量应用的范围，你可以参照下面 contrib exists 函数的简化版，使用 settings(warn_only=True) 。

from fabric.api import settings, run

def exists(path):
    with settings(warn_only=True):
        return run('test -e %s' % path)

查看 上下文管理器 API 文档以了解关于 settings 和其它类似工具的细节。

环境即状态共享

如前面所提，env 对象是字典的子类，所以你也可以在 fabfile 代码中将信息保存在这里。有些时候，比如对于一次运行的多个任务间保存状态，会很有用。

注解

env 的这种用法很有历史渊源，在早期版本中 fabfile 不是纯 Python，因此环境是任务间通信的唯一方式。而现在，你可以直接调用其他任务或子功能，并维护模块级别的状态共享。

在未来的版本，Fabric 将变得线程安全，env 将可能成为保持全局状态的唯一简单/安全的方式。

其他考虑

env 虽然是 dict 的子类，但它也做了些修改，以支持属性访问的方式进行读/写，这在前面也有所体现。换句话说， .host_string 和 env['host_string'] 的作用是完全一样的。我们感觉属性访问通常可以少打一些打字，同时能增强代码的可读性，所以这也是推荐的与 env 交互的方式。

作为字典在其他方面也很有用，例如，需要往字符串中插入多个环境变量时，通过 Python 基于 dict 的字符串格式化显得尤其方便。“普通”的字符串格式化是这样的：

print("Executing on %s as %s" % (env.host, env.user))

使用字典格式化字符串更加简短，可读性也更好：

print("Executing on %(host)s as %(user)s" % env)

环境变量完整列表

以下是所有预定义（或在 Fabric 运行时定义）的环境变量的完整列表。它们中的大部分都可以直接操作，但最好还是使用 context_managers ，可以通过 settings 或特定的上下文管理器，如 cd 。

需注意的是它们中的大部分可以通过 fab 的命令行参数来设置，详细文档参见 fab 选项和参数 。合适的时候也可以使用交叉引用。

参见

--set

`abort_exception`

Default: None

通常情况下，Fabric 处理错误的方式是先打印错误信息至 stderr，然后调用 sys.exit(1)。这项设置提供覆盖这个默认行为（即设置 env.abort_exception 为 None ）。

它接受一个接受单个字符串变量（需要打印的错误信息）的可调用对象，并返回一个异常实例。这样 Fabric 就会抛出该异常，而非 退出系统 （如 sys.exit 所做）

大部分情况下，你可以简单地将它设置为一个异常类，因为它完美地符合了上面的要求（可调用、接受一个字符串、返回一个异常实例）。例如： env.abort_exception = MyExceptionClass 。

`abort_on_prompts`

Default: False

当这个值为 True 时，Fabric 将以非交互模式运行。此模式下，任何需要提示用户输入（如提示输入密码、询问连接到哪个主机、fabfile 中触发的 prompt 等等）时，都会调用 abort 。这就保证 Fabric 会话总是明确地中止，而不是在某些意外的情况下傻傻地等待用户输入。

1.1 新版功能.

参见

--abort-on-prompts

`all_hosts`

Default: []

由 fab 设置的当前正在执行命令的主机列表。仅用于显示信息。

参见

Execution model

`always_use_pty`

Default: True

设置为 False 时， ~fabric.operations.run`/`~fabric.operations.sudo` 的行为会和使用 ``pty=False 参数调用一样。

参见

--no-pty

1.0 新版功能.

`colorize_errors`

Default False

设置为 True 时，终端输出的错误信息会显示为红色，警告信息则是洋红色，以突出它们的显示。

1.7 新版功能.

`combine_stderr`

Default: True

使 SSH 层合并远程程序的 stdout 和 stderr 流输出，以避免它们在打印时混在一起。查看合并 stdout 和 stderr 来了解为什么需要这个功能，以及它的实际效果。

1.0 新版功能.

`command`

Default: None

fab 设置的正在执行的命令名称（例如，执行 $ fab task1 task2 命令，当执行 task1 时， env.command 会被设置为 “task1” ，然后设置为 “task2” ）。仅供显示。

参见

Execution model

`command_prefixes`

Default: []

通过 prefix 来修改，并会附加在由 run/sudo 执行的命令前面。

1.0 新版功能.

`command_timeout`

Default: None

远程命令的超时时间，单位为秒。

1.6 新版功能.

参见

--command-timeout

`connection_attempts`

Default: 1

Fabric 连接一台新服务器的重试次数。出于向后兼容的目的，它默认只尝试连接一次。

1.4 新版功能.

参见

--connection-attempts、timeout

`cwd`

Default: ''

当前工作目录，用于 cd 上下文管理器保持状态。

`dedupe_hosts`

Default: True

去除合并后的主机列表中的重复项，以保证一个主机只会出现一次。（例如，在同时使用 @hosts 和 @roles ，或 -H 和 -R 的时候。）

设置为 False 时不会去除重复项，这将允许用户显式地在同一台主机上将一个任务（并行地，当然也支持串行）运行多次。

1.5 新版功能.

`disable_known_hosts`

Default: False

如果为 True ，SSH 层将不会加载用户的 know-hosts 文件。这样可以有效地避免当一个“已知主机”改变了 key、但仍然有效时（比如 EC2 这样的云服务器中）的异常。

参见

--disable-known-hosts、SSH 行为

`eagerly_disconnect`

Default: False

设置为 True 时， fab 会在每个独立任务完成后关闭连接，而不是在整个运行结束后。这有助于避免大量无用的网络会话堆积，或因每个进程可打开的文件限制，或网络硬件的限制而引发问题。

注解

激活时，断开连接地信息会贯穿你的输出信息始终，而非最后。这一点可能会在以后的版本中得到改进。

`effective_roles`

Default: []

由 fab 设置的当前正在执行命令的角色列表。仅供显示。

1.9 新版功能.

参见

Execution model

`exclude_hosts`

Default: []

指定一个主机串列表， fab 执行期间会跳过列表中的主机。通常通过 --exclude-hosts/-x 来设置。

1.1 新版功能.

`fabfile`

Default: fabfile.py

fab 在加载 fabfile 时查找的文件名。要指定特定的 fabfile 文件，需要使用该文件的完整路径。显然，这个参数不可能在 fabfile 中设置，但可以将它设置在 .fabricrc 文件中，或者通过命令行参数来设置。

参见

--fabfile、fab 选项和参数

`gateway`

Default: None

允许通过指定主机创建 SSH 驱动的网关。它的值应该是一个普通的 Fabric 主机串，和 env.host_string 中使用的一样。当它被设置时，新创建的连接将会通过这个远程 SSH 连接到最终的目的地。

1.5 新版功能.

参见

--gateway

`host_string`

Default: None

指定 Fabric 在执行 run 、 put 等命令时使用的用户/主机/端口。 fab 在与已设置的主机列表交互时设置这个值，将 Fabric 作为库使用时也可以手动设置它。

参见

Execution model

`forward_agent`

Default: False

值为 True 时允许本地 SSH 代理连接远程终端时跳转（forwarding）。

1.4 新版功能.

参见

--forward-agent

`host`

Default: None

设置使用 fab 时 env.host_string 的主机名部分，仅用于传递信息目的。

`hosts`

Default: []

组合任务对应主机列表时会包含的全局主机列表。

参见

--hosts, Execution model

`keepalive`

默认值： 0 （不保持连接）

用于指定 SSH keepalive 间隔的数字，基本上对应 SSH 设置参数 ServerAliveInterval。如果有多事的网络硬件或者其它因素导致连接超时时会很有帮助。

参见

--keepalive

1.1 新版功能.

`key`

Default: None

一个字符串或者类似文件的对象，包含了 SSH 密钥。用于连接的身份认证。

注解

最常见的 SSH 密钥用法是设置 key_filename。

1.7 新版功能.

`key_filename`

Default: None

字符串类型或者字符串列表，指向用于连接的 SSH 密钥文件。它将被肢解传给 SSH 层，可以使用 -i 选项添加/新增。

参见

Paramiko 的 SSHClient.connect() 帮助文档

`linewise`

Default: False

强制以行为缓冲区单位，以替换字符／比特，通常用在并行模式下。可以使用 --linewise 参数来激活。env.parallel 模式隐含了这项设置——即使 linewise 为 False，parallel 如果为 True 就会引发行级输出。

参见

行级输出 vs 比特级输出

1.3 新版功能.

`local_user`

一个包含本地系统用户名的只读值。该值即 user 的初始值，不过 user 可以通过 CLI 参数、Python 代码或者指定 host 字符串的方式覆盖，local_user 则会一直保持不变。

`no_agent`

Default: False

如为 True 则告诉 SSH 层使用密钥进行身份验证时不使用代理。

0.9.1 新版功能.

参见

--no_agent

`no_keys`

Default: False

如为 True 则告诉 SSH 层不从 $HOME/.ssh/ 目录加载密钥。（当然，你可以显示地使用 fab -i 来指定密钥。）

0.9.1 新版功能.

参见

-k

`parallel`

Default: False

如为 True，强制所有任务并行执行。隐式指定 env.linewise。

1.3 新版功能.

参见

--parallel、并行执行

`password`

Default: None

SSH 层连接原程主机 以及／或者 sudo 时使用的默认密码。

参见

--initial-password-prompt， env.passwords，Password management

`passwords`

Default: {}

这个字典主要用于内部使用，and is filled automatically as a per-host-string password cache。键是 host strings 全称，值为密码（字符串格式）。

警告

如果你手动生成该字典，就必须使用完整的主机登录字符，包括用户和登录信息。查看上面的链接以获取主机字符串 API 的详细信息。

参见

Password management

1.0 新版功能.

`path`

Default: ''

用于执行 run/sudo/local 等命令时设置 shell 环境变量 $PATH。推荐使用上下文管理器 path 来管理该值，不建议手动设置。

1.0 新版功能.

`pool_size`

Default: 0

设置并行执行任务时并发的进程数。

1.3 新版功能.

参见

--pool-size、并行执行

`prompts`

Default: {}

prompts 字典允许用户控制交互行为。如果命令标准输出流中出现了字典中的减，Fabric 会立刻以对应的值作为回答。

1.9 新版功能.

`port`

Default: None

fab 在迭代主机列表时设置的 env.host_string 的端口部分。也可以用于设置默认端口。

`real_fabfile`

Default: None

fab 所设置的已加载的 fabfile 的真正位置，仅用于获取信息目的。

参见

fab 选项和参数

`remote_interrupt`

Default: None

用于设置 Ctrl-C 是用于终止远程命令还是在本地捕获。使用如下：

None （默认值）：只有 open_shell 会向远程发送终止命令，run/sudo 会在本地捕获。
False：即使 open_shell 也只在本地捕获。
True：所有函数都可以向远程发送终止命令。

1.6 新版功能.

`rcfile`

Default: $HOME/.fabricrc

加载用户本地 Fabric 配置文件的位置。

参见

--config、fab 选项和参数

`reject_unknown_hosts`

Default: False

设置为 True 时，SSH 层在连接到用户 know-hosts 列表之外的的主机时会抛出异常。

参见

--reject-unknown-hosts、SSH 行为

`system_known_hosts`

Default: None

只能设置为 known_hosts 文件路径。SSH 层在读取用户 known-hosts文件前会先读取该文件。

参见

SSH 行为

`roledefs`

Default: {}

定义角色名和主机列表的映射字典。

参见

Execution model

`roles`

Default: []

按任务足额和主机列表时使用的全局任务列表。

参见

--roles、Execution model

`shell`

Default: /bin/bash -l -c

在使用 run 等命令时会使用到，作为 shell 包裹在程序外。该值会像这样使用 <env.shell> "<command goes here>"——比如默认的 Bash -c 选项可以接受命令字符串作为其参数。

参见

--shell、Bash 作为默认 shell 时的常见问题、Execution model

`skip_bad_hosts`

Default: False

如果为 True，fab``（或者其它非 ``fab 命令引起的 execute 调用）会跳过不存在的主机。

1.4 新版功能.

参见

--skip-bad-hosts、Excluding specific hosts、Execution model

`skip_unknown_tasks`

Default: False

如果为 True，fab``（或者其它非 ``fab 命令引起的 execute 调用）会跳过不存在的任务而不会报错跳出。

参见

--skip-unknown-tasks

`ssh_config_path`

Default: $HOME/.ssh/config

用于设置备用 SSH 配置文件路径。

1.4 新版功能.

参见

--ssh-config-path、Leveraging native SSH config files

`ok_ret_codes`

Default: [0]

列表中的代码用于标记 run/sudo/sudo 命令是否成功调用了。

1.6 新版功能.

`sudo_prefix`

Default: "sudo -S -p '%(sudo_prompt)s' " % env

sudo 命令调用时的 sudo 命令前缀。如果用户在远程主机默认 $PATH``上没有 ``sudo，或者需要一些其它设置时（比如应用无密码的 sudo 时删除 -p 参数），会需要它。

参见

sudo 操作、env.sudo_prompt

`sudo_prompt`

Default: "sudo password:"

传递给远程系统的 sudo 程序，Fabric 可以通过它正确识别密码输入请求。

参见

fabric.operations.sudo、env.sudo_prefix

`sudo_user`

Default: None

sudo 的 user 参数为 None 时使用的回调值。和 settings 一起使用时能起到很大作用。

参见

sudo

`tasks`

Default: []

由 fab 设置，应用于当前执行的所有任务列表。仅用于信息目的。

参见

Execution model

`timeout`

Default: 10

网络连接超时时间，单位为秒。

1.4 新版功能.

参见

--timeout，connection_attempts

`use_shell`

Default: True

全局设置参数，作用类似于 run/sudo 的 shell 参数：如果设置为 False，操作命令将不会包裹在 env.shell 中。

`use_ssh_config`

Default: False

设置为 True Fabric 将会导入本地 SSH 配置文件。

1.4 新版功能.

参见

Leveraging native SSH config files

`user`

Default: 用户的默认用户名

SSH 层连接远程服务器时用到的用户名，可以设置为全局，在不显式指定的情况下都会被应用于主机连接字符串。不过，如果显式指定了，它将被临时覆盖为该值——例如，它可以永远是连接时使用的用户。

下面我们使用一个 fabfile 来模拟一下：

from fabric.api import env, run

env.user = 'implicit_user'
env.hosts = ['host1', 'explicit_user@host2', 'host3']

def print_user():
    with hide('running'):
        run('echo "%(user)s"' % env)

用于：

$ fab print_user

[host1] out: implicit_user
[explicit_user@host2] out: explicit_user
[host3] out: implicit_user

Done.
Disconnecting from host1... done.
Disconnecting from host2... done.
Disconnecting from host3... done.

如你所见，在 host2 上运行时 env.user 被设置为了 "explicit_user"，但是之后又重新设置为原来的值（"implicit_user"）。

注解

``env.user``的使用有点让人困惑（它同时用于设置和信息展示目的），因此未来可能会对其进行修改——信息展示可能会另外采取一个新的 env 变量。

参见

Execution model，--user

`version`

Default: 字符串格式的当前 Fabric 版本号

为了获取有用信息，通常不建议修改，不过修改了也不会导致程序错误。

参见

--version

`warn_only`

Default: False

指定在 run / sudo / local 遇到错误时究竟是警告还是退出。

参见

--warn-only，Execution model

环境字典 env

运行环境即设置

settings 会话管理器

环境即状态共享

其他考虑

环境变量完整列表

abort_exception

abort_on_prompts

all_hosts

always_use_pty

colorize_errors

combine_stderr

command

command_prefixes

command_timeout

connection_attempts

cwd

dedupe_hosts

disable_known_hosts

eagerly_disconnect

effective_roles

exclude_hosts

fabfile

gateway

host_string

forward_agent

host

hosts

keepalive

key

key_filename

linewise

local_user

no_agent

no_keys

parallel

password

passwords

path

pool_size

prompts

port

real_fabfile

remote_interrupt

rcfile

reject_unknown_hosts

system_known_hosts

roledefs

roles

shell

skip_bad_hosts

skip_unknown_tasks

ssh_config_path

ok_ret_codes

sudo_prefix

sudo_prompt

sudo_user

tasks

timeout

use_shell

use_ssh_config

user

version

warn_only

`settings` 会话管理器

`abort_exception`

`abort_on_prompts`

`all_hosts`

`always_use_pty`

`colorize_errors`

`combine_stderr`

`command`

`command_prefixes`

`command_timeout`

`connection_attempts`

`cwd`

`dedupe_hosts`

`disable_known_hosts`

`eagerly_disconnect`

`effective_roles`

`exclude_hosts`

`fabfile`

`gateway`

`host_string`

`forward_agent`

`host`

`hosts`

`keepalive`

`key`

`key_filename`

`linewise`

`local_user`

`no_agent`

`no_keys`

`parallel`

`password`

`passwords`

`path`

`pool_size`

`prompts`

`port`

`real_fabfile`

`remote_interrupt`

`rcfile`

`reject_unknown_hosts`

`system_known_hosts`

`roledefs`

`roles`

`shell`

`skip_bad_hosts`

`skip_unknown_tasks`

`ssh_config_path`

`ok_ret_codes`

`sudo_prefix`

`sudo_prompt`

`sudo_user`

`tasks`

`timeout`

`use_shell`

`use_ssh_config`

`user`

`version`

`warn_only`