Gearman 2.2.0 配置参数详解
Gearman job server 2.2.0 全参数详解，覆盖 gearmand 命令行/配置文件参数、七种持久化队列模块、worker 与 client 侧参数，并附 sqlite/redis/HTTP 模块实测回显与生产配置模板。
Gearman 2.2.0 配置参数详解
目标：逐项讲清 Gearman job server（gearmand）2.2.0 的全部启动参数、配置文件机制、七种持久化队列模块，以及 worker/client 侧的可用配置项，全部参数说明与回显均在 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，2026-10-20 实测）
- 服务端口：4730（主服务）；文中演示用临时实例使用 4740–4750、8081
- 配置文件：/usr/local/etc/gearmand.conf（默认路径，默认不存在）
- systemd 单元：/etc/systemd/system/gearmand.service
- 相关二进制：/usr/local/sbin/gearmand、/usr/local/bin/gearadmin、/usr/local/bin/gearman
说明：为不影响主服务，本文的参数实验均以额外端口启动临时 gearmand 实例进行，实验后即清理，主服务始终运行在 4730。
二、前置条件
- 已按安装指南完成 gearmand 2.2.0 安装并可运行：
gearmand --version返回gearmand 2.2.0 - https://github.com/gearman/gearmand/issues； - 主服务运行中：
systemctl is-active gearmand返回active； gearadmin、gearman两个命令行工具在 PATH 中可用。
三、参数查看与修改方式
3.1 查看参数：gearmand --help
gearmand 的全部参数通过 gearmand --help 查看，输出即参数权威清单（含默认值）：
gearmand --help
实测回显（完整原样，注意首行 Allowed options: 在 2.2.0 中输出两遍，属程序自身行为）：
Allowed options:
Allowed options:
General options:
-b [ --backlog ] arg (=32) Number of backlog connections for
listen.
-d [ --daemon ] Daemon, detach and run in the
background.
--exceptions Enable protocol exceptions by default.
-f [ --file-descriptors ] arg Number of file descriptors to allow for
the process (total connections will be
slightly less). Default is max allowed
for user.
-h [ --help ] Print this help menu.
-j [ --job-retries ] arg (=-1) Number of attempts to run the job
before the job server removes it. This
is helpful to ensure a bad job does not
crash all available workers. Use 0 to
disable retries. Default is -1 (no
limit).
--job-handle-prefix arg Prefix used to generate a job handle
string. If not provided, the default
"H:<host_name>" is used.
--hashtable-buckets arg (=991) Number of buckets in the internal job
hash tables. The default of 991 works
well for about three million jobs in
queue. If the number of jobs in the
queue at any time will exceed three
million, use proportionally larger
values (991 * # of jobs / 3M). For
example, to accommodate 2^32 jobs, use
1733003. This will consume ~26MB of
extra memory. Gearmand cannot support
more than 2^32 jobs in queue at this
time.
--keepalive Enable keepalive on sockets.
--keepalive-idle arg (=-1) If keepalive is enabled, set the value
for TCP_KEEPIDLE for systems that
support it. A value of -1 means that
either the system does not support it
or an error occurred when trying to
retrieve the default value.
--keepalive-interval arg (=-1) If keepalive is enabled, set the value
for TCP_KEEPINTVL for systems that
support it. A value of -1 means that
either the system does not support it
or an error occurred when trying to
retrieve the default value.
--keepalive-count arg (=-1) If keepalive is enabled, set the value
for TCP_KEEPCNT for systems that
support it. A value of -1 means that
either the system does not support it
or an error occurred when trying to
retrieve the default value.
-l [ --log-file ] arg (=/usr/local/var/log/gearmand.log)
Log file to write errors and
information to. If the log-file
parameter is specified as 'stderr',
then output will go to stderr. If
'none', then no logfile will be
generated.
-L [ --listen ] arg Address the server should listen on.
Default is INADDR_ANY.
-P [ --pid-file ] arg (=/usr/local/var/gearmand.pid)
File to write process ID out to.
-r [ --protocol ] arg Load protocol module.
-R [ --round-robin ] Assign work in round-robin order per
worker connection. This is the default
behavior, and it cannot be deactivated.
This command line option does nothing
and is only supported for backwards
compatibility.
-q [ --queue-type ] arg (=builtin) Persistent queue type to use.
--config-file arg (=/usr/local/etc/gearmand.conf)
Can be specified with '@name', too
--syslog Use syslog.
--coredump Whether to create a core dump for
uncaught signals.
-t [ --threads ] arg (=4) Number of I/O threads to use, 0 means
that gearmand will try to guess the
maximum number it can use. Default=4.
-u [ --user ] arg Switch to given user after startup.
--verbose arg (=ERROR) Set verbose level (FATAL, ALERT,
CRITICAL, ERROR, WARNING, NOTICE, INFO,
DEBUG).
-V [ --version ] Display the version of gearmand and
exit.
-w [ --worker-wakeup ] arg (=0) Number of workers to wakeup for each
job received. The default is to wakeup
all available workers.
HTTP:
--http-port arg (=8080) Port to listen on.
Gear:
-p [ --port ] arg (=4730) Port the server should listen on.
--ssl Enable ssl connections.
--ssl-ca-file arg CA file.
--ssl-certificate arg SSL certificate.
--ssl-key arg SSL key for certificate.
builtin:
libsqlite3:
--libsqlite3-db arg Database file to use.
--store-queue-on-shutdown Store queue on shutdown only.
--libsqlite3-table arg (=gearman_queue)
Table to use.
Postgres:
--libpq-conninfo arg PostgreSQL connection information
string.
--libpq-table arg (=queue) Table to use.
redis:
--redis-server arg Redis server
--redis-port arg Redis server port/service
--redis-password arg Redis server password/service
--redis-prefix arg Prefix to use in redis keys
libtokyocabinet:
--libtokyocabinet-file arg File name of the database. [see: man
tcadb, tcadbopen() for name guidelines]
--libtokyocabinet-optimize Optimize database on open.
[default=true]
MySQL:
--mysql-host arg (=localhost) MySQL host.
--mysql-port arg (=3306) Port of server. (by default 3306)
--mysql-user arg MySQL user.
--mysql-password arg MySQL user password.
--mysql-db arg MySQL database.
--mysql-table arg (=gearman_queue) MySQL table name.
要点：builtin 分组下没有任何参数，表示默认内存队列无需配置；其余六个分组（libsqlite3、Postgres、redis、libtokyocabinet、MySQL、HTTP）都是可加载模块，各自的专属参数只在模块被选中时生效。
3.2 配置文件机制（重点，含行为陷阱）
gearmand 支持两种等效的参数传递方式：命令行参数与配置文件。配置文件机制有以下四条实测行为，逐条给出验证过程。
行为一：配置文件内容是「命令行风格」的 token，不是 ini 风格。
gearmand 读入配置文件后，按空白（空格/换行）切分 token，再当作命令行参数重新解析（源码 gearmand/gearmand.cc 中使用 boost tokenizer 切分后走 command_line_parser）。因此每行必须写成 --参数=值 形式。
实测：创建 /etc/gearmand-c1.conf，写 ini 风格的 port=4740：
printf "port=4740\nverbose=DEBUG\n" > /etc/gearmand-c1.conf
cat /etc/gearmand-c1.conf
gearmand --config-file=/etc/gearmand-c1.conf --log-file=stderr
实测回显（实例并未监听 4740，而是按默认值去绑 4730，因主服务占用而超时）：
port=4740
verbose=DEBUG
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
⚠️ 注意：ini 风格的
port=4740被当作未知位置参数静默忽略，不报任何配置错误，服务直接回落到默认端口——这是极易踩中的陷阱。
改为命令行风格后同样的文件立即生效：
printf -- "--port=4740\n--verbose=DEBUG\n" > /etc/gearmand-c1.conf
cat /etc/gearmand-c1.conf
gearmand --config-file=/etc/gearmand-c1.conf --pid-file=/tmp/gm4740.pid --log-file=/tmp/gm4740.log --daemon
sleep 1
ss -ltn | grep 4740
gearadmin -p 4740 --server-verbose
实测回显：
--port=4740
--verbose=DEBUG
LISTEN 0 32 0.0.0.0:4740 0.0.0.0:*
LISTEN 0 32 [::]:4740 [::]:*
DEBUG
端口与日志级别均来自配置文件，gearadmin --server-verbose 返回 DEBUG 证明 verbose 配置生效。
行为二：显式指定 --config-file 且文件不存在时，直接报错退出。
gearmand --config-file=/etc/not-exist.conf --log-file=stderr
实测回显：
gearmand: Could not open configuration file.
行为三：默认路径 /usr/local/etc/gearmand.conf 存在时，即使不传 --config-file 也会自动加载。
printf -- "--port=4750\n" > /usr/local/etc/gearmand.conf
gearmand --pid-file=/tmp/gm4750.pid --log-file=/tmp/gm4750.log --daemon
sleep 1
ss -ltn | grep 4750
rm -f /usr/local/etc/gearmand.conf
kill $(cat /tmp/gm4750.pid)
实测回显：
LISTEN 0 32 0.0.0.0:4750 0.0.0.0:*
LISTEN 0 32 [::]:4750 [::]:*
未传任何端口参数的实例绑定到了 4750，证明默认路径配置文件被自动读取。实验后已删除该文件并停止临时实例。
💡 说明：
--config-file帮助文本中的「Can be specified with '@name', too」指命令行上可用gearmand '@/etc/gearmand-c1.conf'的写法加载配置文件，效果与--config-file=等价。
行为四：命令行参数优先级高于配置文件（后者先解析、命令行后解析覆盖）。
配置文件先于命令行解析，同一参数在两处都出现时以命令行为准。生产实践中建议「公共参数进配置文件，实例差异走命令行」。
3.3 通过 systemd 修改参数
源码方案的服务参数写在 systemd 单元的 ExecStart 行中（安装指南 5.7 的单元文件），修改流程固定为三步：
vim /etc/systemd/system/gearmand.service
systemctl daemon-reload
systemctl restart gearmand
⚠️ 注意：修改
ExecStart后必须执行systemctl daemon-reload，否则改动不生效；systemctl restart后用systemctl status gearmand核对新参数已出现在主进程命令行中。
apt 方案（1.1.19.1）则修改 /etc/default/gearman-job-server 中的 PARAMS 变量后重启 gearman-job-server 服务，无需 daemon-reload。
四、参数总览
4.1 通用参数（General）
| 参数（短/长） | 默认值 | 说明 |
|---|---|---|
-b / --backlog | 32 | 监听 socket 的积压连接数 |
-d / --daemon | 关闭 | 自守护模式，后台运行 |
--exceptions | 关闭 | 默认启用协议异常通知 |
-f / --file-descriptors | 用户上限 | 进程可打开的文件描述符数量（连接数上限略小于此值） |
-h / --help | — | 打印帮助 |
-j / --job-retries | -1（不限制） | 作业在服务端的最大重试次数，0 表示禁止重试 |
--job-handle-prefix | H:<主机名> | 作业句柄前缀 |
--hashtable-buckets | 991 | 内部作业哈希桶数量，支撑约 300 万排队作业 |
--keepalive | 关闭 | socket 启用 TCP keepalive |
--keepalive-idle | -1（系统默认） | TCP_KEEPIDLE 秒数 |
--keepalive-interval | -1（系统默认） | TCP_KEEPINTVL 秒数 |
--keepalive-count | -1（系统默认） | TCP_KEEPCNT 次数 |
-l / --log-file | /usr/local/var/log/gearmand.log | 日志文件；stderr 输出到标准错误；none 不写日志 |
-L / --listen | INADDR_ANY | 监听地址 |
-P / --pid-file | /usr/local/var/gearmand.pid | PID 文件路径 |
-r / --protocol | — | 加载协议模块（如 http） |
-R / --round-robin | 开启（不可关闭） | 同一 worker 连接内按轮转派发；仅为兼容保留的无效开关 |
-q / --queue-type | builtin | 持久化队列类型 |
--config-file | /usr/local/etc/gearmand.conf | 配置文件路径 |
--syslog | 关闭 | 日志走 syslog |
--coredump | 关闭 | 未捕获信号时生成 core dump |
-t / --threads | 4 | I/O 线程数，0 表示自动猜测 |
-u / --user | — | 启动后切换到该用户（降权） |
--verbose | ERROR | 日志级别：FATAL/ALERT/CRITICAL/ERROR/WARNING/NOTICE/INFO/DEBUG |
-V / --version | — | 显示版本并退出 |
-w / --worker-wakeup | 0（唤醒全部） | 每收到一个作业时唤醒的 worker 数量 |
4.2 Gear 协议与 SSL 参数
| 参数 | 默认值 | 说明 |
|---|---|---|
-p / --port | 4730 | Gear 协议监听端口 |
--ssl | 关闭 | 启用 SSL 连接（需编译时开启 SSL 支持） |
--ssl-ca-file | — | CA 证书文件 |
--ssl-certificate | — | 服务端证书 |
--ssl-key | — | 证书私钥 |
4.3 HTTP 协议参数
| 参数 | 默认值 | 说明 |
|---|---|---|
--http-port | 8080 | HTTP 协议模块监听端口（配合 -r http 使用） |
4.4 持久化队列模块参数
| 模块（--queue-type 值） | 专属参数 | 说明 |
|---|---|---|
| builtin（默认） | 无 | 内存队列，服务重启队列丢失 |
| libsqlite3 | --libsqlite3-db、--store-queue-on-shutdown、--libsqlite3-table(=gearman_queue) | SQLite 文件队列 |
| Postgres | --libpq-conninfo、--libpq-table(=queue) | PostgreSQL 队列 |
| redis | --redis-server、--redis-port、--redis-password、--redis-prefix | Redis 队列 |
| libtokyocabinet | --libtokyocabinet-file、--libtokyocabinet-optimize(=true) | Tokyo Cabinet 文件队列 |
| MySQL | --mysql-host(=localhost)、--mysql-port(=3306)、--mysql-user、--mysql-password、--mysql-db、--mysql-table(=gearman_queue) | MySQL 队列 |
💡 技术拓展：持久化队列类型不止一种，选型横向对比——
队列类型 原理/特点 适用场景 builtin（默认） 纯内存，重启即丢 允许丢作业的纯加速型任务 libsqlite3 单文件嵌入式库，零外部依赖 单机持久化，中小规模 redis 外部 Redis 服务，读写快、可独立扩容 已有 Redis 基础设施、高吞吐 MySQL / Postgres 复用现有数据库，便于审计 已有 DBA 体系、需与业务数据同库管理 libtokyocabinet 本地 KV 文件库 单机大容量文件队列 本文实测选用 libsqlite3（零依赖演示）与 redis（生产常用）两种，理由：二者可在单机完整闭环验证且覆盖「文件队列」与「外部存储」两类形态。
五、核心参数分类详解
5.1 网络监听参数
监听端口 -p：Gear 协议端口，默认 4730。实测改为 4740 后监听随之变化（见 3.2 行为一的正例回显，LISTEN 0 32 0.0.0.0:4740）。
监听地址 -L：默认 INADDR_ANY（所有网卡）。只允许本机访问时改为 -L 127.0.0.1，实测（apt 包默认参数即含 --listen=localhost）：
ss -ltn | grep 4730
实测回显：
LISTEN 0 32 127.0.0.1:4730 0.0.0.0:*
LISTEN 0 32 [::1]:4730 [::]:*
积压队列 -b：listen backlog，默认 32。高并发 worker 瞬时重连的场景（如批量重启 worker 集群）建议调大到 128–512。
文件描述符 -f：进程级 fd 上限。Gearman 每个连接占一个 fd，生产环境若 worker 数量多，除 -f 外还需同步放大 systemd 的 LimitNOFILE（安装指南 5.7 单元中已设 65536）。
I/O 线程 -t：默认 4。实测启动 DEBUG 日志可确认线程数生效：
DEBUG 2026-10-20 03:06:45.891023 [ main ] THREADS: 4 -> libgearman-server/gearmand.cc:272
TCP keepalive 三参数：--keepalive 打开开关后，--keepalive-idle/--keepalive-interval/--keepalive-count 分别对应 TCP_KEEPIDLE/TCP_KEEPINTVL/TCP_KEEPCNT；值为 -1 时沿用系统默认。适合worker 经 NAT/防火墙接入、空闲连接易被掐断的场景。
5.2 进程与日志参数
自守护 -d：配合 -P 写 PID 文件。实测（临时实例）：
gearmand -p 4741 --pid-file=/tmp/gm4741.pid --log-file=/tmp/gm4741.log --daemon
cat /tmp/gm4741.pid
实测回显：
40652
日志文件 -l：三种取值——普通路径（写文件）、stderr（标准错误，systemd 场景由 journald 收集）、none（不写）。默认路径 /usr/local/var/log/gearmand.log 所在目录默认不存在，不显式指定时会尝试回退 stderr 并告警：
gearmand: Could not open log file "/usr/local/var/log/gearmand.log", from "/", switching to stderr. (No such file or directory)
日志级别 --verbose：默认 ERROR。可用级别 FATAL、ALERT、CRITICAL、ERROR、WARNING、NOTICE、INFO、DEBUG。实测 DEBUG 级别下的启动日志（比 INFO 多出线程等细节）：
DEBUG 2026-10-20 03:06:45.891023 [ main ] THREADS: 4 -> libgearman-server/gearmand.cc:272
INFO 2026-10-20 03:06:45.891061 [ main ] Initializing Gear on port 4740 with SSL: false
降权运行 -u：以 root 启动后切换到指定用户。systemd 场景下更推荐直接在单元里用 User=（见安装指南 5.7）。
core dump --coredump：排查服务端异常崩溃时打开，崩溃后在工作目录生成 core 文件供 gdb 分析。
5.3 队列持久化参数
默认内存队列 builtin：不传 -q 即为 builtin，作业仅存内存。--status 正常应答、重启后队列清空，适合可容忍重跑的任务。
SQLite 队列（libsqlite3）实测全流程：
mkdir -p /var/lib/gearmand-queue
rm -f /var/lib/gearmand-queue/queue.db
gearmand -p 4741 -q libsqlite3 --libsqlite3-db=/var/lib/gearmand-queue/queue.db --pid-file=/tmp/gm4741.pid --log-file=/tmp/gm4741.log --daemon
sleep 1
ss -ltn | grep 4741
实测回显：
LISTEN 0 32 0.0.0.0:4741 0.0.0.0:*
LISTEN 0 32 [::]:4741 [::]:*
提交一个后台作业（无 worker 消费，滞留队列）：
echo "persist-hello-001" | gearman -h 127.0.0.1 -p 4741 -f persist_test -b
gearadmin -h 127.0.0.1 -p 4741 --status
gearadmin -h 127.0.0.1 -p 4741 --show-jobs
实测回显：
persist_test 1 0 0
.
H:00097e4566a5:1 0 0 1
.
停服、确认落盘、重启、复查队列：
kill -TERM $(cat /tmp/gm4741.pid)
sleep 2
ls -la /var/lib/gearmand-queue/
gearmand -p 4741 -q libsqlite3 --libsqlite3-db=/var/lib/gearmand-queue/queue.db --pid-file=/tmp/gm4741.pid --log-file=/tmp/gm4741.log --daemon
sleep 1
gearadmin -h 127.0.0.1 -p 4741 --status
gearadmin -h 127.0.0.1 -p 4741 --show-jobs
实测回显：
total 24
drwxr-xr-x 2 root root 4096 Oct 20 03:07 .
drwxr-xr-x 1 root root 4096 Oct 20 03:07 ..
-rw-r--r-- 1 root root 12288 Oct 20 03:07 queue.db
persist_test 1 0 0
.
H:00097e4566a5:1 0 0 1
.
服务重启后队列中的 persist_test 作业原样恢复，持久化生效。参数补充说明：--store-queue-on-shutdown 表示仅在关机时写盘（平时驻内存，性能更好但崩溃丢数据）；--libsqlite3-table 默认表名 gearman_queue。
Redis 队列实测全流程：
redis-cli ping
gearmand -p 4744 -q redis --redis-server=127.0.0.1 --redis-port=6379 --pid-file=/tmp/gm4744.pid --log-file=/tmp/gm4744.log --daemon
sleep 1
echo "redis-job-data" | gearman -h 127.0.0.1 -p 4744 -f redis_test -b
gearadmin -h 127.0.0.1 -p 4744 --show-jobs
实测回显：
PONG
H:00097e4566a5:1 0 0 1
.
作业确实写入了 Redis（键名为 _gear_-<函数名>-<uuid> 的 hash）：
redis-cli keys "*"
redis-cli type "_gear_-redis_test-02ea649c-cc34-11f1-bf67-da8c9f1cdb6e"
redis-cli hgetall "_gear_-redis_test-02ea649c-cc34-11f1-bf67-da8c9f1cdb6e"
实测回显：
_gear_-redis_test-02ea649c-cc34-11f1-bf67-da8c9f1cdb6e
hash
data
redis-job-data
priority
1
function
redis_test
unique
02ea649c-cc34-11f1-bf67-da8c9f1cdb6e
hash 字段包括 data（作业数据）、priority（优先级编号）、function（函数名）、unique（唯一键）。同样验证重启恢复：
kill -TERM $(cat /tmp/gm4744.pid)
sleep 2
gearmand -p 4744 -q redis --redis-server=127.0.0.1 --redis-port=6379 --pid-file=/tmp/gm4744.pid --log-file=/tmp/gm4744.log --daemon
sleep 1
gearadmin -h 127.0.0.1 -p 4744 --status
实测回显：
redis_test 1 0 0
.
--redis-password 在 Redis 开启 requirepass 时必填；--redis-prefix 可自定义键前缀（默认 _gear_-），多套 Gearman 集群共用一个 Redis 时用前缀隔离。
PostgreSQL / MySQL / Tokyo Cabinet 队列：参数已在 4.4 表中列出，配置模式与上述一致——-q 选模块、模块参数给连接信息。PostgreSQL 用 --libpq-conninfo "host=10.0.0.1 dbname=gearman user=gearman" 标准连接串；MySQL 需先建库建表（表结构由模块自动创建）； Tokyo Cabinet 用 --libtokyocabinet-file 指定数据库文件。三者连接信息错误时启动即失败并在日志报连接错误，不会静默降级到内存队列。
5.4 作业调度参数
重试次数 -j / --job-retries：worker 执行失败（超时/断连）后服务端重新入队的次数，默认 -1（不限制）。坏作业会反复重试，建议显式设为 2–5 次并让 worker 侧记录失败原因；设 0 表示不重试。
worker 唤醒 -w / --worker-wakeup：每收到一个作业时唤醒多少个休眠 worker，默认 0 表示唤醒全部可用 worker。大量空闲 worker 轮询的场景下，设为 1 可减少无效唤醒（惊群），轻微提升吞吐。
作业句柄前缀 --job-handle-prefix：默认句柄为 H:<主机名>:<序号>。实测自定义前缀：
gearmand -p 4742 --job-handle-prefix=PROD-H --pid-file=/tmp/gm4742.pid --log-file=/tmp/gm4742.log --daemon
sleep 1
echo "prefix-job-data" | gearman -h 127.0.0.1 -p 4742 -f prefix_test -b
gearadmin -h 127.0.0.1 -p 4742 --show-jobs
实测回显：
PROD-H:1 0 0 1
.
句柄变为 PROD-H:1。多套环境共用日志检索时，前缀可快速区分作业来源环境。
哈希桶 --hashtable-buckets：内部作业哈希表桶数，默认 991 约支撑 300 万排队作业；排队量长期超过 300 万时按官方帮助给的公式放大（991 × 作业数 / 300万，如支撑 2^32 作业需 1733003，额外消耗约 26MB 内存）。
5.5 协议与扩展参数
HTTP 协议模块 -r http：让 gearmand 同时提供 HTTP 接口，--http-port 指定端口（默认 8080）。实测（worker 用 rev 命令处理 http_test 函数）：
gearmand -p 4743 -r http --http-port=8081 --pid-file=/tmp/gm4743.pid --log-file=/tmp/gm4743.log --daemon
sleep 1
nohup gearman -h 127.0.0.1 -p 4743 -w -f http_test rev > /tmp/http_worker.out 2>&1 &
sleep 1
curl -s -i -X POST --data "hello-from-http" http://127.0.0.1:8081/http_test
实测回显：
HTTP/1.1 200 OK
X-Gearman-Job-Handle: H:00097e4566a5:2
X-Gearman-Command: WORK_COMPLETE
Content-Length: 15
Server: Gearman/2.2.0
Connection: close
ptth-morf-olleh
POST 的 URL 路径即函数名，请求体即作业数据，响应头 X-Gearman-Job-Handle 返回句柄，响应体是 worker 的处理结果（hello-from-http 被反转）。HTTP 模块的 POST 是同步语义：无 worker 时请求会一直等待，浏览器直接访问会挂起，务必确认 worker 在位。非任务语言的系统（如纯 PHP 页面触发任务）可借此免装客户端库。
协议异常 --exceptions：默认情况下 worker 抛出的异常（WORK_EXCEPTION）不主动通知 client，该开关让服务端默认下发异常通知。
SSL 参数组：--ssl 开启后 worker/client 需同样带 -S 连接；证书链用 --ssl-ca-file/--ssl-certificate/--ssl-key 指定。注意 2.2.0 编译时需开启 SSL 支持（configure 摘要 SSL enabled: no 时该参数无效，见安装指南 5.4）。
轮转派发 -R：2.2.0 中该开关为空操作——同一 worker 连接内的轮转派发已是默认且唯一行为，保留参数仅为向后兼容。
六、worker 与 client 侧参数
gearmand 自带的 gearman 命令行工具可充当临时 worker/client（C 客户端库 libgearman 的程序化参数不在此展开）。其参数分三组，gearman -H 可随时查看：
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)
⚠️ 注意：
-t超时默认仅 2000 毫秒（ping 模式下默认值）；长任务 client 侧应调大-t，否则任务尚未完成 client 即断开。-f可重复多次（client 提交到多个函数、worker 同时注册多个函数）。
逐项要点：
-h/-p：服务端地址与端口，client/worker/gearadmin 三类工具语义一致，多机部署时 worker 与 client 都需指向 job server 的内网地址；-b：后台作业，client 提交即返回不等待结果；-I/-L：高/低优先级，配合服务端--priority-status可验证三条优先级队列的分布；-u：唯一键，同键作业在队列中会被去重合并，幂等任务去重的关键参数；-c：worker 处理满 N 个作业后退出，配合进程管理器做 worker 定期重启（规避内存泄漏）；-i：为 worker 进程写 PID 文件，便于脚本化管理。
以上参数的逐条实测回显与使用示例见 《Gearman 2.2.0 常用 CLI 命令详解》。
七、生产配置模板
适用场景：4 核 8GB 内存、NVMe 磁盘、日均百万级异步任务、worker 与 client 混布内网的中小规模部署。
配置文件 /usr/local/etc/gearmand.conf（命令行风格）：
--port=4730
--listen=0.0.0.0
--queue-type=redis
--redis-server=127.0.0.1
--redis-port=6379
--threads=4
--backlog=128
--job-retries=3
--worker-wakeup=1
--verbose=NOTICE
--log-file=/var/log/gearmand/gearmand.log
--pid-file=/run/gearmand/gearmand.pid
--keepalive
systemd 单元相应简化（参数已迁移到配置文件）：
[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
Restart=on-failure
RestartSec=5
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
逐项说明：
--queue-type=redis：作业落 Redis，服务重启不丢队列（本文 5.3 已实测恢复）；队列键独立于业务键，Redis 侧为该实例分配独立 DB 或用--redis-prefix隔离；--job-retries=3：失败作业最多重试 3 次，防止坏作业无限重跑；--worker-wakeup=1：逐个唤醒 worker，避免惊群；--backlog=128：worker 批量重连时减少连接被拒；--verbose=NOTICE：生产平衡可观测与日志量；排障期临时调到 DEBUG；--keepalive：内网长连接保活，参数细节沿用系统默认。
重启并验证生效：
systemctl daemon-reload
systemctl restart gearmand
systemctl is-active gearmand
gearadmin --server-verbose
实测回显（以本文实验环境等价配置验证）：
active
NOTICE
八、常见问题
Q1：配置文件写了参数却不生效？
配置文件必须是命令行风格（--port=4730），ini 风格（port=4730）会被静默忽略（实测证据见 3.2 行为一）。另外确认没有同名参数同时出现在命令行上——命令行优先。
Q2：没配任何东西，端口却变了？
检查默认路径 /usr/local/etc/gearmand.conf 是否存在：该文件存在就会被自动加载（实测见 3.2 行为三）。这是升级排查「参数莫名变化」的第一现场。
Q3：启动报 Could not open configuration file.
显式 --config-file 指向了不存在的文件。核对路径；默认路径文件不存在则不会报错。
Q4：日志文件写不进去？
运行账号对日志目录无写权限。建目录并 chown 给运行账号（安装指南 5.6），或 --log-file=stderr 交给 journald。
Q5：HTTP 端口请求一直挂起？
HTTP 模块的 POST 是同步等待 worker 结果的语义，无 worker 时请求不会超时返回。先 gearadmin --status 确认函数有可用 worker（第三列大于 0）。
Q6：重启后队列丢了？
未配置持久化队列（默认 builtin 内存队列）。按 5.3 选型并配置 sqlite/redis/MySQL 等队列类型后重启生效；迁移已有 builtin 队列无平滑路径，需停写窗口期让 worker 消化存量作业。
九、参考链接
- Gearman 官网：https://gearman.org/
- 服务端文档：https://gearman.org/gearmand/
- 源码仓库：https://github.com/gearman/gearmand
- 2.2.0 参数权威来源：
gearmand --help（本文 3.1 完整实录） - 站内相关文档：《Gearman 2.2.0 介绍与选型指南》、《Ubuntu 22.04 安装 Gearman 2.2.0 指南》、《Gearman 2.2.0 常用 CLI 命令详解》