Ubuntu 22.04 安装 Capistrano 3.20 指南

目标：在 Ubuntu 22.04 控制机上从零安装 Capistrano 3.20.1（Ruby gem 形态），覆盖在线 gem 安装与离线 gem 包安装两种方案，含 Ruby 依赖、编译链排障、版本管理与卸载。已在 Ubuntu 22.04.5 LTS（x86_64）控制机 + 2 台 Ubuntu 22.04 目标服务器环境实测通过（2026-10-27）。

一、环境信息

控制机（安装 Capistrano 的一端）：Ubuntu 22.04.5 LTS，x86_64
目标服务器（被部署的一端，2 台）：Ubuntu 22.04.5 LTS，仅需 SSH 服务 + git，不装 Capistrano
Ruby：3.0.2p107（Ubuntu 22.04 apt 仓库自带 ruby-full 1:3.0~exp1）
RubyGems：3.3.5（随 ruby-full 安装）
Capistrano：3.20.1（2026-05-16 发布的最新稳定版，查询日期 2026-10-27，RubyGems 页面标注要求 Ruby >= 2.5）
安装方式：RubyGems（gem install），安装后 CLI 为 /usr/local/bin/cap

💡 说明：Capistrano 是「控制器侧」纯 CLI 工具——只在执行部署的控制机（运维工作站或发布机）上安装一次，通过 SSH 遥控多台目标服务器；目标服务器端没有任何 agent 或常驻进程，只需能 SSH 登录并装有 git。

二、前置条件

一台可 sudo 的 Ubuntu 22.04 控制机，磁盘空闲 ≥ 500MB。
在线方案需要控制机能访问 RubyGems 官方源 https://rubygems.org；离线方案只需提前在任意可联网机器下载 .gem 包。
目标服务器侧：已运行 SSH 服务、有部署账号（本文用演示账号 admin / q1w2e3r4）、装有 git。目标服务器的完整准备过程见《Capistrano 3.20 配置参数详解》篇。

先刷新 apt 索引：

apt-get update

实测回显（节选末尾）：

Get:16 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 Packages [4759 kB]
Get:17 http://archive.ubuntu.com/ubuntu jammy-backports/main amd64 Packages [82.9 kB]
Get:18 http://archive.ubuntu.com/ubuntu jammy-backports/universe amd64 Packages [35.6 kB]
Fetched 49.0 MB in 5s (9680 kB/s)
Reading package lists...

三、版本选型说明

项目	取值	说明
Capistrano 最新稳定版	3.20.1（2026-05-16）	RubyGems 官方页实查，查询日期 2026-10-27；SHA256 `b0d54ba5…529e9ae9`
3.x 系列要求	Ruby >= 2.5	Ubuntu 22.04 自带 Ruby 3.0.2 满足
历史大版本	2.x（已归档）、3.x（当前）	2.x 配置语法与 3.x 不兼容，新项目一律 3.x
许可证	MIT	可自由商用

查看 apt 仓库提供的 Ruby 版本：

apt-cache policy ruby-full

实测回显：

ruby-full:
  Installed: (none)
  Candidate: 1:3.0~exp1
  Version table:
     1:3.0~exp1 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages

结论：Ubuntu 22.04 仓库的 Ruby 3.0 满足 Capistrano 3.20 的 >= 2.5 要求，无需编译新版 Ruby，直接用 apt 包即可。

四、在线安装方案（A：RubyGems 官方源，推荐）

最常规的安装路径：apt 装 Ruby 运行环境 → gem 在线安装 Capistrano 及其依赖链。

4.1 方案说明

Capistrano 本体是 Ruby gem，gem install capistrano 会自动解析依赖链（sshkit、net-ssh、net-scp、net-sftp、airbrussh、i18n、concurrent-ruby 等）。其中 net-ssh 依赖的 openssl gem 含 C 原生扩展，需要编译工具链与 Ruby 头文件，因此必须先装 build-essential、ruby-dev、libssl-dev——这是本方案唯一容易踩的坑（见 4.3 排障实录）。

4.2 安装 Ruby 运行环境

DEBIAN_FRONTEND=noninteractive apt-get install -y ruby-full

实测回显（节选末尾）：

Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
Processing triggers for ca-certificates (20260816ubuntu0.22.04.1) ...
Updating certificates in /etc/ssl/certs...
0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

4.3 安装编译工具链（必装，否则 openssl 扩展编译失败）

DEBIAN_FRONTEND=noninteractive apt-get install -y build-essential ruby-dev libssl-dev

实测回显（节选末尾）：

Setting up gnupg (2.2.27-3ubuntu2.5) ...
Setting up build-essential (12.9ubuntu3) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

⚠️ 排障实录：本文第一次实测时漏装了这一步，直接 gem install capistrano 报错失败，错误现象与定位过程完整保留在「八、常见问题」Q1。请务必先装编译链再装 gem。

4.4 在线安装 Capistrano

gem install capistrano

实测回显（完整依赖链照抄）：

Building native extensions. This could take a while...
Successfully installed openssl-4.0.2
Successfully installed net-ssh-8.0.4
Successfully installed net-sftp-4.0.2
Successfully installed net-scp-4.1.3
Successfully installed sshkit-1.25.1
Successfully installed concurrent-ruby-1.3.8
Successfully installed i18n-1.14.8
Successfully installed airbrussh-1.6.2
Successfully installed capistrano-3.20.1
Parsing documentation for openssl-4.0.2
Installing ri documentation for openssl-4.0.2
（中间各 gem 文档安装行，略——输出节选）
Done installing documentation for openssl, net-ssh, net-sftp, net-scp, sshkit, concurrent-ruby, i18n, airbrussh, capistrano after 5 seconds
9 gems installed

⚠️ 网络说明：本次实测（2026-10-27）控制机直连 RubyGems 官方源 https://rubygems.org 一次成功，未发生降级。若你的网络访问 rubygems.org 慢或超时，可换国内镜像源 gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/，或为 gem 配置代理（gem install -p http://<代理>:<端口> capistrano）。

4.5 验证安装

which cap
cap --version
gem list capistrano sshkit net-ssh airbrussh rake i18n concurrent-ruby net-scp net-sftp openssl

实测回显：

/usr/local/bin/cap
Capistrano Version: 3.20.1 (Rake Version: 13.0.6)
capistrano (3.20.1)
sshkit (1.25.1)
net-ssh (8.0.4)
airbrussh (1.6.2)
rake (13.0.6, 13.0.3)
i18n (1.14.8)
concurrent-ruby (1.3.8)
net-scp (4.1.3)
net-sftp (4.0.2)
openssl (4.0.2, default: 3.0.0)

cap 落在 /usr/local/bin/cap，版本 3.20.1；rake 13.0.6 是 gem 安装的新版，13.0.3 是 Ruby 3.0 自带的 default gem，两者共存属正常。

五、离线安装方案（B：.gem 包离线安装，内网/断网环境）

5.1 方案说明

离线环境的核心是把 Capistrano 本体 + 8 个依赖 gem 共 9 个 .gem 文件提前下载好，拷贝到断网控制机后用 gem install --local 本地解析安装。实测证明：只要 9 个包齐全且版本与在线解析结果一致，--local 模式不访问任何网络即可完成全依赖安装。

⚠️ 前提：断网控制机上的 ruby-full、build-essential、ruby-dev、libssl-dev 需提前通过内网 apt 镜像装好（离线 gem 包解决不了 apt 依赖）。

5.2 在可联网机器下载全部 .gem 包

mkdir -p /root/capistrano-offline && cd /root/capistrano-offline
gem fetch capistrano -v 3.20.1
gem fetch airbrussh -v 1.6.2
gem fetch sshkit -v 1.25.1
gem fetch net-ssh -v 8.0.4
gem fetch net-scp -v 4.1.3
gem fetch net-sftp -v 4.0.2
gem fetch openssl -v 4.0.2
gem fetch concurrent-ruby -v 1.3.8
gem fetch i18n -v 1.14.8
ls -la *.gem

实测回显（末段）：

Downloaded concurrent-ruby-1.3.8
Downloaded i18n-1.14.8
-rw-r--r-- 1 root root  15360 Oct 27 09:12 airbrussh-1.6.2.gem
-rw-r--r-- 1 root root  74752 Oct 27 09:11 capistrano-3.20.1.gem
-rw-r--r-- 1 root root  90624 Oct 27 09:12 concurrent-ruby-1.3.8.gem
-rw-r--r-- 1 root root  47616 Oct 27 09:12 i18n-1.14.8.gem
-rw-r--r-- 1 root root  38912 Oct 27 09:12 net-scp-4.1.3.gem
-rw-r--r-- 1 root root  60928 Oct 27 09:12 net-sftp-4.0.2.gem
-rw-r--r-- 1 root root 172544 Oct 27 09:12 net-ssh-8.0.4.gem
-rw-r--r-- 1 root root 206848 Oct 27 09:12 openssl-4.0.2.gem
-rw-r--r-- 1 root root 146944 Oct 27 09:12 sshkit-1.25.1.gem

⚠️ 注意：gem fetch <名> 不带 -v 时取「最新版」，可能与在线安装时解析出的版本不一致（实测 gem fetch i18n 取到 1.15.2、gem fetch concurrent-ruby 取到一个旧的平台特定包 0.7.2-x86_64-linux，均与在线解析的 1.14.8 / 1.3.8 不符）。务必按方案 A 实测回显里的版本清单逐个带 -v 抓取，否则离线安装会因依赖版本不匹配而失败或解析出不同版本。

5.3 拷贝到断网控制机并离线安装

把 9 个 .gem 文件用 U 盘/内网文件服务器/scp 任意方式拷到断网控制机的 /root/cap-gems/，然后：

cd /root/cap-gems
gem install --local capistrano-3.20.1.gem
cap --version

实测回显（在已断开外网的控制机上实测，节选首尾）：

（前段为各依赖 gem 的 Parsing/Installing documentation 行，略——输出节选）
Done installing documentation for openssl, net-ssh, net-sftp, net-scp, sshkit, concurrent-ruby, i18n, airbrussh, capistrano after 5 seconds
9 gems installed

real	0m16.421s
user	0m14.082s
sys	0m2.317s
Capistrano Version: 3.20.1 (Rake Version: 13.0.6)

--local 只使用当前目录的 .gem 文件做依赖解析，9 个包一次装齐，全程无外网请求。

六、方案对比与选择建议

维度	A：在线 gem 安装	B：离线 .gem 包安装
安装来源	RubyGems 官方源	提前下载的 9 个 .gem 文件
是否需联网	控制机需访问 rubygems.org	控制机完全断网可装
版本一致性	gem 自动解析最新兼容版本	需手工锁版本逐个 fetch
耗时	约 1 分钟（含文档生成）	约 16 秒（实测 real 16.4s）
适用场景	可联网的办公/云控制机	内网隔离、等保环境发布机

选择建议：控制机能联网一律选方案 A；只有内网隔离环境才用方案 B，且离线包版本必须按方案 A 的实测清单锁定。

七、配置说明

Capistrano 本体安装后无需任何全局配置文件，所有配置都在「每个待部署项目」的目录里（Capfile、config/deploy.rb、config/deploy/<stage>.rb）。安装后第一件有意义的事是进入项目目录执行：

mkdir -p /root/demo-deploy && cd /root/demo-deploy
cap install STAGES=production

实测回显：

mkdir -p config/deploy
create config/deploy.rb
create config/deploy/production.rb
mkdir -p lib/capistrano/tasks
create Capfile
Capified

生成的 4 个文件/目录的逐项含义、全量配置参数与多 stage 写法见《Capistrano 3.20 配置参数详解》；cap 全部子命令与参数的实测详解见《Capistrano 3.20 常用 CLI 命令详解》。

升级与降级（gem 形态天然支持多版本共存）：

gem install capistrano -v 3.19.2   # 并存安装旧版
gem list capistrano                # 查看共存版本
gem uninstall capistrano -v 3.19.2 # 精确卸载某版本

在项目内锁定版本则用项目 Gemfile：gem 'capistrano', '~> 3.20.1'，配合 bundle exec cap ... 调用；config/deploy.rb 顶部的 lock "~> 3.20.1" 会在 cap 启动时校验运行版本，不匹配即报错退出，防止团队成员用错版本。

八、常见问题

Q1：gem install capistrano 报错 Failed to build gem native extension / You have to install development tools first？

现象实录（未装编译链时的真实报错，节选）：

Building native extensions. This could take a while...
ERROR:  Error installing capistrano:
	ERROR: Failed to build gem native extension.

    current directory: /var/lib/gems/3.0.0/gems/openssl-4.0.2/ext/openssl
/usr/bin/ruby3.0 -I /usr/lib/ruby/vendor_ruby -r ./siteconf20261027-2678-lzenl1.rb extconf.rb
checking for rb_call_super_kw(0, NULL, 0) in ruby.h... *** extconf.rb failed ***
...
/usr/lib/ruby/3.0.0/mkmf.rb:471:in `try_do': The compiler failed to generate an executable file. (RuntimeError)
You have to install development tools first.

定位：net-ssh 8.x 依赖的 openssl gem（4.0.2）含 C 原生扩展，编译需要 gcc、make、Ruby 头文件（ruby-dev）与 OpenSSL 头文件（libssl-dev），纯净 Ubuntu 22.04 默认都没有。

解决：执行 4.3 的 apt-get install -y build-essential ruby-dev libssl-dev 后重跑 gem install capistrano 即成功（本文 4.4 回显即为修复后的真实结果）。

Q2：装完 cap 命令找不到？

gem list capistrano 有但 cap 报 command not found 时，检查 /usr/local/bin 是否在 PATH：echo $PATH。apt 版 Ruby 的 gem 可执行文件默认装到 /usr/local/bin，正常都在 PATH 内；若用 rbenv/RVM 装的 Ruby，则需 rbenv rehash 或重开 shell。

Q3：控制机要不要装 git？

要。cap install、cap production deploy 等流程里控制机本机不直接 clone 业务仓库（clone 发生在目标服务器），但项目若用 Git 管理部署配置本身、或启用 set :local_user, -> { git config user.name.chomp } 之类取值，都需要本机 git。建议 apt-get install -y git 一并装上。

Q4：Ruby 3.0 会不会太旧？

Capistrano 3.20.1 官方要求 Ruby >= 2.5，Ruby 3.0.2 实测完整跑通多机部署/回滚/清理全流程。若需要更新的 Ruby（如 3.3/3.4），可用 rbenv 编译安装后再 gem install capistrano，gem 侧步骤完全一致。

九、卸载与清理

gem uninstall capistrano

实测回显（同时移除了 cap、capify 两个可执行文件）：

Removing cap
Removing capify
Successfully uninstalled capistrano-3.20.1

如需彻底清理依赖链（确认无其他 gem 使用时）：

gem uninstall airbrussh sshkit net-sftp net-scp net-ssh openssl concurrent-ruby i18n -x
rm -rf /root/capistrano-offline /root/cap-gems   # 离线包目录

Ruby 运行环境本身按需保留（其他 Ruby 工具可能复用）；确定不再使用 Ruby 时可 apt-get purge -y ruby-full ruby-dev && apt-get autoremove -y。

十、参考链接

Capistrano 官网文档：https://capistranorb.com/
RubyGems - capistrano（版本与依赖权威出处）：https://rubygems.org/gems/capistrano
GitHub 仓库：https://github.com/capistrano/capistrano
SSHKit（Capistrano 的 SSH 执行层）：https://github.com/capistrano/sshkit