Puter 保姆级部署教程：开源可自托管的个人云电脑

Puter（heyputer/puter，GitHub 约 4.4 万 Star）是一个开源、可自托管的「互联网电脑」：它把文件管理、应用、游戏、AI API 全塞到一个浏览器里，官方定位「The Open-Source Internet Computer」。对开发者而言，Puter 提供云端存储、KV 数据库、Serverless Workers、AI 调用等原生 API，你写的 Web 应用可以一键发布到 Puter 的 App Store。本文基于官方 README 的 Getting Started 章节。

一、项目介绍与适用场景

Puter 既是给用户用的个人云桌面（替代网盘/在线 Office），也是给开发者用的 PaaS：你的应用跑在用户的 Puter 实例里，数据归用户自己。

典型场景：

自建私有云桌面：文件、笔记、表格、相册全在自己服务器。
Web 应用分发平台：发布到 apps.puter.com 获客。
AI 应用后端：用 Puter 的 AI API 调 LLM，不用自己管 Key。

二、核心功能逐条拆解

文件系统：云端对象存储，开发者 API 直接用。
KV 数据库：NoSQL，自带权限。
Serverless Workers：边缘函数。
AI API：统一接口调各家 LLM。
App Store：发布 Web 应用变现。
多语言：内置 30+ 语言，含简体中文。

三、全套官方链接

类型	链接
GitHub 仓库	https://github.com/HeyPuter/puter
官方文档	https://developer.puter.com
在线 Demo	https://puter.com
License	AGPL-3.0

四、硬件与环境前置要求

Node.js：开发模式需要。
内存：2GB 起步。
磁盘：10GB。
系统：Linux / macOS。

五、多平台部署步骤

5.1 一键自托管（官方推荐）

官方 README 原文：

curl -fsSL https://puter.com/selfhost | sh

Windows PowerShell：

irm https://puter.com/selfhost?os=windows | iex

逐段解释：官方脚本自动拉取 docker-compose、起服务。

5.2 本地开发模式

官方 README 原文：

git clone https://github.com/HeyPuter/puter
cd puter
npm install
npm start

逐段解释：克隆仓库、装依赖、启动。官方说明启动后访问 http://puter.localhost:4100。

5.3 Docker 源码构建

官方 README 指引：按 doc/self-hosting.md 建 docker-compose.override.yml 选本地构建。

六、配置文件全部参数解释

主要通过 docker-compose.yml 与环境变量配置，详见 https://developer.puter.com 。

七、启动、后台常驻与开机自启

7.1 启动

一键脚本自动起 docker-compose 后台服务。浏览器访问 http://服务器IP:4100。

7.2 后台常驻

docker-compose.yml 里加 restart: always 或 restart: unless-stopped。

7.3 开机自启

Docker 服务本身设为开机自启（systemctl enable docker），compose 里的容器就会跟着起。

7.4 修改端口与域名

生产环境建议前面套 Nginx 反代 + HTTPS。官方 self-hosting.md 有完整的生产部署清单。

八、功能实操教程

第 1 步：跑 5.1 一键脚本。脚本会自动检测系统、拉取官方 docker-compose、启动容器。首次启动需要等镜像下载（约 1-2GB）。

第 2 步：浏览器访问 http://你的服务器:4100，注册管理员账号。第一个注册的账号自动成为管理员。

第 3 步：体验内置应用——桌面图标里有记事本、计算器、相机、终端、文件管理器。

第 4 步：打开文件管理器，上传一个测试文件，再用 puter.fs.read() 在控制台读出来。

第 5 步：访问 developer.puter.com 读 AI API 文档。写一个 hello.html：

<script src="https://js.puter.com/v2/"></script>
<script>
  puter.ai.chat("你好，介绍一下你自己").then(r => alert(r.message.content));
</script>

第 6 步：把这个 html 上传到 Puter 当应用，发布到 App Store。

第 7 步：在管理后台开启「允许新用户注册」或「邀请制」。

九、全套报错故障排查

报错原文：puter.localhost:4100 打不开原因分析：本地开发模式用了特殊域名 puter.localhost，需要 DNS 解析。解决方案：在 /etc/hosts 加 127.0.0.1 puter.localhost，或直接用 http://localhost:4100。
报错原文：npm install 失败或 node-gyp 报错原因分析：Node 版本太老或缺编译工具。解决方案：装 Node 20 LTS；Ubuntu 执行 sudo apt install build-essential；macOS 装 Xcode Command Line Tools。
报错原文：Docker 端口冲突原因分析：4100 或其他端口被占。解决方案：改 docker-compose.yml 里端口映射，或 lsof -i:4100 找占用进程。
报错原文：注册后无法登录原因分析：首次启动需要初始化管理员账号。解决方案：看终端日志，按提示访问 http://localhost:4100/?init 完成初始化。
报错原文：Puter AI 调用失败原因分析：自托管实例没配 LLM 提供商 Key。解决方案：在管理后台配置 OpenAI/Anthropic Key，或接本地 Ollama。
报错原文：上传文件超过大小限制原因分析：默认 Nginx 或 Node body 限制。解决方案：改 docker-compose 环境变量，详见官方 self-hosting.md。

十、升级、回滚与卸载

升级：一键脚本重跑；开发模式 cd puter && git pull && npm install && npm start；Docker 方式 docker-compose pull && docker-compose up -d。

回滚：开发模式 git checkout <tag>；Docker 方式 docker-compose down && docker pull kvcacheai/mooncake:<旧tag>。

卸载：docker-compose down -v 删数据卷；开发模式 rm -rf puter/；清掉 ~/.puter/ 本地配置。

十一、商用许可与合规风险提示

Puter 采用 AGPL-3.0，商用注意：如果你修改了 Puter 源码并对外提供网络服务，必须开源你的修改。基于 Puter 开发的应用本身可以闭源，但平台层改动需开源。

参考链接：

Puter GitHub README：https://github.com/HeyPuter/puter
开发者文档：https://developer.puter.com
自托管指南：https://github.com/HeyPuter/puter/blob/master/doc/self-hosting.md