本地 PyCharm / Docker CLI 远程连接懒猫 Docker 的完整方案

不安装 Docker Desktop · Win11 & macOS 通用

---

一句话总结

通过 Docker CLI + SSH Unix Socket 转发，在 不安装 Docker Desktop、不破坏懒猫 Playground 的前提下，实现 Win11 / macOS + PyCharm 对远程 Docker（pg-docker / lzc-docker）的完整开发支持。

---

一、总体架构

🎯 目标

• 本地只装 Docker CLI（不装 Docker Desktop）
• Docker 守护进程永远在 懒猫 NAS
• PyCharm / CLI / Compose 都能用
• 不改、不破坏 懒猫 Playground

🧠 架构图

┌────────────────────────┐
│ 本地（Win11 / macOS）    │
│                        │
│ docker CLI + PyCharm   │
│   docker.exe / docker  │
└──────────┬─────────────┘
           │host=ssh://root@lazycat
           │
           │ unix socket
           │
┌──────────▼─────────────┐
│ 懒猫 NAS               │
│ pg-docker / lzc-docker │
│ docker.sock            │
└───────��────────────────┘

🔑 核心概念

组件	角色	类比
docker / docker.exe	客户端 CLI	遥控器 🎮
dockerd（懒猫上运行）	服务端 守护进程	电视机 📺

📌 本地不需要 dockerd，守护进程跑在懒猫 NAS 上。

---

二、本地环境准备（只装 Docker CLI）

✅ Windows 11

1. 下载 Docker CLI（官方静态二进制）

下载地址：https://download.docker.com/win/static/stable/x86_64/

解压后只需保留 docker.exe，其他文件（dockerd.exe 等）不需要，可删除。

2. 放置目录

D:\software\docker\docker.exe

3. 配置环境变量

PowerShell 中执行（只需一次）：

# 将 docker 目录加入当前用户的 PATH 环境变量（永久生效）
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";D:\software\docker", "User")

📌 执行后需要重新打开终端才生效。

📌 这等同于手动操作：系统设置 → 搜索"环境变量" → 编辑用户 PATH → 新建 → 输入路径。

4. 安装 Docker Compose V2 插件

静态包里不含 Compose 插件，需要手动安装。

前往 https://github.com/docker/compose/releases 下载：

docker-compose-windows-x86_64.exe

放到 CLI 插件目录：

# 创建插件目录
mkdir "$env:USERPROFILE\.docker\cli-plugins" -Force

# 复制并重命名（文件名必须是 docker-compose.exe）
Copy-Item "$env:USERPROFILE\Downloads\docker-compose-windows-x86_64.exe" `
          "$env:USERPROFILE\.docker\cli-plugins\docker-compose.exe"

5. 最终目录结构

D:\software\docker\
├── docker.exe                          # CLI 客户端

C:\Users\<用户名>\.docker\
├── contexts\                           # docker context 配置
└── cli-plugins\
    └── docker-compose.exe              # Compose V2 插件

6. 验证

docker version
docker compose version

✅ macOS（Intel / Apple Silicon 通用）

brew install docker

📌 Homebrew 会自动安装 CLI + Compose 插件，不会安装 Docker Desktop，也不会安装 dockerd。

验证：

docker version
docker compose version

两平台对比

项目	macOS（Homebrew）	Windows（手动下载静态包）
docker CLI	✅ 自动装好	✅ 手动放置
docker compose 插件	✅ 自动装好	⚠️ 需要手动装
dockerd 守护进程	❌ 不装（不需要）	⚠️ 包里自带（可删除，省 ~84MB）

---

三、懒猫侧：不破坏 Playground

✅ 原则

做法	说明
❌ 不直接暴露 Docker TCP	避免安全风险
❌ 不改默认 docker.service	保持系统完整
✅ pg-docker / lzc-docker 原样运行	零侵入

确认 pg-docker socket 存在

ls -l /lzcsys/data/playground/docker.sock

确保文件存在即可，无需额外操作。

---

四、SSH 免密 + 端口转发配置（关键）

1. 生成专用密钥（如尚未创建）

ssh-keygen -t ed25519 -f ~/.ssh/id_lazycat_ed25519 -C "lazycat-docker"

将公钥添加到懒猫：

ssh-copy-id -i ~/.ssh/id_lazycat_ed25519.pub root@name.heiyu.space

2. 本地 ~/.ssh/config（Win11 / macOS 通用）

# ===== 全局默认 =====
Host *
    AddKeysToAgent yes
    UseKeychain yes
    
# ===== 懒猫微服（通用连接） =====
Host lazycat
    HostName name.heiyu.space
    User root
    IdentityFile ~/.ssh/id_lazycat_ed25519
    IdentitiesOnly yes

---

五、Docker Context 配置（一次性）

创建并切换

# 创建 context（只需执行一次）
docker context create pg-docker \
  --docker "host=ssh://root@lazycat"

# 如果 socket 不是默认路径：
docker context create pg-docker \
  --docker "host=ssh://root@lazycat/lzcsys/data/playground/docker.sock"

# 切换：
docker context use pg-docker
docker ps

📌 docker context create 和 docker context use 都是一次性操作，配置会持久化保存到 ~/.docker/contexts/。

📌 重启电脑后不需要重新执行，直接 docker ps 即可。

什么时候需要重新创建？

• 换了端口（如 23750 → 23760）
• 重装了系统（~/.docker/ 目录丢失）
• 需要修改配置

# 删掉重建
docker context rm pg-docker
docker context create pg-docker --docker "host=ssh://root@lazycat"
docker context use pg-docker

---

七、PyCharm Docker 配置

进入 Settings → Build, Execution, Deployment → Docker：

配置项	值
Docker 可执行文件	D:\software\docker\docker.exe（Win） / docker（macOS）
Engine API URL	host=ssh://root@lazycat
自动检测	❌ 不勾选
Docker Compose 可执行文件	留空 或 填 docker（不要填 docker.exe 的完整路径）

点击 Test Connection → 显示 ✅ 即成功。

⚠️ 常见报错：unknown flag: --short

原因：旧版 PyCharm 的 Docker 插件内部调用 docker version --short，但此参数在 Docker CLI v25+ 已被移除。

解决方案（按优先级）：

1.升级 PyCharm → Help → Check for Updates（推荐，新版已修复）
2. 使用包装脚本绕过（兜底方案）：

保存为 D:\software\docker\docker-wrapper.bat：

@echo off
setlocal
echo %* | findstr /C:"version --short" >nul
if %errorlevel%==0 (
    D:\software\docker\docker.exe --version
    exit /b 0
)
D:\software\docker\docker.exe %*

然后把 PyCharm 的 Docker 可执行文件指向 D:\software\docker\docker-wrapper.bat。

Docker Compose 使用

PyCharm 的 Docker Compose 会自动走当前 context，docker-compose.yml 正常编写即可：

services:
  app:
    build: .
    ports:
      - "8000:8000"

---

八、增强方案：同时支持多套 Docker

场景说明

Docker 实例	Socket 路径	本地端口	用途
pg-docker	/lzcsys/data/playground/docker.sock	23750	开发环境（推荐）
lzc-docker	/lzcsys/run/lzc-docker/docker.sock	23751	系统服务

多 Context 管理

# 创建
docker context create pg-docker \
  --docker "host=ssh://root@lazycat/lzcsys/data/playground/docker.sock"

docker context create lzc-docker \
  --docker "host=ssh://root@lazycat/lzcsys/run/lzc-docker/docker.sock"

# 切换
docker context use pg-docker    # 开发
docker context use lzc-docker   # 系统服务

# 查看所有 context
docker context ls