本文记录 Windows 上安装 Docker Desktop、理解 WSL 2、迁移存储，以及通过 Docker Compose 部署 Redis 并接入 Spring Boot 的操作过程。面向本机开发学习，假设 Spring Boot 在 Windows 的 IDEA 中运行。

整理日期：2026-10-24。界面可能随版本变化。Redis 使用 7.4 系列作为示例，不代表最新版；需严格复现时固定补丁版本或镜像 digest。密码均为占位示例。

一、理解 Docker、WSL 与 Redis

1. WSL 是什么

WSL（Windows Subsystem for Linux）让 Windows 可以运行 Linux 环境。Ubuntu 是其中一种可安装的 Linux 发行版。

  • WSL 1 使用系统调用兼容方式。
  • WSL 2 使用实际 Linux 内核和轻量虚拟机，适合 Linux 容器。
  • WSL 是运行基础，Ubuntu 是具体发行版，两者不是同一个概念。
  • WSL 2 的 Linux 文件通常保存于动态增长的 VHDX 虚拟磁盘。

2. Docker 的几个概念

名称 作用
镜像 Image 创建容器的模板，例如 redis:7.4
容器 Container 镜像启动后的运行实例
Engine 管理和运行容器的服务
Docker Desktop Windows 桌面应用，集成引擎、CLI 和 Compose 等
Compose 使用 YAML 描述并管理服务
Volume 独立于容器生命周期保存数据
Bind mount 将宿主机具体文件或目录映射进容器

容器共享 Linux 运行环境的内核，不是每个容器都安装一套完整虚拟机。

3. 它们如何配合

1
2
3
4
5
6
7
Windows IDEA / Spring Boot
       ↓ 127.0.0.1:6379
Docker Desktop 发布的端口
       ↓ WSL 2 后端
Redis Linux 容器
       ↓ /data
Docker 命名卷

Docker Desktop 可通过 WSL 2 后端运行 Linux 容器，并不要求额外安装个人 Ubuntu 发行版。安装 Ubuntu 主要用于学习 Linux 或在 WSL 内开发。

使用 Docker Desktop 时，不必再在 Ubuntu 安装独立 Docker Engine；也不需要在 Windows、Ubuntu 和容器中各安装一套 Redis，否则容易出现多个实例与端口冲突。

二、安装与检查 WSL 2

已经安装的电脑先检查，无需重复安装。以下命令均在 Windows PowerShell 执行。

1. 前置条件

  • 系统版本满足当前 Docker Desktop 官方安装要求。
  • 任务管理器 → 性能 → CPU 中“虚拟化”为已启用。
  • 未启用时按电脑厂商说明，到 BIOS/UEFI 开启 Intel VT-x 或 AMD-V。

2. 安装

管理员 PowerShell：

1
wsl --install

按提示重启电脑。首次启动 Ubuntu 时创建 Linux 用户名和密码；输入 Linux 密码时不显示字符属于正常现象。

然后检查和更新：

1
2
3
4
wsl --update
wsl --version
wsl --status
wsl --list --verbose

列表中的 VERSION 为 2，表示该发行版使用 WSL 2。它与 wsl --version 显示的 WSL 软件版本号不是同一个概念。

设置新发行版默认使用 WSL 2：

1
wsl --set-default-version 2

已有发行版仍为 WSL 1 时，先备份，再按实际名称转换：

1
wsl --set-version Ubuntu 2

转换可能耗时并占用额外磁盘空间。

3. 常用命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 查看发行版状态
wsl -l -v

# 进入 Ubuntu
wsl -d Ubuntu

# 在 Ubuntu 执行单条命令
wsl -d Ubuntu -- uname -a

# 停止某个发行版
wsl --terminate Ubuntu

# 停止所有 WSL 发行版与 WSL 2 虚拟机
wsl --shutdown

退出 Linux 终端使用 exit，不一定停止所有后台进程。执行 wsl --shutdown 会影响 Docker Desktop 的 WSL 后端，先保存工作、停止相关服务。

三、安装 Docker Desktop

1. 下载与设置

从 Docker 官方 Windows 安装页 下载适合处理器架构的安装程序。

  1. 安装时选择 WSL 2 后端（如安装程序提供该选项）。
  2. 按提示完成安装，必要时重启或重新登录。
  3. 打开 Docker Desktop，等待 Engine running。
  4. 在设置中确认使用 WSL 2 后端和 Linux 容器模式。
  5. 若需要在 Ubuntu 中运行 Docker 命令，在 Resources → WSL integration 开启 Ubuntu 集成；只用 Windows PowerShell 则不必额外启用个人 Ubuntu 集成。

系统要求和界面入口以官方安装页及实际版本为准。

2. 验证

重新打开普通 PowerShell：

1
2
3
docker version
docker compose version
docker context show

docker version 应包含 Client 和 Server。只有 Client 或连接错误，通常表示引擎未启动。

可选测试：

1
docker run --rm hello-world

出现 Hello from Docker! 表示镜像拉取与容器运行成功。–rm 在运行结束后删除测试容器，镜像仍保留。

若找不到 docker，先重开终端。本机采用每用户安装，CLI 位于：

1
C:\Users\wang\AppData\Local\Programs\DockerDesktop\resources\bin\docker.exe

当前 PowerShell 临时补充 PATH：

1
$env:Path += ";C:\Users\wang\AppData\Local\Programs\DockerDesktop\resources\bin"

其他电脑使用实际安装路径；此设置仅对当前终端有效。

四、避免 WSL 和 Docker 占用过多 C 盘

1. 两类数据分别迁移

Ubuntu 与 Docker Desktop 的数据盘独立，只移动 Ubuntu 不会移动 Docker 镜像、命名卷与缓存。

本机已于 2026-10-23 完成以下迁移并验证：

对象 位置
Ubuntu D:\WSL\Ubuntu
Docker 数据根目录 D:\DockerData\DockerDesktopWSL
Docker 数据盘 D:\DockerData\DockerDesktopWSL\disk\docker_data.vhdx
迁移备份 D:\WSL\MigrationBackup-20261023

这是本机记录。Docker 内部目录随版本可能不同，其他电脑应按界面和实际文件核对。

2. 迁移普通 WSL 发行版

保存工作、退出 Docker、停止 WSL，先备份重要数据，确认目标固定磁盘空间足够，优先使用 NTFS。

较新 WSL 先用 wsl --help 确认支持 –manage 和 –move：

1
2
3
wsl --shutdown
wsl --manage Ubuntu --move D:\WSL\Ubuntu
wsl -d Ubuntu -- sh -c 'id -un; df -h /'

发行版名按实际替换，目标目录不要包含其他重要数据。

旧版本可用导出、导入：

1
2
3
wsl --export Ubuntu D:\WSL\Ubuntu-backup.tar
wsl --import Ubuntu-Migrated D:\WSL\Ubuntu-Migrated D:\WSL\Ubuntu-backup.tar --version 2
wsl -d Ubuntu-Migrated

先验证新实例的文件、用户和服务。导入实例可能默认以 root 启动，需要另设默认用户；支持时可用：

1
wsl --manage Ubuntu-Migrated --set-default-user 用户名

确认后再切换默认发行版。wsl –unregister 会删除对应发行版数据，不要在确认备份和导入成功前注销原实例。 不要手动剪切正在使用的 VHDX。

3. 迁移 Docker 数据

Docker Desktop → Settings → Resources → Advanced → Disk image location。

选择 D 盘目录，Apply & restart，再确认移动。应用可能自动添加 DockerDesktopWSL 子目录。完成后验证新路径、引擎、镜像、容器和卷。

不要随意注销 docker-desktop 或 docker-desktop-data，不同版本存储架构不同，可能丢失数据。

4. 可选的 WSL 资源与 swap 配置

Windows 用户目录的 .wslconfig 是全局 WSL 2 配置，不同于 Linux 内的 /etc/wsl.conf。示例：

1
2
3
4
5
[wsl2]
memory=4GB
processors=4
swap=2GB
swapFile=D:\\WSL\\swap.vhdx

按电脑资源调整，先创建 D:\WSL，并备份、合并已有配置。退出 Docker 后执行 wsl --shutdown，重新启动生效。

该设置影响所有 WSL 2 发行版，memory 是共享环境资源上限，不是每个容器单独分配的内存。之前的本机迁移没有额外修改 swap，本节只是可选配置。

Linux 内删除文件不保证 Windows 的 VHDX 立即缩小；迁移 Docker 数据盘也不会移动仍绑定在 C 盘的项目目录。

五、用 Compose 安装 Redis

1. 建立项目目录

PowerShell：

1
2
New-Item -ItemType Directory -Path D:\DockerProjects\redis-learning -Force
Set-Location D:\DockerProjects\redis-learning

用编辑器创建两个 UTF-8 文件，注意不要多出 .txt：

1
2
3
redis-learning/
├── compose.yaml
└── redis.conf

2. redis.conf

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 容器内部监听
bind 0.0.0.0
protected-mode yes
port 6379

# 前台运行，日志交给 Docker
daemonize no
logfile ""

# 学习用示例，请自行替换
requirepass LearnRedis_6379_ChangeMe

# 持久化目录
dir /data

# AOF，每秒同步
appendonly yes
appendfsync everysec

# 数据内存限制
maxmemory 256mb
maxmemory-policy noeviction

关键理解：

  • bind 0.0.0.0 是容器内部监听，Windows 的访问范围在 Compose 中限制。
  • requirepass 为默认用户设置密码；进一步权限控制可学习 ACL。
  • AOF 记录写操作，everysec 在异常故障时可能丢失最近约一秒的数据；持久化不等于备份。
  • maxmemory 是 Redis 数据内存管理限制，整个进程还有额外开销。
  • noeviction 达到上限后拒绝需要额外内存的写入，避免自动淘汰学习数据；纯缓存场景可研究 allkeys-lru 等策略。
  • Redis 7 的 AOF 可能采用多文件结构，不要假定备份一个 appendonly.aof 就足够。

3. compose.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
services:
  redis:
    image: redis:7.4
    container_name: redis-learning
    restart: unless-stopped
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - ./redis.conf:/usr/local/etc/redis/redis.conf:ro
      - redis-data:/data
    command:
      - redis-server
      - /usr/local/etc/redis/redis.conf

volumes:
  redis-data:
配置 含义
image Redis 7.4 系列镜像，标签仍可能更新
container_name 容器名称，便于 exec
restart 引擎启动后恢复，手动停止的除外
127.0.0.1:6379:6379 宿主机本机端口映射到容器端口
redis.conf 挂载 使用项目配置，ro 表示只读
redis-data:/data 命名卷持久保存数据
command 显式读取自定义配置

命名卷通常带项目名前缀，例如 redis-learning_redis-data，实际以 docker volume ls 为准。本机卷数据存于已迁移到 D 盘的 Docker 数据盘，不是直接出现在项目目录里的普通 data 文件夹。

配置只读挂载时，CONFIG REWRITE 无法写回文件。学习时编辑 redis.conf 再重启；CONFIG SET 的临时修改不等于永久保存。

4. 下载与启动

1
2
3
4
5
6
Set-Location D:\DockerProjects\redis-learning
docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail 50 redis

config 检查 YAML；pull 下载镜像；up 创建/启动服务；-d 表示后台运行。YAML 使用空格缩进，不用 Tab。

预期状态 Up，日志包含 Ready to accept connections。Up 只说明进程运行，仍需验证 Redis 命令。

拉取失败先检查网络、Docker 代理和错误信息，不要随意添加不可信镜像源。

5. 连接与基本读写

PowerShell：

1
docker exec -it redis-learning redis-cli --askpass

按提示输入 redis.conf 中的密码。无需在 Windows 安装客户端，且不必把密码放到命令参数中。

进入 Redis 提示符后执行：

1
2
3
4
5
6
PING
SET study:name "Spring Boot + Redis"
GET study:name
SET study:code "123456" EX 60
TTL study:code
GET study:code

PING 应返回 PONG。EX 60 表示 60 秒过期；TTL 返回剩余秒数，-1 表示未设过期，-2 表示键不存在。

退出：

1
EXIT

退出客户端不会停止服务。

6. 验证持久化

先写入不带过期时间的 study:name，退出 CLI，再执行：

1
2
docker compose restart redis
docker exec -it redis-learning redis-cli --askpass

认证后 GET study:name，应该仍能读到值。

还可退出 CLI 后重建：

1
2
docker compose down
docker compose up -d

再连接并读取。普通 down 删除容器和项目网络，默认保留命名卷。

不要加 -v：docker compose down -v 会删除该项目的数据卷。 改变项目名称或卷名可能使用一个新空卷，不一定是旧数据被删除。

六、Spring Boot 接入

1. 添加 Maven 依赖

在 pom.xml 的 dependencies 内添加，已有则不重复：

1
2
3
4
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

使用 Spring Boot 父 POM 或依赖管理时无需自行指定版本。IDEA 重新加载 Maven。

默认使用 Lettuce，自动配置连接工厂与 StringRedisTemplate，起步无需手写连接池或配置类。

2. application.yml

Spring Boot 3.x/4.x：

1
2
3
4
5
6
7
8
9
spring:
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      password: ${REDIS_PASSWORD}
      database: 0
      connect-timeout: 3s
      timeout: 3s

已有 spring 节点时合并内容，不要创建重复顶层键。Spring Boot 2.x 使用 spring.redis 前缀，先确认版本。

IDEA：Run → Edit Configurations → 当前启动配置 → Environment variables：

1
REDIS_PASSWORD=你在redis.conf中设置的密码

看不到时通过 Modify options 显示。密码不要提交到公共仓库，redis.conf 也应排除提交，公开时提供不含真实密码的示例文件。

若设置 spring.data.redis.url，独立的 host、port、username、password 会被忽略，不要随意混配。

3. 实际读写测试

确保有测试依赖：

1
2
3
4
5
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

在 src/test/java 下创建类，替换包名，并放到启动类同包或子包：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
package com.example.demo;

import java.time.Duration;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.data.redis.core.StringRedisTemplate;
import static org.junit.jupiter.api.Assertions.assertEquals;

@SpringBootTest
class RedisConnectionTest {
    @Autowired
    private StringRedisTemplate redisTemplate;

    @Test
    void shouldWriteAndReadRedis() {
        String key = "study:springboot:connection";
        redisTemplate.opsForValue().set(
                key, "hello redis", Duration.ofMinutes(5));
        String value = redisTemplate.opsForValue().get(key);
        assertEquals("hello redis", value);
        System.out.println("Redis 读取结果：" + value);
    }
}

测试运行配置也需设置 REDIS_PASSWORD，未必继承主程序运行配置。

通过后在 Redis CLI 执行：

1
2
GET study:springboot:connection
TTL study:springboot:connection

应读到 hello redis，以及不超过 300 秒的剩余有效期。仅 Spring Boot 启动成功不能证明 Redis 可用，实际读写才验证完整链路。

先用 StringRedisTemplate 学习字符串，对象可先显式转 JSON；以后再学习统一序列化和缓存注解。

4. 地址随运行位置变化

应用位置 Redis 地址
Windows IDEA 127.0.0.1:6379
与 Redis 同一 Compose 网络的应用容器 redis:6379，redis 为服务名
Ubuntu WSL 内 取决于 NAT/镜像网络和端口监听，需单独检查

容器内 localhost 指向容器自己，不是 Windows 或另一容器。WSL NAT 下访问仅绑定 Windows 回环地址的服务存在限制；先用 Windows IDEA 完成学习，或让应用与 Redis 进入同一 Compose 网络。

七、Redis 命令练习

以下在 Redis CLI 中执行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 字符串与计数
SET study:count 1
INCR study:count
GET study:count

# Hash
HSET study:user:1 name Alice age 20
HGETALL study:user:1

# List
LPUSH study:tasks task1 task2
LRANGE study:tasks 0 -1

# Set：去重
SADD study:tags java redis java
SMEMBERS study:tags

# 过期时间
EXPIRE study:user:1 300
TTL study:user:1

# 分批查找
SCAN 0 MATCH study:* COUNT 100

SCAN 返回下一次游标和本批结果，继续使用返回游标，直到游标为 0。COUNT 是工作量提示，不保证每批精确数量。大数据实例避免使用 KEYS *。

逻辑数据库索引不是独立服务器，也不是权限隔离。先统一使用数据库 0。

八、日常操作与排错

1. 命令速查

Compose 命令在 D:\DockerProjects\redis-learning 目录执行。

目的 命令
启动/应用 Compose 修改 docker compose up -d
状态 docker compose ps
最近日志 docker compose logs –tail 50 redis
实时日志 docker compose logs -f redis
停止，保留容器 docker compose stop
启动已停止的容器 docker compose start
重启并读取 redis.conf docker compose restart redis
删除容器和网络，保留卷 docker compose down
数据卷列表 docker volume ls
资源用量 docker stats redis-learning

查看实际挂载：

1
docker inspect redis-learning --format '{{json .Mounts}}'

Ctrl+C 退出日志/资源查看不会停止后台容器。restart 不会应用 Compose 中改过的端口和挂载，改这些需要 up -d。

重启电脑后先启动 Docker Desktop；restart 策略不会替你启动桌面应用。

2. 备份思路

数据卷保留不等于备份：

  1. 保留 Compose 与配置记录，密码按私有资料管理。
  2. 学习环境可以停止 Redis 后对完整数据卷做离线归档，避免边写边复制。
  3. 恢复到独立测试卷验证后，才算备份可用。
  4. 备份整个 Docker Desktop 数据盘时，按官方指南完全退出 Docker，再复制 VHDX。
  5. 升级前备份并检查兼容性，不要直接用旧版打开新版改写的数据。

3. 故障排查

现象 检查
docker 找不到 重开终端、检查 PATH 与安装位置
连接 Docker Server 失败 Desktop 引擎、context
拉取超时 网络、代理、错误信息
6379 被占用 改为 127.0.0.1:6380:6379，Spring Boot 改 6380
容器反复重启 查看日志，检查配置和挂载
redis.conf 挂载失败 是否为文件、是否多出 .txt、是否在正确目录
NOAUTH 未认证，使用 –askpass
WRONGPASS 密码不一致，改文件后需重启
找不到 REDIS_PASSWORD 在实际运行的主程序/测试配置中设置
Connection refused 容器状态、host、映射端口
OOM command not allowed 达到 maxmemory，检查数据、TTL 与策略
重建后数据为空 卷名、项目名、数据库索引，是否误删卷
测试找不到启动配置 测试类包位置，必要时显式指定启动类

检查 Windows 端口：

1
Get-NetTCPConnection -LocalPort 6379 -ErrorAction SilentlyContinue

宿主机改用 6380 时，容器内 Redis CLI 仍使用容器端口 6379。

4. 注意事项

本文仅发布本机回环端口。不要为连接方便直接向公网开放 Redis 或关闭保护模式；远程使用需另行配置网络访问、ACL 和必要的加密。

不确认数据价值时，不要运行 FLUSHALL、FLUSHDB、docker compose down -v 或 docker system prune –volumes。

九、学习验收

  • 理解镜像、容器、命名卷和绑定挂载。
  • 能用 wsl -l -v 查看状态。
  • docker version 包含 Server。
  • Redis PING 返回 PONG。
  • 完成 SET、GET、EXPIRE、TTL。
  • 重启、重建容器后数据仍在。
  • Spring Boot 实际读写测试通过。
  • 理解 Windows、WSL、容器中的 localhost。
  • 知道数据与备份位置，知道哪些命令删除数据。

建议后续学习：JSON 序列化 → 缓存注解 → 缓存穿透/击穿/雪崩 → 分布式锁和原子操作 → ACL、监控、备份恢复。

十、官方参考