Cup：极简单机容器管理工具，替代Docker Compose的轻量方案

1. 项目概述：一个轻量级容器化应用管理工具

最近在折腾个人服务器和开发环境时，我一直在寻找一个能替代 Docker Compose 但又更轻量、更聚焦于单机场景的工具。Docker Compose 功能强大，但对于我这种只需要在单台机器上快速拉起几个服务、管理一些简单应用的人来说，它的 YAML 配置语法有时显得有点“重”，而且其设计初衷更偏向于多容器应用的编排。就在这个当口，我发现了sergi0g/cup这个项目。简单来说，Cup是一个用 Go 语言编写的、极简风格的容器化应用管理工具。它的核心思想非常直接：用最少的配置和命令，帮你管理基于容器（主要是 Docker）的应用生命周期，包括运行、停止、查看日志和清理。它不试图成为下一个 Kubernetes，而是精准地解决“我在自己的电脑或服务器上，想方便地运行和管理几个容器”这个具体问题。

如果你是一名开发者，经常需要在本地运行数据库、消息队列或者某个后端服务进行开发测试；或者你是一名运维爱好者，在家庭服务器上用 Docker 部署了博客、网盘、智能家居中枢等一堆服务，那么 Cup 很可能就是你一直在找的那个“瑞士军刀”。它通过一个简单的cup.yml配置文件来定义服务，命令集极其精简（cup run,cup stop,cup logs等），几乎没有任何学习成本。接下来，我会深入拆解 Cup 的设计哲学、核心功能、具体用法，并分享我在实际使用中积累的配置技巧和避坑经验。你会发现，将日常的容器管理任务交给 Cup，能让你的工作流变得异常清爽。

2. 核心设计理念与架构解析

2.1 为什么是“Cup”？解决什么痛点？

在容器化生态中，我们已经有了 Docker CLI 和 Docker Compose。Docker CLI 是基础，但管理多个有依赖关系的容器时，需要手动执行多条命令，繁琐且易错。Docker Compose 通过 YAML 文件解决了编排问题，但它是一个相对庞大的工具，其 YAML 语法支持大量用于复杂生产环境的配置项（如部署策略、网络扩展），对于简单场景来说，这些功能多数是用不上的，反而增加了配置文件的复杂度和认知负担。

Cup 的诞生正是为了填补这个空白。它的设计目标非常明确：

1. 极简配置：其配置文件cup.yml的语法比docker-compose.yml更加简洁直观，只保留最核心的容器定义参数（如镜像、端口、卷、环境变量）。
2. 单一二进制文件：Cup 本身是一个静态编译的 Go 二进制文件，无需安装任何运行时或依赖，下载即用，卸载也只是一个删除操作，非常干净。
3. 命令驱动，符合直觉：它的命令集设计得像一个服务管理器。cup run启动所有服务，cup stop停止所有服务，cup logs查看日志，这种模式对于从系统服务管理（如 systemd）转过来的用户来说非常亲切。
4. 专注单机：它不处理集群、节点、高可用等分布式场景，这反而成了它的优势，因为代码和逻辑可以保持极其精简和高效。

从架构上看，Cup 本质上是一个智能的 Docker CLI 封装器和状态管理器。它读取cup.yml，将其中的服务定义转化为对应的docker run命令参数，然后通过 Docker Engine 的 API（通常是本地 Docker Daemon）来创建和运行容器。同时，它会维护一个简单的状态文件（通常是一个 JSON 文件），记录由它启动的容器 ID，以便于后续的集中管理（停止、查看日志等）。这种架构决定了它极其轻量，资源消耗几乎可以忽略不计。

2.2 Cup 与 Docker Compose 的核心差异

为了更清晰地理解 Cup 的定位，我们可以将其与 Docker Compose 做一个快速对比：

从上表可以看出，Cup 更像是一把专门为“简单场景”打磨的锋利小刀，而 Docker Compose 是一套功能齐全的“瑞士军刀”。选择哪一个，完全取决于你的实际需求。如果你追求的是“开箱即用、一目了然、毫无负担”，那么 Cup 的优势就非常明显了。

3. 从零开始使用 Cup：安装与配置详解

3.1 安装 Cup：多种途径任君选择

Cup 的安装过程充分体现了其“轻量”的特性。由于是单一的 Go 二进制文件，安装方式非常灵活。

方法一：直接下载二进制文件（推荐）这是最快捷的方式。前往项目的 GitHub Release 页面，根据你的操作系统和架构下载对应的压缩包。例如，对于 Linux x86_64 系统：

# 下载最新版本的 Cup wget https://github.com/sergi0g/cup/releases/download/v0.1.0/cup_0.1.0_linux_amd64.tar.gz # 解压 tar -xzf cup_0.1.0_linux_amd64.tar.gz # 将二进制文件移动到系统 PATH 目录，例如 /usr/local/bin/ sudo mv cup /usr/local/bin/ # 验证安装 cup --version

对于 macOS 用户，可以使用curl下载 Darwin 版本，过程类似。

方法二：通过包管理器安装如果你的系统有 Homebrew (macOS) 或类似的包管理器，并且 Cup 已被收录，安装会更方便。例如（如果可用）：

# macOS with Homebrew brew install cup # Linux with Homebrew (Linuxbrew) brew install cup

不过，由于 Cup 是一个相对较新的个人项目，可能尚未被所有包管理器收录，因此直接下载二进制文件通常是更可靠的选择。

方法三：从源码构建对于想要体验最新特性或进行开发的用户，可以从源码构建。前提是需要在系统上安装 Go 语言环境（1.16+）。

git clone https://github.com/sergi0g/cup.git cd cup go build -o cup main.go sudo mv cup /usr/local/bin/

注意：无论哪种安装方式，请确保你的系统已经安装了 Docker 并且 Docker Daemon 正在运行。Cup 本身不包含容器运行时，它需要调用本地的 Docker。

3.2 编写你的第一个 cup.yml 文件

配置文件是 Cup 的核心。让我们从一个最简单的例子开始，部署一个 Nginx web 服务器。

在你的项目目录下，创建一个名为cup.yml的文件：

name: my-web-stack services: nginx: image: nginx:alpine ports: - "8080:80" volumes: - ./html:/usr/share/nginx/html

这个配置文件的含义是：

• name: my-web-stack: 定义了这个堆栈的名称，Cup 在管理时会用到这个名字。
• services: 下面定义了所有需要管理的服务。
• nginx: 这是我们定义的一个服务，名字可以自定。
  • image: nginx:alpine: 指定使用的容器镜像。这里使用了体积更小的 Alpine 版本。
  • ports: - "8080:80": 端口映射。将宿主机的 8080 端口映射到容器的 80 端口。
  • volumes: - ./html:/usr/share/nginx/html: 数据卷映射。将当前目录下的html文件夹挂载到容器的 Nginx 默认网页目录。这样我们可以在宿主机直接修改网页文件。

现在，在同一个目录下创建一个html文件夹，并在里面放一个index.html文件，内容随意，比如<h1>Hello from Cup!</h1>。

3.3 核心命令初体验

配置好后，就可以使用 Cup 的命令来管理了。

1. 启动服务：在cup.yml所在目录，执行cup run。

   $ cup run Starting service 'nginx'... done

   Cup 会读取当前目录下的cup.yml，然后启动其中定义的所有服务。你会看到它执行了类似于docker run -d --name my-web-stack_nginx -p 8080:80 -v $(pwd)/html:/usr/share/nginx/html nginx:alpine的命令。

2. 验证服务：打开浏览器，访问http://localhost:8080，你应该能看到刚才创建的index.html页面。

3. 查看服务状态：Cup 没有内置的ps命令，但你可以直接使用docker ps来查看由它启动的容器。你会发现容器名被自动格式化为{stack_name}_{service_name}的形式，这里是my-web-stack_nginx。

4. 查看日志：使用cup logs可以查看所有服务的聚合日志。如果想看特定服务或跟踪实时日志，可以使用cup logs nginx或cup logs -f nginx。

   $ cup logs nginx /docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration ...

5. 停止服务：执行cup stop，Cup 会停止由它启动的所有容器。

   $ cup stop Stopping service 'nginx'... done

6. 清理资源：cup clean命令非常有用。它不仅会停止容器，还会移除这些容器。这相当于执行了docker stop和docker rm。在开发测试中，想彻底重置环境时，这个命令很便捷。

   警告：cup clean会删除容器！请确保容器内没有需要持久化的数据（未通过卷映射出来的数据会丢失）。对于数据库等服务，务必正确配置数据卷。

通过这个简单的例子，你已经感受到了 Cup 的便捷。接下来，我们将深入其配置文件的各个部分。

4. cup.yml 配置文件深度解析

一个完整的cup.yml可以配置多个服务，并支持容器运行所需的绝大多数常见参数。下面我们以一个更复杂的、包含后端 API 和数据库的示例来逐一拆解。

4.1 服务定义：从简单到复杂

假设我们要部署一个简单的 Web 应用，包含一个 PostgreSQL 数据库和一个用 Node.js 写的 API 服务。

name: my-app services: postgres: image: postgres:15-alpine environment: POSTGRES_USER: appuser POSTGRES_PASSWORD: secretpassword POSTGRES_DB: myappdb volumes: - postgres_data:/var/lib/postgresql/data ports: - "5432:5432" api: image: my-api-image:latest # 假设这是你构建好的镜像 environment: DATABASE_URL: postgres://appuser:secretpassword@postgres:5432/myappdb NODE_ENV: production ports: - "3000:3000" depends_on: - postgres volumes: - ./app-logs:/app/logs volumes: postgres_data:

逐项解析：

• name(根级别): 必填。定义项目堆栈的名称，用于容器命名和状态管理。
• services: 必填。所有服务的集合。
  • postgres和api: 服务名称。在 Cup 内部和 Docker 容器命名中会使用到。
• image: 必填。指定 Docker 镜像名和标签。可以是官方镜像（如postgres:15-alpine），也可以是私有镜像。
• environment: 设置容器内的环境变量。对于数据库、应用配置至关重要。强烈建议将敏感信息（如密码）通过环境变量文件或 secrets 管理，而不是硬编码在 YAML 中（Cup 本身可能不支持高级 secrets 管理，这是其局限之一，通常需要借助外部工具或 Docker 本身的功能）。
• volumes: 数据卷映射。有两种形式：
  1. 绑定挂载 (Bind Mount):- ./app-logs:/app/logs，将宿主机路径映射到容器内。适合开发时同步代码或存放日志。
  2. 命名卷 (Named Volume):- postgres_data:/var/lib/postgresql/data，使用在文件底部volumes部分定义的命名卷。Docker 会管理其生命周期和存储位置，是持久化数据库数据的推荐方式。
• ports: 端口映射。格式为"宿主机端口:容器端口"。将容器内部的服务端口暴露给宿主机，从而可以从外部访问。
• depends_on:这是一个需要特别注意的字段。在 Docker Compose 中，depends_on仅控制容器的启动和停止顺序（先启动 A，再启动 B），但并不等待服务“就绪”（比如数据库完成初始化、可以接受连接）。Cup 的depends_on行为类似，它只保证启动顺序。这意味着，如果你的api服务在启动时立即连接数据库，而数据库尚未初始化完成，可能会导致连接失败。解决方案：需要在你的应用代码中实现重试逻辑，或者使用一个启动脚本来等待依赖服务就绪。这是使用简单编排工具时的一个常见陷阱。

4.2 网络配置：容器间通信

默认情况下，Cup 会将所有服务放在 Docker 的默认桥接网络（通常是bridge）中。在这个网络上，容器可以通过服务名称作为主机名互相访问。这就是为什么在上面的例子中，api服务可以通过postgres这个主机名连接到数据库容器（DATABASE_URL: ...@postgres:5432...）。

如果你需要更复杂的网络配置，比如让容器加入一个现有的 Docker 网络，Cup 也提供了支持：

services: my-service: image: nginx network: my-custom-network # 指定容器加入的现有网络

需要注意的是，Cup 本身不会创建网络。你需要预先使用docker network create my-custom-network创建好网络。这对于需要让 Cup 管理的容器与宿主机上其他非 Cup 管理的容器进行通信的场景很有用。

4.3 资源限制与重启策略

对于生产环境或资源受限的环境，限制容器的资源使用是必要的。Cup 支持 Docker 标准的资源限制配置：

services: my-worker: image: worker:latest cpus: "0.5" # 限制使用 0.5 个 CPU 核心 memory: "512M" # 限制内存为 512 MB restart: always # 重启策略：容器退出时总是重启

• cpus: 可以设置为小数，如"1.5"，表示 1.5 个 CPU 核心的计算时间。
• memory: 设置内存限制，单位可以是B,K,M,G。
• restart: 重启策略。可选值通常包括：
  • no: 不自动重启（默认）。
  • always: 容器退出时总是重启。
  • on-failure: 仅在非正常退出（退出代码非0）时重启，可附加最大重试次数，如on-failure:3。

正确设置资源限制可以防止单个容器耗尽主机资源，而合理的重启策略可以确保关键服务在意外退出后能自动恢复。

5. 高级用法与实战技巧

5.1 使用环境变量文件管理敏感配置

永远不要在cup.yml中硬编码密码、API密钥等敏感信息。最佳实践是使用环境变量文件。首先，创建一个.env文件（确保它被添加到.gitignore中）：

# .env 文件 POSTGRES_PASSWORD=my_very_strong_password_here API_SECRET_KEY=another_secret_value

然后，在cup.yml中引用这个文件，并修改环境变量配置：

services: postgres: image: postgres:15-alpine env_file: .env # 指定环境变量文件 environment: POSTGRES_USER: appuser POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} # 引用 .env 中的变量 POSTGRES_DB: myappdb

Cup 会读取.env文件，并将变量注入到容器的环境中。这样，敏感信息就和代码配置分离了。

5.2 处理服务依赖与健康检查

如前所述，depends_on只解决启动顺序，不解决“就绪”问题。为了确保服务间可靠启动，有几种模式：

1. 应用内重试：这是最健壮的方式。在你的应用代码（如 API 服务）连接数据库时，实现一个指数退避的重试循环。

   // Node.js 示例代码片段 const { Client } = require('pg'); let retries = 5; while (retries) { try { const client = new Client(process.env.DATABASE_URL); await client.connect(); console.log('Database connected!'); break; } catch (err) { console.log(`Database connection failed. Retries left: ${retries}`); retries -= 1; await new Promise(res => setTimeout(res, 2000)); // 等待2秒 } }

2. 使用启动脚本：在 Dockerfile 的ENTRYPOINT或CMD中使用一个包装脚本。这个脚本先等待依赖服务就绪，再启动主程序。可以使用wait-for-it.sh或dockerize这类工具。

   # Dockerfile 示例片段 ADD https://github.com/ufoscout/docker-compose-wait/releases/download/2.9.0/wait /wait RUN chmod +x /wait CMD /wait -t 30 postgres:5432 -- /usr/local/bin/your-app-start-command

   然后在cup.yml中，确保api服务depends_onpostgres。

3. 健康检查（如果 Cup 支持）：检查 Cup 的文档或源码，看是否支持在cup.yml中定义healthcheck。如果支持，这将是更优雅的解决方案。如果原生不支持，上述两种方法就是必要的补充。

5.3 结合 Makefile 或 Shell 脚本构建工作流

Cup 专注于运行，而构建镜像、运行测试等任务可以交给其他工具。一个常见的模式是使用Makefile来组织整个工作流：

# Makefile .PHONY: build run stop logs clean build: docker build -t my-api-image:latest ./api run: build cup run stop: cup stop logs: cup logs -f clean: cup clean docker rmi my-api-image:latest || true

这样，通过简单的make run命令，就可以完成构建镜像并启动所有服务的全套操作，极大提升了开发效率。

5.4 在多环境（开发/生产）中使用 Cup

虽然 Cup 配置简单，但通过一些技巧也能实现多环境配置。一种方法是使用不同的环境变量文件和条件逻辑（需要借助外部工具）。

例如，创建cup.dev.yml和cup.prod.yml，以及对应的.env.dev和.env.prod。

# cup.dev.yml name: my-app-dev services: api: image: my-api-image:dev environment: NODE_ENV: development ports: - "3000:3000"

# cup.prod.yml name: my-app-prod services: api: image: my-api-image:prod environment: NODE_ENV: production ports: - "80:3000" restart: always

然后，通过一个简单的包装脚本或别名来切换：

# dev.sh cp cup.dev.yml cup.yml cp .env.dev .env cup run # prod.sh cp cup.prod.yml cup.yml cp .env.prod .env cup run

更高级的做法是使用envsubst等工具，用一个模板cup.yml.template结合不同的环境变量文件来生成最终的cup.yml。

6. 常见问题、故障排查与经验分享

6.1 容器启动失败：镜像拉取或端口冲突

问题现象：执行cup run后，服务启动失败，使用cup logs <service>查看日志，可能看到Error response from daemon: pull access denied或port is already allocated。

排查与解决：

1. 镜像拉取失败：

   • 认证错误：如果是私有镜像仓库，确保你已经在本地执行过docker login。
   • 镜像名或标签错误：仔细检查cup.yml中的image字段。可以手动执行docker pull <image_name>测试。
   • 网络问题：检查 Docker Daemon 的网络连接。

2. 端口冲突：

   • 错误信息会明确提示哪个端口被占用。使用netstat -tulpn | grep :<port>(Linux) 或lsof -i :<port>(macOS) 找出占用端口的进程。
   • 解决方案：要么停止冲突的进程，要么在cup.yml中修改端口映射，例如将"80:3000"改为"8080:3000"。

实操心得：在开发机上，我习惯将常用服务的宿主机端口映射到8000以上的高位端口，如5432->65432(PostgreSQL)，6379->7379(Redis)，这样可以有效避免与系统服务或他人开发环境冲突。

6.2 服务间网络不通：容器无法通过服务名互访

问题现象：api服务日志显示无法连接到postgres:5432，提示Unknown host或连接超时。

排查与解决：

1. 确认网络模式：运行docker inspect <container_id> | grep NetworkMode查看容器是否在同一个网络中。默认情况下，Cup 启动的容器都在默认的bridge网络，但网络名是随机的（如my-app_default）。容器间应能通过服务名通信。
2. 使用容器IP测试：进入api容器 (docker exec -it my-app_api sh)，尝试ping数据库容器的 IP 地址（先通过docker inspect <postgres_container_id> | grep IPAddress获取）。如果 IP 能通但服务名不通，可能是 Docker 的内置 DNS 解析问题。
3. 检查依赖启动顺序：虽然能ping通，但如果数据库还没完成初始化，连接也会失败。确保应用有重试机制。
4. 显式指定网络：如果问题依旧，可以尝试在cup.yml中为所有服务显式指定同一个自定义网络（需预先创建）。

6.3 数据持久化失败：容器重启后数据丢失

问题现象：数据库容器重启后，之前存入的数据全部消失。

原因与解决：这几乎总是因为没有正确配置数据卷持久化。Docker 容器的文件系统是临时的，容器删除后，其中的数据也随之消失。

• 必须为有状态服务（如数据库、文件存储）配置 volumes。
• 对于数据库，强烈建议使用命名卷，如前面示例中的postgres_data。Docker 会将其存储在宿主机的特定目录（如/var/lib/docker/volumes/），生命周期独立于容器。
• 执行cup clean会删除容器，但不会删除命名卷。这是安全的。如果你想彻底清理，需要手动执行docker volume rm <volume_name>。

6.4 Cup 命令不生效或报错

问题现象：执行cup命令无反应，或提示cup.yml not found等错误。

排查步骤：

1. 确认当前目录：Cup 默认会在当前目录寻找cup.yml文件。使用pwd和ls确认文件存在。
2. 检查文件权限：确保cup二进制文件有可执行权限 (chmod +x /usr/local/bin/cup)。
3. 检查 Docker 状态：Cup 是 Docker 的客户端。运行docker version确保 Docker Daemon 正在运行且当前用户有权限访问 Docker Socket（通常需要将用户加入docker组）。
4. 查看详细日志：Cup 本身的错误信息可能有限。可以尝试增加日志级别（如果支持），或者直接查看 Docker Daemon 的日志 (journalctl -u docker.service或sudo tail -f /var/log/docker.log) 来获取更详细的错误信息。

6.5 性能与资源监控

Cup 本身非常轻量，不引入额外性能开销。资源消耗主要来自你运行的容器。你可以使用标准的 Docker 命令来监控：

• docker stats：实时查看所有容器的 CPU、内存、网络 I/O 使用情况。
• docker ps -s：查看容器的大小。
• 结合cup.yml中设置的资源限制 (cpus,memory)，可以有效防止单个服务失控。

经过一段时间的深度使用，Cup 给我的最大感受是“恰到好处的简单”。它没有试图解决所有问题，而是把“在单机上方便地管理容器”这件事做到了极致。它的配置文件清晰易懂，命令直截了当，与 Shell 脚本、Makefile 等工具能无缝结合，完美融入了我的自动化工作流。对于不需要复杂编排的日常场景，它已经成为了我打开终端后最常调用的工具之一。如果你也受困于繁复的docker run命令参数，或者觉得 Docker Compose 的 YAML 文件过于笨重，不妨给sergi0g/cup一个机会，它可能会给你带来意想不到的清爽体验。