kamal-deployment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kamal 2 Deployment

Kamal 2 部署

Kamal is a deployment tool by 37signals that deploys containerized applications to any Linux server using Docker, SSH, and Kamal Proxy. It offers zero-downtime deploys, rolling restarts, automatic SSL/TLS certificates, and auxiliary services management.

Kamal是37signals推出的一款部署工具，它使用Docker、SSH和Kamal Proxy将容器化应用部署到任意Linux服务器。它支持零停机部署、滚动重启、自动SSL/TLS证书以及附属服务管理。

Quick Start

快速开始

bash

undefined

bash

undefined

Install

安装

gem install kamal

Initialize in your project

在项目中初始化

kamal init

Creates: config/deploy.yml, .kamal/secrets, .kamal/hooks/

生成文件: config/deploy.yml, .kamal/secrets, .kamal/hooks/

First deploy (bootstraps servers + deploys)

首次部署（初始化服务器 + 部署）

kamal setup

Subsequent deploys

后续部署

kamal deploy

undefined

kamal deploy

undefined

Key Concepts

核心概念

Service: Your application name, used to uniquely configure containers
Server: A virtual or physical host running your application image
Role: A server group running the same command (e.g.,
```
web
```
,
```
job
```
)
Accessory: A long-running auxiliary service (database, Redis) with independent lifecycle
Kamal Proxy: Reverse proxy for zero-downtime deploys and SSL termination on each server
Kamal 2 provides its own private network called
```
kamal
```
- do NOT add a custom private network in your config

Service（服务）：你的应用名称，用于唯一配置容器
Server（服务器）：运行应用镜像的虚拟或物理主机
Role（角色）：运行相同命令的服务器组（例如
```
web
```
、
```
job
```
）
Accessory（附属服务）：具有独立生命周期的长期运行辅助服务（数据库、Redis）
Kamal Proxy：反向代理，用于实现零停机部署和每台服务器上的SSL终止
Kamal 2 提供专属私有网络
```
kamal
```
- 请勿在配置中添加自定义私有网络

Configuration Reference

配置参考

For complete deploy.yml configuration, see configuration.md.

完整的deploy.yml配置，请查看 configuration.md。

Workflows

工作流程

Initial Setup

初始设置

Run
```
kamal init
```
to generate config files
Configure
```
config/deploy.yml
```
(see configuration.md)
Set up
```
.kamal/secrets
```
with registry credentials and app secrets
Ensure your app has a Dockerfile exposing port 80 with a
```
/up
```
health check

Set

config.assume_ssl = true

and

config.force_ssl = true

production.rb

Exclude

/up

from host authorization in Rails 7+:

ruby

config.host_authorization = { exclude: ->(request) { request.path == "/up" } }

Run
```
kamal setup
```
for the first deployment

运行
```
kamal init
```
生成配置文件
配置
```
config/deploy.yml
```
（查看 configuration.md）
在
```
.kamal/secrets
```
中配置镜像仓库凭证和应用密钥
确保你的应用有一个暴露80端口且包含
```
/up
```
健康检查的Dockerfile

在

production.rb

中设置

config.assume_ssl = true

和

config.force_ssl = true

在Rails 7+中排除

/up

路径的主机授权：

ruby

config.host_authorization = { exclude: ->(request) { request.path == "/up" } }

运行
```
kamal setup
```
完成首次部署

Deploying Updates

部署更新

bash

kamal deploy                    # Full deploy (build + push + deploy)
kamal deploy --skip-push        # Deploy existing image from registry
kamal deploy --version=VERSION  # Deploy specific version

bash

kamal deploy                    # 完整部署（构建 + 推送 + 部署）
kamal deploy --skip-push        # 从镜像仓库部署现有镜像
kamal deploy --version=VERSION  # 部署指定版本

Managing Accessories

管理附属服务

bash

kamal accessory boot all        # Boot all accessories
kamal accessory boot postgres   # Boot specific accessory
kamal accessory reboot redis    # Reboot an accessory
kamal accessory remove postgres # Remove an accessory
kamal accessory details postgres
kamal accessory logs postgres

bash

kamal accessory boot all        # 启动所有附属服务
kamal accessory boot postgres   # 启动指定附属服务postgres
kamal accessory reboot redis    # 重启附属服务redis
kamal accessory remove postgres # 移除附属服务postgres
kamal accessory details postgres
kamal accessory logs postgres

Maintenance & Debugging

维护与调试

bash

undefined

bash

undefined

Logs

日志

kamal app logs # Application logs kamal app logs -f # Follow logs kamal app logs -r web # Logs for specific role kamal proxy logs # Proxy logs

kamal app logs # 应用日志 kamal app logs -f # 实时追踪日志 kamal app logs -r web # 指定角色的日志 kamal proxy logs # 代理日志

Console access

控制台访问

kamal app exec -i 'bin/rails console' kamal app exec -i --reuse bash # Shell into running container kamal app exec --primary "bin/rails about"

kamal app exec -i 'bin/rails console' kamal app exec -i --reuse bash # 进入运行中的容器shell kamal app exec --primary "bin/rails about"

Rollback

回滚

kamal app containers # List available versions kamal rollback [VERSION] # Rollback to version

kamal app containers # 列出可用版本 kamal rollback [VERSION] # 回滚到指定版本

Redeploy (skip bootstrap, proxy setup, pruning, registry login)

重新部署（跳过初始化、代理设置、清理、镜像仓库登录）

kamal redeploy

Locks

部署锁

kamal lock status # Check deploy lock kamal lock acquire -m "reason" # Prevent deploys kamal lock release # Allow deploys again

kamal lock status # 检查部署锁状态 kamal lock acquire -m "reason" # 禁止部署 kamal lock release # 重新允许部署

Server management

服务器管理

kamal server bootstrap # Bootstrap servers with Docker kamal details # Show details about all containers kamal audit # Show audit log from servers kamal prune # Prune old images and containers kamal config # Show combined config (includes secrets!) kamal docs [SECTION] # Show Kamal configuration docs

kamal server bootstrap # 使用Docker初始化服务器 kamal details # 查看所有容器详情 kamal audit # 查看服务器审计日志 kamal prune # 清理旧镜像和容器 kamal config # 查看合并后的配置（包含密钥！） kamal docs [SECTION] # 查看Kamal配置文档

Cleanup

清理

kamal remove # Remove everything from servers

undefined

kamal remove # 移除服务器上的所有相关内容

undefined

Global Flags

全局参数

Flag	Description
`-v, --verbose`	Detailed logging
`-q, --quiet`	Minimal logging
`--version=VERSION`	Run against specific app version
`-p, --primary`	Primary host only
`-h, --hosts=HOSTS`	Comma-separated hosts (supports wildcards)
`-r, --roles=ROLES`	Comma-separated roles (supports wildcards)
`-d, --destination`	Deployment destination
`-H, --skip-hooks`	Skip hook execution

参数	描述
`-v, --verbose`	详细日志
`-q, --quiet`	极简日志
`--version=VERSION`	针对指定应用版本执行命令
`-p, --primary`	仅针对主服务器
`-h, --hosts=HOSTS`	逗号分隔的主机列表（支持通配符）
`-r, --roles=ROLES`	逗号分隔的角色列表（支持通配符）
`-d, --destination`	部署目标
`-H, --skip-hooks`	跳过钩子脚本执行

Database Operations

数据库操作

bash

undefined

bash

undefined

Run migrations via entrypoint (recommended)

通过入口脚本运行迁移（推荐）

bin/docker-entrypoint handles db:prepare automatically

bin/docker-entrypoint 会自动处理db:prepare

Or via pre-deploy hook

或通过部署前钩子执行

kamal app exec -p -q -d $KAMAL_DESTINATION --version $KAMAL_VERSION "rails db:migrate"

Database backup (with S3 backup accessory)

数据库备份（使用S3备份附属服务）

kamal accessory exec s3_backup "sh backup.sh" kamal accessory exec s3_backup "sh restore.sh"

undefined

kamal accessory exec s3_backup "sh backup.sh" kamal accessory exec s3_backup "sh restore.sh"

undefined

Architecture Patterns

架构模式

For complete examples of single-server and multi-server setups, see examples.md.

单服务器和多服务器部署的完整示例，请查看 examples.md。

Single Server (Rails + PostgreSQL + Redis + Sidekiq)

单服务器架构（Rails + PostgreSQL + Redis + Sidekiq）

All services on one VPS with Let's Encrypt SSL. Best for small-to-medium apps.

所有服务部署在一台VPS上，使用Let's Encrypt SSL证书。最适合中小型应用。

Multi-Server (Scaled)

多服务器架构（扩容版）

Separate servers for web, job, database, and cache behind a load balancer on a private network. Best for high-traffic apps.

在私有网络的负载均衡器后，将Web、任务、数据库和缓存服务部署在独立服务器上。最适合高流量应用。

Hooks

钩子脚本

Custom scripts in

.kamal/hooks/

that run at deployment points. If a hook returns non-zero, the command aborts.

Available:

docker-setup

pre-connect

pre-build

pre-deploy

post-deploy

pre-app-boot

post-app-boot

pre-proxy-reboot

post-proxy-reboot

For details, see configuration.md.

.kamal/hooks/

中的自定义脚本，会在部署的特定阶段运行。如果钩子脚本返回非零值，命令将终止。

可用钩子：

docker-setup

pre-connect

pre-build

pre-deploy

post-deploy

pre-app-boot

post-app-boot

pre-proxy-reboot

post-proxy-reboot

。

详细信息，请查看 configuration.md。

Upgrading from Kamal 1

从Kamal 1升级

bash

kamal upgrade              # In-place upgrade from Kamal 1 to 2
kamal upgrade --rolling    # Zero-downtime upgrade
kamal downgrade            # Reverse if needed

bash

kamal upgrade              # 原地从Kamal 1升级到2
kamal upgrade --rolling    # 零停机升级
kamal downgrade            # 如有需要可回滚

Common Gotchas

常见陷阱

Kamal 2 creates its own
kamal
network - remove any custom private network from your config
Always set
config.assume_ssl = true
in
```
production.rb
```
when using SSL
Do NOT use your domain name as the VM hostname - it overrides
```
/etc/resolv.conf
```
Docker port exposure bypasses UFW - closing ports in UFW is not enough, Docker rules are higher in iptables
Short
deploy_timeout
causes failures on underpowered servers - increase it if deploys fail
Asset bridging must be explicitly configured with
```
asset_path
```
- it's not automatic
Accessories must be removed before moving to a new destination
Kamal 2 doesn't support ERB in
```
config/deploy.yml
```
(unlike Kamal 1)
Set
config.reload_routes = false
in Devise initializer to fix ActionController::RoutingError
Enable
forward_headers: true
in proxy config when behind Cloudflare to preserve real client IPs

Kamal 2会创建专属的
kamal
网络 - 请从配置中移除任何自定义私有网络
使用SSL时务必设置
config.assume_ssl = true
在
```
production.rb
```
中
请勿将域名用作VM主机名 - 这会覆盖
```
/etc/resolv.conf
```
Docker端口暴露会绕过UFW - 仅在UFW中关闭端口不够，Docker规则在iptables中的优先级更高
过短的
deploy_timeout
会导致部署失败 - 如果部署失败，请在低配服务器上增加该值
资源桥接必须通过
asset_path
显式配置 - 它不是自动生效的
附属服务必须先移除，再迁移到新的部署目标
Kamal 2不支持在
config/deploy.yml
中使用ERB（与Kamal 1不同）
在Devise初始化器中设置
config.reload_routes = false
以修复ActionController::RoutingError错误
当部署在Cloudflare后时，请在代理配置中启用
forward_headers: true
以保留真实客户端IP

CI/CD

For GitHub Actions deployment workflows, see cicd.md.

GitHub Actions部署工作流示例，请查看 cicd.md。

Backups

备份

For database backup strategies with S3, see backups.md.

基于S3的数据库备份策略，请查看 backups.md。

Server Hardening

服务器加固

For production server security setup, see server-hardening.md.

生产服务器安全设置，请查看 server-hardening.md。

Logging & Monitoring

日志与监控

For Vector log aggregation and structured logging, see logging.md.

Vector日志聚合和结构化日志相关内容，请查看 logging.md。