tkopen/pycharm Docker 镜像 - 轩辕镜像

PyCharm Community Edition Docker容器

本Docker容器提供了一种快速简便的方式来运行或试用PyCharm Community Edition。它支持CPU和GPU两种配置，并可选集成TensorFlow与Jupyter Notebook。项目源代码托管于GitLab仓库。

本文档兼顾初级和资深用户需求：初学者可参考带解释的分步说明，资深用户可快速浏览或直接跳转至高级主题。重要提示：请始终参考官方文档获取最新说明。本文仅为方便提供摘要，完整细节及故障排除请访问文中链接的官方网站。

目录

• 基础镜像标签
• 可选功能
  • 在主机上启用GPU支持
• 安装Docker引擎
• 快速测试镜像（无持久化）
• 安装Docker Compose插件
• 使用Docker Compose进行持久化配置
• 提示与技巧
• 支持
• 贡献
• 参考文档

基础镜像标签

我们提供两种主要镜像变体：

1. 仅CPU：预安装PyCharm Community Edition，适用于无需GPU加速的常规开发。
2. GPU加速：包含PyCharm、TensorFlow及Jupyter Notebook服务器。基于官方TensorFlow镜像构建，要求CPU支持AVX指令集（大多数现代CPU均支持；如遇问题，请参考TensorFlow issue #***）。

镜像版本说明

• CPU镜像：2023年3月后构建的版本基于Ubuntu 22.04 LTS，2025年7月后构建的版本基于Ubuntu 24.04 LTS（标签中已包含Ubuntu版本以明确区分）。
• GPU镜像：基于官方TensorFlow Docker镜像的基础系统，TensorFlow 2.19.0对应Ubuntu 22.04 LTS。

标签格式

• CPU标签：:cpu-<ubuntu_version>-<pycharm_version>（如:cpu-24.04-2025.1.3.1），仅预安装PyCharm。
• GPU标签：:gpu-<tensorflow_version>-jupyter-<pycharm_version>（如:gpu-2.19.0-jupyter-2025.1.3.1），包含PyCharm、TensorFlow及Jupyter Notebook。
• 最新标签：:cpu（最新CPU镜像）或:gpu（最新GPU镜像）。已弃用标签（如-devel、-custom-op、-latest）不再支持。

Python版本说明

所有镜像均仅使用Python 3（版本因基础系统而异）：

• Ubuntu 22.04的CPU镜像：Python 3.8
• Ubuntu 24.04的CPU镜像：Python 3.12
• GPU镜像（基于TensorFlow官方镜像）：Python 3.11

可选功能

GPU标签

基于TensorFlow官方Docker镜像和NVIDIA CUDA构建，需安装NVIDIA Docker以支持GPU。注意：对于TensorFlow 1.13+（含最新标签），需确保NVIDIA驱动支持CUDA 10及以上版本——详见NVIDIA CUDA兼容性矩阵。

GPU镜像包含Jupyter Notebook服务器及TensorFlow示例教程，默认启动Jupyter。如需持久化Notebook，需将卷挂载至/tf/notebooks（详见下文示例）。也可配置容器启动时直接运行PyCharm，随后从PyCharm终端手动启动Jupyter（操作步骤见后）。

在主机上启用GPU支持

如需运行GPU加速容器，需在主机系统（如Ubuntu 24.04）安装NVIDIA Container Toolkit，使Docker能够访问NVIDIA GPU。

1. 添加NVIDIA Container Toolkit仓库：

   sh
   curl -fsSL [***] | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
   curl -s -L [***] | \
     sed 's#deb [***] [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] [***] | \
     sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
   

2. 更新并安装：

   sh
   sudo apt-get update
   sudo apt-get install -y nvidia-container-toolkit
   

3. 配置Docker：

   sh
   sudo nvidia-ctk runtime configure --runtime=docker
   sudo systemctl restart docker
   

4. 验证安装： 运行测试容器确认GPU可访问：

   sh
   docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi
   

   成功执行后将显示GPU详情。

更多细节参见NVIDIA Container Toolkit安装指南。

安装Docker引擎

运行本容器需安装Docker Engine。重要提示：如需最新、最准确的安装步骤，请访问官方Docker Engine安装指南。下文为Ubuntu系统的简要说明——请根据实际操作系统参考官方文档。

常用Docker包有两种：docker.io（Ubuntu官方仓库）和docker-ce（Docker官方维护）。

docker.io（Ubuntu维护）

• 优点：稳定性更高，但版本更新较慢。
• 缺点：功能及安全修复更新滞后。
• 安装命令：

  sh
  sudo apt-get update
  sudo apt-get install docker.io
  

docker-ce（Docker维护，推荐大多数用户）

• 优点：含最新功能，更新频繁。
• 缺点：在Ubuntu特定环境中测试可能较少。
• 安装命令：

  sh
  sudo apt-get update
  sudo apt-get install ca-certificates curl gnupg lsb-release
  curl -fsSL [***] | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] [***] $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  sudo apt-get update
  sudo apt-get install docker-ce docker-ce-cli containerd.io
  

安装后配置

安装完成后：

1. 将当前用户添加至docker用户组：sudo usermod -aG docker $USER。
2. 登出并重新登录（或执行newgrp docker）使配置生效。
3. 验证：运行id确认用户组已添加，再执行docker stats测试Docker是否正常运行。

如遇问题，参见官方Docker Engine文档。

快速测试镜像（无持久化）

以下命令用于临时测试容器，退出后数据将丢失。如需持久化配置，建议使用Docker Compose（详见下文）。

仅CPU（直接启动PyCharm）

sh
docker run -it --rm \
  -e DISPLAY=unix$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  tkopen/pycharm:cpu pycharm

• -it：以交互式终端模式运行
• --rm：容器退出后自动删除
• -e DISPLAY=unix$DISPLAY：传递主机显示环境变量
• -v /tmp/.X11-unix:/tmp/.X11-unix：挂载X11套接字，实现图形界面显示

GPU（启动PyCharm；需手动启动Jupyter）

sh
docker run -it --rm --gpus all \
  -e DISPLAY=unix$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -p 8888:8888 \
  tkopen/pycharm:gpu pycharm

• --gpus all：启用所有GPU
• -p 8888:8888：映射Jupyter默认端口

从PyCharm终端启动Jupyter：

sh
jupyter notebook --notebook-dir=/home/coder --ip 0.0.0.0 --no-browser --allow-root

通过http://localhost:8888访问Jupyter（终端输出中包含登录令牌）。

持久化Notebook（GPU示例）

sh
docker run -it --rm --gpus all \
  -e DISPLAY=unix$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v $HOME/my_notebooks:/tf/notebooks \
  -p 8888:8888 \
  tkopen/pycharm:gpu

• -v $HOME/my_notebooks:/tf/notebooks：将主机my_notebooks目录挂载至容器，实现Notebook持久化

持久化的重要性

未挂载卷时，PyCharm设置、代码及数据将在容器退出后丢失。需持久化的关键目录：

• /home/coder/.cache（缓存）
• /home/coder/.java（Java配置）
• /home/coder/.config/JetBrains（JetBrains配置）
• /home/coder/.local/share/JetBrains（JetBrains本地数据）
• /home/coder/workspace（工作区）

建议通过命令行卷挂载或Docker Compose实现持久化。

安装Docker Compose插件

Docker Compose通过YAML文件简化容器、卷及网络的管理。重要提示：详见官方Docker Compose安装指南获取最新步骤。

Ubuntu系统安装命令：

sh
sudo apt-get update
sudo apt-get install docker-compose-plugin

验证安装：docker compose version。

使用说明参见官方Docker Compose文档。

使用Docker Compose进行持久化配置

从GitLab仓库下载docker-compose.yml文件。

运行CPU容器：

sh
docker compose -f ~/path/to/docker-compose.yml up pycharm

运行GPU容器：

sh
docker compose -f ~/path/to/docker-compose.yml up pycharm-gpu

首次启动PyCharm时，将提示创建/打开项目，选择“打开”并指向/home/coder/workspace目录。

!PyCharm启动界面1

!PyCharm启动界面2

提示与技巧

错误：externally-managed-environment

• Python虚拟环境（Ubuntu 24.04及以上）：Ubuntu 24.04强制实施PEP 668，将系统Python（/usr/bin/python3）标记为“外部管理”，防止全局安装包与系统包冲突。直接运行python3 -m pip install <package>会触发error: externally-managed-environment错误。解决方案：
  • 执行source ~/.profile更新环境变量，随后通过python3 -m pip install <package>安装。
  • 或激活预创建的虚拟环境：source ~/.local/venv/bin/activate，之后可直接使用pip install <package>。
  • 验证：which python3应显示~/.local/venv/bin/python3。
  • PyCharm配置：在“设置 > 终端 > 外壳路径”中设置为/bin/bash -l。

初学者指南

• 守护进程模式：后台运行容器，添加-d参数：docker compose -f ~/path/to/docker-compose.yml up -d pycharm。停止容器：docker compose -f ~/path/to/docker-compose.yml down。
• Docker Hub登录：如遇“unauthorized”错误，执行docker login登录。可在hub.docker.com注册免费账户。
• X11权限：如PyCharm无法显示，执行xhost +local:docker允许Docker访问主机显示。
• Jupyter令牌获取：启动Jupyter时，终端会输出含令牌的URL（如[***]），复制令牌粘贴至浏览器登录。
• 容器状态检查：docker ps查看运行中容器，docker ps -a查看所有容器（含已停止）。

高级用户技巧

• 自定义docker-compose.yml：编辑YAML文件调整卷、端口或环境变量。例如，修改Jupyter端口：ports: ["8889:8888"]。
• 资源限制：在docker-compose.yml中添加CPU/内存限制（如deploy: resources: limits: cpus: "2" memory: "4g"）优化性能。
• GPU调试：GPU加速失败时，通过nvidia-smi验证CUDA兼容性，确保已安装nvidia-container-toolkit（sudo apt-get install nvidia-container-toolkit）。
• 版本固定：生产环境避免使用:cpu或:gpu标签（可能自动更新），建议使用具体版本标签（如:cpu-24.04-2025.1.3.1）。
• 清理资源：通过docker system prune（清理未使用镜像和容器）或docker volume prune（清理未使用卷）释放磁盘空间。

支持

通过GitLab项目issues页面提交问题。

贡献

欢迎提交贡献以提升跨操作系统的可用性，可通过GitLab提交合并请求。

参考文档

• Docker Engine官方文档
• Docker Compose官方文档
• Ubuntu安装Docker Compose
• 桌面环境中的Docker容器