使用 JSON 檔案配置設定管理
本頁面包含有關如何使用 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
設定檔案推送到指定位置。- Mac:
第二步:配置要鎖定的設定
注意
部分配置引數僅適用於特定平臺或特定 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 中,開發人員會看到相關設定呈灰色顯示(不可編輯)。