GameAP 4.5.8 常用 CLI 命令与工具详解

目标：讲透 GameAP v4.5.8 生态的三个命令行工具——面板二进制 gameap、管理 CLI gameapctl、节点代理 gameap-daemon——的全部子命令、参数默认值与真实回显，覆盖安装、托管、HTTPS、节点注册、自助升级的完整运维动线。本文所有 --help/--version 回显均为 Ubuntu 24.04.5 LTS（x86_64）服务器上逐行实测照抄。

一、环境信息

服务器：Ubuntu 24.04.5 LTS（x86_64），systemd 托管
面板二进制：GameAP v4.5.8（Build date: 2026-10-18T17:08:49+00:00）
管理 CLI：gameapctl v0.34.0（Build Date: 2026-09-02T15:00:32+00:00）
节点代理：GameAP Daemon v4.1.5（Build Date: 2026-09-20T02:09:14+00:00，Go 1.27.0 linux/amd64）
面板 Web/API 端口 8025、gRPC 31718、Daemon 监听 31717
演示管理账号：admin / q1w2e3r4

二、工具概览

工具	角色	命令面	获取方式
`gameap`	面板主进程	无子命令，仅 `-env` / `-version` 两个 flag	GitHub release `gameap-v4.5.8-linux-amd64.tar.gz`；或 gameapctl 安装时落盘 `/usr/bin/gameap`
`gameapctl`	安装与运维总管	`daemon(d)` / `panel(p)` / `ui` / `self-update` / `send-logs` / `version(v)`	GitHub release；或官方脚本
`gameap-daemon`	节点代理	`version(v)` / `enroll`	GitHub release `gameap-daemon-v4.1.5-linux-amd64.tar.gz`；或 gameapctl daemon install

官方一键安装脚本（root 执行，下载 gameapctl 与 Daemon）：

bash <(curl -s https://gameap.com/install.sh)

💡 技术拓展：GameAP 的「面板安装」与「节点接入」分属两条 CLI 动线——gameapctl panel install 装面板本体，gameapctl daemon install --connect=grpc://…/<setup-key>（或直接 gameap-daemon enroll）装节点。对比 Pterodactyl 需要面板后台手工建节点再配密钥，GameAP 的节点接入是 Daemon 侧发起的 enrollment 单向动作，面板只需给一个 32 位 setup-key。

三、前置条件

三个二进制均可直接执行（静态获取、动态 glibc 链接，Debian/Ubuntu 系可直接运行；musl 环境如 Alpine 会报 not found，需换 glibc 载体）；
gameapctl panel install 的 --scope=system 需 root + systemd；--scope=user 需真实登录会话（ssh user@host，不能 su/sudo -u，否则 systemctl --user 够不到用户总线）与 lingering（sudo loginctl enable-linger $USER）；
面板 Web 可用（本文示例 http://127.0.0.1:8025，部署见《GameAP Docker Compose 部署指南》）。

四、gameap 面板二进制详解

4.1 全量帮助（实测逐行照抄）

$ ./gameap --help
Usage of ./gameap:
  -env string
    	Path to environment file
  -testify.m string
    	regular expression to select tests of the testify suite to run
  -version
    	Print version information and exit

面板本体刻意极简：配置全部走环境变量（-env 指向 env 文件），运行控制交给 systemd/gameapctl，-testify.m 为 Go 测试框架残留参数、生产无用途。

4.2 版本查询

$ ./gameap --version
GameAP v4.5.8
Build date: 2026-10-18T17:08:49+00:00

4.3 启动与运行参数

$ ./gameap -env /etc/gameap/config.env

实测启动关键日志（SQLite 单机形态，逐行照抄）：

INFO Password blocklist loaded entries=46146 source=embedded
INFO password hashing configured bcrypt_cost=13
WARN Auth secret key is longer than 32 bytes, trimming the key to 32 bytes length=64
INFO Admin user seeded successfully login=admin email=admin@example.com
INFO GameAP started version=v4.5.8 build_date=2026-10-18T17:08:49+00:00

登录动作产生结构化审计行（实测）：

INFO audit event_type=auth.login.success actor_login=admin ip=127.0.0.1 http_method=POST path=/api/auth/login

⚠️ 注意：FILES_LOCAL_BASE_PATH 未设时启动直接 panic：failed to open root directory: open /var/www/gameap/storage/app: no such file or directory（实测）。裸跑务必显式设置该变量或预建目录，详见配置篇。

五、gameapctl 管理 CLI 详解

5.1 顶层帮助与版本（实测逐行照抄）

$ gameapctl --help
NAME:
   gameapctl - GameAP Control

USAGE:
   Find more information at: https://docs.gameap.com/

COMMANDS:
   daemon, d    Daemon actions
   panel, p     GameAP web part actions
   ui           Web interface in default browser. 
   self-update  Update the gameapctl binary to the latest version
   send-logs    Send logs to GameAP support
   version, v   Print version information
   help, h      Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --non-interactive  (default: false)
   --skip-warnings    (default: false)
   --debug            (default: false) [$DEBUG]
   --help, -h         show help

$ gameapctl version
Version: v0.34.0
Build Date: 2026-09-02T15:00:32+00:00

三个全局开关值得记住：--non-interactive（脚本化安装免问答）、--skip-warnings（压掉前置依赖警告）、--debug（排障）。

5.2 panel 子命令族（实测逐行照抄）

$ gameapctl panel --help
NAME:
   gameapctl panel - GameAP web part actions

USAGE:
   gameapctl panel [command options]

DESCRIPTION:
   GameAP web part actions

COMMANDS:
   install, i          Install panel
   start               Start GameAP
   stop                Stop GameAP
   restart             Restart GameAP
   status              GameAP Status
   upgrade, update, u  Update panel to a new version
   uninstall           Uninstall GameAP panel. 
   change-password     Change user password
   https               Manage HTTPS for the panel
   help, h             Shows a list of commands or help for one command

OPTIONS:
   --help, -h  show help

start/stop/restart/status 即 systemd 单元的薄封装（gameap.service），rootless 安装自动作用于 user unit——scope 在安装时记录于 ~/.gameapctl 状态文件，后续命令无需重复传 --scope。

5.3 panel install 参数全表（实测逐行照抄）

$ gameapctl panel install --help
NAME:
   gameapctl panel install - Install panel

USAGE:
   gameapctl panel install [command options]

DESCRIPTION:
   Install panel

OPTIONS:
   --path value               Path to GameAP root directory
   --scope value              Installation scope: 'system' (default, requires root; unit in /etc/systemd/system, binary in /usr/bin, config in /etc/gameap, data in /var/lib/gameap) or 'user' (rootless: systemd user unit, binary in ~/.local/bin, config in ~/.config/gameap, data in ~/.local/share/gameap; Linux only). In user scope ports below 1024 and automatic database server installation are unavailable. (default: "system") [$SCOPE]
   --host value               
   --port value               
   --web-server value         
   --develop                  Install develop version of panel. (default: false)
   --version value            Install specific GameAP release tag (e.g. 4.1, 4.1.2, v4.2.0beta1). Empty = latest stable v4. v3.x is not supported.
   --github                   Install gameap from GitHub. (default: false)
   --database value           Database type. Available: postgres, mysql, sqlite, none.
   --database-host value      
   --database-port value      
   --database-name value      
   --database-username value  
   --database-password value  
   --with-daemon              Daemon will be also installed with panel.  (default: false)
   --grpc-port value          Override gRPC port written to panel config.env (panels >= v4.2). Default: 31718.
   --help, -h                 show help

实操要点（官方 gameapctl README，查询日期 2026-11-02）：

端口探测：系统级默认监听 80，被占用时自动顺延探测 8025、8026…最多十个，README 原文示例回显 Port 80 is already in use, port 8025 will be used instead.；手工指定 --port=8080 则永不替换，端口冲突直接报错并提示空闲口——脚本化安装因此要么拿到指定端口要么失败，行为可预期；
--version：只接受 v4 线（4.1、v4.2.0beta1 等写法均可），v3.x 不支持——旧 PHP 版迁移需另行评估；
--database=none：不装数据库服务，配合 --database-host 等指向既有 PG/MySQL；--scope=user 下 mysql|postgres 仅可指向既有实例（无 root 无法 apt/dnf）；
--with-daemon：面板与节点同机时一条命令全装。

典型安装命令：

# 单机最小生产：SQLite + 面板 + 同机 Daemon
gameapctl panel install --database=sqlite --with-daemon

# rootless：普通用户装到 ~/.local/bin 与 ~/.config/gameap
gameapctl panel install --scope=user --host=<host> --database=sqlite

5.4 panel https 子命令族（实测逐行照抄）

$ gameapctl panel https --help
NAME:
   gameapctl panel https - Manage HTTPS for the panel

USAGE:
   gameapctl panel https [command options]

DESCRIPTION:
   Serve the panel over HTTPS with a self-signed certificate, with a certificate you already have, or with Let's Encrypt. The panel terminates TLS itself, so there is no web server to configure.

COMMANDS:
   enable       Enable HTTPS and restart the panel
   disable      Disable HTTPS and restart the panel
   status       Show the HTTPS configuration
   letsencrypt  Manage Let's Encrypt (ACME) certificates
   help, h      Shows a list of commands or help for one command

OPTIONS:
   --help, -h  show help

enable 的行为细节（官方 README）：自签证书覆盖 HTTP_HOST、主机名、全部网卡地址与回环，有效期 825 天；--domain/--ip 可重复收窄，--force 提前重签；已有证书仍覆盖全部所需名称且未临近过期则复用（浏览器已接受的例外不失效）；--cert/--key 直接指向既有证书（可对接外部 ACME 客户端的产物）。enable 会验证面板以新证书重新拉起后才算成功，失败自动回滚旧 config.env。证书路径与默认端口：

形态	证书	私钥	默认 HTTPS 端口
system scope	`/etc/gameap/certs/panel.crt`	`/etc/gameap/certs/panel.key`	443
user scope	`~/.config/gameap/certs/panel.crt`	`~/.config/gameap/certs/panel.key`	8443
Windows	`C:\gameap\web\certs`	同目录	—

Let's Encrypt 走 gameapctl panel https letsencrypt（交互式向导，也接受 --challenge/--domains/--email/--dns-provider/--staging/--env KEY=VALUE/--non-interactive），写入 ACME_* 并重启服务；ACME 配置存在时 enable 拒绝执行（ACME 优先于磁盘证书）。

5.5 daemon 子命令族（实测逐行照抄）

$ gameapctl daemon --help
NAME:
   gameapctl daemon - Daemon actions

USAGE:
   gameapctl daemon [command options]

DESCRIPTION:
   Daemon actions

COMMANDS:
   install, i          Install daemon
   upgrade, update, u  Update daemon to a new version
   start, s            Start daemon
   stop                Stop daemon
   status              Daemon status
   restart, r          Restart daemon
   help, h             Shows a list of commands or help for one command

OPTIONS:
   --help, -h  show help

$ gameapctl daemon install --help
NAME:
   gameapctl daemon install - Install daemon

USAGE:
   gameapctl daemon install [command options]

DESCRIPTION:
   Install daemon

OPTIONS:
   --connect value                      Connect URL for gRPC enrollment (grpc://host:port/key) [$CONNECT_URL]
   --scope value                        Installation scope: 'system' (default, requires root, writes to /etc and /usr/bin) or 'user' (systemd user units, files under $HOME; Linux only). (default: "system") [$SCOPE]
   --token value                         [$CREATE_TOKEN]
   --host value                          [$PANEL_HOST]
   --config value                        [$CONFIG]
   --work-path value, --work-dir value  Daemon working directory, must be an absolute path (default: /srv/gameap on Linux, C:\gameap on Windows) [$WORK_PATH]
   --github                             Install daemon from GitHub source. (default: false)
   --version value                      Install specific gameap-daemon release tag (e.g. v4.0.0, v4.0.0beta1). Empty = latest stable.
   --help, -h                           show help

--connect 的 setup-key 从面板 API 取（见 6.3）。--work-path 必须是绝对路径，默认 /srv/gameap（Windows C:\gameap）。

5.6 self-update 与其他（实测逐行照抄）

$ gameapctl self-update --help
NAME:
   gameapctl self-update - Update the gameapctl binary to the latest version

USAGE:
   gameapctl self-update [command options]

DESCRIPTION:
   Update the gameapctl binary to the latest version

OPTIONS:
   --force          Update even if dev version is used.  (default: false)
   --github         Build gameapctl from GitHub source. (default: false)
   --version value  Update to specific gameapctl release tag (e.g. 0.26.0, v0.26.0). Empty = latest.
   --help, -h       show help

ui 用默认浏览器打开安装向导页（自动预填探测到的端口）；send-logs 将日志打包发给官方支持（提 Issue 前的排障通道）。

5.7 文件布局速查（官方 README 实测口径）

内容	system scope	user scope
面板配置	`/etc/gameap/config.env`	`~/.config/gameap/config.env`
面板数据	`/var/lib/gameap`	`~/.local/share/gameap`
面板二进制	`/usr/bin/gameap`	`~/.local/bin/gameap`
面板单元	`/etc/systemd/system/gameap.service`	`~/.config/systemd/user/gameap.service`
Daemon 配置	`/etc/gameap-daemon/gameap-daemon.yaml`	`~/.config/gameap-daemon/gameap-daemon.yaml`
Daemon 工作目录	`/srv/gameap`	`~/gameap`
Daemon 二进制	`/usr/bin/gameap-daemon`	`~/.local/bin/gameap-daemon`
Daemon 单元	`/etc/systemd/system/gameap-daemon.service`	`~/.config/systemd/user/gameap-daemon.service`

六、gameap-daemon 节点代理详解

6.1 帮助与版本（实测逐行照抄）

$ ./gameap-daemon --help
NAME:
   gameap-daemon - GameAP Daemon

USAGE:
   gameap-daemon [global options] command [command options]

COMMANDS:
   version, v  Display gameap version
   enroll      Enroll this daemon with the GameAP panel
   help, h     Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --config value, -c value  Path to gameap-daemon config
   --help, -h                show help

$ ./gameap-daemon version
GameAP Daemon version: v4.1.5
Build Date: 2026-09-20T02:09:14+00:00
Go OS/Arch: linux amd64
Go Version: go1.27.0

日常托管形态是 -c /etc/gameap-daemon/gameap-daemon.yaml 直接跑（systemd 单元即如此）；命令行显式子命令只有 enroll 一个——它是「入网」动作，成功后才生成配置文件。

6.2 enroll 参数全表（实测逐行照抄）

$ ./gameap-daemon enroll --help
NAME:
   gameap-daemon enroll - Enroll this daemon with the GameAP panel

USAGE:
   gameap-daemon enroll [command options]

OPTIONS:
   --connect value        Connect URL (grpc://host:port/setupKey)
   --config-path value    Path to write config file (default: "/etc/gameap-daemon/gameap-daemon.yaml")
   --certs-dir value      Directory to save TLS certificates (default: "/etc/gameap-daemon/certs")
   --listen-ip value      IP address the daemon listens on (default: "0.0.0.0")
   --listen-port value    Port the daemon listens on (default: 31717)
   --work-path value      Working directory for game servers (default: "/srv/gameap")
   --steamcmd-path value  Directory where steamcmd is installed (default: "/srv/gameap/steamcmd")
   --help, -h             show help

真实默认值全部来自上表回显：监听 0.0.0.0:31717、游戏目录 /srv/gameap、SteamCMD 目录 /srv/gameap/steamcmd、证书目录 /etc/gameap-daemon/certs。

6.3 节点注册全流程（实测）

第一步，面板侧签发 setup-key（登录取 token 后）：

$ TOKEN=$(curl -s -X POST http://127.0.0.1:8025/api/auth/login \
    -H 'Content-Type: application/json' \
    -d '{"login":"admin","password":"q1w2e3r4"}' | jq -r .token)
$ curl -s -X POST http://127.0.0.1:8025/api/nodes/setup-key \
    -H "Authorization: Bearer $TOKEN"
{"setup_key":"gxaGOpNKUWxYUml41z0R3vTbgbmzKZYy"}

第二步，节点侧 enroll。先记录一次失败实录：用主机名连接时 gRPC 证书 SAN 校验不过（面板自签证书 SAN 仅 localhost + 面板 IP）：

$ ./gameap-daemon enroll --connect grpc://gameap-panel:31718/gxaGOpNKUWxYUml41z0R3vTbgbmzKZYy
x509: certificate is valid for localhost, not gameap-panel

改用面板 IP 后成功：

$ ./gameap-daemon enroll --connect grpc://10.89.56.4:31718/gxaGOpNKUWxYUml41z0R3vTbgbmzKZYy
Successfully registered with panel

注册握手同步下发游戏库（面板 RegisterAck 实测 games=43、gameMods=47）。

第三步，面板侧核验节点入网：

$ curl -s http://127.0.0.1:8025/api/nodes -H "Authorization: Bearer $TOKEN"
[{"id":1,"enabled":true,"name":"10.89.56.5","os":"linux","ip":["10.89.56.5"]}]

注意 POST /api/nodes 手工建节点返回 405——节点只能由 Daemon enrollment 产生，这是 GameAP 的固定工作流。

6.4 enroll 生成的配置文件

/etc/gameap-daemon/gameap-daemon.yaml（实测产物节选，密钥值打码）：

ds_id: 1
api_key: <enroll 生成的 64 位随机密钥>
ca_certificate_file: /etc/gameap-daemon/certs/ca.crt
certificate_chain_file: /etc/gameap-daemon/certs/server.crt
private_key_file: /etc/gameap-daemon/certs/server.key
work_path: /srv/gameap
steamcmd_path: /srv/gameap/steamcmd
log_level: info
grpc:
  address: 10.89.56.4:31718

grpc.address 记录的就是 enroll 时通过校验的面板地址——后续 gameap-daemon -c … 长跑即按它维持双向长连接。

七、注意事项

rootless 限制（官方 README 汇总）：--scope=user 下 1024 以下端口不可用（systemd user unit 无法授予 CAP_NET_BIND_SERVICE，除非管理员调低 net.ipv4.ip_unprivileged_port_start）；不会代装数据库服务；Let's Encrypt http-01 不可用（需 80），要用 --challenge=dns-01；不创建 gameap 系统用户，一切以当前用户运行；
PATH 坑：user scope 二进制落 ~/.local/bin，非登录 shell 常缺该路径，手工运行 gameap 前 export PATH="$HOME/.local/bin:$PATH"（systemd 单元用绝对路径不受影响）；
Daemon 前置依赖：curl 与 gpg 需预装（进程管理器改用 tmux 形态时另需预装 tmux）；SteamCMD 在 64 位系统还需 32 位运行库 lib32gcc、lib32stdc++6、lib32z1——安装器只警告不代装；
OS 支持矩阵（gameapctl 自动测试覆盖，官方 README）：Debian 9–13、Ubuntu 16.04–24.04、CentOS 7 与 Stream 8/9/10、AlmaLinux 9、Fedora 43、Windows Server 2016–2025 与 Win10/11 均 ✔；Amazon Linux 2023 与 Rocky 9.3 为 ⚠（无 i686 用户空间，部分形态受限）。

八、常见问题

8.1 enroll 报 `x509: certificate is valid for localhost, not <主机名>`

实测排障：面板 gRPC 自签证书 SAN 只含 localhost 与面板自身 IP（启动日志 dns_names=[localhost] ip_addresses="[10.89.56.4 127.0.0.1]" 可证）。解决：--connect 用面板 IP；或为面板配置含域名 SAN 的证书后重连。

8.2 改管理员密码被 400 拒绝

gameapctl panel change-password 与 API 同受密码策略约束：min 12 / max 128 + 弱口令黑名单（实测 8 位口令报 invalid input: password must be at least 12 characters long）。演示口令 q1w2e3r4 仅因走 ADMIN_PASSWORD 种子路径才安装成功，上线请改 ≥12 位。

8.3 gameap 二进制「怎么没有子命令」

设计使然（见 4.1）：面板二进制的安装/启停/升级/HTTPS 全部由 gameapctl 承担，gameap 自身只认 -env 与 -version。

8.4 Alpine 环境跑 release 二进制报 `not found`

官方 release 二进制为 glibc 动态链接，musl 环境不可直接运行（实测 not found）；换 Debian/Ubuntu 载体或自行静态编译。

九、参考链接

gameapctl 仓库与 README：https://github.com/gameap/gameapctl （查询日期 2026-11-02）
GameAP Daemon 仓库：https://github.com/gameap/daemon
面板仓库与官方脚本：https://github.com/gameap/gameap 、https://gameap.com/install.sh
文档站：https://docs.gameap.com
站内相关：《GameAP 介绍与选型指南》、《GameAP Docker Compose 部署指南》、《GameAP 4.5.8 配置参数详解》

GameAP 4.5.8 常用 CLI 命令与工具详解

GameAP 4.5.8 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、gameap 面板二进制详解

4.1 全量帮助（实测逐行照抄）

4.2 版本查询

4.3 启动与运行参数

五、gameapctl 管理 CLI 详解

5.1 顶层帮助与版本（实测逐行照抄）

5.2 panel 子命令族（实测逐行照抄）

5.3 panel install 参数全表（实测逐行照抄）

5.4 panel https 子命令族（实测逐行照抄）

5.5 daemon 子命令族（实测逐行照抄）

5.6 self-update 与其他（实测逐行照抄）

5.7 文件布局速查（官方 README 实测口径）

六、gameap-daemon 节点代理详解

6.1 帮助与版本（实测逐行照抄）

6.2 enroll 参数全表（实测逐行照抄）

6.3 节点注册全流程（实测）

6.4 enroll 生成的配置文件

七、注意事项

八、常见问题

8.1 enroll 报 x509: certificate is valid for localhost, not <主机名>

8.2 改管理员密码被 400 拒绝

8.3 gameap 二进制「怎么没有子命令」

8.4 Alpine 环境跑 release 二进制报 not found

九、参考链接

8.1 enroll 报 `x509: certificate is valid for localhost, not <主机名>`

8.4 Alpine 环境跑 release 二进制报 `not found`