PyCharm 如何配置远程 Docker 容器作为 Python 解释器？

在 PyCharm Professional 版中，可以通过 Docker 配置远程 Python 解释器，适合需要统一开发环境或依赖隔离的场景。核心在于通过 SSH 隧道安全连接远程 Docker 守护进程，避免直接暴露 TCP 端口带来的安全风险。

先说结论：该功能仅限 Professional 版，配置核心在于打通本地 PyCharm 与远程 Docker Daemon 的安全连接。

适合：团队环境统一、依赖复杂不愿本地污染、需要 Linux 环境调试的场景
先准备：远程服务器开启 SSH 服务并配置免密登录，本地安装 Docker 客户端（可选，PyCharm 内置即可）
验收：在 PyCharm 内运行脚本能成功打印输出，且远程容器处于运行状态
安全警告：严禁在公网环境直接暴露 Docker TCP 端口（2375），首选 SSH 隧道方案

前置准备：远程服务器配置

在使用 PyCharm 连接前，需确保远程服务器允许 SSH 免密登录，且当前用户有权限操作 Docker。

1. 配置 SSH 免密登录（推荐）

在本地终端生成密钥并复制到远程服务器：

# 生成本地密钥（一路回车即可）
ssh-keygen -t ed25519

# 将公钥部署到远程服务器（替换为实际用户和 IP）
ssh-copy-id user@192.168.1.100

2. 配置 Docker 用户权限

为避免每次操作都需要 sudo，将当前用户加入 docker 组：

# 在远程服务器执行
sudo usermod -aG docker $USER

# 刷新组权限（或重新登录）
newgrp docker

3. 防火墙配置

确保远程服务器开放 SSH 端口（默认 22），无需开放 Docker TCP 端口：

# Ubuntu/Debian (ufw)
sudo ufw allow 22/tcp

# CentOS/RHEL (firewalld)
sudo firewall-cmd `--permanent` `--add-service`=ssh
sudo firewall-cmd `--reload`

PyCharm 配置步骤

1. 添加 SSH 凭据（关键步骤）

在配置解释器前，需先在 PyCharm 中注册远程服务器连接：

打开 Settings (Mac 为 Preferences)。
导航至 Build, Execution, Deployment > Connection > SSH Configurations。
点击 + 号，填写远程服务器 Host、Username。
Auth type 选择 Key pair，导入本地生成的私钥（通常为 ~/.ssh/id_ed25519）。
点击 Test Connection 确保显示 Success，保存配置。

2. 添加 Docker 解释器

打开 Settings > Project > Python Interpreter。
点击右上角齿轮图标 > Add Interpreter > On Docker...。
Server：选择 SSH，并在下拉框中选择上一步配置好的 SSH 连接。
Docker image：输入远程服务器上的镜像名（如 python:3.9），PyCharm 会自动拉取。
Python interpreter path：保持默认（通常为 /usr/local/bin/python）。
点击 OK 完成配置。

验证是否生效

1. 在 PyCharm 中新建 Python 文件，输入 print("remote docker ok")。

2. 运行脚本，观察 Run 窗口是否有输出，且无报错。

3. 登录远程服务器，执行 docker ps，查看是否有 PyCharm 创建的容器处于 Up 状态。

高风险方案警告（TCP 暴露）

不建议使用。直接暴露 Docker TCP 端口（2375）without TLS 等同于给 root 权限。仅在内网隔离环境测试使用，且必须配置防火墙限制 IP。

若必须使用 TCP 连接，请在远程服务器修改 /etc/docker/daemon.json：

{
  "hosts": ["unix:///var/run/docker.sock", "tcp://127.0.0.1:2375"]
}

注意：绑定 0.0.0.0 会允许所有网卡访问，极易被扫描利用。务必配合防火墙限制访问源 IP：

# 仅允许特定本地 IP 访问 2375 端口
sudo ufw allow from 192.168.1.50 to any port 2375

常见坑与排查

Permission denied：远程容器内无法读取挂载代码。检查远程服务器文件权限，确保 Docker 用户有读取权限，或在 PyCharm 映射路径时检查权限设置。
Cannot connect to Docker daemon：SSH 连接成功但 Docker 不可用。确认远程用户已加入 docker 组（见前置准备步骤 2）。
Community 版限制：PyCharm Community Edition 不支持远程解释器功能，配置界面会缺失相关选项。
版本兼容性：本地 PyCharm 集成的 Docker 客户端版本与远程 Docker 服务端版本差异过大可能导致 API 调用失败，保持大版本一致较稳妥。

参考来源

JetBrains 官方文档，Remote development with Docker, URL: https://www.jetbrains.com/help/pycharm/remote-docker.html
Docker 官方安全建议，Protect the Docker daemon socket, URL: https://docs.docker.com/engine/security/