kamal-deployment

Kamal 2 部署

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

快速开始

# Install
gem install kamal

# Initialize in your project
kamal init
# Creates: config/deploy.yml, .kamal/secrets, .kamal/hooks/

# First deploy (bootstraps servers + deploys)
kamal setup

# Subsequent deploys
kamal deploy

核心概念

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

配置参考

完整的 deploy.yml 配置请参阅 configuration.md。

工作流

初始设置

1. 运行 kamal init 以生成配置文件
2. 配置 config/deploy.yml（请参阅 configuration.md）
3. 在 .kamal/secrets 中设置注册表凭据和应用密钥
4. 确保应用有一个暴露端口 80 并带有 /up 健康检查的 Dockerfile
5. 在 production.rb 中设置 config.assume_ssl = true 和 config.force_ssl = true
6. 在 Rails 7 及更高版本中，将 /up 从主机授权中排除：

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

7. 运行 kamal setup 进行首次部署

部署更新

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

管理辅助服务

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

维护与调试

# 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

# 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"

# Rollback
kamal app containers            # List available versions
kamal rollback [VERSION]         # Rollback to 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

# 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

# Cleanup
kamal remove                    # Remove everything from servers

全局标志

标志	说明
-v, --verbose	详细日志
-q, --quiet	最简日志
--version=VERSION	针对指定应用版本运行
-p, --primary	仅主机
-h, --hosts=HOSTS	以逗号分隔的主机（支持通配符）
-r, --roles=ROLES	以逗号分隔的角色（支持通配符）
-d, --destination	部署目标
-H, --skip-hooks	跳过钩子执行

数据库操作

# Run migrations via entrypoint (recommended)
# bin/docker-entrypoint handles db:prepare automatically

# 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)
kamal accessory exec s3_backup "sh backup.sh"
kamal accessory exec s3_backup "sh restore.sh"

架构模式

单服务器和多服务器设置的完整示例请参阅 examples.md。

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

所有服务运行在一台 VPS 上，并使用 Let's Encrypt SSL。适合中小型应用。

多服务器（扩展）

Web、任务、数据库和缓存分别部署在不同服务器上，并通过私有网络接入负载均衡器。适合高流量应用。

钩子

.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。

从 Kamal 1 升级

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

常见注意事项

• Kamal 2 会创建自己的 kamal 网络——请从配置中移除任何自定义私有网络
• 使用 SSL 时，务必在 production.rb 中设置 config.assume_ssl = true
• 请勿将域名用作 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

GitHub Actions 部署工作流请参阅 cicd.md。

备份

使用 S3 的数据库备份策略请参阅 backups.md。

服务加固

有关生产环境的服务安全设置，请参阅 server-hardening.md。

日志记录与监控

有关 Vector 日志聚合和结构化日志记录，请参阅 logging.md。