Apache Pegasus 2.5.0 Shell 命令与运维详解
Apache Pegasus 2.5.0 Shell 命令与运维详解：pegasus-shell 连接方式、表管理（create/ls/drop/use）、数据读写实测（set/get/multi_get 族/scan/count/TTL/incr）、节点与集群观测（nodes/app/server_info/server_stat/remote_command）、HTTP REST 接口与监控接入
Apache Pegasus 2.5.0 Shell 命令与运维详解
目标：系统整理 pegasus-shell 的连接方式、命令分组、数据模型语义与集群观测手段，并覆盖 HTTP REST 接口、Prometheus 监控接入、数据目录与配置文件位置。全部命令与回显取自 Apache Pegasus 2.5.0 实测环境（onebox 集群：3 meta + 3 replica + 1 collector + 本地 ZooKeeper，所有节点 ALIVE），逐条真实记录。
一、环境信息
| 项目 | 值 |
|---|---|
| 版本 | Pegasus Shell 2.5.0 / Pegasus Server 2.5.0 |
| 集群形态 | onebox：3 meta（34601-34603）+ 3 replica（34801-34803）+ 1 collector（34101）+ 本地 ZooKeeper（22181） |
| 集群节点状态 | total_node_count: 3 / alive_node_count: 3 / unalive_node_count: 0 |
| shell 可执行文件 | /pegasus-src/build/release/output/bin/pegasus_shell/pegasus_shell（源码编译产物） |
| 推荐入口 | /pegasus-src/run.sh（子命令 shell，自动生成临时配置） |
| 官方命令文档 | https://pegasus.apache.org/zh/docs/tools/shell/（官方注明「本文档基于 2.5.0 版本」，实测 HTTP 200） |
二、Shell 连接方式
本节给出三种实测可用的连接方式：推荐日常用 run.sh 交互式，脚本化用管道驱动，直连二进制用于脱离 run.sh 的场景。三种方式最终都是执行同一个 pegasus_shell 二进制。
2.1 方式一（推荐）：run.sh shell 交互式
cd /pegasus-src
./run.sh shell
实测输出（进入交互界面）：
Pegasus Shell 2.5.0
Type "help" for more information.
Type "Ctrl-D" or "Ctrl-C" to exit the shell.
The config file is: /pegasus-src/config-shell.ini.130891
The cluster name is: onebox
The cluster meta list is: 127.0.0.1:34601,127.0.0.1:34602,127.0.0.1:34603
run.sh shell 的实现细节（读 run.sh 源码确认）：用 sed 把 src/shell/config.ini 模板中的 @CLUSTER_NAME@、@CLUSTER_ADDRESS@ 替换为 onebox 集群信息，生成临时配置 config-shell.ini.$PID，再软链并执行 ./pegasus_shell config-shell.ini.$PID onebox。因此它默认只连本机 onebox 集群。
2.2 方式二：管道驱动（脚本化）
把命令逐行写进 stdin，shell 逐条执行，EOF 自动退出：
cd /pegasus-src
echo 'nodes' | ./run.sh shell
实测退出行：
dsn exit with code 0
⚠️ 注意：管道模式下没有交互确认流程——
drop t1会直接执行、不询问 yes（实测见 4.5）；TTY 交互模式下 drop 才进入确认。脚本化删表请自行保证命令正确性。
2.3 方式三：直接调用 pegasus_shell 二进制
不经 run.sh，手工生成配置并指定库路径后直接调用（实测可行）：
cd /pegasus-src
sed 's/@CLUSTER_NAME@/onebox/g;s/@CLUSTER_ADDRESS@/127.0.0.1:34601,127.0.0.1:34602,127.0.0.1:34603/g' \
src/shell/config.ini > /tmp/config-shell.ini
export LD_LIBRARY_PATH=/pegasus-src/build/release/output/lib:/pegasus-src/thirdparty/output/lib:$LD_LIBRARY_PATH
ln -sf build/release/output/bin/pegasus_shell/pegasus_shell
echo 'nodes' | ./pegasus_shell /tmp/config-shell.ini onebox
实测输出：
[details]
address status
127.0.0.1:34801 ALIVE
127.0.0.1:34802 ALIVE
127.0.0.1:34803 ALIVE
[summary]
total_node_count : 3
alive_node_count : 3
unalive_node_count : 0
dsn exit with code 0
语法要点：2.5.0 的 pegasus_shell 参数是 <config_file> [cluster_name]，不是 -h <ip> -p <port> 风格。连接其他集群：用 run.sh shell 的 --cluster <ip:port,...> 指定 meta 地址列表，或 -c 指定配置文件（run.sh shell 子命令支持，实测用法）。
三、命令分组速查
进入 shell 后执行 help 可列出全部命令。实测回显（节选头部，完整 usage 与官方 Shell 文档一致）：
Usage:
help
version
cluster_info [-r|--resolve_ip] [-o|--output file_name] [-j|--json]
app <app_name> [-d|--detailed] [-r|--resolve_ip] [-o|--output file_name] [-j|--json]
app_disk <app_name> [-d|--detailed] [-r|--resolve_ip] [-j|--json] [-o|--output file_name]
ls [-a|-all] [-d|--detailed] [-j|--json]
[-o|--output file_name][-s|--status all|available|creating|dropping|dropped]
nodes [-d|--detailed] [-j|--json] [-r|--resolve_ip] [-u|--resource_usage][-o|--output file_name]
[-s|--status all|alive|unalive] [-q|--qps]
create <app_name> [-p|--partition_count num] [-r|--replica_count num]
[-f|--fail_if_exist] [-e|--envs k1=v1,k2=v2...]
drop <app_name> [-r|--reserve_seconds num]
recall <app_id> [new_app_name]
rename <old_app_name> <new_app_name>
use [app_name]
set <hash_key> <sort_key> <value> [ttl_in_seconds]
get <hash_key> <sort_key>
del <hash_key> <sort_key>
exist <hash_key> <sort_key>
count <hash_key>
...（multi_set/multi_get/multi_get_range/multi_get_sortkeys/multi_del/multi_del_range/
incr/check_and_set/check_and_mutate/ttl/hash_scan/full_scan/copy_data/clear_data/
count_data/remote_command/server_info/server_stat/app_stat/flush_log/...）
按用途分组（命令与参数均取自上方实测 usage）：
| 分组 | 命令 | 用途 |
|---|---|---|
| 表管理 | create / drop / recall / rename / ls / use / app / app_disk | 建删表、恢复软删除表、重命名、查看表列表与详情、切换当前表 |
| 数据读写 | set / get / del / exist / count / multi_set / multi_get / multi_get_range / multi_get_sortkeys / multi_del / multi_del_range / incr / check_and_set / check_and_mutate / ttl / hash_scan / full_scan | 组合键的读写删、原子计数、条件写、TTL、扫描 |
| 集群观测 | nodes / cluster_info / app_stat / server_info / server_stat | 节点与表级统计、服务端版本信息与指标 |
| 服务端控制 | remote_command / flush_log | 向服务端下发远程命令（如刷日志）、刷写 commit log |
四、表管理命令详解
4.1 ls：查看表列表
onebox 初始状态（collector 自动建的 stat 表 + 默认 temp 表）：
> ls
[general_info]
app_id status app_name app_type partition_count replica_count is_stateful create_time drop_time drop_expire envs_count
1 AVAILABLE stat pegasus 4 3 true 2026-10-14_17:41:42 - - 0
2 AVAILABLE temp pegasus 8 3 true 2026-10-14_17:41:42 - - 0
[summary]
total_app_count : 2
ls -a 可连软删除（DROPPED）状态一并显示；-s 按 status 过滤，-d 显示详情，-j 输出 JSON。
4.2 create：建表
> create t1 -r 3
实测输出（默认 4 分区，3 副本同步建满 4 分区×3 副本，约 16 秒）：
create app t1 succeed, waiting for app ready
t1 not ready yet, still waiting... (0/4)
t1 not ready yet, still waiting... (0/4)
t1 is ready now: (4/4)
t1 is ready now!
create app "t1" succeed
再次 ls 复核：
3 AVAILABLE t1 pegasus 4 3 true 2026-10-14_17:43:16 - - 0
💡 说明：未指定
-p时默认 partition_count=4（实测 ls 佐证）。-f可让表已存在时报错而非复用；-e可建表时携带表级环境变量（如k1=v1,k2=v2，对应 ls 的 envs_count）。
4.3 use：切换当前表
Pegasus 的数据命令不携带表名，必须先 use <app> 切换：
> use t1
OK
若把表名当第一个参数传入数据命令，shell 会把 t1 当 hash_key、末参当 ttl 解析而报错（实测）：
> set t1 hkey sortkey value ← 错误用法实测
ERROR: parse value as ttl failed
USAGE: set <hash_key> <sort_key> <value> [ttl_in_seconds]
4.4 app：查看单表信息
> app t1
实测输出：
[parameters]
app_name : t1
detailed : false
[general]
app_name : t1
app_id : 3
partition_count : 4
max_replica_count : 3
4.5 drop：删表（软删除）
管道模式实测（无确认、直接执行）：
> drop t1
reserve_seconds = 0
drop app t1 succeed
⚠️ TTY 交互习惯下删完顺手敲
yes会报错（实测）：ERROR: invalid subcommand 'yes'并打印 usage——drop 的确认流程只在交互 TTY 下出现，管道模式下命令即执行。
ls -a 复核软删除状态（DROPPED，7 天后过期清理，drop_expire 即清理时间点）：
3 DROPPED t1 pegasus 4 3 true 2026-10-14_17:43:16 2026-10-14_17:45:11 2026-10-21_17:45:11 0
7 天内可用 recall <app_id>（usage 见第三节）按 app_id 恢复；drop 的 -r 参数可指定保留秒数。
五、数据读写命令详解
以下命令均在 use t1 后执行（app_id=3，实测主副本分布：hash_key=hkey 落在 partition 2，primary=127.0.0.1:34801）。
5.1 set / get：单键写读
> set hkey sortkey value
OK
app_id : 3
partition_index : 2
decree : 5
server : 127.0.0.1:34801
> get hkey sortkey
app_id : 3
partition_index : 2
decree : 5
server : 127.0.0.1:34801
"value"
回显中的 decree 是该分片内单调递增的写版本号，每次成功写操作加一，可用于粗看写入量。set 的第四个参数为可选 TTL 秒数（见 5.5）。
5.2 exist / count：存在性与行内计数
> exist hkey sortkey
app_id : 3
partition_index : 2
server : 127.0.0.1:34801
True
> count hkey
app_id : 3
partition_index : 2
server : 127.0.0.1:34801
1
count 统计同一 hash_key 下的 sort_key 条数。
5.3 multi_get / multi_get_sortkeys：整行批量读
先补两条数据（实测 decree 依次 6、7）：
> set hkey sk2 v2
OK (decree : 6)
> set hkey sk3 v3
OK (decree : 7)
读取同一 hash_key 的全部键值与全部 sort_key：
> multi_get hkey
"hkey" : "sk2" => "v2"
"hkey" : "sk3" => "v3"
"hkey" : "sortkey" => "value"
3 key-value pairs got, fetch completed.
> multi_get_sortkeys hkey
"sk2"
"sk3"
"sortkey"
3 sort keys got, fetch completed.
> count hkey
3
multi_get 族仅带 hash_key 即读整行；multi_get_range/multi_del_range 等变体支持 SortKey 区间（usage 见第三节）。
5.4 incr：原子计数
> incr hkey cnt 5
OK
5 (decree : 9)
> incr hkey cnt
6 (decree : 10)
incr 对目标键做原子自增（带初始值 5 时，键不存在则先置 5），再次不带增量默认加 1。属官方《单行原子操作》能力范畴。
5.5 ttl：数据存活时间
> ttl hkey sortkey
Infinite
未设置 TTL 的数据返回 Infinite；set 时传第四参数即按秒设置 TTL（usage：set <hash_key> <sort_key> <value> [ttl_in_seconds]）。TTL 语义详见官方文档《用户接口/TTL》。
5.6 hash_scan：单 hash_key 范围扫描
> hash_scan hkey "" zz
hash_key: "hkey"
start_sort_key: ""
start_inclusive: true
stop_sort_key: "zz"
stop_inclusive: false
sort_key_filter_type: no_filter
value_filter_type: no_filter
max_count: -1
timout_ms: 5000
detailed: false
no_value: false
"hkey" : "cnt" => "6"
"hkey" : "sk2" => "v2"
"hkey" : "sk3" => "v3"
"hkey" : "sortkey" => "value"
4 key-value pairs got.
参数回显逐字保留 shell 原样拼写（timout_ms 为 2.5.0 原始输出，非本文笔误）。语义：扫描同一 hash_key 下 start_sort_key（含）到 stop_sort_key（不含）之间的数据——注意 stop 边界是开区间（stop_inclusive: false，实测 "zz" 本身未包含在结果里）。
5.7 full_scan：全表扫描
> full_scan
partition: all
hash_key_filter_type: no_filter
...（参数回显同上）
"hkey" : "cnt" => "6"
"hkey" : "sk2" => "v2"
"hkey" : "sk3" => "v3"
"hkey" : "sortkey" => "value"
4 key-value pairs got.
5.8 del：单键删除
> del hkey sk2
OK (decree : 11)
> get hkey sk2
Not found
> count hkey
3
💡 技术拓展：multi_get / hash_scan / full_scan 的适用差异——
命令 读取范围 代价与适用 multi_get（族） 单 hash_key 整行（全部或指定 SortKey） 单分片点读，代价最小，业务主路径 hash_scan 单 hash_key 的 SortKey 区间 单分片区间扫，适合行内列遍历；哈希路由决定其无法跨 hash_key full_scan 整表所有分区 跨全部分片顺序扫，大表代价高，仅用于运维导出/核对，勿在线上高峰随意执行 选型原则：能用 multi_get 不用 hash_scan，能限定 SortKey 区间就不做整行，full_scan 只在可控窗口进行。
六、集群观测命令详解
6.1 nodes：节点状态
> nodes
[details]
address status
127.0.0.1:34801 ALIVE
127.0.0.1:34802 ALIVE
127.0.0.1:34803 ALIVE
[summary]
total_node_count : 3
alive_node_count : 3
unalive_node_count : 0
常用参数（usage 实测）：-s all|alive|unalive 按状态过滤、-d 详情、-q 带 QPS、-u 资源占用、-j JSON。
6.2 server_info：服务端版本与启动时间
> server_info
COMMAND: server-info
CALL [meta-server] [127.0.0.1:34601] succeed: Pegasus Server 2.5.0 (non-git-repo) Release, Started at 2026-10-14 17:41:42
CALL [meta-server] [127.0.0.1:34602] succeed: Pegasus Server 2.5.0 (non-git-repo) Release, Started at 2026-10-14 17:41:42
CALL [meta-server] [127.0.0.1:34603] succeed: Pegasus Server 2.5.0 (non-git-repo) Release, Started at 2026-10-14 17:41:42
CALL [replica-server] [127.0.0.1:34801] succeed: Pegasus Server 2.5.0 (non-git-repo) Release, Started at 2026-10-14 17:41:42
CALL [replica-server] [127.0.0.1:34802] succeed: Pegasus Server 2.5.0 (non-git-repo) Release, Started at 2026-10-14 17:41:42
CALL [replica-server] [127.0.0.1:34803] succeed: Pegasus Server 2.5.0 (non-git-repo) Release, Started at 2026-10-14 17:41:42
Succeed count: 6
Failed count: 0
升级或滚动重启后，用 Started at 一眼判断各进程是否已用新版本启动。
6.3 server_stat：服务端实时指标
实测回显（节选 replica 34801 一条，指标非常丰富）：
CALL [replica-server] [127.0.0.1:34801] succeed: manual_compact_enqueue_count=0,
manual_compact_running_count=0, rdb_block_cache_memory_usage=3552, closing_replica_count=0,
disk_available_max_ratio=38, disk_available_min_ratio=38, disk_available_total_ratio=38,
disk_capacity_total(MB)=804743, opening_replica_count=0, serving_replica_count=16,
commit_throughput=1, learning_count=0, shared_log_size(MB)=0, memused_res(MB)=179,
memused_virt(MB)=1262, batch_get_p99(ns)=0, batch_get_qps=0, get_p99(ns)=119438, get_qps=0,
multi_get_p99(ns)=0, multi_get_qps=0, multi_put_p99(ns)=0, multi_put_qps=0,
put_p99(ns)=2036479, put_qps=0
Succeed count: 6 / Failed count: 0
要点解读：serving_replica_count 为该节点承载数（本例 16，含 stat/temp/t1 各分区副本）；disk_available_*_ratio 为磁盘剩余比例（低于 [replication] disk_min_available_space_ratio（默认 10）会触发写入保护）；get_p99/put_p99 为对应 RPC 的 P99 时延（纳秒）；memused_res/virt 为常驻/虚拟内存。meta 节点上查询 replica 系指标返回 not_found 属正常现象——meta 进程不承载 replica 数据。
6.4 remote_command：服务端远程命令
版本差异实测（重要）：2.5.0 的远程命令参数是连字符风格，旧文档中的下划线写法已失效：
> remote_command -t replica-server flush_log ← 下划线写法在 2.5.0 已失效
CALL [replica-server] [127.0.0.1:34801] succeed: unknown command 'flush_log'
（3 个 replica 均返回 unknown command 'flush_log'）
不确定命令名时，先向服务端要 help 列出真实命令（实测 meta-server 可用命令包括：help / repeat / config-dump / engine / fd.allow_list / flush-log / meta.dump / meta.lb.* / lb.assign_delay_ms / lb.assign_secondary_black_list / meta.live_percentage / perf-counters[-by-postfix|-by-prefix|-by-substr] / reset-log-start-level / server-info / server-stat / system.queue / task-code / task.queue_max_length）：
> remote_command -t meta-server help
连字符写法执行刷日志（实测 replica 与 meta 均成功）：
> remote_command -t replica-server flush-log
CALL [replica-server] [127.0.0.1:34801] succeed: Flush done.
CALL [replica-server] [127.0.0.1:34802] succeed: Flush done.
CALL [replica-server] [127.0.0.1:34803] succeed: Flush done.
Succeed count: 3
Failed count: 0
> remote_command -t meta-server flush-log
CALL [meta-server] [127.0.0.1:34601] succeed: Flush done.
（34602/34603 同）Succeed count: 3
-t 指定目标角色（meta-server / replica-server / collector），不加则按角色默认目标下发。
七、数据模型语义要点
本节把数据命令背后的语义集中说明，便于正确使用第五节的命令。
- 组合键路由：数据键为
<hash_key> <sort_key>组合键。hash 函数对 hash_key 计算哈希后对分区数取模得到分区 ID（官网《数据模型》页口径），同一 hash_key 的数据永远在同一分区——因此 exist/count/multi_get/hash_scan 都只需 hash_key 即可定位到单一分片（回显中的 partition_index 与 server 即路由结果）。 - 排序与边界：分片内按 sort_key 有序存储（内部为 hash_key+sort_key 拼接后作为 RocksDB key）。hash_scan 的 start 为闭区间、stop 为开区间（实测 stop_inclusive: false）。
- TTL 语义：set 第四参数按秒设置存活时间，
ttl命令查询剩余生命（未设返回 Infinite）；过期数据不可读。详见官方《用户接口/TTL》。 - 原子性：get/set/del/incr/check_and_set 等单键（单行）操作具备原子性（官方《单行原子操作》）；multi_* 族针对同一 hash_key 的多条 sort_key，属单行批量原子操作。
- 写版本号 decree：每次成功写操作在分片内单调递增（实测 5→6→7→9→10→11），随命令回显，可判断写入序。
八、HTTP REST 接口
Pegasus 2.x 的 HTTP 服务与 RPC 同端口（meta 34601-34603、replica 34801-34803、collector 34101），没有独立的管理端口，也没有内置 WebUI 页面。用 curl 即可查询。
8.1 根路径：列出支持的接口
curl http://127.0.0.1:34601/
curl http://127.0.0.1:34801/
curl http://127.0.0.1:34101/
实测输出（节选）：
{"/":"Lists all supported calls","/config":"...","/configs":"...",
"/meta/app":"ip:port/meta/app?app_name=temp","/meta/app/duplication":"...",
"/meta/apps":"ip:port/meta/apps","/meta/backup_policy":"...", ...}
{"/":"...","/perfCounter":"Gets the value of a perf counter",
"/pprof/cmdline":"...","/pprof/heap":"...","/pprof/profile":"...",
"/recentStartTime":"...","/replica/data_version":"...","/replica/manual_compaction":"...", ...}
{"/":"...","/perfCounter":"...","/pprof/*":"...","/recentStartTime":"...","/updateConfig":"...","/version":"..."}
三角色暴露的接口集合不同：meta 偏表管理（/meta/apps、/meta/app、/meta/backup_policy 等），replica/collector 偏运行时（/perfCounter、/pprof/*、/recentStartTime 等）。
8.2 常用端点实测
curl http://127.0.0.1:34601/meta/apps
curl http://127.0.0.1:34801/recentStartTime
curl http://127.0.0.1:34101/version
实测输出：
{"general_info":{"1":{"app_id":"1","status":"AVAILABLE","app_name":"stat",...},
"2":{"app_id":"2","status":"AVAILABLE","app_name":"temp","partition_count":"8",...}},
"summary":{"total_app_count":"2"}}
{"RecentStartTime":"2026-10-14 17:41:42"}
{"Version":"","GitCommit":""}
用法要点：/meta/apps 适合监控侧轮询表清单与状态；/meta/app?app_name=<表名> 查单表；/recentStartTime 判断进程最近重启时间（滚动升级核对）；/perfCounter 可按名查询单个性能计数器。
九、Prometheus 监控接入
9.1 默认状态：指标上报关闭
2.5.0 配置模板 [pegasus.server] 段中 perf_counter_sink 默认为空（不上报），prometheus_port 虽预留端口（onebox 由 run.sh 按 prometheus_port=$((9091+i)) 从 9092 起为每个进程递增分配），但默认不监听。实测验证：
curl http://127.0.0.1:9092/metrics
实测结果：连接失败（HTTP 000），9092-9097 无监听——与 perf_counter_sink 为空一致。
9.2 开启方法
指标上报由 perf_counter_sink 控制（可选值含 prometheus；配置模板注释另列 falcon）。依据配置生成链（模板 src/server/config.min.ini → 集群级 config-server.ini → 各进程 config.ini）：
- 改模板：把
src/server/config.min.ini中[pegasus.server]的perf_counter_sink =改为perf_counter_sink = prometheus； - 重新生成并重启：执行
./run.sh clear_onebox后再./run.sh start_onebox -m 3 -r 3 -c（clear 会清数据，重置环境场景适用）；或对已生成的onebox/<role>/config.ini直接修改该项后用./run.sh restart_onebox_instance -h定点重启对应进程； - 验证：
ss -tlnp | grep 909应看到各进程 9092 起的监听，curl http://127.0.0.1:9092/metrics返回指标文本。
⚠️ 本文实测环境未开启该上报（默认关闭、9092 无监听为实测事实），以上开启步骤按配置链推导给出，改动后务必用 curl 实际核对 metrics 可拉取。
9.3 Prometheus Server 与 Grafana
Prometheus Server 自身默认监听 9090（这是 Prometheus 的端口，不是 Pegasus 的）。抓取配置将各 Pegasus 进程的 prometheus_port（onebox 为 9092 起递增）作为 target：
scrape_configs:
- job_name: pegasus
static_configs:
- targets:
- 127.0.0.1:9092
- 127.0.0.1:9093
- 127.0.0.1:9094
可视化看板用 Grafana（官方《高效运维/可视化监控》即 Prometheus + Grafana 方案）。shell 侧无需等监控开启，server_stat（见 6.3）即可拿到核心指标做即时观测。
十、数据目录与配置文件位置
10.1 onebox 运行期目录结构
/pegasus-src/
├── run.sh # 官方一键脚本（build/pack_server/start_onebox/shell/stop_onebox/clear_onebox...）
├── config-server.ini # start_onebox 由 src/server/config.min.ini sed 生成（集群级模板）
├── onebox/ # start_onebox 生成的运行根目录
│ ├── meta1/ # MetaServer #1（34601）
│ │ ├── pegasus_server # 软链到 build/release/output/bin/pegasus_server/pegasus_server
│ │ ├── config.ini # 该进程的最终配置（@META_PORT@ 已替换为 34601）
│ │ ├── result # 启动时 stdout/stderr 重定向文件
│ │ └── log/ # 运行日志（pegasus.*.log）
│ ├── meta2/、meta3/ # MetaServer #2/#3（34602/34603）
│ ├── replica1/、replica2/、replica3/ # ReplicaServer（34801-34803）
│ └── collector/ # Collector（34101）
├── .zk_install/zookeeper-bin/ # 本地 zookeeper 3.7.0（clientPort=22181；conf/zoo.cfg、data/、logs/）
└── build/release/output/ # 编译产物（bin/pegasus_server、bin/pegasus_shell、lib/）
10.2 配置文件生成链
- 模板：
src/server/config.min.ini（onebox 用；生产模板是src/server/config.ini）； - start_onebox 先 sed 替换
@LOCAL_HOSTNAME@/@APP_NAME@/@PARTITION_COUNT@生成源码根目录的config-server.ini； - 再为每个进程 sed 替换
@META_PORT@/@REPLICA_PORT@/@PROMETHEUS_PORT@生成onebox/<role>{n}/config.ini。
meta1 最终 config.ini 中的关键段（实测 cat 节选）：
[apps.meta]
ports = 34601
[apps.collector]
ports = 34101
[meta_server]
server_list = <主机名>:34601,<主机名>:34602,<主机名>:34603
cluster_root = /pegasus/onebox/<主机名>
meta_state_service_type = meta_state_service_zookeeper
[zookeeper]
hosts_list = 127.0.0.1:22181
timeout_ms = 60000
replica 进程对应段为 [apps.replica] ports = 34801（34802/34803 依次类推），meta_list 同样指向 34601-34603。
10.3 数据目录（replica 精确路径）
以 replica1 为例（实测 ls）：
onebox/replica1/data/
├── log/ # 进程运行日志目录（pegasus.*.log 等）
└── replica/
├── slog/ # shared log 目录（低流量时实测为空，文件随写随轮转）
└── reps/ # 每个分片一个目录，命名 <app_id>.<partition>.pegasus
├── 1.1.pegasus/ # app1(stat) p1
├── 2.0.pegasus/ # app2(temp) p0
├── 3.1.pegasus/ ... # app3(t1)
│ └── data/rdb/ # rocksdb 实例目录：000003.log、000009.sst、CURRENT、IDENTITY、LOCK、LOG...
└── ...
meta 进程数据目录：onebox/meta1/data/ 下有 log/（进程日志）与 meta/（meta 本地工作目录）；元数据实际存于 Zookeeper（[zookeeper] hosts_list = 127.0.0.1:22181），znode 根路径为 cluster_root（/pegasus/onebox/<主机名>）。ZooKeeper 存活探测：printf 'ruok' | nc 127.0.0.1 22181 返回 imok（实测）。
10.4 日志特征（排障前必知）
[tools.simple_logger] short_header = false、stderr_start_level = LOG_LEVEL_ERROR：标准错误只从 ERROR 级开始输出。因此启动早期崩溃时 result 文件可能为空、日志目录都未建立，需依赖 gdb/dmesg 定位（AVX-512 SIGILL 完整排障见《Ubuntu 22.04 源码编译部署 Apache Pegasus 2.5.0 指南》常见问题 9.1）。
十一、常见问题（FAQ）
Q1：drop 命令为什么有时询问确认、有时直接删？
交互 TTY 下 drop 会进入确认流程；管道驱动（echo 'drop t1' | ./run.sh shell）没有确认，直接执行（实测：reserve_seconds = 0 / drop app t1 succeed）。删完习惯性敲 yes 会报 ERROR: invalid subcommand 'yes'——它不是 drop 的子命令。
Q2：remote_command 的 flush_log 报 unknown command？
2.5.0 服务端远程命令改用连字符命名，flush-log 才有效（实测 Flush done.）；下划线写法 flush_log 返回 unknown command。拿不准时用 remote_command -t meta-server help 列出服务端真实命令。
Q3：数据命令报 parse value as ttl failed？
数据命令不携带表名。先 use t1 切换当前表，再用 set hkey sortkey value；把表名写在第一个参数位会被当成 hash_key、末参被当 TTL 解析而报错（实测）。
Q4：pegasus_shell 能否用 -h/-p 指定地址？
不能。2.5.0 的参数风格是 <config_file> [cluster_name]；换集群用 run.sh shell 的 --cluster <ip:port,...> 或 -c <配置文件>，或按第二节 2.3 手工生成配置后直连。
Q5：server_stat 里 meta 节点的 replica 指标显示 not_found？ 正常现象。meta 进程不承载 replica 数据，其上无这些指标；replica 系指标看 34801-34803 的输出即可（见 6.3）。
Q6：hash_scan 回显中的 timout_ms 是拼写错误吗？ 是 shell 原始输出如此（实测逐字回显为 timout_ms），非本文笔误，以服务端实际行为为准（默认 5000 毫秒）。
Q7：hash_scan 的 stop_sort_key 包含在结果里吗？
不包含。实测 hash_scan hkey "" zz 回显 stop_inclusive: false，结果不含 "zz" 本身；start_sort_key 默认闭区间（start_inclusive: true）。
Q8：表删了还能恢复吗？
软删除机制：drop 后表为 DROPPED 状态并保留 7 天（实测 ls -a 中 drop_expire 为 7 天后），期间用 recall <app_id> 恢复（usage 见第三节）；过期后数据清理。
十二、参考链接
- Shell 工具官方文档（基于 2.5.0）：https://pegasus.apache.org/zh/docs/tools/shell/
- 官网数据模型：https://pegasus.apache.org/zh/overview/data-model/
- 官网体验 Onebox 集群：https://pegasus.apache.org/zh/overview/onebox/
- 集群部署官方文档：https://pegasus.apache.org/zh/administration/deployment
- 版本发布（下载）页：https://pegasus.apache.org/zh/docs/downloads/
- GitHub 仓库：https://github.com/apache/incubator-pegasus