Panel + Daemon 傻瓜式部署

本页用于单机测试环境：Nginx 提供 Panel HTTPS，Panel 进程只监听回环地址，独立的 TLS Gateway 接受 Daemon 控制连接，Daemon 使用专用普通账户和 Rootless Docker。生产多实例环境还需要 PostgreSQL、Redis 和共享 Artifact Store，不能直接照搬本页的 SQLite 配置。

先确认是否需要 Registry

Panel 与 Daemon 的基础联调不依赖 GameX Registry。只有测试 Plugin 发布、审核、签名、撤销、市场发现或 Registry 独立账户时，才需要另外部署 Registry。Registry 不与 Panel 共用账户、数据库、Session 或 TLS 入口，不要把它当成 Panel 的子模块。

最省事的一键部署

1. 准备测试机

• Ubuntu 26.04 LTS，x86-64，建议至少 2 核、4 GiB 内存和 20 GiB 可用空间。
• 可使用 SSH Key 登录 root；不要把 SSH 密码放进命令参数。
• 云安全组允许入站 TCP 22、80、443 和 9443。
• 公网 IP 必须能从互联网访问；80 端口用于 ACME 校验。

2. 把 SSH Key 放在 Dev 内

例如放到 Dev/.gamex-dev/ssh/test-host-ed25519，权限必须为 0600。部署工具会拒绝使用 Dev 目录外的身份文件，本地编译缓存、二进制和暂存文件也只会写入 Dev/.gamex-dev。

3. 执行一条命令

在 Dev 目录运行：

gamex-references/deployment/test-stack/deploy.sh \
  --host <测试机公网 IP> \
  --identity-file <Dev 内 SSH Key 的绝对路径> \
  --yes

脚本会依次完成：

1. 在 Dev 内交叉编译 gamex、gamex-daemon 和两个 Workspace 辅助程序。
2. 安装 Node.js、Nginx、Docker Rootless 依赖和 Certbot。
3. 创建 gamex-panel 与 gamex 专用账户，禁用系统级 Docker Socket。
4. 上传当前 gamex-panel 工作树，安装依赖并构建生产版本。
5. 为公网 IP 申请短期证书，配置 HTTP 跳转、Panel HTTPS 和自动续期。
6. 初始化单机 Panel，启用 TLS Gateway、管理员 TOTP、SQLite、本地上传和完整性扫描。
7. 生成一次性配对令牌，通过标准 gamex configure 流程注册并启动 Daemon。
8. 把管理员密码、TOTP 密钥和恢复码下载到项目的 Git 忽略私密目录。
9. 验证公网 HTTPS、Gateway TLS、Rootless Docker、systemd 服务和控制连接。

脚本不会把 SSH 密码、Panel 密码或配对令牌输出到 Wiki。首次完成后，到项目的 gamex-references/docs/private/ 目录读取管理员凭据；该目录必须保持 Git 忽略，文件权限必须为 0600。

4. 只读复查

重新部署前先运行只读检查：

gamex-references/deployment/test-stack/deploy.sh \
  --host <测试机公网 IP> \
  --identity-file <Dev 内 SSH Key 的绝对路径> \
  --verify-only

成功输出应包含四个 active 单元、Rootless Docker 检查成功、controlConnected 为 true，以及 Gateway 证书 Verification: OK。

完整手工流程

一键脚本是规范实现；需要人工排障时，按以下顺序拆开执行。

1. 基础软件与账户

安装 Nginx、Node.js 22、Docker、uidmap、slirp4netns、fuse-overlayfs、Python venv、编译工具、curl、rsync 和 jq。创建两个不同的账户：

• gamex-panel：无交互 Shell，只运行 Panel。
• gamex：普通账户，运行 Rootless Docker 与 Daemon。

禁用系统级 Docker：

sudo systemctl disable --now docker.service docker.socket
sudo loginctl enable-linger gamex

然后以 gamex 账户安装并启动 Rootless Docker。最终 Socket 应为 /run/user/<uid>/docker.sock，docker info 的安全选项必须包含 rootless。

2. 构建与上传

在 Dev 内把 Daemon 构建为 Linux x86-64 静态二进制，输出到 .gamex-dev。上传 Panel 时排除 .git、node_modules、dist、data、logs 和现有运行配置，避免覆盖服务器状态。服务器上的 Panel 目录为 /opt/gamex/panel，随后以 gamex-panel 身份执行：

npm ci --no-audit --no-fund
npm run build

3. HTTPS 与 Gateway 证书

先让 Nginx 在 80 端口提供 ACME Webroot，再用支持 IP 证书的 Certbot 申请 shortlived Profile。浏览器入口监听 443，代理到 127.0.0.1:3000；Gateway 直接监听 9443。

短期 IP 证书的链可能包含多张 CA 证书，而 Gateway 的信任固定要求直接签发 CA 恰好一张。续期 Hook 必须从 chain.pem 提取第一张证书作为 Gateway CA 文件，并把私钥以 gamex-panel 所有、0600 权限安装。直接复制整条 chain.pem 会导致 Panel 拒绝启动。

续期单元至少每 12 小时检查一次：

sudo systemctl status gamex-certbot-renew.timer
sudo certbot certificates

4. Panel 运行配置

单机测试建议使用以下边界：

配置	值
Panel 监听	127.0.0.1:3000
反向代理信任	开启
数据库	SQLite，./data/database.sqlite
Cache	内存
文件存储	./data/uploads
Artifact 扫描	integrity
Gateway 监听	0.0.0.0:9443
Gateway 路径	/api/v1/daemon/connect
Gateway 心跳	15 秒
Gateway 租约	45 秒

Panel systemd 单元应使用 gamex-panel 账户，限制可写路径为 Panel 数据目录，并设置 NoNewPrivileges、ProtectSystem、ProtectKernelModules 与 ProtectKernelTunables。

首次初始化时创建独立 SUPER_ADMIN，立即启用 TOTP 并离线保存恢复码。生产凭据不能写入项目；仅测试环境可以写入 Git 忽略、权限 0600 的项目私密文件。

5. Daemon 配对

在 Panel 的 Daemon 管理中以强验证管理员为目标主机创建短期、一次性接入 Link，然后在 Daemon 主机运行：

sudo gamex configure

按隐藏提示粘贴完整接入 Link，输入唯一的 Daemon 名称并确认启用服务。配置成功后会写入 /etc/gamex-daemon/config.yaml 与 /etc/gamex-daemon/identity，并启用 gamex-daemon@gamex.service。不要把 Link 放进命令参数或 Shell History。每增加一台 Daemon 都要创建不同 Link，并在放置 Workspace 前核对架构、CPU、内存、磁盘、Rootless Docker Socket 和在线状态。

6. 验收

sudo gamex doctor
sudo systemctl is-active nginx.service gamex-panel.service gamex-daemon@gamex.service
curl --fail https://<测试机公网 IP>/api/health/ready
sudo curl --unix-socket /run/gamex-daemon/admin.sock http://localhost/status
openssl s_client -connect <测试机公网 IP>:9443 -servername <测试机公网 IP> -verify_return_error -brief

还要确认 3000 只监听回环地址、9443 对外监听、系统级 Docker 保持禁用、证书续期 timer 为 active。重启 Panel 和 Daemon 后，旧连接租约可能保留最多约 45 秒；在 90 秒内恢复 controlConnected=true 属于正常行为。

常见故障

9443 没有监听

先检查 Panel 运行配置是否真的写入全部 DAEMON_GATEWAY_* 字段，再查 Panel 启动日志。如果初始化接口接受了字段但生成配置缺失，这是配置持久化缺陷，不要只在服务器临时追加；应修复生成器并增加回归测试。

Panel 报 CA 数量错误

不要把多证书 chain.pem 原样交给 Gateway。提取第一张直接签发 CA 证书，并保持 Gateway 私钥权限为 0600。

Daemon 一直显示未连接

按顺序检查 9443 云安全组、Gateway TLS 校验、control_url、Daemon 日志和 Panel Gateway 日志。刚重启时先等待租约到期；超过 90 秒仍未连接才按故障处理。

80 或 443 不通

先确认 Nginx 正常，再检查云安全组。80 端口在证书签发与续期期间必须可从公网访问；只开放 443 会导致后续续期失败。

预发布重装与恢复

首个稳定版发布前不支持原地更新。一键命令只用于全新安装；重新部署时应使用空数据库，并重新完成 Panel Setup 和 Daemon 注册。需要恢复生产数据时，只能恢复彼此匹配的 Panel 构建、数据库、Artifact Store、Panel 身份和 Daemon 二进制，不要混用不同版本的协议端。详细步骤见部署、回滚与故障恢复。