Superpowers 自托管指南：从零部署开源实时协作开发环境

看到"想要安装 superpowers"这个检索需求的时候，我第一反应是笑了。这词一摆出来，不同圈子里的人理解可能完全不一样：有人以为是某种效率方法论，有人以为是游戏里的隐藏能力，还有人在找某个浏览器插件。但实际上，在开发者圈子里提到 Superpowers，绝大多数情况下指的是同一个东西——一个开源、免费、可以部署在自己服务器上的实时协作开发环境。如果你正拿着这个词满网找安装教程，那你大概率和我当初一样：不想用别人托管好的在线服务，想自己装一个，把数据和团队协作完全掌握在自己手里。

这篇文章就从我实际部署 Superpowers 的完整经历出发，把这个项目到底是什么、它适合解决什么问题、安装前需要准备什么环境、从拉取代码到跑起来的每一步怎么做、第一次进后台要配置哪些内容，以及真正用起来之后在维护上会遇到哪些坑，一次性讲透。整个路线是我自己一步步跑通过的，你照着抄基本不会有意外。

1. 先别急着敲命令：这个 Superpowers 到底是什么来头

1.1 它不是"超能力"，而是一个浏览器里的实时协作开发平台

Superpowers 的官方定位是：一个基于浏览器的开源实时协作开发环境。听起来有点抽象，我用大白话解释一下。它做的事情本质上和 Google Docs 之于文档一样——文档协作让你和同事同时在浏览器里编辑同一篇稿子，看到对方的光标和修改；Superpowers 把这种体验搬到了"写代码、做项目"这件事上：所有项目文件、资源、脚本都存放在一台服务器上，团队成员用浏览器访问同一个地址，在同一时间编辑同一个项目，任何改动几乎实时同步到其他人的屏幕上。

我最初接触这个项目是被它"天生协作"的架构吸引的。注意我的措辞：天生协作。它不像 VS Code Live Share 那样，需要一个本地 IDE，再靠插件把你的工作区共享给别人。Superpowers 的整个设计从底层就是多人在线的：项目在服务器上，编辑器在浏览器里，数据同步是内置功能，不是后来补的补丁。前端编辑器基于 CodeMirror，界面用 React 实现，后端是 Node.js + TypeScript，整体开源在 GitHub 上。

1.2 核心能力拆解：不止是"能多人编辑"

光说"多人编辑"还不够，Superpowers 真正有价值的地方在于它把开发环境、资源管理和协作整合成了一个整体。我把它拆开讲：

• 实时协作文本编辑：多个用户可以同时进入同一个项目，看到彼此的光标、选中区域和编辑动作，修改几乎零延迟同步。这个体验非常像 Floobits（如果你用过的话）或者 Google Docs，但粒度是代码级别的。
• 场景-实体-组件结构：项目里可以创建"场景（Scene）"、"实体（Entity）"和"组件（Component）"。实体是一个对象，组件挂在实体上提供行为。这套组合逻辑特别适合做游戏原型、交互式网页和创意编程项目。
• 内置资源管理器：可以直接往项目里拖拽图片、音频、3D 模型等资源，上传后多人共享，不需要额外搭一套文件服务器。
• 行为脚本系统：在组件上挂 JavaScript/TypeScript 脚本就能定义逻辑，代码改动会热更新，保存后立即在浏览器里生效，连刷新都不怎么需要。
• 项目发布能力：做好的项目可以绑定域名、生成预览链接，直接分享给访客，而不是只能内部看。

1.3 它适合什么人、解决什么场景

我用它实际跑过的场景有两个，一说你就明白适不适合你了。

第一个场景是远程结对编程。我和一个有段时间没见的朋友想一起写一个浏览器小游戏原型。常规做法是：开一个视频会议，一个人共享屏幕，另一个人看着。体验很差，因为只有一个人在动键盘。换成 Superpowers 之后，两个人在不同城市，打开同一个网址，各写各的模块，光标动来动去，代码互相看得见，沟通效率一下就上来了。

第二个场景是创意编程教学。给学生讲代码，最烦的就是"我这里能跑，你那里跑不起来"。在 Superpowers 里，所有人共用同一个项目环境，不存在本地依赖不一致的问题。你把项目链接丢到班级群里，大家打开就是同一个环境，改完代码所有人立刻看到效果。

如果你需要的是这几个功能点——多人同时改代码、项目数据自己掌控、不依赖本地 IDE、适合快速原型——那这个项目大概率值得你装一趟。

2. 自托管前的路线选择：不要一上来就 npm install

安装这东西之前，我建议你先花十分钟想清楚两个问题：一是用官方托管还是自托管，二是你的服务器环境够不够格。我见过太多人上来就 npm install，装到一半发现 Node 版本不对，或者端口被占用，白白浪费一小时。

2.1 官方托管 vs 自托管，怎么选

Superpowers 官方提供了一个在线托管服务，注册就能用，非常省心。但"想要安装 superpowers"这个需求既然存在，说明有一批人并不满足于托管。我自己选自托管的原因很简单：项目里有一些不想放到第三方平台上的东西，而且我要控制服务的生命周期。托管平台哪天调整策略、限制免费额度，项目就跟着受影响；自己装一台，一切都是可控的。

自托管的代价你要有心理准备：服务器要自己维护、安全要自己操心、升级要自己手动操作。如果你只是一个人想快速试试功能，官方托管完全够用；如果你是团队使用、要做私有化、或者打算长期做项目载体，自托管是更稳的方向。

2.2 环境准备清单

我部署用的是一台 Ubuntu 22.04 的云服务器，2 核 4G 内存。这个配置跑起来毫无压力。实际操作里，最低门槛我觉得 1 核 2G 也能转，但多人同时编辑时会有一点卡顿。下面是我整理的环境要求，照着准备就行：

2.3 大多数人装到一半会卡住的三个环境坑

先说第一个坑：Node.js 版本。这个项目对 Node 版本有要求，建议直接用 Node.js 官网的 LTS 版本。如果你服务器上原本装了旧版 Node，装依赖的时候大概率会报错，要么是 node-gyp 编译失败，要么是某些模块版本不兼容。我的做法是用 nvm 安装和管理 Node 版本，切换起来非常方便，命令形如：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install --lts node -v

第二个坑是端口占用。Superpowers 默认监听 8080 端口，很多服务器上这个端口已经被别的服务占了。你可以先检查端口状态：

sudo lsof -i:8080

如果有进程占用，要么停掉该进程，要么把 Superpowers 的端口改掉。改端口一般在配置文件里动，建议用闲置端口，省得和已有服务打架。

第三个坑是云服务器安全组。很多人明明服务启动成功了，浏览器却打不开，原因就是云服务商控制台里的安全组没放行 8080 端口。这个别忘了到云厂商的安全组规则里加上一条 TCP 8080 的入站规则。本地虚拟机没有这个问题，云服务器几乎必查这一项。

3. 完整安装过程：从拉取源码到浏览器打开管理界面

环境准备好之后，真正的安装流程其实不算复杂。下面这套命令我在全新服务器上完整跑通过，可以直接复制，按顺序执行。

3.1 拉取源码并锁定版本

先到 GitHub 上找到官方仓库，复制仓库地址，然后在服务器上克隆。我建议加--recursive参数，因为项目可能包含子模块，带上这个参数能一次拉全：

git clone --recursive https://github.com/superpowers/superpowers.git cd superpowers

拉到本地后，别急着装依赖。先看一眼项目当前的版本和分支状况。我个人的习惯是切换到官方发布的最新稳定 tag，而不是直接跑 master 分支——master 上可能有不稳定的新特性。用下面两个命令查看：

git tag git checkout tags/<最新稳定版本号>

这一步看似多余，实际能帮你省掉后面很多"这个功能怎么和文档不一样"的困惑。版本锁定之后，项目的依赖结构就固定了，出了问题也好定位。

3.2 安装项目依赖

进入项目目录后，执行依赖安装：

npm install

这一步是整个安装过程中耗时最长的，尤其是服务器在国内、网络状况一般的时候，npm 可能卡在某个包上下载不下来。如果碰到这种情况，换成国内镜像源能快非常多：

npm config set registry https://registry.npmmirror.com npm install

装依赖的过程中我踩过一次比较典型的坑：因为服务器上之前用过非 root 用户跑过别的 Node 项目，部分依赖的编译临时文件残留，导致 install 报出各种权限或者 EACCES 错误。处理办法很简单，删掉 node_modules 和 package-lock.json，回到项目根目录重新安装：

rm -rf node_modules package-lock.json npm install

遇到编译类错误的时候，还可以顺手把 npm 缓存清理一下，npm cache clean --force通常能解决不少诡异问题。

3.3 启动服务并验证

依赖装好之后，按项目 README 里的启动命令来。常见的是直接：

npm start

启动后终端会输出监听的地址和端口。正常情况会看到类似"listening on port 8080"之类的日志。这时先不要关终端，另外开一个 SSH 窗口，执行下面命令确认端口处于监听状态：

netstat -tlnp | grep 8080

确认没问题后，在本地浏览器访问http://你的服务器IP:8080。如果页面能正常打开，恭喜你，服务已经起来了。这一版安装通常不需要初始化数据库之类的额外步骤，首次访问会引导创建管理员账号，后面我会详细说。

3.4 用 Nginx 反向代理和 HTTPS

直接通过 IP 加端口访问在测试阶段没问题，但正式用的时候我有两个强烈建议：一是用域名代替裸 IP，二是配置 HTTPS。理由很简单——浏览器很多高级 API 在非 HTTPS 环境下会被禁用，协作功能依赖的 WebSocket 连接在 HTTPS 下也更稳定，不会莫名其妙被中间网络设备拦掉。

我的 Nginx 配置大概是这样的：

server { listen 80; server_name your-domain.com; return 301 https://$host$request_uri; } server { listen 443 ssl; server_name your-domain.com; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; location / { proxy_pass http://127.0.0.1:8080; 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_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

第 9 到第 11 行的Upgrade和Connection是 WebSocket 能正常走代理的关键，少了这几行，你可能会遇到"登录正常，但协作时老是断线"的问题。SSL 证书用 Let's Encrypt 签一个就行，这里不再展开。

4. 装完不等于会用：首次登录后的权限逻辑与项目配置

服务跑起来之后，很多人以为接着就能开始写代码了。其实还差一步：把后台的用户体系、项目权限、域名绑定搞清楚。这个阶段我一开始是摸黑操作的，后来才慢慢理顺。

4.1 管理员账号是入口

第一次访问站点时，页面会引导你创建第一个账号。有一点要特别注意：这个账号就是系统管理员，权限比后来注册的用户大得多。我当时没太在意，随便用了自己的名字注册，后来才发现邀请队友的时候，队友的权限默认比较受限，只有管理员能改全局设置、创建某些类型的项目。

如果你需要区分"管理员"和"普通成员"，最早的账号通常承担管理员角色，后面邀请进来的人都是普通用户。所以注册第一个账号的时候，建议用一个专门的管理员邮箱，而不是某个人的个人邮箱。

4.2 开放注册还是邀请制

Superpowers 支持用户自助注册。如果你的目的是团队内部使用，我不太建议放开注册，因为任何人拿到你的域名都能注册账号，白白占用资源，还可能有安全风险。更稳的做法是关闭自助注册，由管理员手动创建账号或发送邀请。

邀请逻辑上，管理员后台创建用户之后，对方就能用账号密码登录了。这个机制很简单，但很关键——很多协作工具最后沦为没人用的工具，就是因为第一天把注册权限全放开，然后被一堆垃圾账号搞爆了体验。

4.3 公开项目与私有项目

项目创建时有公开和私有两种可见性设置。公开项目的预览链接可以被不登录的访客打开；私有项目则只有项目内的成员能看到。我做过的项目大部分设为私有，只有最终想展示给别人看的效果才切换成公开。

这个逻辑和代码仓库的公开/私有很类似，但要注意：公开项目不仅仅意味着可读。如果给访客的权限设置不当，对方甚至可能参与编辑。所以对外分享项目链接时，建议到项目设置里确认一下访客的权限级别，避免被陌生人改乱项目内容。

4.4 域名绑定

平台允许给项目绑定独立域名，这样外部访客看到的就是一个漂亮的专属地址，而不是一串又长又难记的内部链接。绑定域名之后，平台会自动做一层分发，访客打开你的域名就能直接看到项目页面。

这个功能对做作品集或者对外演示特别有用。域名解析到服务器 IP，然后在后台的项目设置里填写域名，稍等生效即可。我试下来生效时间基本在一分钟内。

5. 真实协作体验：创建项目、写脚本、拉队友一起开干

配置完基础内容，接下来才进入最好玩的部分——真正上手建一个项目。我以"搭一个浏览器小游戏原型"为例，把从创建到多人协作的完整流程走一遍。

5.1 从空白项目到第一个可见实体

登录后台之后，点击创建项目，会出现几个模板选项，包括空项目、2D 游戏、3D 场景等。如果是从头做，我建议选空项目或者 2D 游戏模板，后者自带基础场景设置，省去手动调渲染器的麻烦。

新建项目后会看到一个工作区界面，默认是一个空的编辑器布局。接下来要做的第一件事是创建一个场景。场景相当于项目的一个舞台，所有可见的东西都要放进场景里。创建完场景，再往场景里添加一个实体，实体的位置、旋转、缩放在右侧属性面板里都能直接改。

这一步我要多说一句：Superpowers 里的"实体"概念和传统游戏引擎的 GameObject 很像，它可以是一个空壳，也可以挂载各种组件。我刚接触的时候总想直接往场景里"画"一个图形，后来才弄明白正确姿势是先建实体，再给实体挂渲染组件，比如 SpriteRenderer，它才会变成一个可见的图形对象。

5.2 给实体挂组件、写行为脚本

视觉效果搞定后，下一步就是让对象动起来。给实体的组件列表里新增一个"行为脚本"组件，然后选择新建脚本，编辑器会打开一个脚本文件，默认内容是 JavaScript 风格的结构。

下面是一个最简单的"点击实体后改变颜色再加一点旋转"的脚本示例：

class MyBehavior { activate() { // 绑定点击事件 this.entity.onClick = () => { // 修改实体颜色 this.entity.sprite.color = "#ff9900"; // 让它持续旋转 this.entity.rotationSpeed = 60; }; } } // 组件系统会把下面这行作为脚本入口 export default MyBehavior;

写完之后直接保存，编辑器里立刻能感受到热更新的威力：不需要刷新页面，当前场景里的实体马上就执行了新逻辑。这种"保存即生效"的爽快感，用传统方式做 Web 项目时很难体会到。

5.3 多人实时协作是怎么运作的

协作的开始方式非常简单——把当前项目的访问链接发给队友，对方登录自己的账号，打开链接，就进入了同一个项目。这么说吧，我在其中一个浏览器窗口改代码，另一个窗口里的光标立刻跟着移动，两个窗口的内容完全同步。这种感觉很微妙，就像有个人在你旁边伸了一只手过来和你一起敲键盘。

要注意的是，同一时刻如果两个人都去改同一个实体组件的同一个属性，后保存的一方会覆盖前一个的操作。实际团队使用的时候，还是建议按模块分工，你写你的行为脚本，我改我的场景布局，冲突概率会小很多。

5.4 把项目发布出去

做完原型之后，需要对外分享时，点发布相关操作后，平台会生成一个独立的预览链接。把这个链接发给任何人，对方不需要登录、不需要知道项目背后的任何信息，打开就是你的作品。

我经常用的一个流程是：开发阶段项目保持私有，队友进来协作开发；到了给客户或者朋友看效果的时候，再开放外面那一层链接。这套流程非常顺滑，比传统的"打包上传到静态服务器"轻量太多了。

6. 跑起来只是开始：备份、安全与升级维护

到这里，你已经拥有了一个能跑的 Superpowers 服务。但把它当成一个长期用的基础设施的话，后面还有三件事值得花时间做：备份、安全、升级。这些是我在真实使用过程中踩过坑才补上的功课。

6.1 数据备份：千万别只备份代码

说到备份，很多人第一个念头是"源码在服务器上，打包带走不就行了"。但 Superpowers 里真正需要备份的不只是项目代码，还有数据库内容、用户信息、上传的资源文件。这些数据散落在安装目录的几个不同位置，单独打包某个文件夹很可能漏东西。

我的备份策略特别简单粗暴：每晚用 cron 对整个服务器里 Superpowers 的数据目录做一次整体压缩快照，然后同步到另一台不同机房的机器或者对象存储里。恢复的时候也不用什么花哨手段，把快照解压回原目录，重启服务，数据就回来了。备份频率看你的使用频度，我这是团队在用、变化比较快，所以设了每天一次；一个人自用的话，每周一次也够了。

6.2 安全加固：对外开放服务的第一课

服务只要暴露在公网上，就一定会有人来探测。开放用户注册那个坑我在前面提过，再补充几个实测有效的加固做法：

• 强制 HTTPS：不仅是为了加密，也是为了浏览器功能完整，建议用上。
• 修改默认端口：如果你坚持用 IP 直连而不是域名，至少把外部访问端口改成一个不常用的高位端口，能挡掉一批无差别扫描。
• Nginx 层限流：对于登录接口做频率限制，防止被人暴力猜密码。Nginx 的模块可以做简易限流，配置也不算复杂。
• 定期检查系统更新：云服务器的安全补丁该装就装，尤其是一键安装脚本自动装好的老版本依赖，尽量跟着项目仓库的更新节奏走。
• 管理员账号启用强密码：这个不用我多说，但实际中总有团队因为图省事用弱密码，结果被扫出来撞库。

6.3 升级与常见故障排查

升级这个事情，我是吃过亏的。有一回我直接在项目目录里执行git pull，然后重启服务，结果项目页面白屏。排查了很久才发现是从一个旧版本跳到新版本，中间跨过了好几个重要变更，但依赖没有同步更新。那次之后我总结了一套稳妥的升级流程：

# 先备份数据目录 # 然后拉取最新代码并切换 tag git fetch --tags git checkout 目标版本tag # 重装依赖 rm -rf node_modules npm install # 重启服务

这套流程的核心思想是：升级前先备份，升级时重装依赖，升级后观察日志。不要图省事直接覆盖，代码可以平滑升级，但依赖和配置文件一定要重新匹配。

说几个我碰到过的常见故障和对应排查思路，放在表格里：

最后再谈一点个人体会。装好 Superpowers 的过程本身并不复杂，真正让我觉得这趟折腾值回票价的时刻，是我和远程队友同时打开一个空白项目，光标在屏幕上互相追逐、代码一行行叠加上去的一瞬间。工具链的胜利不在于装得多华丽，而在于它真的改变了协作方式。如果你打算部署它，我的建议是：先装好，拉着一个人跑通一个小项目，再决定要不要深度使用。那些花里胡哨的插件和高级配置，留着后面慢慢加就行。