教程：使用 Kamal 部署 Rails 应用程序

Kamal 是用于部署容器化 Rails 应用程序的工具。 Kamal 不像 Capistrano 那样通过 SSH 执行任务，而是构建应用程序的 Docker 镜像，将其推送到注册表，并在服务器上以轻量容器的形式运行。

在 RubyMine 中，您可以直接从内置终端运行 Kamal 命令或使用运行任何内容。这样，您无需离开 IDE 即可触发部署、管理环境并监视日志。

在本教程中，您将了解如何使用 Kamal 将示例 Rails 应用程序部署到远程服务器。作为应用程序服务器，Puma 将在 Docker 容器中运行，由 Kamal Proxy 处理 HTTP 和 HTTPS 流量。

先决条件

若要在 RubyMine 中完全使用 Kamal 部署 Rails 应用程序，请确保本地环境和远程服务器满足以下要求。

本地计算机

搭载 macOS 的 Mac
RubyMine 已为您的 Rails 项目安装并配置好
Rails 8 应用程序。对于较旧的 Rails 版本，请将 Kamal 添加到您的 Gemfile 或使用 gem install kamal 在本地安装
项目根目录下有效的 Dockerfile
本地已安装 Docker
可以访问容器注册表（Docker Hub、GitHub Container Registry 或私有注册表），并且凭据已安全存储
本地已配置 SSH

Web 服务器

基于 Linux 的主机
为与 Kamal deploy.yml （或您的 OpenSSH 配置）中定义的相同用户提供 SSH 访问权限
已安装并运行 Docker（如果是新主机，Kamal 可以在 kamal setup 期间安装 Docker）

部署

本部分教程介绍了使用 Kamal 部署应用所需的步骤。

初始化 Kamal

在 RubyMine 中，打开终端：视图｜工具窗口｜终端。或者，点击 IDE 左下角工具栏中的终端图标。
请运行以下命令：
kamal init
这将创建一个 config/deploy.yml 文件。此文件包含多个部署配置项和选项，但在本教程中，我们只关注部署所需的设置。

配置部署

编辑由 kamal init 生成的 config/deploy.yml 文件。

以下是该文件内容的一个示例：

         # Name of your application. Used to uniquely configure containers.
   service: app_name # Name of the application being deployed.

   # Registry path for your Docker image.
   image: user/app_name # Docker image path in the container registry.

   servers:
     web:
       - # List of IPs or hostnames of the servers where the application will be deployed.

   ssh:
     user: user_name # SSH user for connecting to the deployment server(s).

   proxy:
     ssl: true # To disable SSL (useful for local testing), set to false.
     host: app.example.com # The hostname or domain where the app will be accessible.

   registry:
     username: # Registry username for pushing/pulling Docker images (e.g., Docker Hub credentials).
     password: # Registry token or password for authentication.

   env:
     clear:
       RAILS_ENV: # Specifies the environment for the Rails application (e.g., production, development).
       PORT: # The port the application should run on.
       SECRET_KEY_BASE: # Rails secret key base for encryption.

   builder:
     # The architecture used to build the Docker image (amd64 for compatibility with most servers).
       
  

管理密钥

在生产环境中，Rails 需要有效的 SECRET_KEY_BASE 才能进行加密和安全操作。请按以下步骤正确配置：

运行以下任一命令以生成强 SECRET_KEY_BASE：
bin/rails secret # or ruby -rsecurerandom -e 'puts SecureRandom.hex(64)' # or, if using your built Docker image: docker run --rm <your-image> ./bin/rails secret
通过将生成的密钥添加到环境配置中来更新您的 config/deploy.yml 文件：
env: clear: RAILS_ENV: production PORT: "3000" SECRET_KEY_BASE: <%= ENV.fetch("SECRET_KEY_BASE") %>
在运行 kamal deploy 命令之前，将密钥导出到您的环境中：
export SECRET_KEY_BASE="<your-generated-value>"

部署完成后，您的应用程序将使用提供的 SECRET_KEY_BASE 值来保护敏感操作。

运行首次服务器设置

运行 kamal setup 命令以准备服务器进行部署。

部署您的应用程序

现在您已经配置好部署并确保 Web 服务器已就绪，可以开始部署应用程序。

从 RubyMine 终端运行以下命令。
kamal deploy
Kamal 将执行以下操作：
- 在本地构建 Docker 镜像
- 将其推送到您的注册表
- 建立与服务器的 SSH 连接
- 拉取新镜像
- 在配置的环境中启动应用程序
部署完成后，打开浏览器并访问为应用程序配置的 URL。

故障排查

SSH 持续要求输入密码短语或密码

将 SSH 密钥加载到代理中以避免密码短语提示：
ssh-add ~/.ssh/id_ed25519
将 SSH 密钥添加到 macOS 钥匙串以实现持久访问：
ssh-add --apple-use-keychain -K ~/.ssh/id_ed25519
通过配置 ~/.ssh/config 来确保 SSH 使用正确的密钥：
Host your-server-ip User your-username IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yes
测试 SSH 连接以验证是否一切正常：
ssh your-username@your-server-ip

您的页面返回 404

检查请求是否到达 Rails：
# in one shell kamal app logs -f # in another shell curl -I http://app.example.com/
如果日志为空，请修复 DNS 或代理。如果 Rails 日志显示 404，请在您的应用中添加根路由。
检查代理是否正常路由及运行状况良好：
kamal proxy ps kamal proxy logs -f curl -I -H "Host: app.example.com" http://127.0.0.1
在 deploy.yml 中使用返回 200 的健康检查路径（例如， /向上）。
确认应用监听正确端口（默认 3000）并绑定 0.0.0.0：
curl -I http://127.0.0.1:3000/

回滚

如果当前部署有问题，将应用程序回滚到先前版本。这有助于快速恢复到稳定状态。

首先，列出可用的容器，以识别先前的版本：
kamal app containers -q
然后，通过指定所需版本或最新稳定版本，将回滚到之前的镜像：
kamal rollback
回滚后，监控日志和应用健康状态，以确保先前版本运行正常。

另请参阅

2026年 3月 24日