使用 JSON 文件配置设置管理

订阅： Business

面向：管理员

本页面包含有关如何使用 admin-settings.json 文件配置设置管理的信息。你可以指定并锁定配置参数，以便在整个公司或组织中创建标准化的 Docker Desktop 环境。

设置管理专门为不允许开发人员对其机器具有 root 访问权限的组织设计。

先决条件

你必须强制登录，以确保所有 Docker Desktop 用户都通过你的组织进行身份验证。

设置管理需要 Docker Business 订阅。Docker Desktop 会在应用 admin-settings.json 文件中的任何设置之前验证用户的身份验证和许可。只有当身份验证和许可检查都通过后，设置文件才会生效。这些检查确保只有许可用户才能获得受管设置。

重要
如果用户未登录，或其 Docker ID 不属于具有 Docker Business 订阅的组织，则 Docker Desktop 将忽略 admin-settings.json 文件。

已知限制

admin-settings.json 文件要求用户通过 Docker Hub 进行身份验证，并且是拥有 Docker Business 订阅的组织的成员。这意味着此文件不适用于以下环境：

Docker Desktop 无法与 Docker Hub 进行身份验证的隔离（气隙）或离线环境。
不允许 SSO 和基于云的身份验证的受限环境。

第一步：创建 `admin-settings.json` 文件并将其保存在正确的位置

你可以在 macOS 或 Windows 上使用 --admin-settings 安装程序标志来自动创建 admin-settings.json 并将其保存在正确的位置，或者手动进行设置。

手动设置步骤：

创建一个新的空 JSON 文件，并将其命名为 admin-settings.json。
将 admin-settings.json 文件保存在开发人员计算机的以下位置：
- Mac：/Library/Application\ Support/com.docker.docker/admin-settings.json
- Windows：C:\ProgramData\DockerDesktop\admin-settings.json
- Linux：/usr/share/docker-desktop/admin-settings.json
将此文件放置在受保护的目录中，开发人员将无法修改它。
重要
假定你可以通过设备管理软件（例如 Jamf）将 admin-settings.json 设置文件推送到指定位置。

第二步：配置要锁定的设置

注意
部分配置参数仅适用于特定平台或特定 Docker Desktop 版本。下表对此进行了说明。

admin-settings.json 文件需要一个嵌套的配置参数列表，其中每个参数都必须包含 locked 参数。你可以根据自己的要求添加或删除配置参数。

如果 locked: true，用户将无法从 Docker Desktop 或 CLI 编辑此设置。

如果 locked: false，则类似于设置出厂默认值，具体如下：

对于新安装，locked: false 会预填充 Docker Desktop 控制面板中的相关设置，但用户可以修改它。
如果 Docker Desktop 已经安装并正在使用，则会忽略 locked: false。这是因为 Docker Desktop 的现有用户可能已经更新了设置，这会写入相关的配置文件，例如 settings-store.json（或 Docker Desktop 4.34 及更早版本的 settings.json）或 daemon.json。在这种情况下，用户的偏好设置会受到尊重，并且值不会被更改。可以通过将 locked 设置为 true 来控制这些设置。

以下 admin-settings.json 代码和表格提供了参数和值所需语法和描述的示例：

{
  "configurationFileVersion": 2,
  "exposeDockerAPIOnTCP2375": {
    "locked": true,
    "value": false
  },
  "proxy": {
    "locked": true,
    "mode": "system",
    "http": "",
    "https": "",
    "exclude": [],
    "windowsDockerdPort": 65000,
    "enableKerberosNtlm": false
  },
  "containersProxy": {
    "locked": true,
    "mode": "manual",
    "http": "",
    "https": "",
    "exclude": [],
    "pac":"",
    "transparentPorts": ""
  },
  "enhancedContainerIsolation": {
    "locked": true,
    "value": true,
    "dockerSocketMount": {
      "imageList": {
        "images": [
          "docker.io/localstack/localstack:*",
          "docker.io/testcontainers/ryuk:*"
        ]
      },
      "commandList": {
        "type": "deny",
        "commands": ["push"]
      }
    }
  },
  "linuxVM": {
    "wslEngineEnabled": {
      "locked": false,
      "value": false
    },
    "dockerDaemonOptions": {
      "locked": false,
      "value":"{\"debug\": false}"
    },
    "vpnkitCIDR": {
      "locked": false,
      "value":"192.168.65.0/24"
    }
  },
  "kubernetes": {
     "locked": false,
     "enabled": false,
     "showSystemContainers": false,
     "imagesRepository": ""
  },
  "windowsContainers": {
    "dockerDaemonOptions": {
      "locked": false,
      "value":"{\"debug\": false}"
    }
  },
  "disableUpdate": {
    "locked": false,
    "value": false
  },
  "analyticsEnabled": {
    "locked": false,
    "value": true
  },
  "extensionsEnabled": {
    "locked": true,
    "value": false
  },
  "scout": {
    "locked": false,
    "sbomIndexing": true,
    "useBackgroundIndexing": true
  },
  "allowExperimentalFeatures": {
    "locked": false,
    "value": false
  },
  "allowBetaFeatures": {
    "locked": false,
    "value": false
  },
  "blockDockerLoad": {
    "locked": false,
    "value": true
  },
  "filesharingAllowedDirectories": [
    {
      "path": "$HOME",
      "sharedByDefault": true
    },
    {
      "path":"$TMP",
      "sharedByDefault": false
    }
  ],
  "useVirtualizationFrameworkVirtioFS": {
    "locked": true,
    "value": true
  },
  "useVirtualizationFrameworkRosetta": {
    "locked": true,
    "value": true
  },
  "useGrpcfuse": {
    "locked": true,
    "value": true
  },
  "displayedOnboarding": {
    "locked": true,
    "value": true
  },
  "desktopTerminalEnabled": {
    "locked": false,
    "value": false
  }
}

常规

参数	操作系统	描述	版本
`configurationFileVersion`		指定配置文件的格式版本。
`analyticsEnabled`		如果 `value` 设置为 false，Docker Desktop 不会向 Docker 发送使用统计信息。
`disableUpdate`		如果 `value` 设置为 true，则禁用 Docker Desktop 更新的检查和通知。
`extensionsEnabled`		如果 `value` 设置为 false，则禁用 Docker 扩展。
`blockDockerLoad`		如果 `value` 设置为 `true`，用户将无法再运行 `docker load`，并且尝试时会收到错误。
`displayedOnboarding`		如果 `value` 设置为 `true`，新用户将不会看到入职调查。将 `value` 设置为 `false` 没有效果。	Docker Desktop 4.30 及更高版本
`desktopTerminalEnabled`		如果 `value` 设置为 `false`，开发人员将无法使用 Docker 终端与主机交互并直接从 Docker Desktop 执行命令。
`exposeDockerAPIOnTCP2375`	仅限 Windows	在指定端口上公开 Docker API。如果 `value` 设置为 true，Docker API 将在端口 2375 上公开。注意：这没有经过身份验证，只有在受到适当防火墙规则保护的情况下才能启用。

参数	操作系统	描述	版本
`filesharingAllowedDirectories`		指定开发人员可以添加文件共享的路径。也接受 `$HOME`、`$TMP` 或 `$TEMP` 作为 `path` 变量。添加路径后，其子目录也允许共享。如果 `sharedByDefault` 设置为 `true`，该路径将在恢复出厂设置或首次启动 Docker Desktop 时添加。
`useVirtualizationFrameworkVirtioFS`	仅限 macOS	如果 `value` 设置为 `true`，则将 VirtioFS 设置为文件共享机制。注意：如果 `useVirtualizationFrameworkVirtioFS` 和 `useGrpcfuse` 的 `value` 都设置为 `true`，则 VirtioFS 优先。同样，如果 `useVirtualizationFrameworkVirtioFS` 和 `useGrpcfuse` 的 `value` 都设置为 `false`，则将 osxfs 设置为文件共享机制。
`useGrpcfuse`	仅限 macOS	如果 `value` 设置为 `true`，则将 gRPC Fuse 设置为文件共享机制。
`useVirtualizationFrameworkRosetta`	仅限 macOS	如果 `value` 设置为 `true`，Docker Desktop 会开启 Rosetta 以加速 Apple Silicon 上 x86_64/amd64 二进制文件的模拟。注意：这也会自动启用 `Use Virtualization framework`。	Docker Desktop 4.29 及更高版本。

Docker Scout

参数	操作系统	描述	版本
`scout`		将 `useBackgroundIndexing` 设置为 `false` 会禁用加载到镜像存储的镜像的自动索引。将 `sbomIndexing` 设置为 `false` 会阻止用户通过在 Docker Desktop 中检查镜像或使用 `docker scout` CLI 命令来索引镜像。

代理

参数	操作系统	描述	版本
`proxy`		如果 `mode` 设置为 `system` 而不是 `manual`，Docker Desktop 将从系统中获取代理值，并忽略为 `http`、`https` 和 `exclude` 设置的值。将 `mode` 更改为 `manual` 以手动配置代理服务器。如果代理端口是自定义的，请在 `http` 或 `https` 属性中指定，例如 `"https": "http://myotherproxy.com:4321"`。`exclude` 属性指定一个逗号分隔的主机和域列表，这些主机和域将绕过代理。
`windowsDockerdPort`	仅限 Windows	将 Docker Desktop 的内部代理本地公开到此端口，供 Windows Docker 守护进程连接。如果设置为 0，则选择一个随机的空闲端口。如果值大于 0，则使用该确切值作为端口。默认值为 -1，表示禁用此选项。
`enableKerberosNtlm`		设置为 `true` 时，启用 Kerberos 和 NTLM 身份验证。默认为 `false`。有关更多信息，请参阅设置文档。	Docker Desktop 4.32 及更高版本。

容器代理

参数	操作系统	描述	版本
`containersProxy`		创建气隙容器。有关更多信息，请参阅气隙容器。	Docker Desktop 4.29 及更高版本。

Linux 虚拟机

参数	操作系统	描述
`linuxVM`		与 Linux 虚拟机选项相关的参数和设置 - 在此处分组以便于使用。
`wslEngineEnabled`	仅限 Windows	如果 `value` 设置为 true，Docker Desktop 将使用基于 WSL 2 的引擎。这将覆盖安装时使用 `--backend=<backend name>` 标志设置的任何内容。
`dockerDaemonOptions`		如果 `value` 设置为 true，它将覆盖 Docker Engine 配置文件中的选项。请参阅Docker Engine 参考。请注意，为增强安全性，启用增强容器隔离 (Enhanced Container Isolation) 后可能会覆盖部分配置属性。
`vpnkitCIDR`		覆盖用于 `*.docker.internal` 的 vpnkit DHCP/DNS 的网络范围

Windows 容器

参数	操作系统	描述	版本
`windowsContainers`		与 `windowsContainers` 选项相关的参数和设置 - 为方便起见在此处分组。
`dockerDaemonOptions`		覆盖 Linux daemon 配置文件中的选项。请参阅Docker Engine 参考。

注意
此设置无法通过 Docker Admin Console 进行配置。

Kubernetes

参数	操作系统	描述	版本
`kubernetes`		如果 `enabled` 设置为 true，则在 Docker Desktop 启动时会启动一个 Kubernetes 单节点集群。如果 `showSystemContainers` 设置为 true，则 Kubernetes 容器将在 Docker Desktop Dashboard 和运行 `docker ps` 时显示。`imagesRepository` 允许指定 Docker Desktop 从哪个仓库拉取 Kubernetes 镜像。例如，`"imagesRepository": "registry-1.docker.io/docker"`。

注意
使用 imagesRepository 设置和增强容器隔离 (ECI) 时，将以下镜像添加到ECI Docker socket 挂载镜像列表
<custom-image-repo>/desktop-cloud-provider-kind:* <custom-image-repo>/desktop-containerd-registry-mirror:*
这些容器会挂载 Docker socket，因此必须将这些镜像添加到 ECI 镜像列表。否则，ECI 将阻止挂载，并且 Kubernetes 将无法启动。

开发中的功能

参数	操作系统	描述	版本
`allowExperimentalFeatures`		如果 `value` 设置为 `false`，则实验性功能将被禁用。
`allowBetaFeatures`		如果 `value` 设置为 `false`，则 Beta 功能将被禁用。
`enableDockerAI`		如果 `value` 设置为 `false`，则 Docker AI (Ask Gordon) 功能将被禁用。

增强容器隔离

参数	操作系统	描述	版本
`enhancedContainerIsolation`		如果 `value` 设置为 true，Docker Desktop 将通过 Linux 用户命名空间运行所有容器，将其作为非特权容器，防止它们修改 Docker Desktop VM 内的敏感配置，并使用其他高级技术隔离它们。有关更多信息，请参阅增强容器隔离 (Enhanced Container Isolation)。
`dockerSocketMount`		默认情况下，增强容器隔离会阻止将 Docker Engine socket 绑定挂载到容器中（例如，`docker run -v /var/run/docker.sock:/var/run/docker.sock ...`）。这允许您以受控方式放宽此限制。有关更多信息，请参阅ECI 配置。
`imageList`		指示允许哪些容器镜像绑定挂载 Docker Engine socket。
`commandList`		限制容器通过绑定挂载的 Docker Engine socket 可发出的命令。

第三步：重新启动 Docker Desktop

注意
在本地测试通过 admin-settings.json 文件所做的更改，以查看设置是否按预期工作。

要使设置生效

在新安装的情况下，开发人员需要启动 Docker Desktop 并对其组织进行身份验证。
在现有安装的情况下，开发人员需要通过 Docker 菜单退出 Docker Desktop，然后重新启动 Docker Desktop。如果他们已登录，则无需再次登录即可使更改生效。
重要
从 Docker 菜单选择 Restart (重启) 是不够的，因为它只重启了 Docker Desktop 的部分组件。

为了不中断开发人员的工作流程，Docker 不会在更改完成后自动要求开发人员重新启动并重新进行身份验证。

在 Docker Desktop 中，开发人员会看到相关设置呈灰色显示（不可编辑）。