文档 / 核心概念 / 堆栈

堆栈

堆栈是 sh0 中的顶级组织单元。它将相关的应用和服务组合在一起，提供共享配置和项目的统一视图。

什么是堆栈？

堆栈代表一个由一个或多个应用和服务组成的项目或产品。例如，一个典型的 Web 应用堆栈可能包括：

  • 前端应用（React、Vue、Svelte）
  • 后端 API（Node.js、Python、Go）
  • PostgreSQL 数据库
  • Redis 缓存
  • 后台工作进程

所有这些都位于一个堆栈中，共享环境变量，并可通过私有 Docker 网络进行通信。在控制台中打开堆栈时，你可以一目了然地看到所有组件。

Stack list view showing three stacks: 'production-api' with 4 services running, 'staging-frontend' with 2 services running, and 'blog' with 1 service running -- each showing status badges and resource usage
The stack list gives you an overview of all your projects

堆栈 vs 应用 vs 服务

理解层级关系非常重要：

概念描述示例
堆栈项目或产品分组"E-commerce Platform"
应用堆栈中的可部署单元"api", "frontend", "worker"
服务应用的运行中容器实例"api-v3-abc123" (container)

一个堆栈包含一个或多个应用。每个应用以一个或多个服务（容器）的形式运行。当你部署应用时，sh0 会创建一个新服务（容器），并在健康检查通过后可选地移除旧服务。

Note
同一堆栈中的所有应用共享一个 Docker 网络，这意味着它们可以使用应用名称作为主机名互相通信。例如，前端可以通过 http://api:3000 访问 API，无需额外配置。

创建堆栈

有两种方式创建堆栈：

通过控制台：

  1. 点击右上角的 新建堆栈 按钮或从堆栈页面操作。
  2. 输入名称（仅限小写字母、数字和连字符）。
  3. 添加可选描述。
  4. 点击 创建堆栈。
Create Stack dialog with fields for name, description, and a Create Stack button
Creating a new stack from the dashboard

通过 API：

Terminal
curl -X POST http://localhost:9000/api/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-stack", "description": "Production web app"}'

堆栈详情视图

点击堆栈可打开详情视图，提供项目的完整概览：

Stack detail view showing tabs for Apps, Environment, Domains, Backups, and Settings. The Apps tab is active, showing a grid of three apps: frontend (running), api (running), and database (running) with resource usage bars
The stack detail view with all apps visible
  • 应用选项卡 -- 此堆栈中的所有应用及其状态、资源使用情况和快捷操作（部署、重启、停止）。
  • 环境变量选项卡 -- 跨所有应用共享的堆栈级环境变量。
  • 域名选项卡 -- 此堆栈中分配给应用的所有域名。
  • 备份选项卡 -- 此堆栈中数据库的备份计划和历史记录。
  • 设置选项卡 -- 堆栈名称、描述、危险区域（删除堆栈）。

堆栈环境变量

堆栈级环境变量由堆栈中的所有应用继承。这对于共享配置（如 API 密钥、数据库 URL 或适用于整个项目的功能开关）非常有用。

Example Stack Variables
DATABASE_URL=postgres://user:pass@db:5432/myapp
REDIS_URL=redis://cache:6379
APP_ENV=production
STRIPE_API_KEY=sk_live_...
Stack Environment tab showing a list of environment variables with name, value (masked), and action buttons. An 'Add Variable' button and 'Import .env' button are at the top
Managing stack-level environment variables
变量优先级
应用级环境变量会覆盖堆栈级变量。如果堆栈定义了 APP_ENV=production，而应用定义了 APP_ENV=staging，则应用使用 staging。这样你可以共享默认值，同时允许每个应用单独覆盖。

堆栈设置

设置选项卡允许你修改堆栈的元数据并执行管理操作：

  • 名称和描述 -- 更新堆栈的显示名称和描述。
  • Docker 网络 -- 查看此堆栈的内部 Docker 网络名称。
  • 危险区域 -- 删除堆栈及其所有应用、服务和数据。此操作不可逆。
删除堆栈
删除堆栈会移除所有应用、容器、卷及相关数据。在删除前请务必备份重要数据。此操作不可撤销。

常见模式

以下是一些常见的堆栈组织方式：

按项目

每个项目一个堆栈，包含其所有服务。

saas-app (frontend + api + db + redis)

按环境

为预发布和生产环境使用独立堆栈。

myapp-staging / myapp-production

按客户

代理机构可以按客户组织。

client-acme / client-globex

共享服务

公共基础设施使用独立堆栈。

infrastructure (traefik + monitoring + logging)

通过 API 管理堆栈

所有堆栈操作均可通过 REST API 进行。以下是关键端点：

Terminal
# List all stacks
curl http://localhost:9000/api/projects \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get a specific stack
curl http://localhost:9000/api/projects/STACK_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

# Update a stack
curl -X PUT http://localhost:9000/api/projects/STACK_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "new-name", "description": "Updated description"}'

# Delete a stack
curl -X DELETE http://localhost:9000/api/projects/STACK_ID \
  -H "Authorization: Bearer YOUR_TOKEN"
Note
完整的 API 端点列表请参阅 API 参考。
Previous
Your First Deploy
Next
Apps & Services