部署管理

按安装方式查看状态、日志和配置。日常维护从Compose 服务或源码运行开始；升级见升级与备份。

使用服务器 IP 访问

一键安装和本 Wiki 的 Compose 模板默认只允许本机访问。开启服务器 IP 访问时按下列步骤操作；源码部署默认对外监听，可从第 3 步开始。自定义 Compose 先核对 ports 配置。

1. 编辑一键安装的 /opt/gamex-compose/compose.yaml，或手动安装的 ~/gamex-compose/compose.yaml，将面板的 ports 项从 127.0.0.1:3000:3000 改为 3000:3000，保持节点的 GAMEX_PANEL_URL 不变。

2. 应用配置。

   一键安装：

   sudo docker --host unix:///var/run/docker.sock compose \
     -p gamex -f /opt/gamex-compose/compose.yaml up -d

   手动 Compose 安装：在 ~/gamex-compose 目录执行：

   docker compose up -d

   修改安装器生成的配置后，直接通过 Compose 管理。安装器仅允许使用原参数、保留原配置的重试，不会覆盖手动修改。

3. 在服务器防火墙和云安全组中，允许你的电脑访问 TCP 3000 端口。

4. 将“服务器IP”换成实际地址，打开 http://服务器IP:3000/setup。在初始化中将面板地址设为 http://服务器IP:3000；已初始化则在系统设置中更新。

HTTP 支持初始化和密码登录，远程使用通行密钥需通过 HTTPS 域名访问。

自定义脚本安装

一键安装脚本适用于 Linux amd64、arm64，使用 /var/run/docker.sock 对应的本机系统 Docker Engine，需要 Bash、curl、sha256sum 和镜像仓库访问权限。脚本不选择远程 Docker context 或 rootless socket。 若服务器未安装 Docker，自动安装需系统支持 systemd；若已安装，Docker Engine 须为 28+、Compose 须为 2.24+，版本不足时请先升级。

参数	用途
--version latest	镜像标签，默认 latest，也可指定明确的发布版本
--prefix /opt/gamex-compose	安装目录，须为专用绝对路径，默认 /opt/gamex-compose
--project gamex	Compose 项目名，默认 gamex
--port 3000	面板本机端口，默认 3000
--panel-only	仅安装面板，不安装本机节点
--apply	执行安装，省略时仅预览，不安装依赖或启动服务

使用 bash install-compose.sh --help 查看完整参数。

例如，在新主机上使用自定义目录、项目名和端口：

curl -fsSLO https://docs.gamexserver.com/install/install-compose.sh &&
sudo bash install-compose.sh \
  --prefix /srv/gamex --project gamex-prod --port 3001 --apply

脚本不配置 HTTPS 或防火墙，也不执行版本升级或删除数据。

校验安装脚本

在空目录中下载脚本与校验清单，校验通过后安装：

curl -fsSLO https://docs.gamexserver.com/install/install-compose.sh &&
curl -fSL https://docs.gamexserver.com/install/SHA256SUMS -o SHA256SUMS &&
sha256sum --check --ignore-missing SHA256SUMS &&
sudo bash install-compose.sh --apply

管理 Compose 服务

安装脚本部署：使用默认参数安装后，运行以下命令查看状态：

sudo docker --host unix:///var/run/docker.sock compose \
  -p gamex -f /opt/gamex-compose/compose.yaml ps

将末尾的 ps 替换为下列命令，自定义过目录或项目名时同步修改 -f 和 -p。

操作	替换命令
查看最近日志	logs --tail 100
持续查看节点日志	logs -f daemon
重启服务	restart
停止并移除容器	down
再次启动	up -d

手写 Compose 部署：在 compose.yaml 所在目录查看状态，其他操作同样替换末尾的 ps：

docker compose ps

仅安装面板时没有节点日志，数据保留规则见部署数据与访问。

管理源码运行

首次安装和构建依赖见从源码构建。

在面板仓库目录，以启动时相同账号选择需要的操作：

操作	命令
后台启动	npm start
重启正在运行的应用	npm restart
停止后台应用	npm stop
前台运行并查看日志	先执行 npm stop，成功后执行 npm start -- --foreground

npm start 在后台运行应用，不注册开机服务，前台运行时按 Ctrl+C 停止。

需要文件日志时，将 config.toml 中的 LOG_TARGETS 设为 "console,local"。

节点诊断与服务命令见执行节点命令。

配置开机服务

原生安装器可从源码构建面板并注册 systemd 服务，节点需单独接入。

准备 Linux amd64 或 arm64、systemd 240+、Node.js 22.13+、npm 10+、Git、Python 3、 gcc、g++、make、Bash、curl、sha256sum 和标准 Linux 账号工具。 上述依赖须提前安装，其中 Node.js 与 npm 须使用主目录外的系统路径。

在新的空目录执行：

git clone --branch release/v1.2.0 --depth 1 https://github.com/gamex-sh/gamex-panel.git gamex-panel
git -C gamex-panel archive --format=tar.gz release/v1.2.0 > gamex-panel-v1.2.0.tar.gz
curl -fSL https://docs.gamexserver.com/install/install-native.sh -o install-native.sh
sudo bash install-native.sh \
  --archive ./gamex-panel-v1.2.0.tar.gz \
  --sha256 "$(sha256sum gamex-panel-v1.2.0.tar.gz | cut -d ' ' -f 1)" \
  --version 1.2.0 --apply

使用默认参数时，程序位于 /opt/gamex-native，配置、数据和日志位于 /var/lib/gamex-panel；使用 bash install-native.sh --help 查看自定义参数，省略 --apply 可预览安装。

打开 http://localhost:3000/setup 初始化，保持 127.0.0.1:3000 和默认相对数据路径。安装在远程服务器时，先通过 SSH 转发访问。

通过 systemd 选择需要的操作：

操作	命令
查看状态	sudo systemctl status gamex-panel.service
查看最近日志	sudo journalctl -u gamex-panel.service -n 100 --no-pager
启动服务	sudo systemctl start gamex-panel.service
重启服务	sudo systemctl restart gamex-panel.service
停止服务	sudo systemctl stop gamex-panel.service
开启开机自启	sudo systemctl enable gamex-panel.service
关闭开机自启	sudo systemctl disable gamex-panel.service

停止或禁用服务会保留程序和数据。

手动分离部署

仅运行面板

在 Linux amd64 或 arm64 管理主机准备 Docker Engine 28+ 和 Compose 2.24+， 将以下内容保存为 compose.yaml：

name: gamex

services:
  panel:
    image: ghcr.io/gamex-sh/gamex-panel:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - panel-data:/app/data
      - panel-logs:/app/logs
    stop_grace_period: 30s

volumes:
  panel-data:
  panel-logs:

在配置目录运行 docker compose up -d。通过本机或 SSH 转发打开 http://localhost:3000/setup，创建管理员。

用 Compose 接入节点

1. 在面板中为目标游戏主机创建节点。
2. 在 Linux 游戏主机准备 Docker Engine 28+ 和 Compose 2.24+，将 独立节点模板保存为 compose.yaml。
3. 在同目录创建 .env，填入面板地址和该节点的配对信息：

GAMEX_PANEL_URL=https://panel.example.com
GAMEX_DAEMON_ID=NODE_UUID_FROM_PANEL
GAMEX_ENROLLMENT_TOKEN=ONE_TIME_TOKEN_FROM_PANEL

将示例地址、NODE_UUID_FROM_PANEL 和 ONE_TIME_TOKEN_FROM_PANEL 换成面板显示的实际值。

4. 运行 docker compose up -d，等待节点在线且 Docker 状态为已启动。
5. 配对成功后清空 .env 中的 GAMEX_ENROLLMENT_TOKEN，保留 daemon-data。

每台主机单独创建节点并使用自己的配对信息。已配对节点优先使用 /data/config.yaml，修改地址时编辑该文件并重启；仅修改 .env 不会覆盖它。容器升级见升级与备份。

部署数据与访问

Compose 持久卷	内容
panel-data	数据库、上传文件、插件、本机引导状态，以及 config/config.toml 和回滚文件
panel-logs	启用后的面板文件日志
daemon-data	节点配置、身份与持久命令日志
enrollment	同机自动配对的临时凭据

仅部署面板时使用前两个卷，独立节点使用 daemon-data。 保留 Compose 项目名和对应持久卷。docker compose down 保留卷， docker compose down -v 会删除持久卷及其数据。游戏服务器文件位于独立的 Docker 工作区卷，需单独备份。

面板镜像使用 GAMEX_CONFIG_DIR=/app/data/config。应持久化配置目录，不要单独绑定 config.toml 文件：配置更新采用原子替换，并在相邻位置保存回滚文件。自定义数据路径应位于持久化目录内，每个数据库只运行一个面板进程。

同机自动配对会在重启后保留身份，删除、吊销或归档节点不会自动重建或重新授权。一起保留面板和节点数据，已配对后丢失节点身份时，需创建并注册新节点。

各安装方式的备份清单与恢复步骤见升级与备份。

跨主机连接时，将 APP_DOMAIN 设为游戏主机可访问的实际面板地址，建议使用 HTTPS。 节点使用宿主 Docker 管理服务器，请使用可信镜像，并按游戏要求配置端口。

手写同机 Compose 时，面板容器保持监听 0.0.0.0:3000，宿主端口绑定 127.0.0.1。 更换宿主端口时，同步修改 ports 和节点的 GAMEX_PANEL_URL，已配对的节点还需修改持久化的 /data/config.yaml 中的 panel_url 并重启。