GameAP 4.5.8 配置参数详解

目标：把 GameAP v4.5.8 的全部配置项（环境变量族）按功能分类逐项讲清含义、默认值与生效方式，并给出可直接落地的生产模板。参数清单以官方 README（查询日期 2026-11-02）与 v4.5.8 源码 internal/config/config.go（共 216 个 env: 标签）为权威依据，关键行为均经真实服务器实测验证。

一、环境信息

• 服务器：Ubuntu 24.04.5 LTS（x86_64），GameAP v4.5.8（Build date: 2026-10-18T17:08:49+00:00）
• 权威来源：github.com/gameap/gameap README「Configuration」节 + 源码 internal/config/config.go（env 标签与 envDefault 值）
• 验证环境：面板以 PostgreSQL 17 + Redis 7 全栈运行（部署过程见 《GameAP Docker Compose 部署指南》），另以 SQLite 单机形态对照验证若干默认值行为

二、前置条件

• 已完成 GameAP 安装并能启动（安装路径任选官方脚本或 Compose，见站内部署篇）；
• 具备生成强随机密钥的能力：openssl rand -hex 32；
• 理解一条总原则：GameAP 没有独立配置文件格式，全部配置 = 环境变量。二进制仅接受一个命令行参数 -env <path> 指向 env 文件（见 3.1）。

三、参数查看与修改方式

3.1 唯一的命令行参数：-env

实测 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

-testify.m 是 Go 测试框架残留参数，运维中只用 -env 与 -version：

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

3.2 env 文件与 systemd

gameapctl panel install（系统级）生成的配置在 /etc/gameap/config.env，由 systemd 单元 EnvironmentFile= 注入；rootless（--scope=user）形态在 ~/.config/gameap/config.env。修改后需重启面板进程生效（gameapctl panel restart）。

3.3 查看当前生效值

面板无「导出全量配置」API，实操两条路：

# ① 读配置源文件
cat /etc/gameap/config.env

# ② 读进程环境（root）
tr '\0' '\n' < /proc/$(pgrep -x gameap)/environ | grep -E '^(HTTP|DATABASE|CACHE|FILES|AUTH|ENCRYPTION|GRPC|PLUGINS|SECURITY)_'

启动日志会打印关键生效值（gRPC 端口/TLS、bcrypt cost、blocklist 条数、pub-sub driver 等），是最可靠的「实际生效」证据，见各分类下的实测行。

⚠️ 注意：源码 config.go 的 envDefault 标签才是最终权威——README 个别措辞与代码默认值存在出入时，以代码为准；本文两处的取值均经实测日志核对。

四、参数总览

按前缀族分类（v4.5.8，共 216 个 env 标签，README 全量清单核对一致）：

五、核心参数分类详解

5.1 服务监听

5.2 TLS 终结（面板自终结，无需反代）

三个证书来源按优先级择优：ACME > 静态文件 > 内联 PEM；三者皆未配置则 HTTPS 监听不启动、只跑 HTTP。

⚠️ 注意：TLS_FORCE_HTTPS=true 但 HTTPS 端口不可达时会锁死管理入口，开跳转前先验证 443/8443 可达（gameapctl README 同样强调此点）。

5.3 Let's Encrypt（ACME，内嵌 lego 客户端）

关键行为：首次签发失败（LE 不可达/DNS 配错）面板直接退出码 1，不会静默回落 HTTP。多实例横向扩展时官方推荐 dns-01 + CACHE_DRIVER=redis + FILES_DRIVER=s3（Redis 兼作续期分布式锁，S3 让所有副本读同一证书）。状态查询：GET /api/admin/letsencrypt/status，state ∈ disabled/pending/active/renewing/failed。

5.4 数据库

三种生产 URL 格式（官方 README 原文）：

MySQL:      username:password@tcp(host:port)/database?parseTime=true
PostgreSQL: postgres://username:password@host:port/database?sslmode=disable
SQLite:     file:path/to/database.db?_busy_timeout=5000&_journal_mode=WAL&cache=shared

💡 技术拓展：SQLite URL 的三个参数是官方推荐的并发组合——_journal_mode=WAL（预写日志，读写不互斥）、_busy_timeout=5000（写锁竞争时重试 5s）、cache=shared（同进程共享页缓存）。对比 MySQL/PG 走服务端并发控制，SQLite 仅适合单机低并发；面板多实例部署禁用 SQLite。

实测：PG 形态启动时按序应用 23 条迁移（Applied migration path=001_create_gameap_tables.sql version=1 result="OK up ... (22.37ms)"）；SQLite 形态同库文件首启建表。

5.5 认证与安全

实测行为三条：

1. AUTH_SECRET 给 64 个 hex 字符时启动打印 WARN Auth secret key is longer than 32 bytes, trimming the key to 32 bytes length=64——密钥被截为 32 字节使用，属预期，不影响功能但别指望 64 字符全量参与签名；
2. 密码策略硬编码下限：改密 API 提交 8 位口令返回 400 invalid input: password must be at least 12 characters long（min 12 / max 128 不可配）；
3. 启动日志 INFO Password blocklist loaded entries=46146 source=embedded 与 INFO password hashing configured bcrypt_cost=13——bcrypt cost 13 为编译期固定，无 env 可调。

5.6 管理员种子

5.7 RBAC 与缓存

单机可全默认（memory）；多实例必须换 redis/postgres，否则 SSO 票据、ACME 锁、插件同步都不可用。

5.8 文件存储与上传会话

⚠️ 注意：走 nginx 反代时 client_max_body_size 默认 1m 会以 413 拒掉 8M 分块，官方 DOCKER.md 建议 ≥64m。

5.9 日志与审计

审计事件走结构化日志（实测行照抄）：

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

5.10 gRPC 节点通道（面板侧）

源码 config.go envDefault 权威值：

实测启动行：INFO Starting gRPC server address=0.0.0.0:31718 tls_enabled=true mtls_required=false reflection_enabled=false max_recv_mb=10 max_send_mb=10。

5.11 消息总线（PUBSUB）

单机实测启动行 INFO Starting pub-sub listener driver=memory 即默认形态。

5.12 插件系统（PLUGINS_* 族，60+ 项）

v4.5.8 起统一 PLUGINS_ 前缀（旧 PLUGIN_* 拼写仍被接受，启动时翻译并警告改名，未来版本移除）。分五组：

加载与运行时：

权限与恢复：

调度器限额：PLUGINS_SCHEDULER_MIN_INTERVAL(1s)、MAX_TASKS_PER_PLUGIN(32)、CALL_TIMEOUT(60s)、MAX_CALL_TIMEOUT(5m)、MAX_RETRIES(10)、MAX_RETRY_DELAY(10m)、MAX_JITTER(30s)、REFRESH_INTERVAL(30s)。

节点文件与命令（gameap-nodefs/nodecmd）：

实测启动行：INFO plugin node path policy configured mode=unrestricted allowed_paths=0。

存储/缓存/密钥限额：PLUGINS_STORAGE_MAX_KEYS_PER_PLUGIN(10000)、PLUGINS_STORAGE_MAX_VALUE(1M)、PLUGINS_STORAGE_MAX_TOTAL(64M)、PLUGINS_CACHE_MAX_VALUE(1M)、PLUGINS_SECRETS_MAX_KEYS_PER_PLUGIN(64)、PLUGINS_SECRETS_MAX_VALUE(8K)、PLUGINS_SECRETS_REQUIRE_ENCRYPTION(true，ENCRYPTION_KEY 未设时拒绝写密钥)。

同步：PLUGINS_SYNC_DISABLED(false)、PLUGINS_SYNC_REFRESH_INTERVAL(60s)、PLUGINS_SYNC_MIN_BACKOFF(15s)、PLUGINS_SYNC_MAX_BACKOFF(15m)。

限流（每实例令牌桶，RPS/Burst）：nodecmd 5/20、servercontrol 5/20、nodefs 50/200、http 20/50、rbac 10/50、ssh 20/60；被拒调用返回 rate limited: ...，插件不崩。

5.13 插件能力边界（防插件横向渗透，默认严格）

5.14 插件市场

PLUGINS_STORE_URL（默认 https://plugins.gameap.dev/api）、PLUGINS_STORE_LICENSE_KEY（商业插件许可）。

5.15 CAPTCHA（登录防爆破）

5.16 安全响应头（默认全开）

SECURITY_HEADERS_ENABLED=true 总开关；HSTS 族（HSTS_ENABLED=true、HSTS_MAX_AGE=31536000、INCLUDE_SUBDOMAINS=false、PRELOAD=false，仅 TLS 请求下发）；CONTENT_TYPE_OPTIONS=nosniff、FRAME_OPTIONS=SAMEORIGIN、REFERRER_POLICY=strict-origin-when-cross-origin；CSP 族（CSP_ENABLED=true、REPORT_ONLY=false、POLICY 整策覆盖、REPORT_URI、EXTRA_{SCRIPT,STYLE,CONNECT,IMG,FRAME,FONT}_SRC 追加白名单）。CSP 自动按 CAPTCHA provider 放行对应第三方源，未开 CAPTCHA 时零第三方。

5.17 指标与其他

六、生产配置模板

模板 A：多节点生产（16GB 内存 / NVMe SSD / PG17 + Redis7，对应游戏托管业务）

# /etc/gameap/config.env
HTTP_HOST=panel.example.com
HTTP_PORT=443
HTTPS_PORT=443
TLS_FORCE_HTTPS=true
ACME_ENABLED=true
ACME_CHALLENGE_TYPE=dns-01
ACME_EMAIL=ops@example.com
ACME_DOMAINS=panel.example.com
ACME_DNS_PROVIDER=cloudflare

DATABASE_DRIVER=postgres
DATABASE_URL=postgres://gameap:<DB强口令>@db.example.com:5432/gameap?sslmode=require
DATABASE_CONNECT_TIMEOUT=30s

ENCRYPTION_KEY=<openssl rand -hex 32 输出>
AUTH_SECRET=<openssl rand -hex 32 输出>
AUTH_SERVICE=paseto
AUTH_REQUIRE_MFA_FOR_ADMINS=true

CACHE_DRIVER=redis
CACHE_REDIS_ADDR=redis.example.com:6379
CACHE_REDIS_PASSWORD=<Redis口令>
PUBSUB_DRIVER=redis
PUBSUB_REDIS_ADDR=redis.example.com:6379
PUBSUB_REDIS_DB=1
PUBSUB_INSTANCE_ID=panel-1

FILES_DRIVER=s3
FILES_S3_ENDPOINT=https://s3.example.com
FILES_S3_USE_SSL=true
FILES_S3_ACCESS_KEY_ID=<AK>
FILES_S3_SECRET_ACCESS_KEY=<SK>
FILES_S3_BUCKET=gameap

PLUGINS_PERMISSIONS_ENFORCE=true
PLUGINS_NODEFS_PATH_POLICY=node_workpath
LOGGER_LEVEL=info
METRICS_TOKEN=<Prometheus抓取口令>

要点：多实例必须 redis(pub/sub)+s3 共享状态；dns-01 免 80 端口依赖；PLUGINS_PERMISSIONS_ENFORCE=true 提前对齐未来默认。

模板 B：单机自托管（4GB 内存 / SQLite，个人游戏服）

HTTP_HOST=0.0.0.0
HTTP_PORT=8025
DATABASE_DRIVER=sqlite
DATABASE_URL=file:/var/lib/gameap/db.sqlite?_busy_timeout=5000&_journal_mode=WAL&cache=shared
ENCRYPTION_KEY=<openssl rand -hex 32 输出>
AUTH_SECRET=<openssl rand -hex 32 输出>
CACHE_DRIVER=memory
FILES_DRIVER=local
FILES_LOCAL_BASE_PATH=/var/lib/gameap/files
LOGGER_LEVEL=info

七、常见问题

7.1 裸跑 panic failed to open root directory: open /var/www/gameap/storage/app: no such file or directory

FILES_LOCAL_BASE_PATH 未设且缺省目录不存在（实测复现）。设变量或预建目录即恢复，见 5.8。

7.2 启动 WARN Auth secret key is longer than 32 bytes, trimming the key to 32 bytes length=64

AUTH_SECRET 超 32 字节被截断使用（实测），预期行为；想全量利用可改传 base64/原始 32 字节。

7.3 改密报 400 password must be at least 12 characters long

min 12 / max 128 为硬编码策略（实测），AUTH_ALLOW_WEAK_PASSWORDS 只关黑名单、不关长度。另 PUT /api/users/1 必须同时带 email，否则先报 email is required（实测）。

7.4 启动 WARN plugin permission enforcement is disabled

PLUGINS_PERMISSIONS_ENFORCE 默认 false（实测 + 源码一致）。生产建议显式 true 并对已装插件回归验证权限声明。

7.5 旧 PLUGIN_* 变量名还生效吗

生效但启动时逐个翻译并警告新名（README 明示），如 PLUGINS_RUNTIME_CACHE_ENABLED 原名 PLUGIN_COMPILE_CACHE_*；未来版本将移除旧名，新部署一律用 PLUGINS_ 前缀。

7.6 多实例部署 SSO 票据/ACME 续期随机失败

CACHE_DRIVER/PUBSUB_DRIVER 仍是 memory——票据在一台签发、浏览器到另一台兑换即失效，续期锁失去互斥。改 redis/postgres 共享（见 5.7/5.11 与模板 A）。

八、参考链接

• 官方 README「Configuration」全量 env 清单：https://github.com/gameap/gameap （查询日期 2026-11-02）
• 源码权威默认值：github.com/gameap/gameap internal/config/config.go（v4.5.8，216 个 env 标签）
• 官方部署文档：https://github.com/gameap/gameap/blob/main/DOCKER.md
• 文档站：https://docs.gameap.com
• 站内相关：《GameAP 介绍与选型指南》、《GameAP Docker Compose 部署指南》、《GameAP 4.5.8 常用 CLI 命令与工具详解》