常见问题

先记录报错文字和发生时间，再检查对应服务状态。不要通过删除地图、数据库卷或整个数据目录来试错。

部署管理器打不开，或提示 Docker 未运行

桌面版先打开 Docker Desktop，等待运行完成，再重开管理器。Linux 检查安装终端是否成功结束，以及管理端口 3130 是否允许自己的电脑访问。

云服务器同时检查安全组和系统防火墙。只有通过 SSH 隧道访问时，才在自己电脑打开 127.0.0.1:3130。

域名解析了，页面还是打不开

现象	先检查
连接被拒绝	服务和 Nginx 是否运行；网址的协议、端口是否正确
长时间无法连接	公网 IP、安全组、防火墙、域名解析
直接打开域名返回 404	是否遗漏 /play 等已配置的入口路径
HTTPS 无法连接，HTTP 正常	是否已经配置证书并启动 HTTPS 入口，443 是否放行
证书警告	证书是否覆盖当前域名、是否过期

有些域名会让浏览器强制使用 HTTPS，此时仅配置 HTTP 仍会打不开。请完整配置 HTTPS，而不是反复更换浏览器。

具体配置见局域网与公网访问。

登录成功，返回 Play 或 Creator 又要求登录

1. 使用管理器显示的最新地址，退出旧页面后重新登录。
2. 确认 Play、Creator、玩家服务和登录门户使用配套版本。
3. 使用自定义登录镜像时，同步更新对应模板。

独立公网地址支持共享登录，不需要为了登录而强行改成同一个域名。

服主、管理员或创作者登录失败

• Web 部署管理器使用管理端登录密钥。
• 后台“服主登录”使用服主密钥。
• 后台“管理员登录”使用独立管理员账号，不是普通玩家密码。
• Creator 提示没有权限时，请服主在“创作权限”中授权。

多次失败被限流时，先等待再试，不要连续提交。

玩家服务报错或提示数据库连接失败

在“数据配置 → 数据服务”检查 PostgreSQL 是否运行，连接信息是否与原数据库一致，再重新测试连接。

已经有数据时，不要随意改密码或删除数据库。仍然失败，请导出脱敏诊断信息，并记录玩家服务和数据库的错误。

Play 没有地图，或导入失败

先确认导入的是 .boxplay 游戏包，不是 .boxproject 工程；导入后还要将地图组设为开放。

导入失败时检查剩余磁盘空间，并从兼容版本 Creator 重新导出。不要手工改包内清单。具体操作见游玩地图管理。

玩家启动器下载很慢、校验失败或进度不动

1. 保持网络连接，首次进入大地图需要等待。
2. 长时间不动时，关闭当前游戏窗口，再从启动器重新进入一次。
3. 检查是否有新的启动器或引擎版本；服主还需检查地图资源是否完整。
4. 仅某张地图反复失败时，把地图名称、停住的进度和报错交给服主。

进度包含资源校验和缓存写入，不只是网络下载。服务器返回了错误资源时，清理玩家电脑缓存也不能修复，需要服主更新引擎并重新生成有问题的资源缓存。

缓存加速不等于离线游玩；服务器必须保持运行。

备份提示 Permission denied 或 Operation not permitted

先检查部署目录的写入权限、磁盘空间，以及管理器版本。保留完整报错，交给服主或维护者检查具体目录。

不要递归修改整个部署目录的归属，也不要统一设置为 777；数据库和业务服务可能需要不同权限。备份范围见备份与更新。

下载服务组件失败

确认磁盘空间充足、网络能访问 https://assets.box3.fun，再在管理器中重试。下载完成的有效缓存会被复用，不需要反复卸载全部组件。

向维护者提供什么

提供系统、引擎或启动器版本、地图名称、复现步骤、报错截图和时间。部署管理器可从“关于 → 导出诊断包”收集脱敏状态与日志。

不要发送完整 .env、密码、密钥、Cookie 或未脱敏备份。也可以到 GitHub Issues反馈，或加入 QQ 群 1107448537。