本指南适用于有极度洁癖，不喜欢电脑环境乱七八糟刚重装 Windows 家庭版的用户，从零开始配置 WSL2、Docker，并在容器中部署 MySQL、Python 应用，最终通过 CodeBuddy 的 SSH 远程连接像操作完整主机一样开发。

---

1. 系统准备（Windows 家庭版）

1.1 启用必要功能

以管理员身份打开 PowerShell，依次执行：

# 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 启用 WSL
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

1.2 检查 BIOS 虚拟化

重启电脑前，按 Ctrl+Shift+Esc 打开任务管理器 → 性能 → 确认“虚拟化”已启用。若未启用，重启进入 BIOS（通常 Del/F2/F10）开启 Intel VT-x 或 AMD SVM。

1.3 重启电脑

使更改生效。

---

2. 安装 WSL2 与 Ubuntu

2.1 下载并安装 WSL2 内核更新包

浏览器访问：https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi，下载后双击安装。

2.2 设置 WSL2 为默认版本

在普通 PowerShell 中执行：

wsl --set-default-version 2

2.3 安装 Ubuntu 22.04

wsl --install -d Ubuntu-22.04

安装完成后首次启动会提示创建用户名和密码（如用户名 dev，请牢记）。

---

3. 在 WSL2 中安装 Docker Engine

3.1 进入 WSL2 终端

wsl

3.2 安装依赖与 Docker 官方源

sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

3.3 安装 Docker Engine

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3.4 添加用户到 docker 组（免 sudo）

sudo usermod -aG docker $USER

退出并重新进入 WSL2 使组生效。

3.5 配置国内镜像加速（可选，但推荐）

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com",
    "https://docker.nju.edu.cn"
  ]
}
EOF
sudo service docker restart

验证：docker pull hello-world 应成功。

3.6 设置 Docker 开机自启（WSL2 每次需手动启动）

可加入 ~/.bashrc：

echo "sudo service docker start" >> ~/.bashrc

---

4. 创建项目并编写 docker-compose.yml

4.1 创建项目目录

mkdir -p ~/projects/myapp
cd ~/projects/myapp

4.2 编写 docker-compose.yml

nano docker-compose.yml

粘贴以下内容（根据需求修改密码）：

services:
  mysql:
    image: mysql:8.0
    container_name: myapp-mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: root123
      MYSQL_DATABASE: myapp
      MYSQL_USER: devuser
      MYSQL_PASSWORD: devpass123
    ports:
      - "3306:3306"
    volumes:
      - ./mysql-data:/var/lib/mysql
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

  python-dev:
    image: python:3.13-slim
    container_name: myapp-python
    restart: always
    working_dir: /app
    volumes:
      - ./code:/app
    ports:
      - "8000:8000"
      - "2222:22"
    command: ["bash", "-c", "pip install --upgrade pip && tail -f /dev/null"]

保存退出（Ctrl+X，Y，Enter）。

4.3 启动容器

docker compose up -d
docker compose ps

---

5. 进入 Python 容器配置 SSH 并提交镜像

5.1 进入容器

docker exec -it myapp-python bash

5.2 安装 SSH 服务并配置

apt update
apt install -y openssh-server
passwd root   # 设置密码（如 root123）
sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
sed -i 's/#PasswordAuthentication yes/PasswordAuthentication yes/' /etc/ssh/sshd_config
service ssh start
netstat -tlnp | grep 22   # 应显示监听 22

5.3 退出容器并提交镜像

exit
docker commit myapp-python myapp-python-ssh

5.4 修改 docker-compose.yml 使用新镜像

nano docker-compose.yml

将 python-dev 服务改为：

  python-dev:
    image: myapp-python-ssh
    container_name: myapp-python
    restart: always
    working_dir: /app
    volumes:
      - ./code:/app
    ports:
      - "8000:8000"
      - "2222:22"
    command: ["service", "ssh", "start", "-D"]

保存，重启容器：

docker compose down
docker compose up -d

5.5 测试 SSH 连接（在 WSL2 中）

ssh root@127.0.0.1 -p 2222

输入密码，应能登录容器。

---

6. 在容器中部署 Python 项目（以 study-notes（这里是我自己的仓库代码，到这已经可以在容器内写代码了，接着跳到7.1） 为例）

6.1 进入容器并拉取代码

docker exec -it myapp-python bash
cd /app
git clone https://gitee.com/Dengjunxin/study-notes.git

6.2 安装 Python 依赖

cd /app/study-notes/PythonStudy/emp
pip install fastapi uvicorn sqlalchemy pymysql pydantic python-dotenv

6.3 修复导入路径（因项目内使用了绝对导入）

sed -i 's/from PythonStudy.emp.model/from model/g' service/employee.py

6.4 修改数据库连接（将 localhost 改为 MySQL 服务名）

cat > database/db.py << 'EOF'
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

DATABASE_URL = "mysql+pymysql://devuser:devpass123@mysql:3306/myapp"
engine = create_engine(DATABASE_URL, echo=True)
Session = sessionmaker(bind=engine)
Base = declarative_base()

def get_session():
    session = Session()
    try:
        yield session
    finally:
        session.close()
EOF

6.5 启动 FastAPI 应用

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

访问 http://127.0.0.1:8000/docs 可看到自动生成的 API 文档。

---

7. CodeBuddy SSH 远程连接配置

7.1 在 CodeBuddy 中打开远程连接

点击左侧“远程资源管理器”或使用 Ctrl+Shift+P → “Remote-SSH: Connect to Host…”。

7.2 输入连接信息

在输入框中填写：

root@127.0.0.1:2222

然后按提示输入密码（即之前设置的 root 密码）。

7.3 连接成功

连接后，CodeBuddy 左侧文件浏览器将显示容器内的文件系统，终端也可直接执行容器内命令，如同操作远程服务器。

---

8. 保持持久化与后续维护

8.1 代码挂载

已在 docker-compose.yml 中挂载 ./code:/app，因此你在 WSL2 的 ~/projects/myapp/code 中编辑文件，容器内 /app 会自动同步。建议将 git 仓库克隆到该目录。

8.2 容器内修改后提交镜像

若在容器内安装了新软件或更改了配置，可再次提交：

docker commit myapp-python myapp-python-ssh:latest

然后重启容器即可保留更改。

---

常见问题及解决

问题	解决方案
docker pull 超时	配置国内镜像加速（见 3.5）
SSH 连接被拒绝	确保容器内 service ssh start 已运行；检查端口映射 2222:22
MySQL 连接失败	检查 database/db.py 中 host 为 mysql（服务名）而非 localhost
容器重启后修改丢失	使用 docker commit 提交新镜像，并更新 compose 的 image 标签

---

现在你已拥有一个完全可控的开发环境，所有服务运行在容器中，Windows 宿主机干净整洁。