根本原因是容器网络未打通：服务端需绑定0.0.0.0:50051，客户端用服务名（如myservice:50051）而非localhost；Docker Compose中需确保同网段、服务名匹配；Python依赖需在镜像内编译并正确导入；健康检查须用grpc_health_probe；端口映射须写为"50051:50051"。
gRPC服务在Docker Compose里启动就报connection refused
根本原因不是代码写错了，而是容器网络没打通。默认情况下，localhost在容器里指向自己，不是宿主机；而gRPC客户端如果硬写localhost:50051，就会连到空容器内部，自然拒绝连接。
实操建议：
- 服务端启动时绑定
0.0.0.0:50051（别只绑127.0.0.1） - 客户端用服务名当 host：比如
myservice:50051，而不是localhost或host.docker.internal - 确保
docker-compose.yml中两个服务在同一个自定义 network 下（不显式声明时，默认 bridge 网络也行，但服务名必须对得上container_name或服务 key） - Go/Python/Node 客户端初始化 channel 时，host 字符串必须和
docker-compose.yml里的服务名完全一致，大小写敏感
proto 文件编译后 Python 客户端调用总提示ModuleNotFoundError: No module named 'helloworld_pb2'
不是 protoc 没装好，是 Python 路径没导对。Docker 里跑的 Python 进程找不到你生成的 *_pb2.py 文件，因为没加到 PYTHONPATH，或者文件根本没挂载进容器。
实操建议：
- 把
protoc编译命令放在 Dockerfile 里（不是本地编译完再 COPY），避免环境差异；例如：protoc -I./proto --python_out=./src ./proto/helloworld.proto - 生成的
.py文件必须放在容器内 Python 能 import 的路径下，比如/app/src，且/app/src要加进PYTHONPATH - 如果用多阶段构建，确认
builder阶段生成的*_pb2.py确实 COPY 到了 final 阶段的对应目录 - 检查生成的
*_pb2_grpc.py是否 import 了同级的*_pb2.py，路径错一个点都会失败
Docker Compose 启动后 gRPC 健康检查一直unhealthy
gRPC 没内置 HTTP 健康端点，healthcheck 默认走 HTTP GET，直接失效。强行配 curl -f http://localhost:50051 必然失败——那不是 HTTP 端口。
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
实操建议：
- 不要在
docker-compose.yml里给 gRPC 服务配基于 HTTP 的healthcheck - 改用
command方式调用grpc_health_probe：先go install github.com/grpc-ecosystem/grpc-health-probe/cmd/grpc_health_probe@latest，再在 healthcheck 里写：["grpc_health_probe", "-addr=:50051"] - 确保该二进制已放进镜像（COPY 或多阶段安装），且有执行权限
- 如果服务启用了 TLS，加
-tls参数；若用自签名证书，加-tls-skip-verify
从宿主机用 grpcurl 测试容器内服务，始终failed to connect to all addresses
不是防火墙问题，是端口没正确暴露。Docker 默认只映射 port，但 gRPC 是长连接，需要 TCP 层稳定可达；如果 docker-compose.yml 里只写了 "50051"（短格式），Docker 可能没绑定到宿主机 IP，或者被随机端口映射干扰。
实操建议：
- 显式写完整端口映射：
"50051:50051"，别省略左边 - 确认服务端监听的是
0.0.0.0:50051，不是127.0.0.1:50051 - 宿主机执行：
grpcurl -plaintext localhost:50051 list，如果还失败，用telnet localhost 50051先测 TCP 是否通 - Mac/Windows 用户注意：Docker Desktop 的
localhost是可达的；Linux 用户若用 rootless Docker，可能需用127.0.0.1或查ip addr show看实际绑定地址
最常卡住的地方其实是服务名拼写和网络作用域——两个服务不在同一 network 下，或者 container_name 和 client 里写的 host 不一致，错误信息却只显示 connection refused，容易往 TLS 或防火墙上想偏。
