Goku Gateway 3.1.x 配置参数详解

目标：系统讲清 Goku Gateway（goku_lite 社区版 CE）3.1.x 全部配置参数——管理控制台（console）的文件参数与启动参数、网关节点（node）的环境变量与启动参数、离线模式配置文件 goku-node.json 的完整结构，以及管理面上集群/项目/API/策略/负载均衡/插件/配置版本等对象的关键字段。全部取值经 Ubuntu 22.04 实机部署取证（console 3.1.4 + node 3.1.5，2026-10-23 ~ 2026-10-24 实测），源码级字段以开源仓 goku_lite 3.1.3 源码为据并标注来源。

一、环境信息

本章为参数取证环境，所有回显均出自该环境：

• 操作系统：Ubuntu 22.04 x86_64；
• 管理控制台：eolinker/goku-api-gateway-ce-console:3.1.4（镜像内运行目录 console-3.1.4），Web/API 端口 7000 映射宿主 8131，节点注册端口 7005；
• 网关节点：eolinker/goku-api-gateway-ce-node:3.1.5（镜像内运行目录 node-3.1.5），网关端口 6689；
• 配置存储：console 默认 SQLite，实测库文件 work/goku.db（167936 字节，26 张表）；
• 源码口径：eolinker/goku_lite 仓库（最后代码提交 2022-08；GitHub Release 停在 3.1.3），本文源码引用均标注文件与行为；
• 部署与登录：控制台账号 admin / q1w2e3r4（登录实测 {"statusCode":"000000","type":"guest","userID":2}）。

二、前置条件

1. 已有一套可运行的 Goku Gateway（两件套任一形态均可；容器编排部署的完整过程见本专栏部署篇）；
2. 能进入 console 主机执行文件查看命令，或能通过镜像/安装包看到 config/goku.conf 与 config/cluster.yaml；
3. 理解 Goku 的双端口模型：console 同时监听 Web/API 口（listen_port）与节点分发口（admin_bind），node 既监听流量口（6689）也监听自己的 admin 口（7005）。

三、参数查看与修改方式

3.1 console 文件参数：config/goku.conf

console 主配置文件位于运行目录下 config/goku.conf，实测查看：

cat /app/goku-ce/console/config/goku.conf

实测回显：

listen_port: 7000
admin_bind: 0.0.0.0:7005

修改方式：编辑该文件后重启 console 进程生效；容器形态下把整个 config/ 目录挂载到宿主编辑。启动命令里 -c 参数可指向其他路径的配置文件（见 3.2）。

3.2 console 命令行参数

console 进程启动命令（docker inspect 实测 Cmd 字段）：

sh -c ./gateway-console -c config/goku.conf -u ${GOKU_ADMIN} -p ${GOKU_ADMIN_PASSWORD}

3.3 console 环境变量

docker inspect 实测 console 环境变量：

["GOKU_ADMIN_PASSWORD=q1w2e3r4","PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin","CONSOLE_DIR=console-3.1.3","GOKU_ADMIN=admin"]

GOKU_ADMIN 默认 admin、GOKU_ADMIN_PASSWORD 由部署者传入；CONSOLE_DIR 是镜像构建期遗留变量（值 console-3.1.3），实际运行目录为 console-3.1.4，不参与任何运行时行为，无需设置。

3.4 node 环境变量与启动参数

node 容器实测环境变量：

["GOKU_ADMIN_ADDRESS=10.89.61.2:7005","INSTANCE=dbcf5af2f61546367cae44869e1dc21a","PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin","NODE_DIR=node-3.1.3","NODE_PORT=6689"]

node 二进制启动参数（./node --help 实测）：

Usage of ./node:
  -admin string
        Please provide a valid host!
  -config string
        Please provide a config file
  -debug

  -instance string
        Please provide a valid instance!

运行中节点进程实测（容器内 ps aux）：

USER         PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root           1  0.0  0.0  11700  2760 ?        Ss   Oct23   0:00 sh -c ./run.sh start ${GOKU_ADMIN_ADDRESS} ${INSTANCE}
root          10  0.0  0.1 1118852 43316 ?       Sl   Oct23   0:02 /app/goku-ce/node/node-3.1.5/node --admin=10.89.61.2:7005 --instance=dbcf5af2f61546367cae44869e1dc21a

可见官方 run.sh 把 GOKU_ADMIN_ADDRESS 与 INSTANCE 转为 --admin/--instance；NODE_DIR、CONSOLE_DIR 同为镜像遗留变量（实际运行目录 node-3.1.5）。

3.5 管理面对象参数：控制台与 Open API

集群、项目、API、策略、负载均衡、插件、配置版本等对象在控制台图形界面配置，也可走管理 Open API 查看——实测以登录 cookie 调 /strategy/getList 查看策略参数：

curl -s -b cookies.txt -X POST -d 'currentPage=1&pageSize=10' http://127.0.0.1:8131/strategy/getList

实测回显：

{"page":{"itemNum":1,"page":1,"pageSize":10,"totalNum":1},"statusCode":"000000","strategyList":[{"strategyID":"QYYGza","strategyName":"demo-strategy","updateTime":"2026-10-23 22:17:26","createTime":"2026-10-23 22:12:35","groupID":0,"groupName":"未分组","enableStatus":1,"strategyType":0,"updater":"","creater":""}],"type":"strategy"}

Open API 各端点的逐条实测见本专栏命令篇《Goku Gateway 3.1.x 管理面与 CLI 命令详解》。

四、参数总览

如何选配置域：改监听端口/数据库 → goku.conf；改节点注册地址/实例标识 → node 环境变量；要离线固化路由不走 console → goku-node.json；改路由、策略、负载均衡 → 控制台或 Open API（配置会生成版本并下发到 node）。

五、核心参数分类详解

5.1 console 服务口参数（listen_port / admin_bind）

console 的双端口是理解整个部署的关键（源码 console/server.go：admin_bind 缺失时启动报 [ERROR] Illegal admin_bind!，listen_port 缺失报 [ERROR] Illegal listen port!）：

console 启动日志实证（docker logs 实测）：

dbcf5af2f61546367cae44869e1dc21a
2026/10/23 22:28:59 Listen: 7000
2026/10/23 22:28:59 Start Successfully!
dbcf5af2f61546367cae44869e1dc21a

Listen: 7000 与 Start Successfully! 即两端口就绪的标志；日志中成对出现的 dbcf5af2f61546367cae44869e1dc21a 是节点实例标识（INSTANCE），console 以该 key 区分节点。

5.2 console 数据库参数（db_type 系列）

console 数据库参数的加载逻辑（源码 console/cluster.go 的 getDefaultDatabase()）：

dbType := conf.MastValue("db_type", "sqlite3")
switch dbType {
case mysqlDriver:  // 读 db_port(默认3306)/db_host/db_user/db_password/db_name
case sqlite3Driver: // Path 取 conf.MastValue("db_path", "./work/goku.db")
default:           // 报 unsupported database type
}

实测佐证：本环境 goku.conf 只写了两个端口键，未写任何 db_*，console 即按默认 sqlite3 在 ./work/goku.db 落库——宿主挂载卷中实测存在 goku.db（167936 字节）。库内核心表（实测表清单）：goku_admin（账号）、goku_gateway_api（API）、goku_gateway_api_group（API 分组）、goku_gateway_project（项目）、goku_gateway_strategy（策略）、goku_gateway_strategy_group（策略分组）、goku_balance（负载均衡）、goku_node_info（节点）、goku_gateway_version_config（配置版本）、goku_plugin、goku_monitor_module 等。

MySQL 外置示例（生产建议，管理数据不随 console 实例消失）：

listen_port: 7000
admin_bind: 0.0.0.0:7005
db_type: mysql
db_host: 10.0.0.11
db_port: 3306
db_user: goku
db_password: ${GOKU_DB_PASSWORD}
db_name: goku_ce

💡 说明：${GOKU_DB_PASSWORD} 为系统级真实密钥占位，导出方式 export GOKU_DB_PASSWORD=你的密码 后由启动环境注入；其余示例值均须替换为实际规划值。

5.3 多机房模板 cluster.yaml

console config/cluster.yaml 是初始机房（集群）定义模板，实测内容：

cluster:
  -
    name: "Default"
    title: "默认机房"
    note: "默认机房"
    db:
      driver: "mysql"
      host: "127.0.0.1"
      port: 3306
      userName: "root"
      password: "123456"
      database: "goku_ee"
    redis:
      mode: "stand"
      addrs: "127.0.0.1:6379"    # stand、cluster模式下addrs为redis地址，多个地址间用英文逗号隔开
      password: "123456"
      dbIndex: 0

⚠️ 注意：CE 3.1.4 单机房部署不要改 cluster.yaml；文件中的 db/redis 段是旧版模板形态，运行时生效的数据库是 goku.conf 的 db_* 系列。实测环境未配置 Redis，功能不受影响。

控制台实测查询机房列表（/cluster/list）：

{"clusters":[{"id":1,"name":"Default","title":"Default","note":"default","nodeCount":1,"redis":null}],"page":{"itemNum":1,"totalNum":1},"statusCode":"000000","type":"cluster"}

redis: null 与上文「未配置 Redis」吻合，nodeCount: 1 表明 Default 机房已挂接 1 个节点。

5.4 node 环境变量详解

节点注册结果实测（/node/getList，cluster=Default）：

{"nodeList":[{"nodeID":1,"nodeName":"node-1","nodeKey":"dbcf5af2f61546367cae44869e1dc21a","listenAddress":"10.89.61.3:6689","adminAddress":"10.89.61.3:7005","cluster":"Default","cluster_title":"Default","version":"3.1.4","nodeStatus":1,"groupName":"未分类","isUpdate":false,"gatewayPath":"","createTime":"2026-10-23 21:54:29","updateTime":"2026-10-23 22:04:43"}],"page":{"itemNum":1,"totalNum":1},"statusCode":"000000","type":"node"}

字段对照：nodeKey ← INSTANCE；listenAddress ← 数据面口（NODE_PORT）；adminAddress 是 node 自身的 7005 管理口；nodeStatus: 1 运行中；version 为注册上报版本。

5.5 node 运行模式：console 模式与 config 模式

node 有两种取配置的方式，由官方启动脚本 run.sh 判定（脚本实测关键逻辑）：

CONFIG_PATH=$WORK_PATH/goku-node.json
RUN_MODEL="console"
if [ -f "$CONFIG_PATH" ]; then
    RUN_MODEL="config"
fi
if [[ "$ADMIN" == "" && "$RUN_MODEL" == "console" ]] ; then
    echo "start fail :need admin url"
    exit 1
fi

💡 技术拓展：网关的配置获取方式不止「控制台中心化下发」一种，常见形态对比——

形态	代表	特点	适用场景
控制台下发（推/拉混合）	Goku console 模式	图形化管理、热更新、版本回滚	有管理面的中大型部署
本地配置文件	Goku config 模式、NGINX conf	无外部依赖、改动需重启或 reload	单点、边缘、离线
声明式 API/存储驱动	APISIX(etcd)、Kong(DB-less)	配置即数据、可 GitOps	云原生、自动化流水线

Goku CE 同时支持前两种：默认 console 模式，work 目录放入 goku-node.json 即自动切换 config 模式。本环境实测运行在 console 模式（ps aux 回显 --admin=... 形态）。

run.sh 的启停用法（无参数执行实测）：

Usage: /app/goku-ce/node/node-3.1.5/run.sh {start|stop|reload|restart|force-reload} [admin url] [port]

run.sh 会在 work 目录生成 node.env 记录启动环境，实测内容（两行）：

ENV_PORT=
ENV_ADMIN=10.89.61.2:7005

5.6 node 离线配置 goku-node.json（GokuConfig 结构）

config 模式的配置文件结构与控制台下发的配置同构，源码定义于 config/config.go 的 GokuConfig，逐字段如下（json tag 即文件键名）：

日志字段实测佐证：node 实际运行日志中输出的 $strategy、$balance、$finally_server、$proxy_status_code、$request_time、$retry 等字段即来自 access_log.fields 自定义机制（节点系统日志实测节选）：

[2026-10-23 22:33:34] [INFO]  $http_referer="" $request_id=vSFhF7zH3tWqzChc $status_code=200 $body_bytes_sent=896 $request="GET /demo HTTP/1.1" $host="127.0.0.1:6689" $proxy="GET / HTTP" $finally_server="10.89.61.4:80" $proxy_status_code=200 $strategy="RGAtKBd 开放策略" $api="1 " $remote_addr=10.89.61.1 $balance=demo-balance $retry="10.89.61.4:80" $request_time=1.206177ms $http_user_agent="curl/7.81.0"

5.7 管理面对象关键字段

以下字段均可在控制台或 Open API 响应中直接观察到（回显见 3.5 与本节）：

策略（strategy）：strategyID 6 位随机串（实测 QYYGza）、strategyName、groupID/groupName（策略分组，默认「未分组」）、strategyType（0=开放策略，即匿名可访问）、enableStatus（1=已启用）。策略是 Goku 的多租户与访问控制单元：不同策略绑定不同 API 与认证方式。

💡 技术拓展：API 网关的「访问策略/租户」粒度各家不同——

粒度	代表	说明
策略=租户单元	Goku（strategy）	一组 API + 一套认证/插件的组合，匿名策略兜底
消费者=租户单元	Kong（consumer）	凭据挂在消费者上，按 consumer 鉴权
路由级插件	APISIX	认证以插件形式逐路由挂载

Goku 用 strategy 把「API 集合 + 认证 + 插件」打包，配合 anonymousStrategyID 实现开放兜底；本环境实测即存在一个开放策略（strategyType: 0，名称含「开放策略」）承接未认证流量。

负载均衡（balance）：balanceName、serviceType（实测 static 静态节点表；另支持服务发现类型）、staticCluster（静态节点表，实测 {"Default":"10.89.61.4:80"}）、balanceDesc。查询回显（/balance/getList）：

{"balanceList":[{"balanceName":"demo-balance","serviceName":"static","serviceType":"static","serviceDriver":"static","appName":"","static":"","staticCluster":{"Default":"10.89.61.4:80"},"balanceDesc":"nginx backend","createTime":"2026-10-23 22:11:25","updateTime":"2026-10-23 22:11:25","canDelete":0}],"page":{"itemNum":1,"totalNum":1},"statusCode":"000000","type":"balance"}

💡 技术拓展：Goku 的负载均衡算法为加权轮询（官方 README：Round-robin with weight）。常见负载均衡算法横向对比——

算法	特点	适用场景
轮询 RR / 加权轮询 WRR	依次/按权重分配	Goku 支持的形态，后端同构用 RR、异构用权重
最小连接 LC	发给当前连接最少的节点	长连接、处理耗时差异大
源地址哈希	同客户端固定同节点	需会话保持
一致性哈希	节点增减迁移最小	缓存类后端

Goku CE 仅提供轮询族，需要 LC/哈希时应评估其他网关。

API（api）：挂在项目下，关键字段 requestUrl（请求路径）、methods、requestType、timeoutTotal（总超时）、steps（转发链，含目标 balance、重试 retry、超时 timeout、黑白名单）。

配置版本（versionConfig）：console 的配置发布单元，每次改动可生成一个版本，发布后按机房下发到 node。查询回显（/version/config/getList，节选前 3 条）：

{"configList":[{"versionID":9,"name":"http-proto","version":"v9","remark":"HTTP proto","createTime":"2026-10-23 22:33:25","publishStatus":1,"publishTime":"2026-10-23 22:33:25","publisher":""},{"versionID":8,"name":"debug-log","version":"v8","remark":"debug log","createTime":"2026-10-23 22:33:00","publishStatus":0,"publishTime":"2026-10-23 22:33:00","publisher":""},{"versionID":7,"name":"get-method","version":"v7","remark":"GET method","createTime":"2026-10-23 22:24:21","publishStatus":0,"publishTime":"2026-10-23 22:24:21","publisher":""}
],"page":{"itemNum":9,"totalNum":9},"statusCode":"000000","type":"versionConfig"}

publishStatus: 1 为已发布（实测仅 v9 已发布），其余为待发布草稿；remark 可自拟（实测 v2 备注为 fix adminAddress，正是修正节点地址后发布的版本）。

插件（plugin）：node 镜像内置 5 个插件（/app/goku-ce/node/node-3.1.5/plugin/ 实测清单）：

goku-apikey_auth.so
goku-basic_auth.so
goku-extra_params.so
goku-ip_restriction.so
goku-params_transformer.so

对应能力：Apikey 认证、Basic 认证、额外参数注入、IP 黑白名单、参数转换；控制台汇总接口 pluginCount: 5 与此吻合。

六、生产配置模板

适用规模：4GB 内存以上服务器、单机房、纯 HTTP(S) API 代理场景（Go 实现，无 JVM；实测 node 进程 RSS 约 42MB，ps aux 回显 RSS 43316KB，内存占用极低，瓶颈主要在上游吞吐）。

console 的 goku.conf（MySQL 外置模板）：

listen_port: 7000
admin_bind: 0.0.0.0:7005
db_type: mysql
db_host: 10.0.0.11
db_port: 3306
db_user: goku
db_password: ${GOKU_DB_PASSWORD}
db_name: goku_ce

node（compose 环境变量片段）：

environment:
  - GOKU_ADMIN_ADDRESS=10.0.0.10:7005
  - INSTANCE=<控制台节点key>

要点：① 管理数据落 MySQL 并定期备份；② 多节点时各 node 用不同 INSTANCE、指向同一 console；③ node 无状态可横向扩展，扩容只需再起一个 node 实例；④ admin_bind 仅对内网开放，listen_port 前置反代加 TLS；⑤ 版本发布走 versionConfig 机制，先灰度一台再全量发布。

七、常见问题（FAQ）

Q1：goku.ini 在哪？

Goku 3.1.x 的 console/node 配置载体是 YAML（config/goku.conf、config/cluster.yaml）与环境变量，不存在 goku.ini。历史上部分文档提到 goku.ini 的说法不适用于本版本；以镜像内 config/ 目录实测为准。

Q2：db_type 填了别的值为什么起不来？

getDefaultDatabase() 只认 sqlite3/mysql 两种（源码 case 分支），其他值直接返回 unsupported database type 并 panic。

Q3：INSTANCE 能随便写吗？

不能。它必须与控制台里节点的 key 一致（控制台添加节点时生成），否则 console 侧节点状态与下发目标对不上。实测环境中 INSTANCE=dbcf5af2f61546367cae44869e1dc21a 与 /node/getList 的 nodeKey 完全一致。

Q4：节点版本号为什么显示 3.1.4 而镜像 tag 是 3.1.5？

node 3.1.5 镜像内部 version 文件内容为 3.1.3、注册上报为 3.1.4，属官方镜像的历史遗留（三层版本号），逐项取证见本专栏部署篇 2.3 节；功能与配置下发不受影响。

Q5：首启管理员密码登录不上？

console 初始化时对 -p 密码做了双重 MD5 落库而登录校验只做单次 MD5（实测 goku_admin.loginPassword = md5(md5("q1w2e3r4"))），排障与重置步骤见本专栏部署篇 FAQ Q3。

Q6：改了配置怎么生效？

console 文件参数（端口/数据库）改文件后重启进程；管理面对象（策略/负载/API）在控制台发布新版本配置，node 免重启热更新（官方 README：Continuously updates configurations without restart nodes）。

八、参考链接

1. 本专栏认知篇（架构、版本现状、选型对比）：《Goku Gateway 3.1.x 介绍与选型指南》
2. 本专栏部署篇（两件套部署、端口映射、持久化与排障实录）：见专栏《Goku Gateway 3.1.x Docker Compose 部署指南》
3. 本专栏命令篇（CLI 与 Open API 实测）：见专栏《Goku Gateway 3.1.x 管理面与 CLI 命令详解》
4. GitHub 仓库（含 config/config.go 源码）：https://github.com/eolinker/goku_lite
5. 官方文档站：https://help.eolinker.com/