先明确：Cursor 与 Docker 的正确组合方式

Cursor 是面向开发者的 AI 编程工具，本身更接近桌面开发客户端。它并不等同于一个可直接放进容器长期运行的 Web 服务。

因此，所谓 Docker 部署，更推荐理解为：用 Docker 快速搭建统一的远程开发环境，再让 Cursor 连接进去写代码、运行项目和调试依赖。

这样做的好处是：环境可复制、依赖不污染本机、团队成员配置一致，升级和回滚也更容易控制。

常见适用场景包括：

• 新电脑不想反复安装 Node、Python、Java 等依赖。
• 团队项目需要统一运行环境。
• 希望把开发环境部署在云主机或内网服务器上。
• 需要在不同版本依赖之间快速切换。

若只是个人本机写少量代码，直接安装 Cursor 客户端即可，没必要为了“容器化”增加复杂度。

准备工作：系统、Docker 与目录规划

开始前需要准备一台 Linux、macOS 或 Windows 设备。Windows 用户建议启用 WSL2 后再使用 Docker Desktop。Linux 用户可安装 Docker Engine 与 Compose 插件。

安装完成后，执行 docker version 和 docker compose version。能正常显示版本信息，说明基础环境可用。

建议为项目单独建立目录，例如 /opt/cursor-dev 或用户目录下的 cursor-dev。

目录中至少包含三类内容：

• 项目代码目录 workspace
• 容器配置文件 docker-compose.yml
• 可选的 Dockerfile

不要把 SSH 私钥、服务令牌、生产配置直接写进镜像文件。敏感信息应放在本机安全位置，通过环境变量或挂载方式临时传入。

方案一：用 Docker Compose 创建远程开发容器

这是最稳妥的部署方式。思路是创建一个带有常用开发依赖和 SSH 服务的容器，将项目目录挂载进去，再用 Cursor 的 Remote SSH 能力连接。

第一步：在项目目录下新建 Dockerfile。基础镜像可选择 ubuntu:22.04、node:20、python:3.11 等。镜像内安装 git、curl、openssh-server、sudo、常用编译工具。并创建普通开发用户，避免长期使用 root。

第二步：编写 docker-compose.yml。核心配置包括：

• 指定 build 或 image
• 挂载 ./workspace 到容器内 /workspace
• 映射 SSH 端口，例如宿主机 2222 对应容器 22
• 设置容器名称，如 cursor-dev
• 配置 restart: unless-stopped

如项目需要数据库或缓存，可单独增加服务，但不要把所有组件都塞进一个容器。

第三步：启动环境。进入配置目录后执行 docker compose up -d --build。首次构建时间取决于基础镜像和依赖数量。

启动后执行 docker ps 查看容器状态，再执行 docker logs cursor-dev 检查 SSH 服务是否正常。如果日志中没有明显报错，就可以进入连接阶段。

在 Cursor 中连接容器环境

打开 Cursor 后，安装或启用 Remote SSH、Dev Containers 相关能力（具体名称会随版本略有变化）。

使用 SSH 方式时，连接地址通常为 user@主机地址，端口填写 2222。若是本机容器，主机地址可用 127.0.0.1；若是远程服务器，则填写服务器地址。首次连接会提示确认主机指纹，确认来源无误后再继续。

连接成功后，在 Cursor 中打开 /workspace 目录即可开始开发。项目依赖建议在容器内安装，例如 npm install、pip install、mvn install 等。这样本机只承担编辑和交互工作，实际运行环境都在容器中。

若需要调试端口，例如前端 3000、后端 8000，应在 compose 文件中提前映射端口，并确认本机防火墙规则允许访问。

方案二：Dev Containers 更适合团队协作

如果团队成员都使用相似的编辑器生态，可以在项目中加入 .devcontainer 目录。把开发镜像、依赖安装命令、启动后脚本写成标准配置。

Cursor 打开项目后，可根据提示重新在容器中打开工作区。它的优势是配置跟随代码仓库，成员拉取项目后无需口头传递环境步骤。

这种方式更适合长期项目。建议把基础镜像版本写死，例如 node:20.11 或 python:3.11-slim，而不是长期使用 latest。latest 看似省事，实际会导致不同时间构建出来的环境不一致，排查问题时很难复现。

更新升级：先备份，再替换，再验证

升级分两类：Cursor 客户端升级和Docker 开发环境升级。

客户端升级通常通过官方安装包或内置更新完成。升级前建议关闭正在运行的任务，确认项目代码已提交或备份。

容器环境升级则更需要流程化，尤其是涉及语言运行时、系统库、数据库客户端版本时。

推荐升级步骤如下：

• 第一，备份 docker-compose.yml、Dockerfile、.devcontainer 目录以及重要环境变量文件。
• 第二，记录当前镜像标签和容器 ID（可执行 docker images 与 docker ps -a 查看）。
• 第三，在单独分支或复制目录中修改镜像版本。
• 第四，执行 docker compose build --no-cache 重新构建。
• 第五，用 docker compose up -d 启动。
• 第六，运行项目测试、依赖检查和关键功能验证。

如果项目数据存放在数据卷中，升级前还要确认卷的位置和备份方式。代码目录可以通过 Git 管理，但数据库文件、上传文件、缓存索引等并不一定在代码仓库里。误删容器或卷可能造成不可恢复的损失。

回滚方案：固定版本与保留旧镜像

可回滚的前提是升级前有记录。最简单的做法是在 compose 文件中固定镜像标签，并在升级前保留旧镜像。

若新版本异常，先执行 docker compose down 停止当前服务，再把配置中的镜像标签改回旧版本，随后执行 docker compose up -d。若旧镜像仍在本机，启动会很快；若已被清理，则需要重新拉取或重新构建。

对于自定义 Dockerfile，建议通过 Git 管理配置文件。每次升级依赖前提交一次变更，出现问题时直接回到上一个提交。

注意：若使用数据卷，回滚应用版本不等于回滚数据结构。特别是数据库迁移之后，旧版本程序可能无法读取新结构。因此升级前应确认是否有迁移脚本，必要时在测试环境先演练。

疑难排查：常见问题与处理思路

问题一：docker compose up 后容器立即退出。
先执行 docker logs 容器名 查看日志。常见原因是启动命令写错、SSH 服务未启动、配置文件格式错误。可以临时将 command 改为 sleep infinity，让容器保持运行后再进入内部排查。

问题二：Cursor 连接不上容器。
优先检查端口映射是否正确（例如 2222:22）；再检查宿主机端口是否被占用；随后确认容器内 sshd 是否运行。若使用密钥登录，要检查 authorized_keys 权限：用户目录通常为 700，authorized_keys 通常为 600。

问题三：容器内能运行，本机访问不到服务。
检查应用监听地址是否为 0.0.0.0。有些开发服务默认只监听 127.0.0.1，在容器内可访问，但宿主机无法访问。还要确认 compose 中已映射对应端口（例如 3000:3000）。

问题四：依赖安装很慢或经常失败。
可为包管理器配置稳定的软件源，并利用 Docker 构建缓存。不要在每次启动容器时重复安装全部依赖。推荐把基础依赖写进镜像，把项目依赖放在明确的安装步骤中。

问题五：文件权限混乱。
宿主机挂载目录到容器后，容器用户与本机用户 ID 不一致，可能导致文件无法修改。解决办法是在 Dockerfile 中创建与宿主机相同 UID 的用户，或在 compose 中指定 user。不要为了省事长期使用最高权限运行开发容器。

安全边界与实用建议

开发容器不是天然安全隔离区。

• 不要把生产密钥、正式环境配置、客户数据直接放入容器镜像。
• 不要将 SSH 端口暴露到不可信网络。
• 不要使用弱口令。
• 不要把 Docker 管理权限随意开放给无关用户。

若必须远程连接，应限制来源地址，并使用密钥登录。

镜像来源也要谨慎。优先使用官方镜像或可信团队维护的基础镜像，避免使用来历不明、长期无人维护的镜像。定期执行镜像漏洞扫描，或至少关注基础镜像更新记录。

清理镜像时，不要盲目执行会删除卷的命令，删除前先确认数据是否已备份。

总体建议：

• 个人使用可采用 Compose 快速搭建。
• 团队项目优先使用 Dev Containers。
• 升级时固定版本、保留旧配置。
• 回滚时先停服务，再恢复标签。
• 遇到连接问题，按“容器状态、端口映射、服务进程、权限配置”的顺序排查。

把这些流程固化下来，Cursor 与 Docker 的组合会成为稳定、高效、可复制的 AI 编程工作台。