Ubuntu 22.04 安装 Gearman 2.2.0 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Gearman job server（gearmand）及配套客户端工具，覆盖「apt 仓库在线安装」与「官方源码编译安装 2.2.0」两种方案，并完成 systemd 托管与运行验证。全文命令与回显均在 Ubuntu 22.04 x86_64 环境实测通过，版本基准为 2026-10-20 实查的官方最新稳定版 Gearman 2.2.0。Gearman 的定位与三角色架构见《Gearman 2.2.0 介绍与选型指南》。

一、环境信息

本文所有操作均在以下环境实测通过：

操作系统：Ubuntu 22.04 LTS（jammy），x86_64
内核 C 编译器：gcc 11.4.0（源码编译方案使用）
Boost 版本：1.74.0（Ubuntu 22.04 官方仓库）
目标软件：Gearman job server（gearmand）2.2.0（官方 GitHub Releases 当前最新稳定版，发布于 2026-10-19）
监听端口：4730（Gearman 协议默认端口）
运行账号：gearman（apt 方案由软件包自动创建）/ gearmand（源码方案手动创建）
服务管理：systemd

二、前置条件

2.1 更新系统软件源

安装前先刷新 apt 索引，确保后续依赖安装基于最新版本清单：

apt-get update

实测回显（节选首尾）：

Hit:1 http://archive.ubuntu.com/ubuntu jammy InRelease
Hit:2 http://archive.ubuntu.com/ubuntu jammy-updates InRelease
Hit:3 http://archive.ubuntu.com/ubuntu jammy-security InRelease
Reading package lists... Done

2.2 基础工具

后续步骤会用到下载与校验工具，一并安装：

apt-get install -y wget curl ca-certificates

实测回显（节选）：

Reading package lists... Done
Building dependency tree... Done
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

💡 说明：回显中 0 newly installed 表示本机已有这些工具；在新装机器上会显示实际安装的包数量，属正常差异。

2.3 时间与防火墙确认

Gearman 服务端只监听 4730 端口，安装前确认端口未被占用：

ss -ltn | grep 4730 || echo "端口 4730 空闲"

实测回显：

端口 4730 空闲

三、版本选型说明

3.1 查询官方最新稳定版

Gearman 的版本发布信息以 GitHub Releases 页为准，可通过 releases.atom 订阅源查询（该源不限流，避免直连 GitHub API）：

curl -s https://github.com/gearman/gearmand/releases.atom | grep -oE '<title>[^<]+</title>' | head -5

实测回显（2026-10-20 查询）：

<title>Release notes from gearmand</title>
<title>2.2.0</title>
<title>2.1.0: August 2026 Feature and Significant Bug Fixes Release</title>
<title>2.0.0: Major release with several potentially breaking changes and a large number of fixes and improvements</title>

当前官方最新稳定版为 2.2.0。

3.2 安装方案与版本对照

方案	实际版本	来源	是否需联网	适用场景
方案 A：apt 仓库安装	1.1.19.1+ds-2build1	Ubuntu jammy/universe 官方仓库	是	快速验证、对版本无要求的存量应用
方案 B：源码编译安装	2.2.0	GitHub 官方 Releases	是（可离线转移）	需要最新版特性、修复与 2.x 系列行为

关键差异：Ubuntu 22.04 仓库中的 Gearman 为 1.1.19.1（1.x 系列旧版），与 2.2.0 在协议参数、持久化队列模块（2.x 新增 redis 队列等）、CLI 行为上均有差异；生产环境建议以方案 B 安装 2.2.0 为准。两个版本的 gearmand --help 参数集合不同，跨版本迁移前请核对《Gearman 2.2.0 配置参数详解》（本专栏配置篇）。

四、方案 A：apt 仓库在线安装

4.1 方案说明

Ubuntu 22.04 的 universe 仓库内置了 Gearman 全家桶：gearman-job-server（服务端）、gearman-tools（gearadmin/gearman 命令行工具）、libgearman-dev（C 客户端开发库）。优点是一条命令完成安装并自动生成 systemd 服务；缺点是版本停留在 1.1.19.1。

先确认仓库候选版本：

apt-cache policy gearman-job-server gearman-tools libgearman-dev

实测回显：

gearman-job-server:
  Installed: (none)
  Candidate: 1.1.19.1+ds-2build1
  Version table:
     1.1.19.1+ds-2build1 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages
gearman-tools:
  Installed: (none)
  Candidate: 1.1.19.1+ds-2build1
  Version table:
     1.1.19.1+ds-2build1 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages
libgearman-dev:
  Installed: (none)
  Candidate: 1.1.19.1+ds-2build1
  Version table:
     1.1.19.1+ds-2build1 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages

4.2 安装软件包

apt-get install -y gearman-job-server gearman-tools libgearman-dev

实测回显（节选尾段）：

Unpacking libgearman-dev (1.1.19.1+ds-2build1) ...
Setting up libgearman-dev (1.1.19.1+ds-2build1) ...
Setting up gearman-job-server (1.1.19.1+ds-2build1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/gearman-job-server.service → /lib/systemd/system/gearman-job-server.service.
invoke-rc.d: policy-rc.d denied execution of start.
Setting up gearman-tools (1.1.19.1+ds-2build1) ...

⚠️ 注意：Created symlink 说明服务已设为开机自启；若回显中出现 invoke-rc.d: policy-rc.d denied execution of start，表示当前环境策略阻止了安装阶段的自动启动（受限环境常见），手动执行下文 4.4 的启动命令即可，不影响安装结果。

4.3 服务单元与默认参数

安装生成的 systemd 单元文件位于 /lib/systemd/system/gearman-job-server.service：

[Unit]
Description=gearman job control server
Documentation=http://gearman.info/

[Service]
EnvironmentFile=-/etc/default/gearman-job-server
ExecStartPre=/usr/bin/install -d -o gearman /run/gearman
PermissionsStartOnly=true
User=gearman
Type=forking
Restart=always
PIDFile=/run/gearman/gearmand.pid
ExecStart=/usr/sbin/gearmand --pid-file=/run/gearman/gearmand.pid $PARAMS

[Install]
WantedBy=multi-user.target

逐项说明：

EnvironmentFile=-/etc/default/gearman-job-server：启动参数集中在 /etc/default/gearman-job-server 的 PARAMS 变量中，改参数改这里，无需动单元文件（前导 - 表示文件不存在也不报错）；
User=gearman：以软件包自动创建的系统账号 gearman 运行；
Type=forking + PIDFile：gearmand 以 --daemon 方式自守护，systemd 通过 PID 文件跟踪主进程；
Restart=always：进程退出后自动拉起。

默认的 /etc/default/gearman-job-server 参数（实测原样）：

# Parameters to pass to gearmand.
PARAMS="--listen=localhost \
 --daemon \
 --log-file=/var/log/gearman-job-server/gearmand.log"

💡 说明：默认 --listen=localhost，即只监听 127.0.0.1:4730。若要接受远程 worker/client 连接，把该值改为 0.0.0.0 或具体内网地址后 systemctl restart gearman-job-server。

4.4 启动服务并设置开机自启

systemctl start gearman-job-server
systemctl enable gearman-job-server

实测回显：

Synchronizing state of gearman-job-server.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable gearman-job-server

确认运行状态：

systemctl is-active gearman-job-server
ss -ltn | grep 4730

实测回显：

active
LISTEN 0      32         127.0.0.1:4730      0.0.0.0:*
LISTEN 0      32             [::1]:4730         [::]:*

4.5 验证安装结果

/usr/sbin/gearmand -V
/usr/bin/gearadmin --server-version

实测回显：

gearmand 1.1.19.1+ds - https://github.com/gearman/gearmand/issues
1.1.19.1+ds

--server-version 返回服务端真实运行版本，与二进制版本一致，安装链路完整可用。

五、方案 B：源码编译安装 2.2.0

5.1 方案说明

官方通过 GitHub Releases 发布源码包 gearmand-2.2.0.tar.gz，在 Ubuntu 22.04 上以标准 configure && make && make install 流程编译，安装到 /usr/local。这是获取 2.2.0 最新版本的唯一途径（仓库无 2.x 软件包）。

5.2 安装编译依赖

gearmand 2.2.0 依赖 boost、libevent、openssl 等库，一次性装齐：

apt-get install -y build-essential automake autoconf libtool pkg-config gperf \
    libboost-all-dev libevent-dev libssl-dev uuid-dev \
    libhiredis-dev libpq-dev libtokyocabinet-dev libsqlite3-dev libmysqlclient-dev

实测回显（节选尾段）：

Setting up libboost-mpi-python-dev (1.74.0.3ubuntu7) ...
Setting up libboost-mpi-dev (1.74.0.3ubuntu7) ...
Setting up libboost-all-dev (1.74.0.3ubuntu7) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

💡 说明：libhiredis-dev（redis 持久化队列）、libsqlite3-dev（sqlite 队列）、libpq-dev（PostgreSQL 队列）是 2.2.0 各持久化队列模块的编译开关，缺哪个对应的队列模块就不编入，装齐后 configure 阶段可全部启用。

5.3 下载源码包并校验

从 GitHub 官方 Releases 下载 2.2.0 源码包：

cd /tmp
wget https://github.com/gearman/gearmand/releases/download/2.2.0/gearmand-2.2.0.tar.gz

实测回显（节选）：

--2026-10-20 03:05:00--  https://github.com/gearman/gearmand/releases/download/2.2.0/gearmand-2.2.0.tar.gz
Resolving github.com (github.com)... 140.82.121.3
Connecting to github.com (github.com)|140.82.121.3|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 1149010 (1.1M) [application/octet-stream]
Saving to: 'gearmand-2.2.0.tar.gz'

gearmand-2.2.0.tar.gz                  100%[=========================================================================>]   1.10M  --.-KB/s    in 0.1s

2026-10-20 03:05:01 (8.5 MB/s) - 'gearmand-2.2.0.tar.gz' saved [1149010/1149010]

下载后校验完整性（SHA256，2026-10-20 对官方发布件实算）：

sha256sum gearmand-2.2.0.tar.gz

实测回显：

fec69ec0e893147a9eb8bfa203e173cc5598adc372e307fea12d587d13071d75  gearmand-2.2.0.tar.gz

5.4 解压并配置编译选项

tar xzf gearmand-2.2.0.tar.gz
cd gearmand-2.2.0
./configure --prefix=/usr/local

实测回显（节选检测项）：

checking for uuid_generate_time_safe... yes
checking for joinable pthread attribute... PTHREAD_CREATE_JOINABLE
checking for PTHREAD_PRIO_INHERIT... yes
checking for C compiler vendor... gnu
checking for C compiler version... 11.4.0
checking that generated files are newer than configure... done

configure 结束时输出能力摘要（实测原样）：

   * Building with hiredis      yes
   * Building with libsqlite3   yes
   * Building with libdrizzle   yes
   * Building with libmemcached not found
   * Building with libpq        yes
   * Building with tokyocabinet yes
   * Building with libmysql     yes
   * SSL enabled:               no
   * wolfssl found:             no
   * openssl found:             yes
   * make -j:                   13
   * VCS checkout:              no
   * sphinx-build:

逐项解读：

Building with hiredis/libsqlite3/libpq 均为 yes：对应的 redis、sqlite、PostgreSQL 持久化队列模块已编入；
libmemcached not found：本机未装 libmemcached 开发库，对应队列模块未编入（需要时 apt-get install -y libmemcached-dev 后重新 configure）；
SSL enabled: no：虽然 openssl found: yes，但 2.2.0 需要显式开启，将 configure 命令改为 ./configure --prefix=/usr/local --with-ssl=yes 即可启用 --ssl 相关参数；本文按默认（不启用 TLS）继续。

5.5 编译与安装

make -j$(nproc)
make install

make 实测回显（节选尾段）：

  CXXLD    t/postgres
  CXXLD    t/mysql
  CXXLD    t/sqlite
  CXXLD    t/tokyocabinet
  CXXLD    t/redis
  CXXLD    t/httpd
make[2]: Leaving directory '/tmp/gearmand-2.2.0'
make[1]: Leaving directory '/tmp/gearmand-2.2.0'

make install 实测回显（节选尾段，可见三件套落位）：

libtool: install: /usr/bin/install -c gearmand/gearmand /usr/local/sbin/gearmand
libtool: install: /usr/bin/install -c bin/.libs/gearman /usr/local/bin/gearman
libtool: install: /usr/bin/install -c bin/gearadmin /usr/local/bin/gearadmin
make[3]: Leaving directory '/tmp/gearmand-2.2.0'
make[2]: Leaving directory '/tmp/gearmand-2.2.0'
make[1]: Leaving directory '/tmp/gearmand-2.2.0'

安装完成后验证二进制：

/usr/local/sbin/gearmand --version

实测回显：

gearmand 2.2.0 - https://github.com/gearman/gearmand/issues

5.6 创建运行账号与目录

以专用系统账号运行服务端，创建日志与数据目录：

useradd --system --user-group --home-dir /var/lib/gearmand --create-home --shell /usr/sbin/nologin gearmand
mkdir -p /var/log/gearmand
chown gearmand:gearmand /var/log/gearmand

useradd 无输出即为成功，确认账号：

id gearmand

实测回显：

uid=999(gearmand) gid=999(gearmand) groups=999(gearmand)

5.7 systemd 托管

创建单元文件 /etc/systemd/system/gearmand.service（完整内容如下）：

[Unit]
Description=Gearman job server (gearmand)
Documentation=https://gearman.org/gearmand/
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=gearmand
Group=gearmand
RuntimeDirectory=gearmand
ExecStart=/usr/local/sbin/gearmand --pid-file=/run/gearmand/gearmand.pid --log-file=/var/log/gearmand/gearmand.log --verbose=INFO
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

逐项说明：

Type=simple：2.2.0 前台运行（不自守护），systemd 直接跟踪主进程，无需 PID 文件配合 Type=forking；
RuntimeDirectory=gearmand：systemd 自动创建 /run/gearmand 并在服务停止时清理，PID 文件写入其中；
User/Group=gearmand：以 5.6 创建的专用账号降权运行；
ExecStart 中 --verbose=INFO：日志级别 INFO，便于排障；可用级别为 FATAL、ALERT、CRITICAL、ERROR、WARNING、NOTICE、INFO、DEBUG（详见《Gearman 2.2.0 配置参数详解》）；
LimitNOFILE=65536：Gearman 每个 worker/client 连接占用一个文件描述符，生产环境建议显式放大。

⚠️ 注意：若此前按方案 A 装过 apt 版本，gearman-job-server 服务占用了 4730 端口，需先执行 systemctl stop gearman-job-server 停止它，再用 systemctl disable gearman-job-server 取消其自启，然后才启动本单元，否则新服务绑定端口超时失败（见八、常见问题 Q1）。

加载并启动：

systemctl daemon-reload
systemctl enable gearmand
systemctl start gearmand

实测回显：

Synchronizing state of gearmand.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable gearmand
Created symlink /etc/systemd/system/multi-user.target.wants/gearmand.service → /etc/systemd/system/gearmand.service.

确认运行状态：

systemctl status gearmand --no-pager

实测回显（节选）：

● gearmand.service - Gearman job server (gearmand)
     Loaded: loaded (/etc/systemd/system/gearmand.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-20 03:02:47 UTC; 5s ago
   Main PID: 40360 (gearmand)
      Tasks: 7 (limit: 5753)
     Memory: 2.1M
        CPU: 12ms
     CGroup: /system.slice/gearmand.service
             └─40360 /usr/local/sbin/gearmand --pid-file=/run/gearmand/gearmand.pid --log-file=/var/log/gearmand/gearmand.log --verbose=INFO

5.8 验证服务可用

ss -ltn | grep 4730
gearadmin --server-version
gearadmin --status

实测回显：

LISTEN 0      32           0.0.0.0:4730      0.0.0.0:*
LISTEN 0      32              [::]:4730         [::]:*
2.2.0
.

4730 端口已在 IPv4/IPv6 双栈监听；
gearadmin --server-version 返回 2.2.0，服务端真实版本符合预期；
--status 空队列时输出 .（管理协议以 . 单独一行表示输出结束），服务正常应答。

再发一个往返任务做端到端验证（worker 端注册 rev 函数执行 rev 命令，client 端提交字符串）：

gearman -w -f rev rev &
sleep 1
echo "install-ok" | gearman -f rev

实测回显：

ko-llatsni

worker 把 install-ok 反转成 ko-llatsni 返回，client/worker/job server 三角色链路全通。

六、方案对比与选择建议

维度	方案 A：apt 安装	方案 B：源码编译
实际版本	1.1.19.1+ds	2.2.0（官方最新）
安装耗时	约 1 分钟	约 3–10 分钟（视核数）
systemd 服务	自动生成 `gearman-job-server.service`	手写 `gearmand.service`
二进制位置	/usr/sbin/gearmand、/usr/bin/{gearadmin,gearman}	/usr/local/sbin/gearmand、/usr/local/bin/{gearadmin,gearman}
升级方式	`apt-get upgrade` 跟随仓库	重新下载新版本源码编译覆盖
持久化队列	libdrizzle/memcached 等 1.x 模块	sqlite/PostgreSQL/redis 等 2.x 模块
适用场景	快速验证、依赖旧版 libgearman 的存量应用	生产部署、需要 2.x 特性

选择建议：新项目与生产环境选方案 B（2.2.0 为官方当前主线，2.x 对 1.x 有不兼容变更，新装不必背负历史包袱）；仅在维护必须运行 1.x 的存量应用时选方案 A。两方案可共存（二进制路径不同），但同机同时只能有一个 job server 占用 4730 端口。

七、配置说明

安装完成后的关键文件与目录：

路径	说明
/usr/local/sbin/gearmand	服务端主程序（方案 B）
/usr/local/bin/gearadmin	服务端管理命令（查看状态、worker 列表等）
/usr/local/bin/gearman	命令行 client/worker 工具
/usr/local/lib/libgearman.so.8	C 客户端开发库
/usr/local/etc/gearmand.conf	服务端默认配置文件路径（默认不存在，创建后自动读取）
/var/log/gearmand/gearmand.log	服务端日志（systemd 单元中指定）
/run/gearmand/gearmand.pid	PID 文件（RuntimeDirectory 自动管理）

最小可用配置已在 systemd 单元中给出（PID 文件、日志文件、INFO 级别）。更多参数（持久化队列、线程数、worker 唤醒等）的逐项详解与实测见《Gearman 2.2.0 配置参数详解》。

八、常见问题

Q1：启动时报 Timeout occurred when calling bind() 怎么办？

日志中出现：

  ERROR 2026-10-20 03:05:38.000000 [  main ] Timeout occurred when calling bind() for 0.0.0.0:4730 -> libgearman-server/gearmand.cc:686

原因是 4730 端口已被其他进程（常见为 apt 版 gearman-job-server 未停干净）占用。定位并处理：

ss -ltnp | grep 4730
systemctl stop gearman-job-server
systemctl start gearmand

处理后再用 systemctl is-active gearmand 确认为 active。

Q2：装了方案 B 后 gearmand -V 还是显示旧版本 1.1.19.1？

apt 版与源码版二进制分别在 /usr/sbin 与 /usr/local/sbin，$PATH 中 /usr/local/sbin 在前。若 shell 缓存了旧路径，执行 hash -r 清除后 which gearmand 应显示 /usr/local/sbin/gearmand。也可用绝对路径调用明确版本。

Q3：启动时报 Could not open configuration file.

--config-file 指向的文件不存在时会直接报错退出（实测回显：gearmand: Could not open configuration file.）。检查路径拼写；注意该报错仅在使用显式 --config-file=<路径> 时出现——若使用默认路径 /usr/local/etc/gearmand.conf，文件不存在会静默跳过。

Q4：启动时报 Unknown queue xxx

--queue-type 传入了本构建未编入的模块名。实测回显：

  ERROR 2026-10-20 03:01:18.685376 [  main ] Unknown queue xxx initialize(UNKNOWN_OPTION) -> libgearman-server/queue.cc:256
gearmand: Error while initializing the queue : xxx

可用队列类型以 gearmand --help 输出的分组为准（本文构建实测支持 builtin、libsqlite3、Postgres、redis），或回到 5.2 补装对应开发库后重新编译。

Q5：无法打开日志文件

以非 root 用户运行且日志目录不可写时报：

gearmand: Could not open log file "/usr/local/var/log/gearmand.log", from "/", switching to stderr. (No such file or directory)

按 5.6 建好 /var/log/gearmand 并 chown 给运行账号，或在启动参数中用 --log-file 指向可写路径。

九、卸载与清理

9.1 卸载 apt 版本

systemctl stop gearman-job-server
systemctl disable gearman-job-server
apt-get purge -y gearman-job-server gearman-tools libgearman-dev

实测回显（节选尾段）：

Removing gearman-job-server (1.1.19.1+ds-2build1) ...
Warning: group `gearman' has no more members.
Done.
Processing triggers for man-db (2.10.1-1) ...

9.2 卸载源码编译版本

systemctl stop gearmand
systemctl disable gearmand
rm /etc/systemd/system/gearmand.service
systemctl daemon-reload
rm -f /usr/local/sbin/gearmand /usr/local/bin/gearadmin /usr/local/bin/gearman
rm -f /usr/local/lib/libgearman*
rm -rf /usr/local/include/libgearman* /var/log/gearmand /var/lib/gearmand
userdel gearmand

以上命令均无报错输出即清理完成；gearmand --version 不再可用即卸载成功。

十、参考链接

Gearman 官网：https://gearman.org/
官方下载页（GitHub Releases）：https://github.com/gearman/gearmand/releases
2.2.0 源码包直链：https://github.com/gearman/gearmand/releases/download/2.2.0/gearmand-2.2.0.tar.gz
版本订阅源：https://github.com/gearman/gearmand/releases.atom
站内相关文档：《Gearman 2.2.0 介绍与选型指南》、《Gearman 2.2.0 配置参数详解》、《Gearman 2.2.0 常用 CLI 命令详解》