kamal

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kamal Deployment

Kamal 部署

Kamal is a zero-downtime deployment tool for containerized applications, originally built by 37signals for deploying Rails apps but works with any containerized web application.

Kamal是一款面向容器化应用的零停机部署工具，最初由37signals为部署Rails应用而开发，但可用于任意容器化Web应用。

Core Concepts

核心概念

Philosophy: Kamal uses an imperative "push" model where you explicitly tell servers what to do, unlike declarative tools like Kubernetes. It combines SSH, Docker, and Kamal Proxy to achieve zero-downtime deployments.

Components:

SSH/SSHKit: Remote command execution
Docker: Container runtime and image management
Kamal Proxy: Reverse proxy for zero-downtime deployments (routes traffic between container versions)
Accessories: Supporting services (PostgreSQL, MySQL, Redis, etc.)

设计理念：Kamal采用命令式的“推送”模型，你需要明确告知服务器执行操作，这与Kubernetes等声明式工具不同。它结合SSH、Docker和Kamal Proxy实现零停机部署。

核心组件：

SSH/SSHKit：远程命令执行
Docker：容器运行时与镜像管理
Kamal Proxy：用于零停机部署的反向代理（在不同版本容器间路由流量）
附属服务（Accessories）：配套服务（PostgreSQL、MySQL、Redis等）

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Set up Kamal for a new project
Configure
```
config/deploy.yml
```
or understand configuration options
Deploy applications or troubleshoot deployment failures
Manage multiple environments (staging, production)
Configure accessories (databases, Redis, etc.)
Debug deployment issues or container problems
Perform rollbacks or maintenance mode
Understand Kamal commands and workflows
Set up CI/CD pipelines with Kamal

当你需要以下操作时使用本技能：

为新项目搭建Kamal环境
配置
```
config/deploy.yml
```
或了解配置选项
部署应用或排查部署失败问题
管理多环境（ staging、生产环境）
配置附属服务（数据库、Redis等）
调试部署问题或容器故障
执行回滚或维护模式
了解Kamal命令与工作流
搭建基于Kamal的CI/CD流水线

Quick Start Workflow

快速开始工作流

Initial Setup

初始设置

bash

undefined

bash

undefined

1. Install Kamal

1. 安装Kamal

gem install kamal

2. Initialize configuration

2. 初始化配置

cd your-app kamal init

3. Edit config/deploy.yml

3. 编辑config/deploy.yml

- Set service name and image

- 设置服务名称与镜像

- Add server IP addresses

- 添加服务器IP地址

- Configure registry credentials

- 配置镜像仓库凭证

- Set environment variables

- 设置环境变量

4. Configure secrets in .kamal/secrets

4. 在.kamal/secrets中配置敏感信息

KAMAL_REGISTRY_PASSWORD=your-token RAILS_MASTER_KEY=your-key

5. Run initial setup (installs Docker, deploys everything)

5. 执行初始设置（安装Docker，部署所有内容）

kamal setup

undefined

kamal setup

undefined

Standard Deploy

标准部署

bash

kamal deploy              # Build, push, deploy with zero downtime
kamal deploy -d staging   # Deploy to staging environment
kamal app logs -f         # Follow application logs

bash

kamal deploy              # 构建、推送并零停机部署
kamal deploy -d staging   # 部署到staging环境
kamal app logs -f         # 实时查看应用日志

Common Operations

常用操作

bash

kamal app exec -i --reuse "bin/rails console"  # Rails console
kamal app logs -g "error"                       # Search logs
kamal rollback <version>                        # Rollback
kamal app maintenance                           # Maintenance mode
kamal app live                                  # Exit maintenance

bash

kamal app exec -i --reuse "bin/rails console"  # 进入Rails控制台
kamal app logs -g "error"                       # 搜索错误日志
kamal rollback <version>                        # 回滚到指定版本
kamal app maintenance                           # 启用维护模式
kamal app live                                  # 退出维护模式

Configuration Patterns

配置模式

Basic deploy.yml Structure

基础deploy.yml结构

yaml

service: myapp
image: username/myapp

servers:
  web:
    - 192.168.1.10

registry:
  server: ghcr.io
  username: myuser
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  secret:
    - RAILS_MASTER_KEY
  clear:
    RAILS_ENV: production

proxy:
  ssl: true
  host: example.com

yaml

service: myapp
image: username/myapp

servers:
  web:
    - 192.168.1.10

registry:
  server: ghcr.io
  username: myuser
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  secret:
    - RAILS_MASTER_KEY
  clear:
    RAILS_ENV: production

proxy:
  ssl: true
  host: example.com

Multi-Server with Roles

带角色的多服务器配置

yaml

servers:
  web:
    hosts:
      - 192.168.1.10
      - 192.168.1.11
  worker:
    hosts:
      - 192.168.1.12
    cmd: bundle exec sidekiq

yaml

servers:
  web:
    hosts:
      - 192.168.1.10
      - 192.168.1.11
  worker:
    hosts:
      - 192.168.1.12
    cmd: bundle exec sidekiq

Accessories (Supporting Services)

附属服务配置

yaml

accessories:
  postgres:
    image: postgres:15
    host: 192.168.1.20
    port: 5432
    env:
      secret:
        - POSTGRES_PASSWORD
      clear:
        POSTGRES_DB: myapp_production
    directories:
      - data:/var/lib/postgresql/data
  
  redis:
    image: redis:7
    host: 192.168.1.21
    directories:
      - data:/data

For comprehensive configuration options, see references/configuration.md.

yaml

accessories:
  postgres:
    image: postgres:15
    host: 192.168.1.20
    port: 5432
    env:
      secret:
        - POSTGRES_PASSWORD
      clear:
        POSTGRES_DB: myapp_production
    directories:
      - data:/var/lib/postgresql/data
  
  redis:
    image: redis:7
    host: 192.168.1.21
    directories:
      - data:/data

如需完整配置选项，请查看 references/configuration.md。

Essential Commands

核心命令

Deployment

部署相关

```
kamal init
```
- Initialize configuration files
```
kamal setup
```
- First-time setup (installs Docker, deploys everything)
```
kamal deploy
```
- Standard deploy with zero downtime
```
kamal redeploy
```
- Fast redeploy (skips proxy setup)
```
kamal rollback VERSION
```
- Rollback to previous version

```
kamal init
```
- 初始化配置文件
```
kamal setup
```
- 首次环境搭建（安装Docker，部署所有内容）
```
kamal deploy
```
- 标准零停机部署
```
kamal redeploy
```
- 快速重新部署（跳过代理设置）
```
kamal rollback VERSION
```
- 回滚到指定版本

Application Management

应用管理

```
kamal app logs [-f]
```
- View logs (follow with -f)
```
kamal app exec "COMMAND"
```
- Run command in container
```
kamal app exec -i --reuse "bash"
```
- Interactive shell
```
kamal app maintenance
```
- Enable maintenance mode
```
kamal app live
```
- Disable maintenance mode
```
kamal app containers
```
- List all containers (for rollback)
```
kamal app version
```
- Show deployed version

```
kamal app logs [-f]
```
- 查看日志（-f参数实时追踪）
```
kamal app exec "COMMAND"
```
- 在容器内执行命令
```
kamal app exec -i --reuse "bash"
```
- 进入交互式shell
```
kamal app maintenance
```
- 启用维护模式
```
kamal app live
```
- 关闭维护模式
```
kamal app containers
```
- 列出所有容器（用于回滚）
```
kamal app version
```
- 查看已部署版本

Accessories

附属服务管理

```
kamal accessory boot NAME
```
- Start accessory
```
kamal accessory logs NAME [-f]
```
- View accessory logs
```
kamal accessory exec NAME "CMD"
```
- Run command in accessory

```
kamal accessory boot NAME
```
- 启动附属服务
```
kamal accessory logs NAME [-f]
```
- 查看附属服务日志
```
kamal accessory exec NAME "CMD"
```
- 在附属服务容器内执行命令

Troubleshooting

故障排查

```
kamal config
```
- Show parsed configuration
```
kamal lock status
```
- Check deployment lock
```
kamal lock release
```
- Release stuck lock
```
kamal server exec "CMD"
```
- Run command on host

```
kamal config
```
- 查看解析后的配置
```
kamal lock status
```
- 检查部署锁状态
```
kamal lock release
```
- 释放卡住的部署锁
```
kamal server exec "CMD"
```
- 在宿主机执行命令

Multiple Environments

多环境操作

```
kamal deploy -d staging
```
- Deploy to staging
```
kamal deploy -h 192.168.1.10
```
- Deploy to specific host
```
kamal deploy -r web
```
- Deploy to specific role

For complete command reference, see references/commands.md.

```
kamal deploy -d staging
```
- 部署到staging环境
```
kamal deploy -h 192.168.1.10
```
- 部署到指定主机
```
kamal deploy -r web
```
- 部署到指定角色的服务器

如需完整命令参考，请查看 references/commands.md。

Common Workflows

常用工作流

Deploy with Database Migration

带数据库迁移的部署

Using pre-deploy hook (recommended):

Create

.kamal/hooks/pre-deploy

bash

#!/bin/bash
kamal app exec -p -q "bin/rails db:migrate"

bash

chmod +x .kamal/hooks/pre-deploy
kamal deploy

使用预部署钩子（推荐）：

创建

.kamal/hooks/pre-deploy

：

bash

#!/bin/bash
kamal app exec -p -q "bin/rails db:migrate"

bash

chmod +x .kamal/hooks/pre-deploy
kamal deploy

Rollback Workflow

回滚工作流

bash

undefined

bash

undefined

Check what went wrong

排查问题原因

kamal app logs

List available versions

查看可用版本

kamal app containers

Rollback to previous version

回滚到指定版本

kamal rollback abc123def

undefined

kamal rollback abc123def

undefined

Debugging Failed Deployments

部署失败排查

Check logs:
```
kamal app logs -n 500
```
Check container status:
```
kamal server exec "docker ps -a"
```
Test health endpoint:
```
kamal app exec "curl localhost:3000/up"
```
Check configuration:
```
kamal config
```
Release stuck locks:
```
kamal lock release
```

查看日志：
```
kamal app logs -n 500
```
检查容器状态：
```
kamal server exec "docker ps -a"
```
测试健康检查端点：
```
kamal app exec "curl localhost:3000/up"
```
检查配置：
```
kamal config
```
释放卡住的部署锁：
```
kamal lock release
```

Multiple Environments Pattern

多环境配置模式

Create environment-specific configs:

```
config/deploy.yml
```
(production)
```
config/deploy.staging.yml
```

bash

kamal setup -d staging
kamal deploy -d staging
kamal deploy  # production

For detailed workflows, troubleshooting guides, and best practices, see references/workflows.md.

创建环境专属配置文件：

```
config/deploy.yml
```
（生产环境）
```
config/deploy.staging.yml
```
（staging环境）

bash

kamal setup -d staging
kamal deploy -d staging
kamal deploy  # 部署到生产环境

如需详细工作流、排查指南及最佳实践，请查看 references/workflows.md。

Database and Accessory Management

数据库与附属服务管理

Running Commands in Accessories

在附属服务中执行命令

bash

undefined

bash

undefined

PostgreSQL

kamal accessory exec postgres "psql -U myapp" kamal accessory exec postgres "pg_dump -U myapp myapp_production" > backup.sql

Redis

kamal accessory exec redis "redis-cli"

MySQL

kamal accessory exec mysql "mysql -u root -p myapp_production"

undefined

kamal accessory exec mysql "mysql -u root -p myapp_production"

undefined

Litestream (SQLite Replication)

Litestream（SQLite 复制）

bash

kamal accessory exec litestream "litestream generations /data/production.sqlite3"
kamal accessory exec litestream "litestream restore /data/production.sqlite3"

bash

kamal accessory exec litestream "litestream generations /data/production.sqlite3"
kamal accessory exec litestream "litestream restore /data/production.sqlite3"

Configuration for Common Scenarios

常见场景配置

Custom SSH User/Port

自定义SSH用户/端口

yaml

ssh:
  user: deploy
  port: 2222

yaml

ssh:
  user: deploy
  port: 2222

Custom Build Context

自定义构建上下文

yaml

builder:
  context: .
  dockerfile: Dockerfile.production
  args:
    RUBY_VERSION: 3.2.0

yaml

builder:
  context: .
  dockerfile: Dockerfile.production
  args:
    RUBY_VERSION: 3.2.0

Health Check Configuration

健康检查配置

yaml

healthcheck:
  path: /up
  port: 3000
  interval: 10
  max_attempts: 7

yaml

healthcheck:
  path: /up
  port: 3000
  interval: 10
  max_attempts: 7

Aliases for Common Commands

常用命令别名

yaml

aliases:
  console: app exec --interactive --reuse "bin/rails console"
  shell: app exec --interactive --reuse "bash"
  logs: app logs -f

Use:

kamal console

instead of full command.

yaml

aliases:
  console: app exec --interactive --reuse "bin/rails console"
  shell: app exec --interactive --reuse "bash"
  logs: app logs -f

使用方式：

kamal console

替代完整命令。

CI/CD Integration

CI/CD 集成

GitHub Actions Example

GitHub Actions 示例

yaml

- name: Deploy
  env:
    KAMAL_REGISTRY_PASSWORD: ${{ secrets.REGISTRY_TOKEN }}
    RAILS_MASTER_KEY: ${{ secrets.RAILS_MASTER_KEY }}
  run: |
    gem install kamal
    kamal deploy

yaml

- name: Deploy
  env:
    KAMAL_REGISTRY_PASSWORD: ${{ secrets.REGISTRY_TOKEN }}
    RAILS_MASTER_KEY: ${{ secrets.RAILS_MASTER_KEY }}
  run: |
    gem install kamal
    kamal deploy

Key Limitations

主要限制

No automatic state reconciliation - Kamal won't automatically decommission containers if you remove them from config
No dynamic provisioning - Cannot auto-scale or provision servers on demand
Single-server load balancing only - Kamal Proxy balances containers on each server, not across servers (use external load balancer for that)

无自动状态同步 - 如果你从配置中移除容器，Kamal不会自动销毁这些容器
无动态扩容 - 无法自动扩容或按需配置服务器
仅单服务器负载均衡 - Kamal Proxy仅在单台服务器的容器间做负载均衡，跨服务器负载均衡需使用外部负载均衡器

References

参考文档

This skill includes comprehensive reference documentation:

configuration.md - Complete
```
config/deploy.yml
```
reference with all options, registry configurations, accessory setups, and example configurations
commands.md - Detailed command reference for all Kamal CLI commands with options and examples
workflows.md - Common deployment workflows, troubleshooting patterns, CI/CD integration, security best practices, and production guidelines

Read these references when you need detailed information about specific configuration options, commands, or deployment patterns.

本技能包含完整的参考文档：

configuration.md - 完整的
```
config/deploy.yml
```
参考，包含所有配置选项、镜像仓库配置、附属服务设置及示例配置
commands.md - 所有Kamal CLI命令的详细参考，包含选项与示例
workflows.md - 常见部署工作流、排查模式、CI/CD集成、安全最佳实践及生产环境指南

当你需要了解特定配置选项、命令或部署模式的详细信息时，请阅读这些参考文档。