1. 项目概述一个被低估的本地开发利器如果你和我一样常年泡在本地开发环境里和各种服务、数据库、中间件打交道那你一定对“端口冲突”、“环境变量混乱”、“服务依赖启动顺序”这些词深恶痛绝。每次新开一个项目或者临时测试一个想法都得手动去启动一堆服务改一堆配置过程繁琐不说还容易出错。leftathome/glovebox这个项目就是来解决这个痛点的。你可以把它理解为一个轻量级的、声明式的本地开发环境编排与管理工具。它不像 Docker Compose 那样重也不像手动写一堆脚本那样乱而是用一种简洁的 YAML 配置文件把你项目所需的所有服务比如 Web 服务器、数据库、缓存、消息队列等定义好然后一条命令就能让整个环境“活”起来。我第一次看到这个项目名glovebox手套箱时就觉得特别形象。在化学实验室里手套箱是一个隔离的操作环境你可以安全地在里面处理对空气或水分敏感的材料。而在软件开发中glovebox为你构建了一个隔离的、可复现的“操作环境”让你能安全、便捷地启动和管理一组相互关联的服务而不用担心污染宿主机环境或与其他项目冲突。它尤其适合前端全栈、微服务本地联调、需要固定依赖版本的个人项目等场景。对于独立开发者、小团队或者任何追求开发效率的人来说这绝对是一个值得放入工具箱的利器。2. 核心设计理念与架构拆解2.1 为什么是 Glovebox而不是其他市面上管理本地服务的工具不少比如docker-compose、minikube/kind本地K8s、vagrant甚至是一堆bash脚本。glovebox的定位非常清晰极致简单和快速。它不是为了模拟生产环境那是docker-compose和kind的强项也不是为了管理复杂的虚拟机vagrant它的目标就是让你用最小的认知负担和启动成本在本地跑起一组服务。它的核心优势在于零守护进程glovebox本身只是一个二进制文件启动服务时才会运行没有常驻后台的守护进程不占用额外资源用完即走非常干净。声明式配置所有服务、依赖、环境变量、端口映射都在一个glovebox.yml文件里定义。这种“基础设施即代码”的方式使得你的开发环境可以被版本控制新同事拉下代码就能获得一模一样的环境。依赖感知你可以明确指定服务之间的启动顺序A 依赖 B则 B 先于 A 启动并且glovebox会等待被依赖的服务健康检查通过后再启动下一个这比手动脚本可靠得多。资源绑定与清理glovebox启动的服务其生命周期与glovebox命令绑定。当你停止glovebox时它会尝试优雅地停止所有它启动的服务。这避免了后台残留一堆进程的情况。2.2 配置文件深度解析glovebox.yml的每一个字段glovebox的强大和易用性几乎全部体现在它的配置文件里。我们来看一个典型的、功能比较全面的glovebox.yml示例name: my-fullstack-app services: postgres: image: postgres:15-alpine ports: - 5432:5432 environment: POSTGRES_USER: myuser POSTGRES_PASSWORD: mysecretpassword POSTGRES_DB: myapp_dev healthcheck: test: [CMD-SHELL, pg_isready -U myuser] interval: 5s timeout: 3s retries: 5 volumes: - postgres_data:/var/lib/postgresql/data redis: image: redis:7-alpine ports: - 6379:6379 command: redis-server --appendonly yes healthcheck: test: [CMD, redis-cli, ping] interval: 5s api-server: build: ./backend ports: - 3000:3000 environment: DATABASE_URL: postgres://myuser:mysecretpasswordpostgres:5432/myapp_dev REDIS_URL: redis://redis:6379 depends_on: postgres: condition: service_healthy redis: condition: service_healthy # 使用宿主机的环境变量避免密码泄露在代码库中 env_file: .env.api web-app: build: ./frontend ports: - 8080:80 environment: API_BASE_URL: http://localhost:3000 # 开发模式下的热重载卷挂载 volumes: - ./frontend/src:/app/src volumes: postgres_data:我们来逐一拆解每个关键部分name: 项目名称。这主要用于在多个glovebox环境同时运行时进行区分。services: 核心部分定义了所有需要运行的服务。每个服务是一个键值对键是服务名如postgres值是该服务的配置。image: 指定使用的 Docker 镜像。这是启动服务最直接的方式。build: 如果服务需要从本地 Dockerfile 构建则使用此字段后面跟 Dockerfile 所在的上下文路径如./backend。glovebox会先执行docker build。ports: 端口映射格式为宿主机端口:容器内端口。这是将容器服务暴露给本地访问的关键。environment: 设置容器内的环境变量。这里有一个重要技巧对于密码等敏感信息强烈建议使用env_file或通过宿主机环境变量传入而不是直接写死在 YAML 文件中以防配置文件被提交到公开仓库。env_file: 指定一个包含环境变量的文件路径。文件内容通常是KEYVALUE格式。这是管理敏感配置和不同环境开发、测试配置的最佳实践。depends_on: 定义服务依赖关系。glovebox会按照依赖顺序启动服务。condition: service_healthy表示不仅等待依赖服务启动还要等待其通过健康检查healthcheck这对于数据库等需要初始化时间的服务至关重要。healthcheck: 定义如何检查服务是否“健康”并已准备好接受连接。这是实现可靠依赖启动的核心。支持CMD、CMD-SHELL等多种形式。volumes: 定义数据卷用于持久化数据如数据库数据或将宿主机目录挂载到容器内如前端代码目录用于实现热重载。command: 覆盖容器默认的启动命令。volumes(顶级字段): 声明在services部分使用的命名数据卷。这确保了即使容器被删除数据如postgres_data依然保留在宿主机上。注意glovebox的配置语法与docker-compose高度相似但并非完全兼容。它做了很多简化只保留了最核心、最常用的字段。这意味着从docker-compose.yml迁移过来通常很容易但复杂的功能如network自定义、extends等可能需要调整思路或暂时无法实现。这其实是glovebox“简单至上”哲学的一种体现。2.3 与 Docker Compose 的精准对比何时选择谁这是一个无法回避的问题。简单对比如下特性GloveboxDocker Compose核心目标快速启动、简化本地开发定义和运行多容器 Docker 应用涵盖开发、测试、生产配置复杂度极简字段少学习成本低功能全面字段多配置灵活但也更复杂守护进程无按需启动有 (docker-compose命令本身无但依赖 Docker 守护进程)生产适用性不推荐仅为本地开发优化可以常用于 CI/CD 和生产环境部署网络管理自动创建隔离网络服务间通过服务名通信支持自定义网络功能更强大扩展性较弱专注于核心场景强支持插件、扩展配置、合并文件等启动速度通常更快逻辑更直接相对标准选择建议用 Glovebox当你需要一个轻量、快速、零配置的方式来管理本地开发依赖数据库、缓存、Mock API等特别是用于个人项目、原型验证、或者作为大型项目中一个独立组件的开发环境时。用 Docker Compose当你的项目需要严格模拟生产环境配置非常复杂多网络、资源限制、扩展配置或者你需要在 CI/CD 流水线或生产服务器上使用同一套配置时。实际上它们并非互斥。我个人的工作流中一个项目里可能同时存在glovebox.yml用于快速启动开发依赖和docker-compose.yml用于集成测试或生产构建。Glovebox更像是你桌面上一个即开即用的“开发沙盒”。3. 从零开始实战搭建一个全栈应用开发环境理论说了这么多我们动手搭一个真实的全栈应用Node.js API React 前端 PostgreSQL Redis的开发环境感受一下glovebox的流畅。3.1 环境准备与工具安装首先你需要安装glovebox。因为它是一个独立的二进制文件安装极其简单。以 macOS 和 Linux 为例# 使用 curl 下载最新版本请前往项目 GitHub 仓库查看最新版本号 curl -L -o glovebox.tar.gz https://github.com/leftathome/glovebox/releases/download/v0.8.0/glovebox_0.8.0_darwin_all.tar.gz # 解压 tar -xzf glovebox.tar.gz # 将二进制文件移动到系统路径如 /usr/local/bin sudo mv glovebox /usr/local/bin/ # 验证安装 glovebox --version对于 Windows 用户可以直接下载对应的.exe文件并将其所在目录添加到系统 PATH 环境变量中。当然glovebox的底层依赖于 Docker 来运行容器。所以请确保你的机器上已经安装了Docker Desktop或Docker Engine并且 Docker 服务正在运行。在终端执行docker --version确认即可。3.2 编写第一个glovebox.yml文件在你的项目根目录下创建一个名为glovebox.yml的文件。我们将一步步填充内容。第一步定义数据持久化卷。我们不希望每次关闭数据库数据就丢失。name: fullstack-dev-env volumes: postgres_data:第二步添加 PostgreSQL 服务。这是我们的主数据库。services: postgres: image: postgres:15-alpine # 使用 Alpine 版本更轻量 ports: - 5432:5432 # 将容器5432端口映射到本地5432方便用 GUI 工具连接 environment: POSTGRES_USER: devuser POSTGRES_PASSWORD: devpassword # 生产环境切勿使用此简单密码 POSTGRES_DB: myapp_dev volumes: - postgres_data:/var/lib/postgresql/data # 数据持久化 healthcheck: test: [CMD-SHELL, pg_isready -U devuser] interval: 5s timeout: 3s retries: 10 # 给数据库足够的启动时间第三步添加 Redis 服务。用作缓存或会话存储。redis: image: redis:7-alpine ports: - 6379:6379 command: redis-server --appendonly yes # 启用 AOF 持久化 healthcheck: test: [CMD, redis-cli, ping] interval: 5s第四步添加后端 API 服务。假设你的后端代码在./backend目录其中包含Dockerfile。api: build: ./backend # 指向后端 Dockerfile 所在目录 ports: - 3000:3000 # 假设你的 Node.js 应用监听 3000 端口 environment: # 关键这里使用服务名‘postgres’和‘redis’作为主机名。 # 在 glovebox 创建的内部网络中服务名即主机名。 DATABASE_URL: postgres://devuser:devpasswordpostgres:5432/myapp_dev REDIS_URL: redis://redis:6379 NODE_ENV: development depends_on: postgres: condition: service_healthy # 等待数据库健康 redis: condition: service_healthy # 等待 Redis 健康 # 开发模式将本地代码目录挂载到容器实现代码变更热重载 volumes: - ./backend:/usr/src/app - /usr/src/app/node_modules # 匿名卷防止覆盖宿主机的 node_modules第五步添加前端 React 服务。假设前端代码在./frontend目录使用nginx提供服务。web: build: ./frontend # 指向前端 Dockerfile 所在目录 ports: - 8080:80 # 前端访问端口 environment: # 前端需要知道后端 API 地址。这里使用宿主机 localhost # 因为前端是从用户浏览器发请求而不是从容器网络内部。 REACT_APP_API_BASE: http://localhost:3000 depends_on: - api # 前端依赖于后端 API但通常不需要健康检查 # 同样挂载源码目录用于开发热更新如果使用 nginx 静态服务此配置可能不同 # 更常见的做法是前端在宿主机用 npm start这里仅作容器化示例。现在你的glovebox.yml文件就完成了。它清晰地定义了四个服务及其关系。3.3 启动、管理与交互在项目根目录下执行一个简单的命令glovebox up你会看到glovebox开始执行一系列动作解析glovebox.yml文件。为该项目创建一个独立的 Docker 网络通常是glovebox-项目名。按顺序拉取镜像如果本地没有或构建镜像对于build的服务。根据depends_on和healthcheck的配置依次启动服务。你会看到它等待postgres和redis健康检查通过后才启动api服务。所有服务启动后glovebox会附着到所有服务的日志输出让你在一个窗口看到所有日志流。此时打开浏览器访问http://localhost:8080查看前端页面。访问http://localhost:3000/api/health假设你有这个端点测试后端 API。用psql或任何 GUI 工具如 TablePlus, DBeaver连接localhost:5432用户devuser密码devpassword数据库myapp_dev可以操作数据库。用redis-cli连接localhost:6379操作 Redis。其他常用命令glovebox up -d: 后台模式启动服务不附着日志。glovebox logs [service_name]: 查看特定或所有服务的日志。glovebox ps: 查看本项目下所有运行中的服务状态类似于docker ps但只过滤出本glovebox环境管理的容器。glovebox stop: 停止所有服务但不删除容器和卷。下次glovebox up会很快。glovebox down:停止并删除所有服务容器但默认保留volumes中定义的命名卷。这是比较彻底的清理。glovebox exec service_name command: 在运行中的服务容器内执行命令。例如glovebox exec postgres psql -U devuser -d myapp_dev可以直接进入数据库命令行。实操心得在开发时我习惯用glovebox up在前台运行这样所有日志一目了然排查问题非常方便。当需要临时离开或专注写代码时可以CtrlC中断然后使用glovebox up -d切换到后台。glovebox ps命令是我最常用的之一它能快速确认所有服务是否都在预期状态下运行。4. 高级技巧与最佳实践4.1 环境变量与敏感信息管理直接在glovebox.yml中写明文密码是绝对禁止的尤其是项目需要提交到 Git 仓库时。我们有更安全的方式方法一使用env_file创建一个.env.api文件确保它在.gitignore中DATABASE_URLpostgres://realuser:complexpasswordpostgres:5432/myapp_dev API_SECRET_KEYsupersecretkey123然后在glovebox.yml中引用api: # ... 其他配置 ... env_file: .env.api # 可以同时使用 environment 和 env_file后者优先级更高 environment: NODE_ENV: development方法二使用宿主机环境变量在运行glovebox前先在终端导出变量或在glovebox.yml中使用${VAR_NAME}语法注意glovebox对变量替换的支持可能不如docker-compose完整需测试。export DB_PASSWORDmysecret glovebox up在 YAML 中environment: POSTGRES_PASSWORD: ${DB_PASSWORD:-defaultpassword} # 如果DB_PASSWORD不存在则用默认值方法三推荐使用.env文件配合env_file在项目根目录创建.env文件加入.gitignore里面定义所有环境变量。然后让各个服务的env_file都指向这个文件或者使用工具如direnv在进入项目目录时自动加载。这样管理起来最集中。4.2 开发效率优化热重载与代码挂载对于需要频繁修改代码的后端如 Node.js、Python和前端项目每次改代码都重建镜像是不可接受的。volumes挂载是解决这个问题的银弹。后端 Node.js 示例api: build: ./backend volumes: # 将宿主机当前目录下的 backend 文件夹挂载到容器的 /app 目录 - ./backend:/app # 这是一个关键技巧创建一个匿名卷覆盖容器内的 node_modules。 # 这样容器内 npm install 生成的 node_modules 不会因为宿主机挂载而被清空。 - /app/node_modules environment: # 很多 Node.js 框架在开发模式下支持文件监听重启 NODE_ENV: development前端 React (使用 Node 开发服务器) 示例更常见的模式是前端开发不使用glovebox容器化而是在宿主机直接运行npm start因为它依赖热模块替换HMR在容器内配置稍复杂。但如果你坚持容器化web-dev: build: context: ./frontend # 使用开发阶段的 Dockerfile dockerfile: Dockerfile.dev ports: - 3001:3000 # 假设开发服务器跑在3000端口 volumes: - ./frontend/src:/app/src - ./frontend/public:/app/public - /app/node_modules # 覆盖启动命令直接运行 npm start command: npm start environment: CHOKIDAR_USEPOLLING: true # 在某些文件系统如 Docker for Mac 的默认挂载下需要这个来启用文件监听注意事项在 macOS 和 Windows 上由于 Docker Desktop 的虚拟机文件系统性能问题使用volumes挂载进行文件同步可能会有延迟。如果发现代码更改后容器内反应慢可以尝试调整CHOKIDAR_USEPOLLING环境变量或者考虑使用docker-sync等第三方工具来提升性能。4.3 多环境配置管理你可能需要为“开发”、“测试”、“演示”准备不同的环境配置如数据库名、API 端点。glovebox本身没有多环境文件继承功能但我们可以用一些技巧实现技巧一使用多个 YAML 文件创建glovebox.dev.yml、glovebox.staging.yml通过-f参数指定glovebox -f glovebox.dev.yml up glovebox -f glovebox.staging.yml up在不同文件里你可以修改镜像标签、环境变量、端口等。技巧二环境变量控制 通用模板创建一个基础的glovebox.yml其中敏感或可变的配置通过环境变量注入。然后通过不同的.env文件或命令行环境变量来区分环境。# glovebox.yml services: postgres: image: postgres:${POSTGRES_VERSION:-15}-alpine environment: POSTGRES_DB: ${DB_NAME:-myapp_dev}# 开发环境 export POSTGRES_VERSION15 export DB_NAMEmyapp_dev glovebox up # 测试环境 export POSTGRES_VERSION14 export DB_NAMEmyapp_test glovebox up5. 常见问题排查与调试实录即使工具再简单在实际操作中也会遇到各种问题。这里记录了几个我踩过的坑和解决方法。5.1 服务启动失败端口已被占用现象运行glovebox up时某个服务如postgres启动失败日志显示port is already allocated。原因宿主机上该端口如 5432已经被其他进程可能是另一个 Docker 容器也可能是本地安装的 PostgreSQL占用。排查与解决确认占用者在终端运行lsof -i :5432(macOS/Linux) 或netstat -ano | findstr :5432(Windows)查看是哪个进程占用了端口。解决方案方案A推荐在glovebox.yml中修改端口映射换一个空闲端口。例如将5432:5432改为5433:5432。之后连接数据库时使用localhost:5433。方案B停止并移除占用端口的进程。如果是另一个无关的 Docker 容器可以用docker ps找到并docker stop它。如果是本地安装的服务可能需要通过系统服务管理工具如systemctl、brew services来停止。方案C如果占用端口的就是你之前启动的glovebox环境但没清理干净。运行glovebox down确保所有容器被删除然后再glovebox up。5.2 依赖服务未就绪健康检查失败现象api服务启动失败日志显示连接数据库超时或被拒绝。但glovebox的日志显示它已经尝试启动api了。原因depends_on配置了condition: service_healthy但被依赖的服务如postgres的健康检查 (healthcheck) 设置不合理要么检查命令不对要么等待时间intervaltimeout*retries太短数据库还没初始化完就判定为不健康。排查与解决检查健康检查命令进入postgres容器手动执行健康检查命令pg_isready -U devuser看是否能成功。调整健康检查参数增加interval、timeout或retries的值给数据库更长的启动和准备时间。对于重型服务初始启动可能需几十秒。healthcheck: test: [CMD-SHELL, pg_isready -U devuser] interval: 10s # 检查间隔延长 timeout: 5s # 单次检查超时延长 retries: 15 # 重试次数增加 start_period: 30s # Docker Compose v2.1 支持表示容器启动后多久开始健康检查glovebox可能不支持但可参考思路简化依赖如果只是快速测试可以将condition: service_healthy改为condition: service_started如果glovebox支持或者直接去掉condition仅保留depends_on: [postgres]。但这会引入风险即api可能在数据库完全准备好之前就开始连接。5.3 容器内无法解析服务名现象在api服务的容器内无法通过postgres这个主机名连接到数据库但通过localhost:5432从宿主机可以连接。原因glovebox会为每个项目创建一个独立的 Docker 网络服务名在这个网络内作为主机名使用。如果api服务配置的DATABASE_URL写成了localhost那它指向的是容器自己的环回地址而不是postgres服务。排查与解决确认连接字符串确保在服务配置的environment中连接其他服务时使用的是服务名而不是localhost或127.0.0.1。正确示例postgres://devuser:devpasswordpostgres:5432/myapp_dev。进入容器测试使用glovebox exec api sh进入api容器然后尝试ping postgres或nslookup postgres看是否能解析到 IP 地址。同时用cat /etc/hosts查看应该能看到glovebox自动添加的服务名映射条目。检查网络运行docker network ls找到名字类似glovebox-fullstack-dev-env_default的网络然后docker network inspect network_id查看Containers部分确认api和postgres容器是否都在这个网络中。5.4 数据卷权限问题现象尤其是使用 Linux 主机或某些 Linux 容器时挂载宿主机目录后容器内应用如 Node.js报错“没有写入权限”或“无法创建目录”。原因宿主机上的用户 UID/GID 与容器内运行进程的用户如node用户的 UID 通常是 1000不匹配导致权限冲突。排查与解决查看容器内用户glovebox exec api id查看容器内当前用户的 UID/GID。方案A修改宿主机目录权限简单粗暴适合开发环境在宿主机上将项目目录的权限改为宽松模式例如chmod -R 777 ./backend。注意这有安全风险仅用于本地开发。方案B指定容器运行用户更安全在 Dockerfile 中确保以非 root 用户运行并且该用户的 UID/GID 与你的宿主机开发用户匹配。或者在glovebox.yml中指定userapi: build: ./backend user: 1000:1000 # 格式UID:GID替换成你宿主机的 UID:GID (通过 id -u 和 id -g 查看) volumes: - ./backend:/app方案C使用命名卷对于需要持久化但不需要直接编辑的文件如数据库数据、node_modules使用命名卷而非宿主机目录绑定挂载可以避免权限问题。5.5glovebox down后数据丢失现象运行glovebox down后再次glovebox up发现数据库回到了初始状态。原因glovebox down默认会删除容器但会保留在顶级volumes:字段中声明的命名卷。如果你的数据没有存储在命名卷中而是存储在容器内部或匿名卷中数据就会丢失。排查与解决确认卷配置检查glovebox.yml对于需要持久化的数据如 PostgreSQL 的/var/lib/postgresql/data必须使用在顶级volumes:中声明的命名卷。volumes: postgres_data: # 这里声明命名卷 services: postgres: volumes: - postgres_data:/var/lib/postgresql/data # 这里使用命名卷检查卷是否存在运行docker volume ls你应该能看到一个名为project_name_postgres_data的卷。谨慎使用-v参数glovebox down -v命令会删除所有关联的命名卷导致数据永久丢失。除非你确定要清理所有数据否则不要使用这个参数。经过这些实战和问题排查你应该能感受到glovebox在简化本地开发工作流上的巨大潜力。它用极简的配置覆盖了日常开发中 80% 的环境管理需求让你能更专注于代码本身而不是繁琐的环境搭建。
Glovebox：轻量级本地开发环境编排工具实战指南
发布时间：2026/5/18 18:12:53
1. 项目概述一个被低估的本地开发利器如果你和我一样常年泡在本地开发环境里和各种服务、数据库、中间件打交道那你一定对“端口冲突”、“环境变量混乱”、“服务依赖启动顺序”这些词深恶痛绝。每次新开一个项目或者临时测试一个想法都得手动去启动一堆服务改一堆配置过程繁琐不说还容易出错。leftathome/glovebox这个项目就是来解决这个痛点的。你可以把它理解为一个轻量级的、声明式的本地开发环境编排与管理工具。它不像 Docker Compose 那样重也不像手动写一堆脚本那样乱而是用一种简洁的 YAML 配置文件把你项目所需的所有服务比如 Web 服务器、数据库、缓存、消息队列等定义好然后一条命令就能让整个环境“活”起来。我第一次看到这个项目名glovebox手套箱时就觉得特别形象。在化学实验室里手套箱是一个隔离的操作环境你可以安全地在里面处理对空气或水分敏感的材料。而在软件开发中glovebox为你构建了一个隔离的、可复现的“操作环境”让你能安全、便捷地启动和管理一组相互关联的服务而不用担心污染宿主机环境或与其他项目冲突。它尤其适合前端全栈、微服务本地联调、需要固定依赖版本的个人项目等场景。对于独立开发者、小团队或者任何追求开发效率的人来说这绝对是一个值得放入工具箱的利器。2. 核心设计理念与架构拆解2.1 为什么是 Glovebox而不是其他市面上管理本地服务的工具不少比如docker-compose、minikube/kind本地K8s、vagrant甚至是一堆bash脚本。glovebox的定位非常清晰极致简单和快速。它不是为了模拟生产环境那是docker-compose和kind的强项也不是为了管理复杂的虚拟机vagrant它的目标就是让你用最小的认知负担和启动成本在本地跑起一组服务。它的核心优势在于零守护进程glovebox本身只是一个二进制文件启动服务时才会运行没有常驻后台的守护进程不占用额外资源用完即走非常干净。声明式配置所有服务、依赖、环境变量、端口映射都在一个glovebox.yml文件里定义。这种“基础设施即代码”的方式使得你的开发环境可以被版本控制新同事拉下代码就能获得一模一样的环境。依赖感知你可以明确指定服务之间的启动顺序A 依赖 B则 B 先于 A 启动并且glovebox会等待被依赖的服务健康检查通过后再启动下一个这比手动脚本可靠得多。资源绑定与清理glovebox启动的服务其生命周期与glovebox命令绑定。当你停止glovebox时它会尝试优雅地停止所有它启动的服务。这避免了后台残留一堆进程的情况。2.2 配置文件深度解析glovebox.yml的每一个字段glovebox的强大和易用性几乎全部体现在它的配置文件里。我们来看一个典型的、功能比较全面的glovebox.yml示例name: my-fullstack-app services: postgres: image: postgres:15-alpine ports: - 5432:5432 environment: POSTGRES_USER: myuser POSTGRES_PASSWORD: mysecretpassword POSTGRES_DB: myapp_dev healthcheck: test: [CMD-SHELL, pg_isready -U myuser] interval: 5s timeout: 3s retries: 5 volumes: - postgres_data:/var/lib/postgresql/data redis: image: redis:7-alpine ports: - 6379:6379 command: redis-server --appendonly yes healthcheck: test: [CMD, redis-cli, ping] interval: 5s api-server: build: ./backend ports: - 3000:3000 environment: DATABASE_URL: postgres://myuser:mysecretpasswordpostgres:5432/myapp_dev REDIS_URL: redis://redis:6379 depends_on: postgres: condition: service_healthy redis: condition: service_healthy # 使用宿主机的环境变量避免密码泄露在代码库中 env_file: .env.api web-app: build: ./frontend ports: - 8080:80 environment: API_BASE_URL: http://localhost:3000 # 开发模式下的热重载卷挂载 volumes: - ./frontend/src:/app/src volumes: postgres_data:我们来逐一拆解每个关键部分name: 项目名称。这主要用于在多个glovebox环境同时运行时进行区分。services: 核心部分定义了所有需要运行的服务。每个服务是一个键值对键是服务名如postgres值是该服务的配置。image: 指定使用的 Docker 镜像。这是启动服务最直接的方式。build: 如果服务需要从本地 Dockerfile 构建则使用此字段后面跟 Dockerfile 所在的上下文路径如./backend。glovebox会先执行docker build。ports: 端口映射格式为宿主机端口:容器内端口。这是将容器服务暴露给本地访问的关键。environment: 设置容器内的环境变量。这里有一个重要技巧对于密码等敏感信息强烈建议使用env_file或通过宿主机环境变量传入而不是直接写死在 YAML 文件中以防配置文件被提交到公开仓库。env_file: 指定一个包含环境变量的文件路径。文件内容通常是KEYVALUE格式。这是管理敏感配置和不同环境开发、测试配置的最佳实践。depends_on: 定义服务依赖关系。glovebox会按照依赖顺序启动服务。condition: service_healthy表示不仅等待依赖服务启动还要等待其通过健康检查healthcheck这对于数据库等需要初始化时间的服务至关重要。healthcheck: 定义如何检查服务是否“健康”并已准备好接受连接。这是实现可靠依赖启动的核心。支持CMD、CMD-SHELL等多种形式。volumes: 定义数据卷用于持久化数据如数据库数据或将宿主机目录挂载到容器内如前端代码目录用于实现热重载。command: 覆盖容器默认的启动命令。volumes(顶级字段): 声明在services部分使用的命名数据卷。这确保了即使容器被删除数据如postgres_data依然保留在宿主机上。注意glovebox的配置语法与docker-compose高度相似但并非完全兼容。它做了很多简化只保留了最核心、最常用的字段。这意味着从docker-compose.yml迁移过来通常很容易但复杂的功能如network自定义、extends等可能需要调整思路或暂时无法实现。这其实是glovebox“简单至上”哲学的一种体现。2.3 与 Docker Compose 的精准对比何时选择谁这是一个无法回避的问题。简单对比如下特性GloveboxDocker Compose核心目标快速启动、简化本地开发定义和运行多容器 Docker 应用涵盖开发、测试、生产配置复杂度极简字段少学习成本低功能全面字段多配置灵活但也更复杂守护进程无按需启动有 (docker-compose命令本身无但依赖 Docker 守护进程)生产适用性不推荐仅为本地开发优化可以常用于 CI/CD 和生产环境部署网络管理自动创建隔离网络服务间通过服务名通信支持自定义网络功能更强大扩展性较弱专注于核心场景强支持插件、扩展配置、合并文件等启动速度通常更快逻辑更直接相对标准选择建议用 Glovebox当你需要一个轻量、快速、零配置的方式来管理本地开发依赖数据库、缓存、Mock API等特别是用于个人项目、原型验证、或者作为大型项目中一个独立组件的开发环境时。用 Docker Compose当你的项目需要严格模拟生产环境配置非常复杂多网络、资源限制、扩展配置或者你需要在 CI/CD 流水线或生产服务器上使用同一套配置时。实际上它们并非互斥。我个人的工作流中一个项目里可能同时存在glovebox.yml用于快速启动开发依赖和docker-compose.yml用于集成测试或生产构建。Glovebox更像是你桌面上一个即开即用的“开发沙盒”。3. 从零开始实战搭建一个全栈应用开发环境理论说了这么多我们动手搭一个真实的全栈应用Node.js API React 前端 PostgreSQL Redis的开发环境感受一下glovebox的流畅。3.1 环境准备与工具安装首先你需要安装glovebox。因为它是一个独立的二进制文件安装极其简单。以 macOS 和 Linux 为例# 使用 curl 下载最新版本请前往项目 GitHub 仓库查看最新版本号 curl -L -o glovebox.tar.gz https://github.com/leftathome/glovebox/releases/download/v0.8.0/glovebox_0.8.0_darwin_all.tar.gz # 解压 tar -xzf glovebox.tar.gz # 将二进制文件移动到系统路径如 /usr/local/bin sudo mv glovebox /usr/local/bin/ # 验证安装 glovebox --version对于 Windows 用户可以直接下载对应的.exe文件并将其所在目录添加到系统 PATH 环境变量中。当然glovebox的底层依赖于 Docker 来运行容器。所以请确保你的机器上已经安装了Docker Desktop或Docker Engine并且 Docker 服务正在运行。在终端执行docker --version确认即可。3.2 编写第一个glovebox.yml文件在你的项目根目录下创建一个名为glovebox.yml的文件。我们将一步步填充内容。第一步定义数据持久化卷。我们不希望每次关闭数据库数据就丢失。name: fullstack-dev-env volumes: postgres_data:第二步添加 PostgreSQL 服务。这是我们的主数据库。services: postgres: image: postgres:15-alpine # 使用 Alpine 版本更轻量 ports: - 5432:5432 # 将容器5432端口映射到本地5432方便用 GUI 工具连接 environment: POSTGRES_USER: devuser POSTGRES_PASSWORD: devpassword # 生产环境切勿使用此简单密码 POSTGRES_DB: myapp_dev volumes: - postgres_data:/var/lib/postgresql/data # 数据持久化 healthcheck: test: [CMD-SHELL, pg_isready -U devuser] interval: 5s timeout: 3s retries: 10 # 给数据库足够的启动时间第三步添加 Redis 服务。用作缓存或会话存储。redis: image: redis:7-alpine ports: - 6379:6379 command: redis-server --appendonly yes # 启用 AOF 持久化 healthcheck: test: [CMD, redis-cli, ping] interval: 5s第四步添加后端 API 服务。假设你的后端代码在./backend目录其中包含Dockerfile。api: build: ./backend # 指向后端 Dockerfile 所在目录 ports: - 3000:3000 # 假设你的 Node.js 应用监听 3000 端口 environment: # 关键这里使用服务名‘postgres’和‘redis’作为主机名。 # 在 glovebox 创建的内部网络中服务名即主机名。 DATABASE_URL: postgres://devuser:devpasswordpostgres:5432/myapp_dev REDIS_URL: redis://redis:6379 NODE_ENV: development depends_on: postgres: condition: service_healthy # 等待数据库健康 redis: condition: service_healthy # 等待 Redis 健康 # 开发模式将本地代码目录挂载到容器实现代码变更热重载 volumes: - ./backend:/usr/src/app - /usr/src/app/node_modules # 匿名卷防止覆盖宿主机的 node_modules第五步添加前端 React 服务。假设前端代码在./frontend目录使用nginx提供服务。web: build: ./frontend # 指向前端 Dockerfile 所在目录 ports: - 8080:80 # 前端访问端口 environment: # 前端需要知道后端 API 地址。这里使用宿主机 localhost # 因为前端是从用户浏览器发请求而不是从容器网络内部。 REACT_APP_API_BASE: http://localhost:3000 depends_on: - api # 前端依赖于后端 API但通常不需要健康检查 # 同样挂载源码目录用于开发热更新如果使用 nginx 静态服务此配置可能不同 # 更常见的做法是前端在宿主机用 npm start这里仅作容器化示例。现在你的glovebox.yml文件就完成了。它清晰地定义了四个服务及其关系。3.3 启动、管理与交互在项目根目录下执行一个简单的命令glovebox up你会看到glovebox开始执行一系列动作解析glovebox.yml文件。为该项目创建一个独立的 Docker 网络通常是glovebox-项目名。按顺序拉取镜像如果本地没有或构建镜像对于build的服务。根据depends_on和healthcheck的配置依次启动服务。你会看到它等待postgres和redis健康检查通过后才启动api服务。所有服务启动后glovebox会附着到所有服务的日志输出让你在一个窗口看到所有日志流。此时打开浏览器访问http://localhost:8080查看前端页面。访问http://localhost:3000/api/health假设你有这个端点测试后端 API。用psql或任何 GUI 工具如 TablePlus, DBeaver连接localhost:5432用户devuser密码devpassword数据库myapp_dev可以操作数据库。用redis-cli连接localhost:6379操作 Redis。其他常用命令glovebox up -d: 后台模式启动服务不附着日志。glovebox logs [service_name]: 查看特定或所有服务的日志。glovebox ps: 查看本项目下所有运行中的服务状态类似于docker ps但只过滤出本glovebox环境管理的容器。glovebox stop: 停止所有服务但不删除容器和卷。下次glovebox up会很快。glovebox down:停止并删除所有服务容器但默认保留volumes中定义的命名卷。这是比较彻底的清理。glovebox exec service_name command: 在运行中的服务容器内执行命令。例如glovebox exec postgres psql -U devuser -d myapp_dev可以直接进入数据库命令行。实操心得在开发时我习惯用glovebox up在前台运行这样所有日志一目了然排查问题非常方便。当需要临时离开或专注写代码时可以CtrlC中断然后使用glovebox up -d切换到后台。glovebox ps命令是我最常用的之一它能快速确认所有服务是否都在预期状态下运行。4. 高级技巧与最佳实践4.1 环境变量与敏感信息管理直接在glovebox.yml中写明文密码是绝对禁止的尤其是项目需要提交到 Git 仓库时。我们有更安全的方式方法一使用env_file创建一个.env.api文件确保它在.gitignore中DATABASE_URLpostgres://realuser:complexpasswordpostgres:5432/myapp_dev API_SECRET_KEYsupersecretkey123然后在glovebox.yml中引用api: # ... 其他配置 ... env_file: .env.api # 可以同时使用 environment 和 env_file后者优先级更高 environment: NODE_ENV: development方法二使用宿主机环境变量在运行glovebox前先在终端导出变量或在glovebox.yml中使用${VAR_NAME}语法注意glovebox对变量替换的支持可能不如docker-compose完整需测试。export DB_PASSWORDmysecret glovebox up在 YAML 中environment: POSTGRES_PASSWORD: ${DB_PASSWORD:-defaultpassword} # 如果DB_PASSWORD不存在则用默认值方法三推荐使用.env文件配合env_file在项目根目录创建.env文件加入.gitignore里面定义所有环境变量。然后让各个服务的env_file都指向这个文件或者使用工具如direnv在进入项目目录时自动加载。这样管理起来最集中。4.2 开发效率优化热重载与代码挂载对于需要频繁修改代码的后端如 Node.js、Python和前端项目每次改代码都重建镜像是不可接受的。volumes挂载是解决这个问题的银弹。后端 Node.js 示例api: build: ./backend volumes: # 将宿主机当前目录下的 backend 文件夹挂载到容器的 /app 目录 - ./backend:/app # 这是一个关键技巧创建一个匿名卷覆盖容器内的 node_modules。 # 这样容器内 npm install 生成的 node_modules 不会因为宿主机挂载而被清空。 - /app/node_modules environment: # 很多 Node.js 框架在开发模式下支持文件监听重启 NODE_ENV: development前端 React (使用 Node 开发服务器) 示例更常见的模式是前端开发不使用glovebox容器化而是在宿主机直接运行npm start因为它依赖热模块替换HMR在容器内配置稍复杂。但如果你坚持容器化web-dev: build: context: ./frontend # 使用开发阶段的 Dockerfile dockerfile: Dockerfile.dev ports: - 3001:3000 # 假设开发服务器跑在3000端口 volumes: - ./frontend/src:/app/src - ./frontend/public:/app/public - /app/node_modules # 覆盖启动命令直接运行 npm start command: npm start environment: CHOKIDAR_USEPOLLING: true # 在某些文件系统如 Docker for Mac 的默认挂载下需要这个来启用文件监听注意事项在 macOS 和 Windows 上由于 Docker Desktop 的虚拟机文件系统性能问题使用volumes挂载进行文件同步可能会有延迟。如果发现代码更改后容器内反应慢可以尝试调整CHOKIDAR_USEPOLLING环境变量或者考虑使用docker-sync等第三方工具来提升性能。4.3 多环境配置管理你可能需要为“开发”、“测试”、“演示”准备不同的环境配置如数据库名、API 端点。glovebox本身没有多环境文件继承功能但我们可以用一些技巧实现技巧一使用多个 YAML 文件创建glovebox.dev.yml、glovebox.staging.yml通过-f参数指定glovebox -f glovebox.dev.yml up glovebox -f glovebox.staging.yml up在不同文件里你可以修改镜像标签、环境变量、端口等。技巧二环境变量控制 通用模板创建一个基础的glovebox.yml其中敏感或可变的配置通过环境变量注入。然后通过不同的.env文件或命令行环境变量来区分环境。# glovebox.yml services: postgres: image: postgres:${POSTGRES_VERSION:-15}-alpine environment: POSTGRES_DB: ${DB_NAME:-myapp_dev}# 开发环境 export POSTGRES_VERSION15 export DB_NAMEmyapp_dev glovebox up # 测试环境 export POSTGRES_VERSION14 export DB_NAMEmyapp_test glovebox up5. 常见问题排查与调试实录即使工具再简单在实际操作中也会遇到各种问题。这里记录了几个我踩过的坑和解决方法。5.1 服务启动失败端口已被占用现象运行glovebox up时某个服务如postgres启动失败日志显示port is already allocated。原因宿主机上该端口如 5432已经被其他进程可能是另一个 Docker 容器也可能是本地安装的 PostgreSQL占用。排查与解决确认占用者在终端运行lsof -i :5432(macOS/Linux) 或netstat -ano | findstr :5432(Windows)查看是哪个进程占用了端口。解决方案方案A推荐在glovebox.yml中修改端口映射换一个空闲端口。例如将5432:5432改为5433:5432。之后连接数据库时使用localhost:5433。方案B停止并移除占用端口的进程。如果是另一个无关的 Docker 容器可以用docker ps找到并docker stop它。如果是本地安装的服务可能需要通过系统服务管理工具如systemctl、brew services来停止。方案C如果占用端口的就是你之前启动的glovebox环境但没清理干净。运行glovebox down确保所有容器被删除然后再glovebox up。5.2 依赖服务未就绪健康检查失败现象api服务启动失败日志显示连接数据库超时或被拒绝。但glovebox的日志显示它已经尝试启动api了。原因depends_on配置了condition: service_healthy但被依赖的服务如postgres的健康检查 (healthcheck) 设置不合理要么检查命令不对要么等待时间intervaltimeout*retries太短数据库还没初始化完就判定为不健康。排查与解决检查健康检查命令进入postgres容器手动执行健康检查命令pg_isready -U devuser看是否能成功。调整健康检查参数增加interval、timeout或retries的值给数据库更长的启动和准备时间。对于重型服务初始启动可能需几十秒。healthcheck: test: [CMD-SHELL, pg_isready -U devuser] interval: 10s # 检查间隔延长 timeout: 5s # 单次检查超时延长 retries: 15 # 重试次数增加 start_period: 30s # Docker Compose v2.1 支持表示容器启动后多久开始健康检查glovebox可能不支持但可参考思路简化依赖如果只是快速测试可以将condition: service_healthy改为condition: service_started如果glovebox支持或者直接去掉condition仅保留depends_on: [postgres]。但这会引入风险即api可能在数据库完全准备好之前就开始连接。5.3 容器内无法解析服务名现象在api服务的容器内无法通过postgres这个主机名连接到数据库但通过localhost:5432从宿主机可以连接。原因glovebox会为每个项目创建一个独立的 Docker 网络服务名在这个网络内作为主机名使用。如果api服务配置的DATABASE_URL写成了localhost那它指向的是容器自己的环回地址而不是postgres服务。排查与解决确认连接字符串确保在服务配置的environment中连接其他服务时使用的是服务名而不是localhost或127.0.0.1。正确示例postgres://devuser:devpasswordpostgres:5432/myapp_dev。进入容器测试使用glovebox exec api sh进入api容器然后尝试ping postgres或nslookup postgres看是否能解析到 IP 地址。同时用cat /etc/hosts查看应该能看到glovebox自动添加的服务名映射条目。检查网络运行docker network ls找到名字类似glovebox-fullstack-dev-env_default的网络然后docker network inspect network_id查看Containers部分确认api和postgres容器是否都在这个网络中。5.4 数据卷权限问题现象尤其是使用 Linux 主机或某些 Linux 容器时挂载宿主机目录后容器内应用如 Node.js报错“没有写入权限”或“无法创建目录”。原因宿主机上的用户 UID/GID 与容器内运行进程的用户如node用户的 UID 通常是 1000不匹配导致权限冲突。排查与解决查看容器内用户glovebox exec api id查看容器内当前用户的 UID/GID。方案A修改宿主机目录权限简单粗暴适合开发环境在宿主机上将项目目录的权限改为宽松模式例如chmod -R 777 ./backend。注意这有安全风险仅用于本地开发。方案B指定容器运行用户更安全在 Dockerfile 中确保以非 root 用户运行并且该用户的 UID/GID 与你的宿主机开发用户匹配。或者在glovebox.yml中指定userapi: build: ./backend user: 1000:1000 # 格式UID:GID替换成你宿主机的 UID:GID (通过 id -u 和 id -g 查看) volumes: - ./backend:/app方案C使用命名卷对于需要持久化但不需要直接编辑的文件如数据库数据、node_modules使用命名卷而非宿主机目录绑定挂载可以避免权限问题。5.5glovebox down后数据丢失现象运行glovebox down后再次glovebox up发现数据库回到了初始状态。原因glovebox down默认会删除容器但会保留在顶级volumes:字段中声明的命名卷。如果你的数据没有存储在命名卷中而是存储在容器内部或匿名卷中数据就会丢失。排查与解决确认卷配置检查glovebox.yml对于需要持久化的数据如 PostgreSQL 的/var/lib/postgresql/data必须使用在顶级volumes:中声明的命名卷。volumes: postgres_data: # 这里声明命名卷 services: postgres: volumes: - postgres_data:/var/lib/postgresql/data # 这里使用命名卷检查卷是否存在运行docker volume ls你应该能看到一个名为project_name_postgres_data的卷。谨慎使用-v参数glovebox down -v命令会删除所有关联的命名卷导致数据永久丢失。除非你确定要清理所有数据否则不要使用这个参数。经过这些实战和问题排查你应该能感受到glovebox在简化本地开发工作流上的巨大潜力。它用极简的配置覆盖了日常开发中 80% 的环境管理需求让你能更专注于代码本身而不是繁琐的环境搭建。
