Gearman 2.2.0 常用 CLI 命令详解

目标：系统梳理 Gearman 2.2.0 自带的三个命令行工具（服务端 gearmand、管理工具 gearadmin、客户端/worker 工具 gearman）的全部子命令与参数，每条命令均给出实测回显与列语义解读， Ubuntu 22.04 + Gearman 2.2.0 环境逐条实测通过。安装与参数配置见《Ubuntu 22.04 安装 Gearman 2.2.0 指南》与《Gearman 2.2.0 配置参数详解》。

一、环境信息

操作系统：Ubuntu 22.04 LTS（jammy），x86_64
Gearman 版本：gearmand 2.2.0（源码编译安装于 /usr/local）
服务端：gearmand 以 systemd 托管运行于 4730 端口
相关二进制：/usr/local/sbin/gearmand、/usr/local/bin/gearadmin、/usr/local/bin/gearman
演示函数：rev（调用系统 rev 命令反转输入）、echo_fn（无命令 worker，原样回显）、wc_fn（调用 wc -c 统计字节数）、mail_out（无 worker 的排队演示函数）

说明：文中「worker 侧」指注册函数等待作业的一方，「client 侧」指提交作业的一方；gearman 一个二进制通过 -w 开关切换两种身份。

二、工具概览

2.1 三个工具的分工

工具	身份	用途
gearmand	job server	启动服务端进程，参数即配置（详解见配置篇）
gearadmin	运维管理端	查询服务状态、worker 列表、管理函数与作业队列
gearman	client / worker	命令行提交作业（client）或注册函数执行命令（worker）

2.2 gearadmin 参数总览

gearadmin --help

实测回显（完整原样）：

Options:
  --help                         Options related to the program.
  -h [ --host ] arg (=localhost) Connect to the host
  -p [ --port ] arg (=4730)      Port number or service to use for connection
  --server-version               Fetch the version number for the server.
  --server-verbose               Fetch the verbose setting for the server.
  --create-function arg          Create the function from the server.
  --cancel-job arg               Remove a given job from the server's queue
  --drop-function arg            Drop the function from the server.
  --show-unique-jobs             Show job handles and unique IDs of jobs on the
                                 server.
  --show-jobs                    Show all jobs on the server.
  --getpid                       Get Process ID for the server.
  --status                       Status for the server.
  --priority-status              Queued jobs status by priority.
  --workers                      Workers for the server.
  -S [ --ssl ]                   Enable SSL connections.

注意：2.2.0 的 gearadmin 没有 --shutdown 参数（1.x 时代曾提供，2.x 已移除），停止服务端需走 systemd（systemctl stop gearmand）或向进程发 SIGTERM，见五、5.6。

2.3 gearman 参数总览

gearman -H

实测回显（完整原样；直接运行 gearman --help 会先报一行 usage 错误再打印同样内容，推荐用 -H）：


gearman Error in usage(No Functions were provided).

Client mode: gearman [options] [<data>]
Worker mode: gearman -w [options] [<command> [<args> ...]]
  Ping mode: gearman --ping [options]
                      - Send ECHO request to server
                        (connectivity check; no worker needed)

Common options to client, ping, and worker modes:
        -h <host>     - Job server host
        -H            - Print this help menu
        -v            - Print diagnostic information to stdout(false)
        -p <port>     - Job server port
        -t <timeout>  - Timeout in milliseconds
                        (defaults to 2 seconds in ping mode)
        -i <pidfile>  - Create a pidfile for the process
        -S            - Enable SSL connections

Client options:
        -f <function> - Function name to use for jobs (can give many)
        -b            - Run jobs in the background(false)
        -I            - Run jobs as high priority
        -L            - Run jobs as low priority
        -n            - Run one job per line(false)
        -N            - Same as -n, but strip off the newline(false)
        -P            - Prefix all output lines with functions names
        -s            - Send job without reading from standard input
        -u <unique>   - Unique key to use for job

Worker options:
        -f <function> - Function name to use for jobs (can give many)
        -c <count>    - Number of jobs for worker to run before exiting
        -n            - Send data packet for each line(false)
        -N            - Same as -n, but strip off the newline(false)
        -w            - Run in worker mode(false)

三种模式：默认 client（提交作业）、-w worker（注册函数）、--ping（连通性探测）。

三、前置条件

gearmand 2.2.0 已安装并以 systemd 运行：systemctl is-active gearmand 返回 active；
服务端口可连：gearadmin --server-version 返回 2.2.0；
gearadmin、gearman 在 PATH 中（源码安装位于 /usr/local/bin）；
演示用 worker 命令 rev、wc 为 Ubuntu 自带工具，无需额外安装。

四、gearmand 服务端命令

4.1 查看版本

gearmand --version

实测回显：

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

4.2 前台与守护运行

前台运行（日志走 stderr，Ctrl+C 停止）：

gearmand -p 4740 --log-file=stderr

实测回显（INFO 级别下的正常启动日志）：

   INFO 2026-10-20 03:06:45.891023 [  main ] Initializing Gear on port 4740 with SSL: false
   INFO 2026-10-20 03:06:45.891061 [  main ] Starting up with pid 40610, verbose is set to DEBUG
   INFO 2026-10-20 03:06:45.891061 [  main ] Listening on 0.0.0.0:4740 (10)
   INFO 2026-10-20 03:06:45.891061 [  main ] Listening on :::4740 (11)

守护运行用 -d 并配 -P 写 PID 文件、-l 写日志文件（回显与要点详见《Gearman 2.2.0 配置参数详解》 5.2 节）。生产环境不建议手动运行，统一走 systemd（安装指南 5.7 的单元文件）。

4.3 停止服务端

2.2.0 无 gearadmin --shutdown，标准方式：

systemctl stop gearmand

手动运行时向进程发 SIGTERM（kill -TERM <pid>）即可优雅停止；持久化队列（sqlite/redis 等）在停机时保存队列状态。

五、gearadmin 管理命令详解

gearadmin 每条命令独立执行，-h/-p 指向目标 job server（默认 localhost:4730），多台服务端逐台执行即可巡检。管理协议的输出以单独一行 . 表示结束。

5.1 服务器信息三连

gearadmin --server-version
gearadmin --server-verbose
gearadmin --getpid

实测回显：

2.2.0
INFO
40360

--server-version：服务端真实运行版本（与 gearmand --version 的二进制版本对照，可发现「升级了二进制没重启服务」的错位）；
--server-verbose：当前日志级别（本文主服务以 --verbose=INFO 启动）；
--getpid：服务端进程号，可与 systemctl status gearmand 的 Main PID 互相印证。

连不上服务端时的报错（实测，服务未启动时）：

Error: Error connecting to localhost.

5.2 队列状态 --status

gearadmin --status

空队列时实测回显：

注册一个函数后再看（--create-function 见 5.4）：

demo_func       0       0       0
.

每行四列，语义为（与服务端源码输出格式一致）：

列	含义
1	函数名
2	队列中的作业总数（job_total）
3	正在执行的作业数（job_running）
4	注册了该函数的 worker 连接数（worker_count）

压入真实作业后的实例（2 个待执行、1 个在跑、1 个 worker 在位）：

wc_fn   2       0       0
rev     0       0       1

💡 巡检要点：第 2 列持续增长且第 4 列为 0，说明函数没有 worker 注册、作业在持续堆积，是最常见的生产故障形态；第 4 列大于 0 但第 2 列不消化，则多为 worker 卡死。

5.3 优先级队列 --priority-status

gearadmin --priority-status

实测回显（mail_out 函数有 1 个高优先级、2 个普通、1 个低优先级排队作业，无 worker）：

mail_out        1       2       1       0
.

五列语义：函数名、高优先级排队数、普通优先级排队数、低优先级排队数、worker 连接数。Gearman 的作业优先级由 client 侧 -I/-L 指定，服务端内部维护高/普通/低三条队列，派发时高优先级先出队。

5.4 worker 视图 --workers

先在另一终端起两个 worker（起法见六、6.1）：

gearman -w -f rev rev &
gearman -w -f echo_fn &

gearadmin --workers

实测回显：

38 ::3433:3032:3200:0 - : rev
39 ::3537:3038:3600:0 - : echo_fn
.

每行格式为 fd 对端地址客户端ID : 函数列表：

列	含义
1	连接的文件描述符编号
2	worker 对端地址（IPv6 十六进制形式）
3	worker 注册的客户端 ID（`gearman` CLI 未设置时显示 `-`）
4	冒号后为该连接注册的全部函数名

一个连接注册多个函数时，冒号后以空格分隔列出多个函数名。排查「worker 在不在、注册了什么函数」以本命令为准。

5.5 函数管理：create-function / drop-function

gearadmin --create-function demo_func
gearadmin --status
gearadmin --drop-function demo_func
gearadmin --status

实测回显：

OK
demo_func       0       0       0
.
OK
.

--create-function <名>：在服务端预先注册函数，返回 OK，--status 立即可见（0 0 0 表示无作业无 worker）；
--drop-function <名>：删除函数，返回 OK；
预注册用于配置管理场景（服务端先行建好函数清单，worker 上线前 --status 即可校验）。

5.6 作业管理：show-jobs / show-unique-jobs / cancel-job

先制造排队作业（mail_out 无 worker，作业滞留队列）：

echo "bg-job-1" | gearman -b -u uid-001 -f mail_out
echo "bg-job-2" | gearman -b -f mail_out
gearadmin --show-jobs
gearadmin --show-unique-jobs

实测回显：

H:00097e4566a5:12       0       0       1
H:00097e4566a5:13       0       0       1
.
H:00097e4566a5:12       uid-001
H:00097e4566a5:13       bc512736-cc34-11f1-84fe-da8c9f1cdb6e
.

--show-jobs：每行 句柄重试次数(ignore) 忽略标记排队标记 四列。第三、四列需要留意：正常排队作业显示 0 1（未忽略、在队列）；
--show-unique-jobs：每行 句柄唯一键。client 用 -u 显式指定的键原样保留（uid-001），未指定的由服务端自动生成 UUID。

取消作业：

gearadmin --cancel-job "H:00097e4566a5:13"
gearadmin --cancel-job "H:999:404"
gearadmin --show-jobs

实测回显：

OK
Error: UNKNOWN_JOB
H:00097e4566a5:13       0       1       0
.

三个行为值得记住：

取消成功返回 OK；句柄不存在返回 Error: UNKNOWN_JOB；
取消不是物理删除：被取消的作业仍出现在 --show-jobs 中，但忽略标记置 1、排队标记置 0（上例 0 1 0），不再派发给 worker；
默认内存队列（builtin）下，重启服务端后所有作业（含被取消的）全部清空，--show-jobs 回到 .。

5.7 停止服务的说明（无 --shutdown）

如 2.2 所述，2.2.0 移除了 --shutdown。远端批量运维若依赖该命令，替代方案是登录目标机执行 systemctl stop gearmand，或通过 SSH 向服务进程发 kill -TERM。

六、gearman 客户端与 worker 命令详解

6.1 worker 模式（-w）

基本形态：gearman -w -f <函数名> <命令>——注册函数，每个作业到达时把作业数据作为标准输入传给命令，命令的标准输出作为结果回传 client。

起一个反转字符串的 worker：

gearman -w -f rev rev &

-f rev 注册函数名 rev，行尾 rev 是要执行的系统命令。对应的 client 提交（见 6.2）后，worker 侧无输出、client 侧收到反转结果。

无命令的 echo worker：不给命令时，worker 收到作业后把数据原样打印到自己的标准输出（不回传 client）：

gearman -w -f echo_fn > /tmp/w_echo.out &
echo "echo-me-back" | gearman -f echo_fn
cat /tmp/w_echo.out

实测回显（client 侧无输出，数据出现在 worker 的输出文件中）：

echo-me-back

worker 命令带参数必须用 -- 分隔：wc -c 这样的命令若直接跟在选项后面，其 -c 会被 gearman 当作自己的选项解析而报错：

gearman -w -f wc_fn wc -c &

实测回显（worker 启动即失败，打印用法错误）：


gearman Error in usage(-?).

Client mode: gearman [options] [<data>]
（后接完整帮助文本，与 2.3 的 -H 输出一致）

原因：gearman 按短选项解析命令行（getopt），wc 之后的 -c 被吃成 worker 的 -c 计数选项且缺参数。正确写法加 -- 终止选项解析：

gearman -w -f wc_fn -- wc -c &
sleep 1
echo "count-my-bytes" | gearman -f wc_fn

实测回显：

count-my-bytes 恰为 15 字节，wc -c 的统计结果经 job server 回传 client。规则：worker 命令若自带选项，一律 gearman -w -f <函数> -- <命令> <参数...>。

计数 worker（-c）：处理满 N 个作业后自动退出，用于 worker 定期重生（规避长驻进程内存增长）。实测：先造 3 个排队作业，再起 -c 2 的 worker：

echo "job-one" | gearman -b -f rev
echo "job-two" | gearman -b -f rev
echo "job-three" | gearman -b -f rev
gearadmin --status
gearman -w -c 2 -f rev rev < /dev/null
echo "exit=$?"
gearadmin --status

实测回显：

rev     3       0       0
.
exit=0
rev     1       0       0
.

worker 处理 2 个作业后以 0 退出，队列剩 1 个待后续 worker 消化。

6.2 client 模式

前台提交（同步等结果）：默认从标准输入读数据：

echo "hello-world" | gearman -f rev

实测回显：

dlrow-olleh

后台提交（-b）：提交即返回、不等结果。注意 2.2.0 默认不打印作业句柄，加 -v 才显示：

echo "bg-verbose-test" | gearman -b -v -u uid-002 -f mail_out

实测回显：

Task created: H:00097e4566a5:16

后台作业的结果不会回传（没有等待中的 client），适合 fire-and-forget 场景；需要结果的任务用前台模式或让 worker 侧回写存储。

唯一键（-u）：同键的排队作业被服务端去重合并（幂等提交防重复）：

echo "bg-job-1" | gearman -b -u uid-001 -f mail_out
gearadmin --show-unique-jobs

实测回显：

H:00097e4566a5:12       uid-001
.

优先级（-I / -L）：高/低优先级提交，配合 --priority-status 验证：

echo "high-job" | gearman -I -b -f mail_out
echo "low-job" | gearman -L -b -f mail_out
gearadmin --priority-status

实测回显：

mail_out        1       2       1       0
.

高/普通/低三条队列分别计数 1/2/1，与提交次数吻合。

行模式（-n / -N）：-n 把输入按行拆成多个作业逐行提交；-N 在 -n 基础上去掉行尾换行：

printf "line-one\nline-two\n" | gearman -n -f rev
printf "strip-me\n" | gearman -N -f rev

实测回显（-n 每行各返回一个结果；-N 的结果不带换行）：

eno-enil
owt-enil
em-pirts

输出加函数名前缀（-P）：多函数提交时区分结果来源，需配合 -n：

printf "px1\npx2\n" | gearman -n -P -f rev

实测回显：

rev: 1xp
rev: 2xp

位置参数与 -s：默认读标准输入；-s 跳过标准输入读取，配合命令行位置参数直接发数据：

gearman -b -s -f mail_out "positional-data"

实测回显（后台模式无输出，--status 可见作业入队）：

mail_out        4       0       0
.

多函数提交：-f 重复多次时，同一份数据向每个函数各提交一次，client 收到多个结果：

gearman -w -f multi_a rev &
gearman -w -f multi_b rev &
sleep 1
echo "multi-data" | gearman -f multi_a -f multi_b

实测回显（两个 worker 各处理一份，client 收到两份结果）：

atad-itlum
atad-itlum

诊断输出（-v）：client 侧打印任务创建信息：

echo "verb-test" | gearman -v -f rev

实测回显：

tset-brev
Task created: H:00097e4566a5:11

6.3 ping 模式（--ping）

向服务端发 ECHO 请求做连通性探测，不需要任何 worker 在位：

gearman --ping
echo "exit=$?"
gearman --ping -v

实测回显：

exit=0
ping OK

成功时静默返回 0；-v 打印 ping OK。-t 可调整超时（毫秒，默认 2000），监控脚本常用形态：gearman --ping -h 10.0.0.1 -t 1000。

七、注意事项

短选项解析规则：gearman 用 getopt 解析，worker 执行的命令若带 - 开头参数，必须用 -- 分隔（6.1 的 wc -c 实录），否则报 Error in usage(-?)。
后台提交不回显句柄：2.2.0 的 -b 默认静默，需要句柄做后续 --cancel-job 时加 -v，或用 gearadmin --show-jobs 反查。
--show-jobs 的取消语义：被取消的作业仍占一行（忽略标记 1、排队标记 0），不要按行数判断有效积压，以 --status 的 job_total 减去 show-jobs 中忽略标记为 1 的行数为准；内存队列重启即全清。
--status 与 --priority-status 列数不同：前者 4 列（函数/总数/执行中/worker 数），后者 5 列（函数/高/普通/低/worker 数），巡检脚本注意区分。
2.2.0 无 --shutdown：停止服务端用 systemctl stop gearmand 或 SIGTERM。
-t 超时单位是毫秒且 client 默认 2 秒（ping 模式默认 2 秒）：长任务 client 记得调大，否则 client 先断、worker 结果无处投递。
多函数提交是「各提交一次」：-f a -f b 会产生两份作业，计费型任务注意重复执行成本。

八、常见问题

Q1：gearadmin 报 Error: Error connecting to localhost.

服务端未启动或地址不对。先 systemctl is-active gearmand 确认，远程服务器用 -h <IP> -p <端口> 指向目标；本机非默认端口用 -p 指定。

Q2：gearman -f 提交后卡住不动？

函数没有可用 worker（gearadmin --status 第 4 列为 0）。前台提交会一直等服务端派发，确认 worker 已按 6.1 起好、函数名拼写一致后再试。

Q3：Error in usage(-?) 或 Error in usage(No Functions were provided).

前者是 worker 命令参数被误当选项，加 -- 分隔（见 6.1）；后者是 client 模式没给 -f 函数名（如直接运行 gearman --help 触发），用 gearman -H 看帮助。

Q4：--cancel-job 返回 OK 但 --status 数字没降？

取消只置忽略标记，被取消作业在彻底清除前仍计入 --status 的 job_total（实测见 5.6）；以 --show-jobs 的排队标记列判断有效积压，或重启服务端清空内存队列。

Q5：后台作业的句柄忘了，怎么找？

gearadmin --show-unique-jobs 若提交时用过 -u 可按唯一键对上句柄；否则 gearadmin --show-jobs 列出全部句柄逐一核对。

九、参考链接

Gearman 官网：https://gearman.org/
管理协议与命令源码：https://github.com/gearman/gearmand（bin/gearadmin.cc、libgearman-server/text.cc）
站内相关文档：《Gearman 2.2.0 介绍与选型指南》、《Ubuntu 22.04 安装 Gearman 2.2.0 指南》、《Gearman 2.2.0 配置参数详解》