Gaea 2.4.2 常用命令与管理端口详解

目标：汇总 Gaea 2.4.2 日常运维的全部高频入口——gaea 进程命令行、13306 服务端口的客户端接入行为、13307 管理端口的全套 HTTP API、日志与可观测命令——每条命令均给出实测输入与真实回显，形成一份可直接上手的运维手册。实测环境：Gaea 2.4.2 部署于 10.89.71.5（/opt/gaea，file 配置模式），后端 MySQL 5.7.44 双节点（10.89.71.2、10.89.71.3），客户端 mysql 8.0.46 于 10.89.71.4。

一、环境信息

角色	位置/版本	凭据
Gaea 代理	10.89.71.5，服务端口 13306 / 管理端口 13307	前端 root/q1w2e3r4；管理端口 admin/q1w2e3r4
后端 slice-0 / slice-1	10.89.71.2:3306 / 10.89.71.3:3306（MySQL 5.7.44）	root/q1w2e3r4
客户端	10.89.71.4（mysql Ver 8.0.46）	—
租户/分片	namespace gaea_test；逻辑库 db_test；tbl_user（mod 分表）、tbl_order（mycat_mod 分库）、tbl_config（全局表）、tbl_order_detail（关联表）	—
部署目录	/opt/gaea（bin/ + etc/ + logs/）	—

前置阅读：部署过程见《Gaea 2.4.2 安装指南》，配置字段见《Gaea 2.4.2 配置参数详解》。

二、命令速查表

场景	命令/入口	说明
启动	`./bin/gaea -config ./etc/gaea.ini`	前台启动，工作目录须为部署目录
构建信息	`./bin/gaea -info`	版本/构建时间等
停止	`kill -TERM <pid>`	优雅退出，日志记录 `got signal 15, quit`
重载本地配置	`kill -USR1 <pid>` 或管理端口 reload API	热重载 gaea.ini
客户端接入	`mysql -h 10.89.71.5 -P 13306 -uroot -pq1w2e3r4`	MySQL 协议
健康检查	`GET /api/proxy/ping`	管理端口
版本查询	`GET /api/proxy/version`	管理端口，免鉴权
配置指纹	`GET /api/proxy/config/fingerprint`	管理端口
SQL 指纹	`GET /api/proxy/stats/{session,backend}sqlfingerprint/:namespace`	慢/错 SQL 指纹
指标抓取	`GET /api/metric/metrics`	Prometheus 格式
性能分析	`GET /debug/pprof/*`	管理端口

三、gaea 进程命令详解

3.1 启动参数

gaea 二进制仅支持三个参数（源码 cmd/gaea/main.go）：

参数	说明
`-config`	配置文件路径，默认 `./etc/gaea.ini`
`-info`	打印构建信息后退出
`-num-cpu`	GOMAXPROCS 设置，默认 0（自动取 CPU 核数，启动日志打印 `max use cpu : N(default)`）

构建信息查询（实测）：

cd /opt/gaea && ./bin/gaea -info

Build Version Information:Version: unknown
GitRevision: unknown
User: root@9efd6925d1b3
GolangVersion: go1.23.12
BuildStatus: Modified
BuildTime: 2026-10-23--15:19:28
BuildBranch:
BuildGitDirty: 0

（源码包构建无 git 元数据，Version/GitRevision 显示 unknown；git clone 构建则带版本号，见《安装指南》4.5。）

前台启动（实测回显要点，GIN 路由清单为管理端口全部 API 注册记录，节选）：

cd /opt/gaea && ./bin/gaea -config ./etc/gaea.ini

Build Version Information:Version: unknown
...
max use cpu : 4(default)[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
[GIN-debug] GET    /api/proxy/ping           --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).ping-fm (2 handlers)
[GIN-debug] PUT    /api/proxy/proxyconfig/reload --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).reloadProxyConfig-fm (2 handlers)
[GIN-debug] PUT    /api/proxy/config/prepare/:name --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).prepareConfig-fm (2 handlers)
[GIN-debug] PUT    /api/proxy/config/commit/:name --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).commitConfig-fm (2 handlers)
[GIN-debug] PUT    /api/proxy/namespace/delete/:name --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).deleteNamespace-fm (2 handlers)
[GIN-debug] GET    /api/proxy/config/fingerprint --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).configFingerprint-fm (2 handlers)
[GIN-debug] GET    /api/proxy/stats/sessionsqlfingerprint/:namespace --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).getNamespaceSessionSQLFingerprint-fm (2 handlers)
[GIN-debug] GET    /api/proxy/stats/backendsqlfingerprint/:namespace --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).getNamespaceBackendSQLFingerprint-fm (2 handlers)
[GIN-debug] DELETE /api/proxy/stats/sessionsqlfingerprint/:namespace --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).clearNamespaceSessionSQLFingerprint-fm (2 handlers)
[GIN-debug] DELETE /api/proxy/stats/backendsqlfingerprint/:namespace --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).clearNamespaceBackendSQLFingerprint-fm (2 handlers)
[GIN-debug] GET    /debug/pprof/...（profile/heap/goroutine/threadcreate/allocs/block/mutex 等一组）
[GIN-debug] GET    /api/metric/metrics
[GIN-debug] GET    /api/proxy/version

⚠️ 注意：不带 -config 直接运行 ./bin/gaea 时加载默认 ./etc/gaea.ini；若其中 config_type=etcdv3 而本机无 etcd，实测直接退出：
max use cpu : 4(default)init manager failed, error: client is nil

3.2 后台运行与守护

生产用 systemd（unit 模板见《安装指南》第六章）；临时后台运行：

cd /opt/gaea && nohup ./bin/gaea -config ./etc/gaea.ini > logs/stdout.log 2>&1 &

启动成功后的端口监听（实测）：

netstat -ltnp | grep -E '13306|13307'

tcp        0      0 0.0.0.0:13307           0.0.0.0:*               LISTEN      4746/gaea
tcp        0      0 0.0.0.0:13306           0.0.0.0:*               LISTEN      4746/gaea

3.3 停止与重载

优雅停止（实测，日志同步记录）：

kill -TERM 4746

[2026-10-23 15:30:56.677] [INFO] [900000001] got signal 15, quit

本地配置热重载（实测）：

kill -USR1 $(pidof gaea)

日志记录新旧配置对比（old/new 字段逐项打印），无需重启进程即可更新 gaea.ini 的日志、端口、鉴权等本地配置项。

⚠️ 注意：kill -USR1 与管理端口 PUT /api/proxy/proxyconfig/reload 等价（均热重载本地配置）；namespace 租户配置在 file 模式下不支持热加载，改动必须重启进程（见《配置参数详解》第六章）。

四、管理端口（13307）API 详解

管理端口是 HTTP 服务，除 /api/proxy/version 外均需 Basic Auth（admin/q1w2e3r4）。错误凭据实测：

curl -i -u admin:wrong http://10.89.71.5:13307/api/proxy/ping

HTTP/1.1 401 Unauthorized

4.1 GET /api/proxy/version —— 版本查询（免鉴权）

curl -s http://10.89.71.5:13307/api/proxy/version

"unknown"

返回构建版本号（源码包构建为 "unknown"；带 git 元数据构建返回 v2.4.2 等真实版本）。

4.2 GET /api/proxy/ping —— 健康检查

curl -s -u admin:q1w2e3r4 http://10.89.71.5:13307/api/proxy/ping

"OK"

适合接入负载均衡健康探测与监控拨测。

4.3 GET /api/proxy/config/fingerprint —— 配置指纹

curl -s -u admin:q1w2e3r4 http://10.89.71.5:13307/api/proxy/config/fingerprint

{"proxy_config_fingerprint":"2afe8b7e3a69e69f7f4bf1429209b8cb"}

用于快速比对多个 gaea-proxy 实例的配置是否一致（多实例集群中指纹不同即配置漂移）。

4.4 GET /api/proxy/stats/sessionsqlfingerprint/:namespace —— 慢/错 SQL 指纹

curl -s -u admin:q1w2e3r4 http://10.89.71.5:13307/api/proxy/stats/sessionsqlfingerprint/gaea_test

实测（触发过一次慢 SQL 与一次错误 SQL 后）：

{"slow_sql":{"cf979fb3da827137f633ea865c5f9f9b":"select sleep(?), ?"},"error_sql":{"cdbfe2f1f0bb175c6edee8033e7f9aa9":"insert into tbl_user values(?+)"}}

slow_sql：超过 slow_sql_time 阈值的语句指纹。实测 namespace 配 1000ms，前端执行 SELECT SLEEP(2), 1 即命中；
error_sql：执行失败的语句指纹。实测 INSERT INTO tbl_user VALUES (101, 'nocol', 1)（未指定列名）被记录；
指纹值（md5）用于聚合同类语句，排查时复制指纹到应用侧日志即可定位原始 SQL。

后端 SQL 指纹（GET /api/proxy/stats/backendsqlfingerprint/:namespace，回显结构相同，统计 gaea 发往后端实例的语句）；两接口均支持 DELETE 方法清空对应指纹库。

4.5 PUT /api/proxy/proxyconfig/reload —— 本地配置热重载

curl -s -X PUT -u admin:q1w2e3r4 http://10.89.71.5:13307/api/proxy/proxyconfig/reload

"OK"

实测效果与 kill -USR1 一致（详见 3.3）。

4.6 PUT /api/proxy/config/prepare/:name 与 commit/:name —— namespace 二阶段变更（生产模式）

prepare 校验新配置 → commit 原子发布，用于 etcd/etcdv3 生产模式下租户配置的灰度下发。file 模式下调用无效（依赖 etcd client，报 client is nil 类错误）；PUT /api/proxy/namespace/delete/:name 同理。

4.7 GET /api/metric/metrics —— Prometheus 指标

curl -s -u admin:q1w2e3r4 http://10.89.71.5:13307/api/metric/metrics | head -8

实测（节选，连接池维度的核心指标）：

gaea_proxy_backend_connect_pool_active_counts{cluster="gaea_default_cluster",ip_addr="10_89_71_2:3306",namespace="gaea_test",role="master",slice="slice-0"} 2
gaea_proxy_backend_connect_pool_active_counts{cluster="gaea_default_cluster",ip_addr="10_89_71_3:3306",namespace="gaea_test",role="master",slice="slice-1"} 1
gaea_proxy_backend_connect_pool_capacity_counts{cluster="gaea_default_cluster",ip_addr="10_89_71_2:3306",namespace="gaea_test",role="master",slice="slice-0"} 12
gaea_proxy_backend_connect_pool_capacity_counts{cluster="gaea_default_cluster",ip_addr="10_89_71_3:3306",namespace="gaea_test",role="master",slice="slice-1"} 12
gaea_proxy_backend_connect_pool_idle_counts{cluster="gaea_default_cluster",ip_addr="10_89_71_2:3306",namespace="gaea_test",role="master",slice="slice-0"} 12
gaea_proxy_backend_connect_pool_idle_counts{cluster="gaea_default_cluster",ip_addr="10_89_71_3:3306",namespace="gaea_test",role="master",slice="slice-1"} 12

指标维度：cluster/namespace/slice/role/ip_addr，可直接被 Prometheus 抓取（采集地址 http://<proxy>:13307/api/metric/metrics）。Gaea 官方还提供 Grafana 面板模板（docs/grafana.md），导入即可用。

4.8 GET /debug/pprof/* —— 性能分析

curl -s -u admin:q1w2e3r4 "http://10.89.71.5:13307/debug/pprof/goroutine?debug=1" | head -3

goroutine profile: total 24
4 @ 0x47422e 0x44ff05 0x606027 0x47c601
#       0x606026        github.com/XiaoMi/Gaea/util/timer.(*Timer).run+0x86     /work/Gaea-2.4.2/util/timer/timer.go:98

标准 Go pprof 全家桶（heap/goroutine/block/mutex 等），配合 go tool pprof 线上性能分析。

五、服务端口（13306）客户端接入实测

5.1 基本接入

mysql -h 10.89.71.5 -P 13306 -uroot -pq1w2e3r4 -e "SHOW DATABASES; SELECT VERSION();"

Database
db_test
VERSION()
5.7.44

SHOW DATABASES 只返回 namespace allowed_dbs 白名单内的逻辑库 db_test（后端实例上的系统库与其它库均被隐藏）。

握手版本（status 命令，节选）：

Server version:         5.6.20-gaea MySQL Community Server (GPL)
Protocol version:       10
Connection:             gaea-proxy via TCP/IP

与 SELECT VERSION() 的差异说明：握手显示 gaea.ini 配置的 server_version，后者透传后端真实版本，两者不一致属正常。

认证失败（实测）：

ERROR 1045 (28000): Access denied for user 'root'@'10.89.71.4:36190' (using password: Yes)

5.2 元数据语句行为

mysql -h 10.89.71.5 -P 13306 -uroot -pq1w2e3r4 db_test -e "SHOW TABLES; DESC tbl_user;"

Tables_in_db_test
tbl_config
tbl_user_0000
tbl_user_0001
ERROR 1105 (HY000) at line 1: get plan error, db: db_test, origin sql: DESC tbl_user, err: build plan error: stmt type does not support shard now

SHOW TABLES 直通 default_slice（slice-0）的物理库，返回物理表名（含 _0000 编号后缀）；mycat 方式的 tbl_order 位于独立物理库 db_test_0~3，不出现在该列表；
分片表的 DESC/CREATE TABLE 等元数据 DDL 不支持（物理结构请到后端实例查看）。

5.3 分片表 CRUD 速览

写入与聚合（mod 分表，id % 4 路由）：

mysql -h 10.89.71.5 -P 13306 -uroot -pq1w2e3r4 db_test \
  -e "SELECT COUNT(*) AS cnt, SUM(age) AS sum_age, MIN(age) AS min_age, MAX(age) AS max_age FROM tbl_user; SELECT name, age FROM tbl_user WHERE id = 4;"

cnt     sum_age min_age max_age
7       141     20      27
name    age
dave    23

更新与删除（单分片精确路由）：

mysql -h 10.89.71.5 -P 13306 -uroot -pq1w2e3r4 db_test \
  -e "UPDATE tbl_user SET age = 30 WHERE id = 1; SELECT name, age FROM tbl_user WHERE id = 1; DELETE FROM tbl_user WHERE id = 8; SELECT COUNT(*) AS cnt FROM tbl_user;"

name    age
alice   30
cnt
7

全局表广播（INSERT IGNORE 写法，详见《配置参数详解》第七章 Q5）：

mysql -h 10.89.71.5 -P 13306 -uroot -pq1w2e3r4 db_test \
  -e "INSERT IGNORE INTO tbl_config (k, v) VALUES ('max_users', '10000'), ('site_name', 'quzuo'); SELECT * FROM tbl_config ORDER BY k;"

k               v
max_users       20000
site_name       quzuo

父子表 JOIN（linked 关联表 + 父表分片键等值条件）：

mysql -h 10.89.71.5 -P 13306 -uroot -pq1w2e3r4 db_test \
  -e "SELECT o.order_id, d.item FROM tbl_order o, tbl_order_detail d WHERE o.user_id = d.user_id AND d.user_id = 1;"

order_id        item
1001            keyboard
1005            keyboard

5.4 受限语句速查（实测报错原文）

语句	实测报错
`CREATE TABLE tbl_user (...)`（分片表 DDL）	`ERROR 1105 (HY000): get plan error, ... stmt type does not support shard now`
`DESC tbl_user`（分片表）	同上
`INSERT INTO tbl_user VALUES (101, 'nocol', 1)`	`ERROR 1105 (HY000): get plan error, ... insert or replace must specify columns`
`SELECT AVG(age) FROM tbl_user`	`ERROR 1105 (HY000): get plan error, ... is a shard table, avg is not supported`
`SELECT SLEEP(2), 1`	执行成功但记入慢 SQL 指纹（1000ms 阈值）
跨分片事务 `BEGIN; ...两片写入...; COMMIT;`	不报错且全部落库（无原子性保证，应用侧规避）

六、日志与可观测命令

6.1 日志文件

file 模式日志落在 log_path 目录（本文 /opt/gaea/logs/）：

ls -la /opt/gaea/logs/

-rw-r--r-- 1 root root  18765 Oct 23 15:41 gaea.log
-rw-r--r-- 1 root root    994 Oct 23 15:41 stdout.log

gaea.log：主日志（Notice 级记录启动/停止/重载/异常；Debug 级另记录后端健康检查等明细）；
stdout.log：GIN 路由注册与启动横幅（配合 nohup 重定向产生）。

启动成功日志（实测）：

[2026-10-23 15:02:43.855] [INFO] [900000001] [server] NewAdminServer, Api Server running, netProto: http, addr: 0.0.0.0:13307
[2026-10-23 15:02:43.855] [INFO] [900000001] server start succ, netProtoType: tcp4, addr: 0.0.0.0:13306

后端健康检查（Debug 级，实测）：

[2026-10-23 15:30:39.108] [DEBUG] [900000001] [ns:gaea_test, slice-0:10.89.71.2:3306] start check master
[2026-10-23 15:30:39.108] [DEBUG] [900000001] [ns:gaea_test, slice-1:10.89.71.3:3306] start check master

6.2 常用跟踪命令

tail -f /opt/gaea/logs/gaea.log                      # 跟踪主日志
journalctl -u gaea-proxy -f                          # systemd 托管时跟踪 stdout
curl -s -u admin:q1w2e3r4 http://10.89.71.5:13307/api/proxy/stats/sessionsqlfingerprint/gaea_test   # 巡检慢/错 SQL
curl -s -u admin:q1w2e3r4 http://10.89.71.5:13307/api/metric/metrics | grep -E 'pool_active|session_counts'   # 连接池水位

七、排障命令组合速查

症状	排查路径
前端连不上（连接拒绝）	`netstat -ltnp \| grep 13306`（进程存活？）→ `tail -50 logs/gaea.log`（启动失败？）→ namespace JSON 语法校验
前端连不上（Access denied）	核对 namespace `users` 里的账号密码；看日志认证失败记录
启动即退出 `client is nil`	`config_type=etcdv3` 但无 etcd；file 体验改 `config_type=file`
启动即退出 `invalid character ...`	namespace 目录混入坏 JSON，`python3 -m json.tool` 逐个校验
SQL 报 `doesn't exist`	物理分表未建或命名不符（kingshard 系 `_0000` 补零；mycat 系按 `databases` 展开同名表）
SQL 报 `stmt type does not support shard now`	分片表不支持该语句（DDL/DESC 等），到后端实例执行
疑似慢查询	`sessionsqlfingerprint` 接口查慢 SQL 指纹 → 定位应用日志 → 后端 `EXPLAIN`
多实例配置漂移	逐台 `GET /api/proxy/config/fingerprint` 比对指纹
连接池打满	metrics 里 `pool_active_counts` 逼近 `capacity_counts` → 调大 namespace `capacity/max_capacity`

八、参考链接

管理端口 API 实现源码：proxy/server/admin.go（本文第四章路由与鉴权行为的核对基准）
启动入口源码：cmd/gaea/main.go（第三章命令行参数）
官方 Grafana 面板说明：docs/grafana.md
部署与安装：《Gaea 2.4.2 安装指南》
配置字段与分片规则：《Gaea 2.4.2 配置参数详解》
选型背景：《Gaea 2.4.2 介绍与选型指南》
同组中间件运维实践：《BlazingMQ 0.95.20 常用 CLI 命令详解》