去年有个朋友问我：“Superpowers 到底怎么装？”当时我还没正经用过这个项目，只约略知道它是个开源协作工具。后来为了把团队的游戏原型环境从单人本地编辑改成多人在线协作，我专门把 Superpowers 完整部署了一遍，也踩了不少坑。简单说，Superpowers 不是一个传统意义上“装完就能玩”的游戏编辑器，而是一个基于浏览器、通过 WebSocket 做实时同步的协作式游戏创作平台，支持 2D/3D 场景编辑，游戏逻辑用 TypeScript 写，能够让几个人同时在一个项目里改场景、写代码。这篇文章想把从选型、安装、反向代理、数据备份到问题排查的完整过程整理出来，给准备自托管 Superpowers 的团队或个人一个可以直接照着做的参考。
1. 先搞清楚：Superpowers 到底是什么
1.1 它和我们熟悉的游戏引擎差别很大
很多人第一次接触 Superpowers，会下意识拿它和 Unity、Godot 这类引擎对比。Unity 和 Godot 通常是先下载一个体积不小的桌面软件，然后在本地新建工程、打开编辑器、写脚本，因为开发流程都在自己电脑上完成，所以多人协作往往要靠 Git 或者各种目录同步工具。
Superpowers 的思路不太一样。它的编辑器跑在浏览器里，服务端由一个 Node.js 进程提供，客户端打开浏览器页面之后，所有场景物体的移动、属性修改、代码改动，都会通过 WebSocket 实时广播给同一个项目的其他协作者。这种体验很接近“多人同时编辑一份在线文档”，只不过文档里的内容变成了 3D 场景、资源和 TypeScript 脚本。也正因为服务器承担了项目存储和同步职责，所以安装 Superpowers 最关键的环节其实是服务器端部署，而不是本地客户端。
如果你只是一个人做一个 HTML5 小游戏，用官方站点或者本地桌面端就能快速开始；但如果你和我一样，需要让几个成员同时在小项目里搭建原型、互相看对方操作，那自托管一台服务器几乎是绕不开的选择。搞清楚这一点之后，再去看各种安装教程，思路会清晰很多。
1.2 自托管的收益和代价
我选择自托管，主要有三个原因。第一是数据在自己手上，项目素材、脚本、场景文件都落在自己服务器的磁盘里，不会因为第三方平台调整配额或者服务下线而受影响。第二是协作层可控，我可以自己设置端口、接入域名、分配账号和权限，甚至把工作环境限制在团队内网里，这对商业项目原型来说很重要。第三是资源占用可以预估，团队规模不大的时候，一台 2 核 2G 的服务器就能跑得很稳。
代价也很真实：你需要自己维护 Node.js 环境或者容器，处理端口映射、反向代理、HTTPS 证书、数据备份这些原本不用关心的脏活。不过这些工作在当下都是很成熟的运维操作，只要按照下面的步骤一步步来，花一个下午就能完成部署。如果你嫌麻烦，也可以用官方在线版本快速体验，但一旦决定长期使用、稳定协作，自托管带来的可控性远大于那一点维护成本。
1.3 安装前要建立的整体认知
我见过不少人在安装 Superpowers 时反复折腾，核心原因不是某个命令不会敲，而是没有把一个基本问题想透：Superpowers 由“服务端 + 浏览器端/客户端”两部分组成，协作时所有人的动作都要经过服务器中转。所以部署本质上要做三件事：
- 把服务端跑起来；
- 让团队成员的浏览器能正确访问到服务端；
- 保证服务端的数据目录不会因为升级或容器重建而丢数据。
这三件事分别对应端口能不能通、WebSocket 是否能正常升级、数据有没有挂载到宿主机。后文所有安装步骤，其实都是在围绕这三件事展开。想清楚了这一点，你会发现 Nginx 配置和数据卷挂载并不是什么高深的内容，只是为了防止最关键的两个故障点：连不上和丢数据。
2. 安装前的准备工作与方案选型
2.1 三种运行方式怎么选
Superpowers 常见的运行方式有桌面客户端、Docker 容器和 Node.js 源码部署。桌面客户端适合个人体验，它本质是一个打包好的本地服务加浏览器外壳，单人用起来最简单；但要让外部协作者访问，桌面端的能力有限。Docker 容器适合团队长期使用，环境隔离、升级方便、数据卷也比较好管理。源码部署则适合想深入改造项目，或者希望在自己的 Node.js 环境里定制插件的人。
| 运行方式 | 适合场景 | 维护成本 | 协作能力 |
|---|---|---|---|
| 桌面客户端 | 个人本地体验、快速验证 | 低 | 单人为主，远程协作不推荐 |
| Docker 容器 | 团队稳定使用、服务器部署 | 低 | 强，升级和回滚方便 |
| Node.js 源码 | 二次开发、深度定制 | 中高 | 强，但需要自己关注依赖项 |
如果让我推荐，我会建议小团队优先选择 Docker。原因很直白：Docker 的启动参数、数据卷、重启策略都能在一条命令里说清楚，出问题后重建容器的成本非常低。源码部署虽然灵活，但 npm 依赖升级、系统环境差异、权限问题都会在关键时刻跳出来干扰你，对不想折腾服务器的人来说并不友好。
2.2 服务器配置与端口规划
Superpowers 本身不是什么重型应用，Node.js 进程的内存占用通常在几百 MB 到 1G 左右，但实际需求会因为团队规模和使用方式而浮动。我建议最低配是 2 核 2G 内存、20G 以上磁盘，内存太小容易出现进程被系统杀掉的情况；磁盘空间主要消耗在纹理、音频、模型这些资源文件上，素材越多，磁盘增长越快。
端口方面，Superpowers 服务默认的通信端口是 2870，但这不意味着你一定要在公网暴露 2870。常见的做法是让 Nginx 监听 80 或 443 端口，再把请求转发到内网地址 127.0.0.1:2870。这样做的好处是访问时不带端口号，HTTPS 证书也好配置，更重要的是 WebSocket 连接可以跟着 HTTP 一起走，不需要额外开放其他端口。注意一点：WebSocket 使用的是和 HTTP 一样的 TCP 端口，不存在“再多开一个端口给 WebSocket”这种说法，很多新手在这里会被误导。
2.3 动手前先回答三个问题
开始安装之前，先花十分钟把下面三个问题定下来，能省掉后面一大堆返工。
第一个问题：服务器有没有公网入口？如果你的服务器在内网，团队成员只能通过内网访问，那反向代理可以省略；如果需要在外部访问，需要先确认公网 IP、域名解析和云服务商的安全组规则都由谁负责。
第二个问题：域名和证书要不要配？临时测试用 IP 加端口完全足够；但长期协作一定要有个域名，哪怕是一个二级域名。原因不是“好看”，而是浏览器对 HTTPS 页面发起 HTTP 请求会有混合内容限制，如果以后你想在 HTTPS 下面用编辑器的所有功能，服务地址就必须也走 HTTPS。
第三个问题：数据目录放在哪里？使用 Docker 时，这个问题就是数据卷要挂载到宿主机哪个路径；使用源码部署时，就是服务以哪个用户运行、数据写在哪个目录。提前规划好，后面升级容器或者迁移服务器才不会丢项目。
3. 服务器端完整安装实录
3.1 用 Docker 构建并启动服务
我这里选择自己写一个简单的 Dockerfile 来构建镜像，而不是直接使用某个来历不明的现成镜像。有时候第三方镜像版本比较旧，或者里面有多余的依赖，自建镜像虽然多花一点构建时间，但心里更踏实。Dockerfile 内容如下：
FROM node:18-bullseye RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/* RUN git clone https://github.com/superpowers/superpowers.git /app WORKDIR /app RUN npm install --production EXPOSE 2870 CMD ["npm", "start"]构建镜像：
docker build -t superpowers-local:1.0 .然后启动容器：
docker run -d --name superpowers \ -p 2870:2870 \ -v superpowers-data:/app/data \ --restart unless-stopped \ superpowers-local:1.0这里几个参数有必要解释一下。-d表示后台运行，关掉终端后容器不会跟着退出；--name superpowers给容器起了个固定名字，后续查看日志、执行命令都方便；-p 2870:2870把宿主机的 2870 端口映射到容器内的 2870 端口，外部访问的就是宿主机这个端口；-v superpowers-data:/app/data创建了一个名为superpowers-data的数据卷并挂载到容器内的数据目录，这一步直接决定了后续容器删除后项目数据会不会丢；--restart unless-stopped让容器在服务器重启后自动恢复运行。
启动后先看状态：
docker ps docker logs -f superpowers看到服务日志中输出监听地址，就说明服务跑起来了。这时用浏览器访问http://服务器IP:2870，能出现初始配置界面就是正常。如果项目实际用的数据目录不是/app/data，以官方仓库里的说明为准，但提前挂载一个卷不会有什么坏处。
如果团队里有多个服务要管理，用 Docker Compose 会更直观。创建一个docker-compose.yml：
services: superpowers: build: . ports: - "2870:2870" volumes: - superpowers-data:/app/data restart: unless-stopped volumes: superpowers-data:然后执行docker compose up -d即可。
3.2 用 Node.js 源码方式部署
如果你不想用 Docker，想在宿主机上直接跑 Node.js 服务，步骤也不复杂。我建议先通过 nvm 安装 Node.js，避免直接用系统包管理器装到不合适的版本。安装命令大致如下：
sudo mkdir -p /opt/superpowers sudo chown -R "$USER":"$USER" /opt/superpowers git clone https://github.com/superpowers/superpowers.git /opt/superpowers cd /opt/superpowers npm install npm start有一点必须提醒：如果安装和使用过程中涉及权限切换，尽量用普通用户来跑服务，不要直接用sudo npm start。因为 Node.js 在运行时会往数据目录里写文件，如果以 root 身份创建了这些文件，之后用普通用户维护目录时就会遇到权限错乱，排查起来很麻烦。
源码部署适合接进 systemd 托管。创建一个服务文件/etc/systemd/system/superpowers.service：
[Unit] Description=Superpowers server After=network.target [Service] User=deploy WorkingDirectory=/opt/superpowers ExecStart=/usr/bin/npm start Restart=always RestartSec=10 [Install] WantedBy=multi-user.target然后执行：
sudo systemctl daemon-reload sudo systemctl enable --now superpowers日志查看用journalctl -u superpowers -f。这个模式下，项目数据默认写在工作目录下，如果你改了WorkingDirectory，备份时就要留意对应路径。
3.3 用 Nginx 做反向代理并正确转发 WebSocket
直接使用IP:2870访问能工作，但我强烈建议长期使用加一层 Nginx 反向代理。一是为了统一入口，团队成员只记一个域名；二是为了后面接 HTTPS 证书；三是因为 Nginx 对 WebSocket 有标准的代理支持，配置正确后连接非常稳定。
我的 Nginx 配置长这样：
server { listen 80; server_name your.domain.com; location / { proxy_pass http://127.0.0.1:2870; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }这里面最关键的是Upgrade和Connection两行。没有它们，WebSocket 握手就无法完成，表现就是编辑器页面能打开，但项目一直加载不出来，或者连接反复断开。proxy_read_timeout和proxy_send_timeout也需要调大，否则 Nginx 会在默认 60 秒后断开长时间不活跃的连接，多人协作时会时不时出现同步中断。
写完配置执行：
nginx -t sudo systemctl reload nginx如果之前已经申请了 HTTPS 证书，把server块改成监听 443 ssl 即可，proxy_pass部分不用动。
3.4 数据备份和恢复不能临时抱佛脚
自托管最怕的不是服务崩了，而是服务崩了之后发现项目数据全没了。Superpowers 的项目文件、账号数据都保存在数据目录里，所以备份策略围绕这个目录展开。
Docker 模式下，我倾向于先停容器再打包，避免文件正在写入时备份导致数据不一致：
docker stop superpowers docker run --rm -v superpowers-data:/data -v $(pwd):/backup \ alpine tar czf /backup/superpowers-$(date +%F).tar.gz -C /data . docker start superpowers源码部署模式下，直接打包数据目录也一样，但最好先停止 systemd 服务：
sudo systemctl stop superpowers sudo tar czf /backup/superpowers-$(date +%F).tar.gz /opt/superpowers/data sudo systemctl start superpowers备份文件生成后，一定要做一次恢复演练，不要等出事了才第一次接触解压命令。恢复时如果权限不对，记得把文件 chown 回服务运行用户，否则启动后会发现“只读”“没有权限”之类的问题。把备份命令写进 cron 定期执行，比靠脑子记住定期备份要可靠得多。
4. 客户端安装与首次项目启动
4.1 访问端选择：浏览器直连还是桌面客户端
Superpowers 的核心编辑器在浏览器里就能跑，所以在服务器部署完成后，团队成员的浏览器本身就是客户端，不需要额外安装什么大软件。第一次访问时，直接在浏览器输入http://服务器IP:2870或者https://你的域名即可。
桌面客户端适合那些想要“本地应用窗口”体验的人，它本质上还是连到服务器，只是外面套了一层桌面壳。要注意的是，如果你给服务配置了 HTTPS 证书，客户端里的服务器地址一定要填https://开头的完整地址，否则浏览器会拦截混合内容，WebSocket 也连不上。这个坑我在自己电脑上遇到过，填连接地址时复制粘贴最容易漏掉协议头。
4.2 创建账号、项目并邀请协作者
首次打开页面时，一般会引导你创建管理员账号，这一步相当于服务器的“所有者”。之后在界面里创建团队成员的普通账号，每个协作者用自己的账号登录。
创建新项目时，根据需求选择 2D 或 3D 模板，我一般先从空白模板开始，避免模板里带的示例资源干扰后续修改。项目创建后，编辑器会打开一个类似 Web IDE 的界面，左侧是资源管理器，中间是场景视口，右侧是属性面板，底部或侧边可以打开代码编辑器。
邀请协作者最直接的方式是：在服务器管理界面为对方创建账号，然后进入项目成员设置，把对方用户名加进来并分配相应权限。权限等级可以参考常见的“编辑/查看”模型：编辑者可以改场景和资源，查看者只能观察实时状态，管理员负责项目增删和成员管理。多人同时在线时，场景视图里会显示各自的彩色光标，你能清楚地看到对方正在拖动哪个物体。
4.3 写第一段脚本：让方块动起来
给新手看一个最简单的脚本示例。假设场景里有一个方块实体，希望在运行时让它横向移动。在资源管理器里新建一个 TypeScript 脚本，命名为CubeMover，代码如下：
class CubeMover extends Sup.Behavior { speed = 2; update() { const pos = this.actor.getLocalPosition(); pos.x += this.speed * Sup.Time.deltaTime; this.actor.setLocalPosition(pos); } }这段代码干的事情很简单：每一帧把方块当前位置取出来，在 x 方向上增加speed * deltaTime，再写回去。之所以要乘deltaTime，是为了让移动速度不依赖帧率，避免在不同电脑上运行时快慢不一致。保存脚本后，把它当作组件挂到场景里的方块实体上，点预览就能看到方块运动了。
如果你用的版本里 API 名字和我写的有些差异，不要硬抄，以官方模板或文档为准。版本更新时我见过不少类似getPosition改成getLocalPosition的变化，照着官方示例顺手调整一下就行。
5. 常见问题与排查技巧实录
5.1 页面打不开，先查端口和防火墙
访问不到服务时，不用急着怀疑 Superpowers 坏了。先在服务器上执行：
ss -lntp | grep 2870有输出说明服务在监听；如果没有任何结果，先看 Docker 容器或 Node.js 进程有没有在跑。确认服务正常后，再检查云服务商的安全组和服务器自身的防火墙。有些安全组默认只放行 80 和 443，你直接访问 2870 端口自然会被拦在外面。如果已经用了 Nginx 把服务代理到 80 端口，那 2870 端口的公网访问反而不需要开放，只需要保证 Nginx 能访问本机 127.0.0.1:2870 即可。
5.2 反向代理之后编辑器一直转圈，问题多出在 WebSocket
症状是首页能打开，项目列表能看到，但进入项目后一直加载，或者编辑器状态一直停留在连接中。打开浏览器开发者工具，切到 Network 面板，刷新一下页面，重点看 WebSocket 这条请求。正常状态应该是101 Switching Protocols，如果看到 404 或者 500，说明 Nginx 配置里的 location 没有正确匹配到服务路径，或者Upgrade头没有被转发。
另外，如果前面还挂了 CDN，很多 CDN 默认不支持 WebSocket，或者只支持严格的 HTTP 请求。这种情况会让你误以为是 Nginx 配置不对。临时办法是把域名解析直连服务器，或者把 WebSocket 路径绕过 CDN，只要确认直连时连接是稳定的，问题就定位在 CDN 上。
5.3 多人协作延迟、断开，先看带宽和资源占用
多人在线协作的所有资源同步都要经过服务器，所以当协作者反馈“操作很卡”“经常掉线”时，先看服务器带宽是不是被打满了。上传带宽尤其重要，几个人同时拖入大纹理素材时，瞬间流量会撑满家庭宽带的弱项。解决办法有两个方向：一是提升服务器带宽，二是在项目里压缩素材，不要把几 MB 的 PNG 直接拖进场景。转成压缩过的 WebP 或者合理缩小尺寸，明显能改善协同体验。
还可以同时看一眼docker stats或者htop，确认内存没有被打满。如果持续在 90% 以上，就需要关掉一些不用的项目，或者增加 swap。对小型团队来说，swap 是一个性价比很高的临时手段。
5.4 忘记管理员密码，不要急着删库
服务器跑久了，管理员密码有可能会被忘记。这时候先别慌，更别直接在服务器上乱删数据目录。先做一份完整备份，然后找到存放用户数据的数据库或文件，一般在数据目录下。根据官方文档或数据目录结构，看看有没有重置密码的命令行脚本；如果没有，再考虑备份后重置用户数据并重新创建管理员账户。项目数据和用户数据通常是分开存储的，所以重建管理员不会把已有项目也一起删掉。
我个人的习惯是，管理员账号的密码写进服务器的.env文件里，而不是记录在聊天软件中。这样即使忘掉了，还能在被授权访问服务器的同事那里找回。
5.5 容器升级后项目数据不见了，问题几乎都出在“没挂卷”
这个坑我见过太多次了。很多人第一次启动容器时图省事，没有挂载数据卷，项目全写在容器可写层里。容器还在的时候一切正常，一升级或者一删除容器，数据就跟着容器一起没了。升级前用下面命令检查一下挂载情况：
docker inspect superpowers看输出里的Mounts部分，确认宿主机路径和容器内数据目录之间有映射。如果发现没有挂载，先立即用docker cp把数据从旧容器里拷出来：
docker cp superpowers:/app/data ./backup然后再创建新容器，把备份目录或新数据卷正确挂载进去。这个排查思路可以同时用在容器迁移、磁盘迁移和服务器换机场景里。
5.6 一些值得长期坚持的操作习惯
我在部署完 Superpowers 之后，给自己定了几条土规矩，现在回头看都很值得分享。每周做一次数据备份，备份后顺手确认备份文件大小是正常增长而不是突然变成几 KB；每次升级容器前，都会先docker inspect看一眼挂载路径和镜像 tag，确认没有问题再动手；服务器磁盘使用量超过 70% 时，主动清理无用的临时资源和旧备份。说难听一点，这些习惯平时看着不起眼，但真到磁盘满了或者需要回滚版本的时候，它们就是救命稻草。
如果你准备把 Superpowers 引入团队，我建议第一周先安排两三个人小规模试用，把编辑习惯、项目模板、资源命名规范都定下来，再慢慢增加成员。协作工具真正顺手的时刻，不是安装完成的那一刻，而是小团队已经习惯在同一个场景里互相修改、随时预览并高效同步的时候。
