WSL-Ubuntu 下 Docker 搭建 Hyperf：从启动失败到最佳开发结构
1、参考：在 WSL-Ubuntu 中 Docker 下安装 Hyperf。现在启动失败：[ERROR] RedisException: Connection refused。如图1
![参考：在 WSL-Ubuntu 中 Docker 下安装 Hyperf。现在启动失败：[ERROR] RedisException: Connection refused。](https://www.shuijingwanwq.com/wp-content/uploads/2026/04/1-3.jpg)
[ERROR] RedisException: Connection refused in /data/project/hyperf-skeleton/vendor/hyperf/redis/src/RedisConnection.php:318
Stack trace:
<h1>0 /data/project/hyperf-skeleton/vendor/hyperf/redis/src/RedisConnection.php(318): Redis->connect()</h1>
<h1>1 /data/project/hyperf-skeleton/vendor/hyperf/redis/src/RedisConnection.php(129): Hyperf\Redis\RedisConnection->createRedis()</h1>
<h1>2 /data/project/hyperf-skeleton/vendor/hyperf/redis/src/RedisConnection.php(83): Hyperf\Redis\RedisConnection->reconnect()</h1>
<h1>3 /data/project/hyperf-skeleton/vendor/hyperf/redis/src/Pool/RedisPool.php(58): Hyperf\Redis\RedisConnection->__construct()</h1>
<h1>4 /data/project/hyperf-skeleton/vendor/hyperf/pool/src/Pool.php(160): Hyperf\Redis\Pool\RedisPool->createConnection()</h1>
<h1>5 /data/project/hyperf-skeleton/vendor/hyperf/pool/src/Pool.php(45): Hyperf\Pool\Pool->getConnection()</h1>
<h1>6 /data/project/hyperf-skeleton/vendor/hyperf/redis/src/Redis.php(126): Hyperf\Pool\Pool->get()</h1>
<h1>7 /data/project/hyperf-skeleton/vendor/hyperf/redis/src/Redis.php(40): Hyperf\Redis\Redis->getConnection()</h1>
<h1>8 /data/project/hyperf-skeleton/vendor/hyperf/async-queue/src/Driver/RedisDriver.php(188): Hyperf\Redis\Redis->__call()</h1>
<h1>9 /data/project/hyperf-skeleton/vendor/hyperf/async-queue/src/Driver/RedisDriver.php(80): Hyperf\AsyncQueue\Driver\RedisDriver->move()</h1>
<h1>10 /data/project/hyperf-skeleton/vendor/hyperf/async-queue/src/Driver/Driver.php(68): Hyperf\AsyncQueue\Driver\RedisDriver->pop()</h1>
<h1>11 /data/project/hyperf-skeleton/vendor/hyperf/async-queue/src/Process/ConsumerProcess.php(51): Hyperf\AsyncQueue\Driver\Driver->consume()</h1>
<h1>12 /data/project/hyperf-skeleton/vendor/hyperf/process/src/AbstractProcess.php(101): Hyperf\AsyncQueue\Process\ConsumerProcess->handle()</h1>
<h1>13 [internal function]: Hyperf\Process\AbstractProcess->Hyperf\Process{closure}()</h1>
<h1>14 {main}</h1>
2、HyPerf 连接 Redis 失败，大概率是以下三者之一导致（Redis 没启动 / 地址写错 / 端口不通）。我现在是本地开发环境，最终决定架构如下：
WSL（开发环境）
│
├── dev-mysql（共用）
├── dev-redis（共用）
│
├── hyperf 项目
├── laravel 项目
├── 其他 PHP 项目
3、创建一个公共网络
ubuntu@DESKTOP-H4MGQIU:~$ docker network create dev-net 4b1b11f4edbeb6ea2dc17600e5366ddffa4e1fd1eec9d0c6da546764d9fe919c
4、启动 Redis
ubuntu@DESKTOP-H4MGQIU:~$ docker network create dev-net 4b1b11f4edbeb6ea2dc17600e5366ddffa4e1fd1eec9d0c6da546764d9fe919c ubuntu@DESKTOP-H4MGQIU:~$ docker run -d \ --name dev-redis \ --network dev-net \ -p 6379:6379 \ redis:alpine Unable to find image 'redis:alpine' locally alpine: Pulling from library/redis 911c6948605d: Pull complete 80ad90552b45: Pull complete 4f4fb700ef54: Pull complete 794ebd49c5d4: Pull complete e14f845a52ff: Pull complete 8b960ad4ebe4: Pull complete 589002ba0eae: Pull complete 1eff8ef023e3: Download complete 3130250ed578: Download complete Digest: sha256:2afba59292f25f5d1af200496db41bea2c6c816b059f57ae74703a50a03a27d0 Status: Downloaded newer image for redis:alpine 01c8cedc5e855b78766d3232fe7df6b55ca822256c94ece0cd510e1bcab246ef
5、启动 MySQL 8
ubuntu@DESKTOP-H4MGQIU:~$ docker run -d \ --name dev-mysql8 \ --network dev-net \ -e MYSQL_ROOT_PASSWORD=root \ -p 3306:3306 \ mysql:8 Unable to find image 'mysql:8' locally 8: Pulling from library/mysql 91c980086743: Pull complete eba8eed90d75: Pull complete d4c7048d1cf1: Pull complete 50200b0c89a3: Pull complete 3cd28adefbd9: Pull complete 03f8ae82fc56: Pull complete 43105b2d4e4a: Pull complete 4d14d7bf02a4: Pull complete 1a7d4892b7d2: Pull complete 68420c358694: Pull complete 09ed159fbec4: Download complete 0ad5e3bd9c41: Download complete Digest: sha256:da906917ca4ace3ba55538b7c2ee97a9bc865ef14a4b6920b021f0249d603f3d Status: Downloaded newer image for mysql:8 232e8abe63d581fcbf5effab51e84eb4bb046255c8851635e58cfe1d8a85c7e6
6、让 Hyperf 加入这个网络，验证是否成功，验证是否成功。符合预期。如图2
ubuntu@DESKTOP-H4MGQIU:~$ docker network connect dev-net hyperf
ubuntu@DESKTOP-H4MGQIU:~$ docker inspect hyperf
[
{
"Id": "9232c1fa90d72165f31c1e1adc4fdc897a665a1e9e580242af4a342765f7154a",
"Created": "2026-03-19T11:07:00.928914099Z",
"Path": "/bin/sh",
"Args": [],
"State": {
"Status": "running",
"Running": true,
"Paused": false,
"Restarting": false,
"OOMKilled": false,
"Dead": false,
"Pid": 2188,
"ExitCode": 0,
"Error": "",
"StartedAt": "2026-03-23T09:23:00.14362394Z",
"FinishedAt": "2026-03-23T09:16:50.3053747Z"
},
"Image": "sha256:3cbda08f3892507d760d31bba8b68aeb4b916333055bbf05cf46ea18c67fc935",
"ResolvConfPath": "/var/lib/docker/containers/9232c1fa90d72165f31c1e1adc4fdc897a665a1e9e580242af4a342765f7154a/resolv.conf",
"HostnamePath": "/var/lib/docker/containers/9232c1fa90d72165f31c1e1adc4fdc897a665a1e9e580242af4a342765f7154a/hostname",
"HostsPath": "/var/lib/docker/containers/9232c1fa90d72165f31c1e1adc4fdc897a665a1e9e580242af4a342765f7154a/hosts",
"LogPath": "/var/lib/docker/containers/9232c1fa90d72165f31c1e1adc4fdc897a665a1e9e580242af4a342765f7154a/9232c1fa90d72165f31c1e1adc4fdc897a665a1e9e580242af4a342765f7154a-json.log",
"Name": "/hyperf",
"RestartCount": 0,
"Driver": "overlayfs",
"Platform": "linux",
"MountLabel": "",
"ProcessLabel": "",
"AppArmorProfile": "",
"ExecIDs": null,
"HostConfig": {
"Binds": [
"/home/ubuntu/wwwroot/hyperf-skeleton:/data/project"
],
"ContainerIDFile": "",
"LogConfig": {
"Type": "json-file",
"Config": {}
},
"NetworkMode": "bridge",
"PortBindings": {
"9501/tcp": [
{
"HostIp": "",
"HostPort": "9501"
}
]
},
"RestartPolicy": {
"Name": "no",
"MaximumRetryCount": 0
},
"AutoRemove": false,
"VolumeDriver": "",
"VolumesFrom": null,
"ConsoleSize": [
49,
188
],
"CapAdd": null,
"CapDrop": null,
"CgroupnsMode": "private",
"Dns": [],
"DnsOptions": [],
"DnsSearch": [],
"ExtraHosts": null,
"GroupAdd": null,
"IpcMode": "private",
"Cgroup": "",
"Links": null,
"OomScoreAdj": 0,
"PidMode": "",
"Privileged": true,
"PublishAllPorts": false,
"ReadonlyRootfs": false,
"SecurityOpt": [
"label=disable"
],
"UTSMode": "",
"UsernsMode": "",
"ShmSize": 67108864,
"Runtime": "runc",
"Isolation": "",
"CpuShares": 0,
"Memory": 0,
"NanoCpus": 0,
"CgroupParent": "",
"BlkioWeight": 0,
"BlkioWeightDevice": [],
"BlkioDeviceReadBps": [],
"BlkioDeviceWriteBps": [],
"BlkioDeviceReadIOps": [],
"BlkioDeviceWriteIOps": [],
"CpuPeriod": 0,
"CpuQuota": 0,
"CpuRealtimePeriod": 0,
"CpuRealtimeRuntime": 0,
"CpusetCpus": "",
"CpusetMems": "",
"Devices": [],
"DeviceCgroupRules": null,
"DeviceRequests": null,
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": null,
"OomKillDisable": null,
"PidsLimit": null,
"Ulimits": [],
"CpuCount": 0,
"CpuPercent": 0,
"IOMaximumIOps": 0,
"IOMaximumBandwidth": 0,
"MaskedPaths": null,
"ReadonlyPaths": null
},
"Storage": {
"RootFS": {
"Snapshot": {
"Name": "overlayfs"
}
}
},
"Mounts": [
{
"Type": "bind",
"Source": "/home/ubuntu/wwwroot/hyperf-skeleton",
"Destination": "/data/project",
"Mode": "",
"RW": true,
"Propagation": "rprivate"
}
],
"Config": {
"Hostname": "9232c1fa90d7",
"Domainname": "",
"User": "root",
"AttachStdin": true,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"9501/tcp": {}
},
"Tty": true,
"OpenStdin": true,
"StdinOnce": true,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
"SW_VERSION=v6.1.7",
"COMPOSER_VERSION=2.9.4",
"COMPOSER_ALLOW_SUPERUSER=1",
"PHPIZE_DEPS=autoconf dpkg-dev dpkg file g++ gcc libc-dev make php81-dev php81-pear pkgconf re2c pcre-dev pcre2-dev zlib-dev libtool automake libaio-dev openssl-dev curl-dev"
],
"Cmd": null,
"Image": "hyperf/hyperf:8.1-alpine-v3.18-swoole",
"Volumes": null,
"WorkingDir": "/data/project",
"Entrypoint": [
"/bin/sh"
],
"Labels": {
"license": "MIT",
"maintainer": "Hyperf Developers <a href="mailto:group@hyperf.io">group@hyperf.io</a>",
"version": "1.0"
}
},
"NetworkSettings": {
"SandboxID": "31c7e20513fa9eb5bc38e9e5225b797b4cd2391ed9f0a9700e4f3b3460190dfd",
"SandboxKey": "/var/run/docker/netns/31c7e20513fa",
"Ports": {
"9501/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "9501"
},
{
"HostIp": "::",
"HostPort": "9501"
}
]
},
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"DriverOpts": null,
"GwPriority": 0,
"NetworkID": "b874ea6a38fefb11a4bf500d54ffe2365d3e22de5fc57610d7379bbb177b6be5",
"EndpointID": "1ecfdc26abb9841bca3f3f158d0d2fae70bad4db686d7837ed1fada1a177da55",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.2",
"MacAddress": "16:1e:f4:8e:99:5f",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"DNSNames": null
},
"dev-net": {
"IPAMConfig": {},
"Links": null,
"Aliases": [],
"DriverOpts": {},
"GwPriority": 0,
"NetworkID": "4b1b11f4edbeb6ea2dc17600e5366ddffa4e1fd1eec9d0c6da546764d9fe919c",
"EndpointID": "c03c1b28859f6e6dd736ce2c891e33226a428a9e8ca5232971626df2dfd9b907",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.5",
"MacAddress": "ce:80:6d:68:f9:90",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"DNSNames": [
"hyperf",
"9232c1fa90d7"
]
}
}
},
"ImageManifestDescriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:2852fa7c75e5f7c8b36dbc0ffaff8c6d7f1227f8454dbb0ab3cbccecb617da9c",
"size": 1055,
"platform": {
"architecture": "amd64",
"os": "linux"
}
}
}
]
ubuntu@DESKTOP-H4MGQIU:~$ docker exec -it hyperf sh
/data/project # ping dev-redis
PING dev-redis (172.18.0.2): 56 data bytes
64 bytes from 172.18.0.2: seq=0 ttl=64 time=0.393 ms
64 bytes from 172.18.0.2: seq=1 ttl=64 time=0.203 ms
64 bytes from 172.18.0.2: seq=2 ttl=64 time=0.360 ms
64 bytes from 172.18.0.2: seq=3 ttl=64 time=0.136 ms
64 bytes from 172.18.0.2: seq=4 ttl=64 time=0.104 ms
64 bytes from 172.18.0.2: seq=5 ttl=64 time=0.250 ms
64 bytes from 172.18.0.2: seq=6 ttl=64 time=0.080 ms
64 bytes from 172.18.0.2: seq=7 ttl=64 time=0.077 ms
64 bytes from 172.18.0.2: seq=8 ttl=64 time=0.110 ms
64 bytes from 172.18.0.2: seq=9 ttl=64 time=0.080 ms
^C
--- dev-redis ping statistics ---
10 packets transmitted, 10 packets received, 0% packet loss
round-trip min/avg/max = 0.077/0.179/0.393 ms
/data/project # ping dev-mysql8
PING dev-mysql8 (172.18.0.3): 56 data bytes
64 bytes from 172.18.0.3: seq=0 ttl=64 time=0.392 ms
64 bytes from 172.18.0.3: seq=1 ttl=64 time=0.338 ms
64 bytes from 172.18.0.3: seq=2 ttl=64 time=0.230 ms
64 bytes from 172.18.0.3: seq=3 ttl=64 time=0.355 ms
^C
--- dev-mysql8 ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max = 0.230/0.328/0.392 ms
/data/project #
7、修改 Hyperf 配置，让它连到 Redis / MySQL。修改 Redis 配置，打开文件：.env ，修改相关变量。如图3
8、再次启动 Hyperf 服务，启动成功。如图4
/data/project/hyperf-skeleton # php bin/hyperf.php start [DEBUG] [command] Commands registered by Hyperf\Command\Listener\RegisterCommandListener [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Command\Listener\RegisterCommandListener listener. [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Config\Listener\RegisterPropertyHandlerListener listener. [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\DbConnection\Listener\RegisterConnectionResolverListener listener. [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ExceptionHandlerListener listener. [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ErrorExceptionHandler listener. [DEBUG] Event Hyperf\Framework\Event\BeforeMainServerStart handled by Hyperf\Process\Listener\BootProcessListener listener. [INFO] Worker#1 started. [DEBUG] Event Hyperf\Framework\Event\AfterWorkerStart handled by Hyperf\Server\Listener\AfterWorkerStartListener listener. [DEBUG] Event Hyperf\Framework\Event\AfterWorkerStart handled by Hyperf\Server\Listener\InitProcessTitleListener listener. [INFO] Worker#2 started. [INFO] Worker#3 started. [INFO] Worker#0 started. [INFO] HTTP Server listening at 0.0.0.0:9501 [DEBUG] Event Hyperf\Framework\Event\AfterWorkerStart handled by Hyperf\Server\Listener\AfterWorkerStartListener listener. [DEBUG] Event Hyperf\Framework\Event\AfterWorkerStart handled by Hyperf\Server\Listener\AfterWorkerStartListener listener. [DEBUG] Event Hyperf\Framework\Event\AfterWorkerStart handled by Hyperf\Server\Listener\AfterWorkerStartListener listener. [DEBUG] Event Hyperf\Framework\Event\AfterWorkerStart handled by Hyperf\Server\Listener\InitProcessTitleListener listener. [DEBUG] Event Hyperf\Framework\Event\AfterWorkerStart handled by Hyperf\Server\Listener\InitProcessTitleListener listener. [DEBUG] Event Hyperf\Framework\Event\OnManagerStart handled by Hyperf\Server\Listener\InitProcessTitleListener listener. [DEBUG] Event Hyperf\Framework\Event\AfterWorkerStart handled by Hyperf\Server\Listener\InitProcessTitleListener listener. [INFO] Process[queue.default.0] start. [DEBUG] Event Hyperf\Process\Event\BeforeProcessHandle handled by Hyperf\Process\Listener\LogBeforeProcessStartListener listener. [DEBUG] Event Hyperf\Process\Event\BeforeProcessHandle handled by Hyperf\Server\Listener\InitProcessTitleListener listener.
9、HTTP 服务已经启动，可以通过 http://localhost:9501 访问。如图5
