环境变量配置参考

按当前代码与部署模板说明。使用配套程序、资源和配置；下列值是公开默认值或示例，不代表某台服务器的实际环境。

常用配置

• 战斗范围与随机瞬移：客户端默认值、服务端同步范围。
• HP／SP 恢复及拾取：自动恢复、自动拾取。
• 新手出生位置：游戏服务端中的 HAPPYRO_NEW_PLAYER_START。
• 传送、召怪与工具权限：玩法权限。
• 游戏地址、端口与后台开关：Docker 部署入口。
• 镜头、画质和声音：客户端设置。

常用示例

# 地图服（下面一项由地图服读取）
HAPPYRO_AREA_SIZE=14
# 客户端默认值（下面各项由 Gateway 读取）
CLIENT_AUTO_COMBAT_SEARCH_RANGE=14
CLIENT_AUTO_COMBAT_ACTIVITY_RANGE=30
CLIENT_AUTO_TELEPORT_ENABLED=true
CLIENT_AUTO_TELEPORT_WAIT_SECONDS=2
CLIENT_AUTO_TELEPORT_INTERVAL_SECONDS=2

Docker 在部署目录 .env 填写；原生部署将地图服项放入 profile，CLIENT_* 放入 Gateway 环境。修改后按下一节生效，已有玩家偏好可能优先于默认值。

配置位置与生效方式

场景	配置位置	修改后如何生效
场景Docker 离线包	配置位置部署目录 .env，参照同包 .env.example	修改后如何生效重新创建受影响容器；仅 restart 不会更新容器环境
场景Gateway 原生运行	配置位置repos/happyro-gateway/.env，参照根仓库 deploy/remote-client/.env.example	修改后如何生效重启 Gateway；客户端配置还需刷新网页
场景Linux 原生游戏服务	配置位置根仓库 deploy/rathena/profile.env，通过配套启动脚本传入	修改后如何生效重启相关服务
场景macOS 原生地图服	配置位置同一个 deploy/rathena/profile.env	修改后如何生效macos-services.sh start 同步地图服 plist；已加载服务需 stop/start，单独 kickstart 不读取 profile
场景独立 systemd 地图服	配置位置unit 的 Environment= 或 EnvironmentFile=	修改后如何生效重载 unit 后重启地图服
场景Go API 原生运行	配置位置导出进程环境，或 systemd EnvironmentFile / launchd EnvironmentVariables	修改后如何生效重启 API；Go API 不自动加载 .env
场景Admin 前端	配置位置正式部署由独立 Admin 容器提供页面，API 提供运行配置	修改后如何生效下述 API 参数不是 Vite 构建变量；无需把数据库密码写入前端

Gateway 重启会断开其承载的游戏 WebSocket；地图服重启会影响在线角色，安排在合适维护时机。只调整已支持的客户端默认值无需重新构建 PWA。

完整参数

表头区分模板默认值与程序默认值；地图服覆盖项留空时读取当前文件配置，并非强制采用表中内置值。

Docker 部署入口

本节默认值来自根仓库 deploy/docker/.env.example 与 Compose。相对路径以部署目录为基准。

变量	模板默认值 / 要求	用途
变量COMPOSE_PROJECT_NAME	模板默认值 / 要求happyro	用途Compose 项目名
变量RELEASE_VERSION	模板默认值 / 要求打包时由 deploy/docker/VERSION 填充	用途包版本；不要手工与镜像版本混用
变量GATEWAY_IMAGE / SERVER_IMAGE / API_IMAGE / ADMIN_IMAGE / DATABASE_IMAGE	模板默认值 / 要求对应组件镜像，版本由打包填充	用途必须使用同一发布包中的镜像引用
变量RESOURCE_DIR	模板默认值 / 要求./resources	用途客户端和目录资源
变量DATA_DIR	模板默认值 / 要求./data	用途数据库、服务端配置和日志等持久数据
变量CUSTOM_DIR	模板默认值 / 要求./custom	用途自定义 NPC、数据库及资源
变量GAME_PUBLIC_URL	模板默认值 / 要求http://127.0.0.1:3338	用途玩家可访问的游戏地址，局域网使用服务器地址
变量ADMIN_PUBLIC_URL	模板默认值 / 要求http://127.0.0.1:8000	用途后台公开地址，传入 API 的 APP_URL
变量ADMIN_CSRF_ORIGIN_CHECK_ENABLED	模板默认值 / 要求false	用途是否校验后台 Origin 与 Sec-Fetch-Site；true 时仅信任 APP_URL 对应来源。关闭来源校验仍要求有效 CSRF Token
变量ADMIN_PASSWORD_CHANGE_ENABLED	模板默认值 / 要求true	用途后台自助改密；演示环境设为 false，隐藏入口并拒绝请求，后台不能覆盖，CLI 不受影响
变量GATEWAY_PORT / ADMIN_PORT	模板默认值 / 要求3338 / 8000	用途宿主机发布端口，支持 地址:端口；仅本机访问可设置 127.0.0.1:3338 / 127.0.0.1:8000。调整端口时同步公开 URL，修改后重建对应容器
变量ADMIN_PROXY_SUBNET / ADMIN_PROXY_DYNAMIC_RANGE / ADMIN_PROXY_IP	模板默认值 / 要求172.30.81.0/29 / 172.30.81.4/30 / 172.30.81.2	用途Admin 与 API 专用网段、动态地址池及池外的 Admin 固定地址；API 仅信任此代理 IP。网段冲突时三项配套调整并重建网络
变量SOCKET_PROXY_URL	模板默认值 / 要求空	用途可选外部 WebSocket 地址，空值保持同源
变量DB_PASSWORD	模板默认值 / 要求必填，敏感	用途游戏数据库用户密码
变量ADMIN_DB_PASSWORD	模板默认值 / 要求必填，敏感	用途API 管理库及游戏数据访问账号密码
变量MARIADB_ROOT_PASSWORD	模板默认值 / 要求必填，敏感	用途数据库 root 密码
变量INTERSERVER_PASSWORD	模板默认值 / 要求必填，敏感	用途游戏服务间认证密码，服务端入口限制不超过 23 字符
变量GAME_CONTROL_TOKEN	模板默认值 / 要求必填，敏感	用途API 与游戏控制接口共享令牌
变量ADMIN_INITIAL_USERNAME / ADMIN_INITIAL_PASSWORD	模板默认值 / 要求admin / admin（密码敏感）	用途初始化后台账号；不是修改已有账号密码的入口
变量SHOW_DEFAULT_CREDENTIALS	模板默认值 / 要求false	用途控制默认账号提示；还受初始化用户名和密码条件约束
变量SESSION_SECURE_COOKIE	模板默认值 / 要求false	用途HTTPS 部署设 true，让会话 Cookie 仅通过 HTTPS 发送
变量APP_TIMEZONE	模板默认值 / 要求Asia/Shanghai	用途同时传给 API 和 Gateway 的 IANA 显示时区

密码和令牌使用部署工具生成的值，不提交真实环境文件。Server 入口要求 DB_PASSWORD、INTERSERVER_PASSWORD、GAME_CONTROL_TOKEN 只含字母、数字、下划线或连字符。已有数据库换密码需要同步数据库账号本身；仅修改容器变量不会自动完成凭据迁移。

客户端默认设置（Gateway）

以下表格依据 happyro-client/src/Core/ClientDefaults.schema.json 核对。所有条目都可在 Gateway 环境配置；Docker 模板和 Compose 已透传。留空继承表中的 PWA 默认值。布尔值使用 true / false；类别列表使用逗号分隔且不重复。镜头数值是客户端距离参数，寻怪与活动范围单位为地图格。

自动战斗与瞬移

配置项与环境变量	默认值	允许范围
配置项与环境变量自动战斗 · 搜怪范围 CLIENT_AUTO_COMBAT_SEARCH_RANGE	默认值14	允许范围1–50，整数
配置项与环境变量自动战斗 · 活动范围 CLIENT_AUTO_COMBAT_ACTIVITY_RANGE	默认值30	允许范围1–100，整数
配置项与环境变量自动战斗 · 无目标随机瞬移 CLIENT_AUTO_TELEPORT_ENABLED	默认值true	允许范围true / false
配置项与环境变量自动战斗 · 无目标等待 CLIENT_AUTO_TELEPORT_WAIT_SECONDS	默认值2	允许范围1–60，整数
配置项与环境变量自动战斗 · 最短瞬移间隔 CLIENT_AUTO_TELEPORT_INTERVAL_SECONDS	默认值2	允许范围1–300，整数

活动范围不能小于搜怪范围；实际搜怪上限还受服务端同步范围限制。默认随机瞬移开启不代表登录后自动开始战斗。

自动恢复

配置项与环境变量	默认值	允许范围
配置项与环境变量自动恢复 · HP 低于（%） CLIENT_AUTO_RECOVERY_HP_TRIGGER_PERCENT	默认值50	允许范围1–99，整数
配置项与环境变量自动恢复 · HP 恢复至（%） CLIENT_AUTO_RECOVERY_HP_TARGET_PERCENT	默认值80	允许范围2–100，且高于触发比例，整数
配置项与环境变量自动恢复 · SP 低于（%） CLIENT_AUTO_RECOVERY_SP_TRIGGER_PERCENT	默认值20	允许范围1–99，整数
配置项与环境变量自动恢复 · SP 恢复至（%） CLIENT_AUTO_RECOVERY_SP_TARGET_PERCENT	默认值50	允许范围2–100，且高于触发比例，整数

HP／SP 的恢复目标必须高于各自触发比例；道具选择与启停由玩家设置，见自动恢复。

自动拾取

配置项与环境变量	默认值	允许范围
配置项与环境变量自动拾取 · 开关 CLIENT_AUTO_PICKUP_ENABLED	默认值false	允许范围true / false
配置项与环境变量自动拾取 · 范围 CLIENT_AUTO_PICKUP_RANGE	默认值5	允许范围1–15，整数
配置项与环境变量自动拾取 · 每轮拾取时限 CLIENT_AUTO_PICKUP_BATCH_SECONDS	默认值5	允许范围1–30，整数
配置项与环境变量自动拾取 · 默认类别 CLIENT_AUTO_PICKUP_CATEGORIES	默认值equipment,consumable,card,other	允许范围equipment, consumable, card, other

镜头

配置项与环境变量	默认值	允许范围
配置项与环境变量镜头 · 桌面距离 CLIENT_CAMERA_DESKTOP_ZOOM	默认值125	允许范围1–325
配置项与环境变量镜头 · 手机横屏距离 CLIENT_CAMERA_PHONE_LANDSCAPE_ZOOM	默认值95	允许范围1–325
配置项与环境变量镜头 · 手机竖屏距离 CLIENT_CAMERA_PHONE_PORTRAIT_ZOOM	默认值170	允许范围1–325
配置项与环境变量镜头 · 平板/大屏横屏距离 CLIENT_CAMERA_TABLET_LANDSCAPE_ZOOM	默认值125	允许范围1–325
配置项与环境变量镜头 · 平板/大屏竖屏距离 CLIENT_CAMERA_TABLET_PORTRAIT_ZOOM	默认值155	允许范围1–325
配置项与环境变量镜头 · 平滑移动 CLIENT_CAMERA_SMOOTH	默认值true	允许范围true / false

镜头和音量等设置的「恢复默认」读取本次 Gateway 下发值。

画质与地图显示

配置项与环境变量	默认值	允许范围
配置项与环境变量画质 · 渲染比例 CLIENT_GRAPHICS_QUALITY	默认值100	允许范围25–100
配置项与环境变量画质 · 帧率上限 CLIENT_GRAPHICS_FPS_LIMIT	默认值60	允许范围-1, 30, 60, 90, 120
配置项与环境变量画质 · 性能模式 CLIENT_GRAPHICS_PERFORMANCE_MODE	默认值false	允许范围true / false
配置项与环境变量画质 · 显示范围 CLIENT_GRAPHICS_VIEW_AREA	默认值14	允许范围4–20
配置项与环境变量画质 · 游戏光标 CLIENT_GRAPHICS_CURSOR	默认值true	允许范围true / false
配置项与环境变量画质 · 像素清晰显示 CLIENT_GRAPHICS_PIXEL_PERFECT_SPRITES	默认值false	允许范围true / false
配置项与环境变量高级画质 · 泛光开关 CLIENT_GRAPHICS_BLOOM_ENABLED	默认值false	允许范围true / false
配置项与环境变量高级画质 · 景深开关 CLIENT_GRAPHICS_BLUR_ENABLED	默认值false	允许范围true / false
配置项与环境变量高级画质 · 抗锯齿开关 CLIENT_GRAPHICS_FXAA_ENABLED	默认值false	允许范围true / false
配置项与环境变量高级画质 · 自然饱和度开关 CLIENT_GRAPHICS_VIBRANCE_ENABLED	默认值false	允许范围true / false
配置项与环境变量高级画质 · 卡通开关 CLIENT_GRAPHICS_CARTOON_ENABLED	默认值false	允许范围true / false
配置项与环境变量高级画质 · 锐化开关 CLIENT_GRAPHICS_CAS_ENABLED	默认值false	允许范围true / false
配置项与环境变量高级画质 · 泛光强度 CLIENT_GRAPHICS_BLOOM_INTENSITY	默认值0.5	允许范围0.1–3
配置项与环境变量高级画质 · 景深范围 CLIENT_GRAPHICS_BLUR_AREA	默认值14	允许范围3–20
配置项与环境变量高级画质 · 景深强度 CLIENT_GRAPHICS_BLUR_INTENSITY	默认值3	允许范围2–10
配置项与环境变量高级画质 · 抗锯齿边缘阈值 CLIENT_GRAPHICS_FXAA_EDGE_THRESHOLD	默认值0.125	允许范围0.063–0.333
配置项与环境变量高级画质 · 饱和强度 CLIENT_GRAPHICS_VIBRANCE	默认值0.15	允许范围-0.9–0.9
配置项与环境变量高级画质 · 卡通强度 CLIENT_GRAPHICS_CARTOON_POWER	默认值1.5	允许范围0.1–9.9
配置项与环境变量高级画质 · 描边强度 CLIENT_GRAPHICS_CARTOON_EDGE_SLOPE	默认值1.5	允许范围1.5–5.9
配置项与环境变量高级画质 · 锐化对比度 CLIENT_GRAPHICS_CAS_CONTRAST	默认值0	允许范围0–1
配置项与环境变量高级画质 · 锐化强度 CLIENT_GRAPHICS_CAS_SHARPENING	默认值1	允许范围0–1
配置项与环境变量地图显示 · 雾 CLIENT_MAP_FOG	默认值false	允许范围true / false
配置项与环境变量地图显示 · 光照贴图 CLIENT_MAP_LIGHTMAP	默认值true	允许范围true / false
配置项与环境变量地图显示 · 技能特效 CLIENT_MAP_EFFECTS	默认值true	允许范围true / false
配置项与环境变量地图显示 · 简化特效 CLIENT_MAP_MIN_EFFECTS	默认值false	允许范围true / false
配置项与环境变量地图显示 · 显示未命中 CLIENT_MAP_SHOW_MISS	默认值true	允许范围true / false
配置项与环境变量地图显示 · 名称字体样式 CLIENT_MAP_SHOW_NAME_STYLE	默认值true	允许范围true / false
配置项与环境变量地图显示 · 光照平滑参数 CLIENT_MAP_SMOOTH_LIGHT	默认值0	允许范围0, 1, 2
配置项与环境变量地图显示 · 光环模式 CLIENT_MAP_AURA	默认值1	允许范围0, 1, 2

声音

配置项与环境变量	默认值	允许范围
配置项与环境变量音频 · 背景音乐开关 CLIENT_BGM_ENABLED	默认值true	允许范围true / false
配置项与环境变量音频 · 背景音乐音量 CLIENT_BGM_VOLUME	默认值0.5	允许范围0–1
配置项与环境变量音频 · 音效开关 CLIENT_SOUND_ENABLED	默认值true	允许范围true / false
配置项与环境变量音频 · 音效音量 CLIENT_SOUND_VOLUME	默认值0.5	允许范围0–1

文字与界面

配置项与环境变量	默认值	允许范围
配置项与环境变量脚本文字 · 最低对比度目标 CLIENT_SCRIPT_TEXT_MIN_CONTRAST	默认值4.5	允许范围4.5–7
配置项与环境变量界面 · 通知显示时长 CLIENT_TOAST_DURATION_SECONDS	默认值2	允许范围1–10，整数
配置项与环境变量界面 · 紧凑布局聊天预览行数 CLIENT_CHAT_PREVIEW_COMPACT_LINES	默认值3	允许范围2, 3, 4, 5, 6, 7, 8
配置项与环境变量界面 · 宽松布局聊天预览行数 CLIENT_CHAT_PREVIEW_SPACIOUS_LINES	默认值5	允许范围2, 3, 4, 5, 6, 7, 8
配置项与环境变量界面 · 聊天预览频道标签 CLIENT_CHAT_PREVIEW_TABS	默认值true	允许范围true / false

脚本文字对比度是部署策略，不保存到玩家偏好；自动修正始终开启。背景无法达到目标时选黑白两端中对比度更高者。

游戏服务端

环境变量	默认值	范围 / 用途
环境变量HAPPYRO_AREA_SIZE	默认值14	范围 / 用途5–50 的十进制整数，覆盖 area_size；影响实体同步、广播及部分 AI / 跟随逻辑
环境变量HAPPYRO_MAX_WALK_PATH	默认值17	范围 / 用途1–32 的十进制整数，覆盖 max_walk_path；限制单次路径长度
环境变量HAPPYRO_NEW_PLAYER_START	默认值classic	范围 / 用途ship 或 classic，新建人类角色出生策略，杜兰独立

同步范围与行走上限仅接受表内范围的十进制整数，非法非空值会令地图服报错退出。留空时继承文件配置，见优先级和空值。

搜怪范围与服务端同步范围

服务端默认同步 14 格，客户端默认搜怪 14 格、活动 30 格，单次行走上限 17 格。同步范围决定收到哪些实体；搜怪范围筛选当前目标；活动范围限制目标相对起点的位置；单次行走上限限制路径长度。

地图服在登录、换图和配置变化时下发实际上限，客户端同步限制搜怪设置与执行（最高 50 格）。未收到时等待；断线清除旧上限，不清空其他偏好。具体行为和范围示意见自动战斗。

同步范围与性能

扩大同步范围通常增加服务器、网络和客户端负担，实际影响取决于玩家与魔物密度。画质里的显示范围不会扩大服务端同步范围。修改后重启对应原生地图服或重建 map 容器，无需重编 PWA；具体步骤见生效方式。

玩法与工具权限环境变量

以下 10 项由地图服进程读取。未设置或留空时保留当前 battle 文件和后台管理方式；非空值在配置导入后覆盖文件。均使用十进制整数，布尔项填 0 / 1，不接受 true / false。

环境变量	用途	当前默认	允许范围
环境变量HAPPYRO_NAVIGATION_TELEPORT_POLICY	用途导航传送权限	当前默认2	允许范围0–2
环境变量HAPPYRO_NAVIGATION_TELEPORT_CROSS_MAP	用途导航跨地图传送	当前默认1	允许范围0–1
环境变量HAPPYRO_NAVIGATION_TELEPORT_COOLDOWN	用途导航传送冷却（秒）	当前默认1	允许范围0–3600
环境变量HAPPYRO_GAME_TOOLS_MONSTER_SPAWN_POLICY	用途图鉴召怪权限	当前默认2	允许范围0–2
环境变量HAPPYRO_GAME_TOOLS_MONSTER_SPAWN_COOLDOWN	用途召怪冷却（秒）	当前默认1	允许范围0–3600
环境变量HAPPYRO_GAME_TOOLS_MONSTER_SPAWN_DURATION	用途召怪存活时间（秒）	当前默认600	允许范围1–3600
环境变量HAPPYRO_GAME_TOOLS_MONSTER_SPAWN_ALLOW_BOSS	用途允许召唤 Boss / MVP	当前默认1	允许范围0–1
环境变量HAPPYRO_GAME_TOOLS_CHARACTER_MAINTENANCE_POLICY	用途角色维护权限	当前默认2	允许范围1–2
环境变量HAPPYRO_GAME_TOOLS_GAME_SETTINGS_POLICY	用途游戏设置工具权限	当前默认2	允许范围1–2
环境变量HAPPYRO_GAME_TOOLS_ITEM_GRANT_POLICY	用途物品发放权限	当前默认2	允许范围1–2

权限值：0 关闭（仅支持范围含 0 的项目）、1 仅管理员、2 所有玩家。角色维护、游戏设置及物品发放仅支持 1 / 2，不支持 0。默认值以当前配置为准。

非空环境变量控制的项目，在后台或游戏内设置提交时会被 API 明确拒绝，提示具体环境变量名；检查发生在写入配置文件之前，整批请求均不执行。地图服控制接口也会在修改前拒绝含受控项的整批请求。当前表单仍可输入，限制在提交时反馈。需要恢复后台管理时清空对应变量，并重新创建地图服容器或重启原生地图服。

API 从地图服读取覆盖状态，不需要复制这些变量到 API 环境。修改后的操作统一见生效方式。

示例：保持普通玩家可以导航，限制召怪和发放为管理员操作：

HAPPYRO_NAVIGATION_TELEPORT_POLICY=2
HAPPYRO_NAVIGATION_TELEPORT_CROSS_MAP=1
HAPPYRO_NAVIGATION_TELEPORT_COOLDOWN=1
HAPPYRO_GAME_TOOLS_MONSTER_SPAWN_POLICY=1
HAPPYRO_GAME_TOOLS_ITEM_GRANT_POLICY=1

这些项目沿用地图服原有 GM 临时命令行为；GM 临时改值不等于改写部署配置，下次 battle 重载或进程重启会重新应用环境变量。经验、掉落、精炼、死亡惩罚等项目未提供对应的环境变量覆盖，继续使用原有配置和已开放的后台入口。

服务连接参数

以下为 Docker Server 入口变量，通常由 Compose 固定或映射，不能只在部署 .env 随意新增同名变量。原生脚本采用 profile 生成的配置文件。

变量	Server 入口默认值 / 要求	用途
变量DB_HOST / DB_PORT	Server 入口默认值 / 要求database / 3306	用途游戏库连接
变量DB_USER	Server 入口默认值 / 要求happyro	用途游戏服务数据库用户（不是 API 的 DB_USERNAME）
变量DB_MAIN_DATABASE / DB_LOG_DATABASE	Server 入口默认值 / 要求happyro / happyro_log	用途游戏库、日志库
变量DB_PASSWORD	Server 入口默认值 / 要求必填，敏感	用途数据库密码
变量INTERSERVER_USER	Server 入口默认值 / 要求happyro_interserver	用途服务间账号
变量INTERSERVER_PASSWORD	Server 入口默认值 / 要求必填，敏感	用途服务间密码
变量GAME_SERVER_IP	Server 入口默认值 / 要求127.0.0.1	用途发给客户端的服务地址，Docker 由 Gateway 转发
变量LOGIN_PORT / CHAR_PORT / MAP_PORT / WEB_PORT	Server 入口默认值 / 要求6900 / 6121 / 5121 / 8889	用途服务内部端口，不等同于宿主机网页端口
变量WEB_ALLOWED_ORIGIN	Server 入口默认值 / 要求Compose 使用 GAME_PUBLIC_URL	用途游戏 Web API 允许的来源
变量GAME_CONTROL_TOKEN	Server 入口默认值 / 要求必填，敏感	用途与 API 保持一致
变量HAPPYRO_CUSTOM_NPC_PATH	Server 入口默认值 / 要求Compose：/opt/happyro/custom/npc	用途定制 NPC 挂载目录

原生 deploy/rathena/profile.env 另有 SERVER_LAN_IP=127.0.0.1、WEB_BIND_IP=127.0.0.1 和 WEB_ALLOWED_ORIGIN=http://127.0.0.1:3338，由配置脚本使用，不是通用的地图服 getenv 参数。

Gateway 服务与资源

本节列程序默认值，并标明部署模板差异。路径以程序约定的工作目录或项目根解析，多个 DATA_OVERRIDE_PATH 使用系统路径分隔符。

变量	程序默认值	用途 / 说明
变量HOST	程序默认值未指定监听地址	用途 / 说明原生模板使用 127.0.0.1，容器按部署设置
变量PORT	程序默认值3338	用途 / 说明HTTP / WebSocket 监听端口
变量NODE_ENV	程序默认值未设	用途 / 说明production 启用生产行为；生产启动脚本设为 production
变量CLIENT_PUBLIC_URL	程序默认值http://localhost:8000	用途 / 说明客户端公开入口，Docker 映射 GAME_PUBLIC_URL
变量ENABLE_WSPROXY	程序默认值未设时关闭	用途 / 说明精确 true 开启；HappyRO 模板开启
变量ENABLE_STATIC_SERVE	程序默认值未设时关闭	用途 / 说明精确 true 开启；HappyRO 模板开启
变量ROBROWSER_PATH	程序默认值../../repos/happyro-client/dist/Web	用途 / 说明PWA 静态目录
变量ROBROWSER_PUBLIC_PATH	程序默认值/	用途 / 说明HappyRO 原生模板使用 /applications/pwa
变量WS_ALLOWED_TARGETS	程序默认值127.0.0.1:6900,127.0.0.1:6121,127.0.0.1:5121	用途 / 说明逗号分隔 host:port 白名单
变量WS_TARGET_REDIRECTS	程序默认值空	用途 / 说明逗号分隔 来源host:port=目标host:port，容器映射到内部服务
变量REMOTE_CLIENT_URL	程序默认值空	用途 / 说明可选 HTTP(S) 资源入口，空值同源
变量SOCKET_PROXY_URL	程序默认值空	用途 / 说明可选 WS(S) 封包代理入口，空值同源
变量RATHENA_WEB_API_URL	程序默认值空	用途 / 说明游戏 Web API 上游；原生模板 http://127.0.0.1:8889
变量HAPPYRO_API_URL	程序默认值http://127.0.0.1:18081	用途 / 说明Go API 上游
变量HTTP_PROXY_TIMEOUT_MS	程序默认值5000	用途 / 说明上游 HTTP 超时，毫秒
变量APP_TIMEZONE	程序默认值Asia/Shanghai	用途 / 说明IANA 显示时区，非法名称拒绝启动
变量CACHE_MAX_FILES	程序默认值5000	用途 / 说明内存资源缓存文件数
变量CACHE_MAX_MEMORY_MB	程序默认值1024	用途 / 说明缓存内存预算，MB
变量CACHE_WARM_UP	程序默认值未设时关闭	用途 / 说明精确 true 开启启动预热；模板开启
变量CACHE_WARM_UP_LIMIT	程序默认值500	用途 / 说明启动预热文件数
变量DATA_OVERRIDE_PATH	程序默认值空	用途 / 说明内置散装资源目录列表
变量CUSTOM_RESOURCE_PATH	程序默认值空	用途 / 说明用户自定义资源目录
变量CLIENT_DIAGNOSTICS_DIR	程序默认值空，关闭上传	用途 / 说明可选浏览器诊断接收目录
变量ESRGAN_ENABLED	程序默认值未设时关闭	用途 / 说明HappyRO 模板关闭；开启需另行安装插件及准备缓存
变量ESRGAN_CACHE_DIR	程序默认值./upscaled_cache	用途 / 说明可选放大资源缓存

Go API 与后台

以下为 API 程序默认值，不是 .env.example 的示例值。例如程序 HTTP_LISTEN 默认 :8080，原生示例写为 0.0.0.0:18081；程序 APP_URL 默认 http://localhost:8080，Docker 将 ADMIN_PUBLIC_URL 映射到它。Docker 中未映射的变量须明确加入相应服务 environment。

变量	程序默认值 / 要求	用途 / 允许值
变量APP_TIMEZONE	程序默认值 / 要求Asia/Shanghai	用途 / 允许值显式 IANA 时区，禁止空值和 Local；存储仍为 UTC
变量HTTP_LISTEN	程序默认值 / 要求:8080	用途 / 允许值HTTP 监听地址
变量APP_URL	程序默认值 / 要求http://localhost:8080	用途 / 允许值HTTP(S) 绝对地址，不含凭据、查询或 fragment
变量ADMIN_CSRF_ORIGIN_CHECK_ENABLED	程序默认值 / 要求false	用途 / 允许值是否校验后台 Origin 与 Sec-Fetch-Site；true 时仅信任 APP_URL 对应来源。关闭来源校验仍要求有效 CSRF Token
变量ADMIN_PASSWORD_CHANGE_ENABLED	程序默认值 / 要求true	用途 / 允许值后台自助改密；演示环境设为 false，隐藏入口并拒绝请求，后台不能覆盖，CLI 不受影响
变量LOG_LEVEL	程序默认值 / 要求info	用途 / 允许值日志级别
变量GIN_MODE	程序默认值 / 要求按 Gin 运行环境	用途 / 允许值原生示例使用 release
变量HTTP_TRUSTED_PROXIES	程序默认值 / 要求空列表	用途 / 允许值逗号分隔的受信代理地址
变量DB_HOST / DB_PORT	程序默认值 / 要求127.0.0.1 / 3306	用途 / 允许值管理库连接；端口为 uint16
变量DB_DATABASE / DB_USERNAME / DB_PASSWORD	程序默认值 / 要求无默认，密码敏感	用途 / 允许值管理库名称、用户和密码
变量GAME_DB_HOST / GAME_DB_PORT	程序默认值 / 要求127.0.0.1 / 3306	用途 / 允许值游戏库连接
变量GAME_DB_DATABASE / GAME_DB_USERNAME / GAME_DB_PASSWORD	程序默认值 / 要求无默认，密码敏感	用途 / 允许值游戏库名称、用户和密码
变量GAME_LOG_DB_DATABASE	程序默认值 / 要求happyro_log	用途 / 允许值游戏日志库
变量ADMIN_INITIAL_USERNAME / ADMIN_INITIAL_PASSWORD	程序默认值 / 要求admin / admin（敏感）	用途 / 允许值初始化账号
变量SHOW_DEFAULT_CREDENTIALS	程序默认值 / 要求false	用途 / 允许值默认账号提示开关
变量SESSION_LIFETIME	程序默认值 / 要求2h	用途 / 允许值正数时长
变量SESSION_REMEMBER_LIFETIME	程序默认值 / 要求720h	用途 / 允许值记住登录时长，不能小于 SESSION_LIFETIME
变量SESSION_SECURE_COOKIE	程序默认值 / 要求false	用途 / 允许值HTTPS Cookie 开关
变量GAME_CONTROL_BASE_URL	程序默认值 / 要求http://127.0.0.1:8889	用途 / 允许值控制接口 HTTP(S) 绝对地址
变量GAME_CONTROL_TOKEN	程序默认值 / 要求无默认，敏感	用途 / 允许值与游戏服务共享的令牌
变量GAME_CONTROL_TIMEOUT	程序默认值 / 要求3s	用途 / 允许值控制请求正数超时
变量GAME_ADMIN_GROUP_IDS	程序默认值 / 要求2,3,4,10,99	用途 / 允许值逗号分隔的整数 GM 分组
变量GAME_ITEM_IMAGE_ROOT / GAME_MONSTER_IMAGE_ROOT	程序默认值 / 要求空	用途 / 允许值物品 / 魔物图片根目录
变量GAME_MAP_INDEX_PATH	程序默认值 / 要求../happyro-server/db/map_index.txt	用途 / 允许值地图索引
变量GAME_WORLD_ASSET_ROOT	程序默认值 / 要求resources/game-data/world	用途 / 允许值世界目录资源
变量GAME_SERVER_BATTLE_CONFIG_PATH	程序默认值 / 要求HTTP 服务必填绝对路径	用途 / 允许值后台维护的 battle 配置文件；与地图服共享所在目录，支持原子替换

API 的 DB_* 与 Server 的 DB_* 不完全同义：API 连接的是后台管理库，Server 连接的是游戏库。不要直接把一套服务环境复制给另一套服务。Go 时长使用 3s、2h 等格式，不能只填无单位数字。

注意事项

优先级和空值

• 玩家设置：浏览器保存值 > Gateway 提供的默认值 > PWA 内置默认值。自动战斗设置按服务器、账号和角色区分，不写入游戏数据库，也不跨设备同步。
• 地图服覆盖：非空环境变量 > battle 配置文件及 import > 内置默认值。空值保留文件配置；battle 重载会重新应用当前进程环境。
• 空值语义不统一：CLIENT_* 空值继承内置默认值；地图服覆盖空值继承文件；Compose 的 :- 把空值视为未配置，其他变量应按各自说明填写。
• 环境变量修改默认配置，不直接切换玩家正在运行的自动战斗状态。

未列入部署模板的进程变量，不会仅因写入 Docker .env 就进入容器，必须有 Compose environment 映射。不同服务的同名变量也可能用途不同，按对应表格配置。

核对与维护

本文依据以下源码和模板整理；更新参数时同时更新对应文档表格：

• 根仓库：deploy/docker/.env.example、deploy/docker/compose.yml、deploy/docker/server/entrypoint.sh、deploy/remote-client/.env.example、deploy/rathena/profile.env。
• Client：src/Core/ClientDefaults.schema.json，57 项客户端字段及默认值来源。
• Gateway：index.js、runtime-config.js、client-defaults.js、src/controllers/clientController.js。
• Server：src/map/battle.cpp、conf/battle/client.conf、src/char/new_player_start.hpp。
• API：internal/config/config.go、.env.example。

排障时先确认变量是否进入目标进程，再检查配置优先级、个人保存值及代码版本。不要在工单或日志中粘贴包含密码的完整环境。其他操作见访问地址与目录、日常维护和自定义配置。