Puter 介绍与选型指南

Puter（HeyPuter/puter）开源互联网操作系统/个人云认知与选型篇：WebOS 定位、Node.js 多服务架构、puter.js 应用平台与 AI 网关溯源，并与 Nextcloud/ownCloud/Cloudreve/Seafile 逐维量化对比（星数 44040 取证于 2026-11-01）。

PuterPuterDockerCompose文件传输文件服务器2026/11/01

Puter 介绍与选型指南

目标：本文是 Puter 的认知与选型篇，基于官方仓库、官方文档站与官方 Release 源联网溯源整理，帮助读者在 10 分钟内判断 Puter 是否适合自建、与 Nextcloud/ownCloud/Cloudreve/Seafile 等同类自托管网盘的差异在哪里。本文为纯溯源整理，不包含本地部署实测；部署与配置操作见本专栏后续各篇（查询日期：2026-11-01）。

一、环境信息

本文为认知与选型篇，全部信息来自以下官方渠道联网溯源，未做本地部署实测：

  • 软件仓库：https://github.com/HeyPuter/puter（GitHub 仓库页 HTML，星数与许可信息取证日期 2026-11-01）
  • 官方网站：https://puter.com（首页 HTML，运营主体信息取证日期 2026-11-01）
  • 官方自托管文档：仓库内 doc/self-hosting.md（main 分支快照，取证日期 2026-11-01）
  • 版本发布源：https://github.com/HeyPuter/puter/releases.atom（Atom 订阅源，取证日期 2026-11-01）
  • 开发者平台：https://developer.puter.com（puter.js 与云端能力文档入口）

💡 说明：本文引用的版本号、星数、许可类型均标注了取证渠道与日期。Puter 迭代速度较快（月度发版节奏），动手部署前请以官方 Releases 页面的最新值为准，部署实操可参考 《Puter Docker Compose 部署指南》。

二、软件概述

2.1 一句话定位

Puter 的官方自述是「The Internet OS!（互联网操作系统）」与「The Open-Source Internet Computer!（开源互联网电脑）」：它是一个运行在浏览器里的完整桌面环境——桌面、窗口、任务栏、文件管理器、终端、内置应用一应俱全——底层则是一套多用户个人云（文件存储、键值数据库、AI 网关、静态网站托管、Serverless Workers）。对普通用户，它是一台「开箱即用的云端电脑」；对开发者，它是一个可以通过 puter.js 一行脚本调用云能力的应用平台。

2.2 基本身份信息（来源：GitHub 仓库页，2026-11-01 取证）

项目内容
项目全称Puter（HeyPuter/puter）
运营/维护主体Puter Technologies Inc.（来源：puter.com 首页 HTML）
开源许可AGPL-3.0（仓库与全部子模块；第三方库各自保留其许可）
GitHub Stars44,040（仓库页 HTML stargazerCount 字段，2026-11-01）
主语言JavaScript / Node.js
最新稳定版26.10.1（2026-10-25 发布，来源：Releases Atom 源）
部署形态Docker Compose 一键脚本 / 手工 Compose / 源码构建；同时提供 puter.com 托管服务

从版本号规则即可看出产品定位：Puter 采用 YY.MM(.patch) 的日历化版本（如 26.10.1 即 2026 年 10 月第 1 个补丁版），发版节奏为每月一个大版本、按需出补丁——Releases 源显示 26.08.2（08-24）→ 26.09（09-10）→ 26.09.1（09-20）→ 26.10（10-05）→ 26.10.1（10-25），一年内可稳定预期 12 个左右的功能版本。

2.3 为什么值得关注

在「自托管网盘」这个已经相当拥挤的赛道里，Puter 的差异化不在「又一个网盘」，而在三点：

  1. 它是完整的 WebOS 而不只是文件列表：Nextcloud/ownCloud 的核心交互是「网页上的文件目录树」，Puter 的核心交互是「一台电脑的桌面」——有窗口管理、有拖拽、有内置办公与开发应用，文件只是这台电脑里最基础的资源之一。
  2. 它把「云能力」产品化成了前端 API：通过官方 puter.js SDK，任何静态网页引入一个 <script> 标签就能获得用户认证、文件系统、键值数据库、AI 推理、静态托管等能力，且这些 API 直接面向「你自建的这套 Puter 实例」，这是同类产品没有的产品化深度。
  3. AI 能力是一等公民：Puter 内置 AI 提供商网关（OpenAI/Claude/Gemini/Ollama 等均可在配置中接入），内置应用与第三方应用都能通过 puter.js 直接调用 puter.ai 系列 API——把「个人云 + AI」合并成一套自托管栈。

三、核心架构

3.1 技术栈与整体分层（来源：官方 self-hosting 文档与仓库结构，2026-11-01）

Puter 是一个典型的「Node.js 多服务编排」栈，官方 docker-compose.yml 一次性拉起全部依赖：

层组件角色
入口层Caddy（caddy:2.11-alpine）反向代理，80/443 入口，按子域名路由到 Puter 及其托管站点
应用层Puter 主服务（ghcr.io/heyputer/puter）Node.js 后端：认证、文件元数据、驱动 API、应用平台、Web 桌面前端
关系数据MariaDB（mariadb:11）用户、文件条目（fsentry）、权限、应用等主数据；首次启动自动跑 49 个迁移脚本
缓存/队列Valkey（valkey/valkey:8-alpine）Redis 兼容，用作缓存、会话与限流；官方配置以 Redis cluster 模式连接
键值数据DynamoDB Local（amazon/dynamodb-local）KV 存储（puter.kv API 的底层），首次启动自动建表
对象存储RustFS（rustfs/rustfs）S3 兼容对象存储，存放文件实体内容（官方文件注明可用 MinIO 平替）
一次性初始化AWS CLI（amazon/aws-cli）首次启动创建 S3 存储桶并写入 CORS 配置后退出

💡 技术拓展：文件元数据与文件实体的分离存储是网盘类系统的常见架构。常见做法对比——

方案原理代表产品
全入库（BLOB 存数据库）文件内容直接存数据库行轻量 PHP 网盘
元数据 + 本地磁盘目录树入库，内容落本地文件系统Seafile（块级去重）、Cloudreve（可选）
元数据 + 对象存储目录树入库，内容写 S3 兼容存储Puter、Nextcloud（S3 后端模式）

Puter 采用第三种：MariaDB/MySQL 只存「谁在哪个目录有什么文件」，文件本体全部写入 S3 兼容对象存储（自托管时默认 RustFS），这让存储层天然可替换为任意 S3 兼容后端（MinIO、云厂商 S3 等）。

3.2 子域名路由模型

Puter 的多域名设计是其架构中最容易踩坑的一点（官方 Requirements 明确要求一条通配符 DNS 记录）：主服务按子域名区分流量类型——

  • puter.<你的域名>：Web 桌面与 API 主入口；
  • site.<你的域名>：用户静态网站托管的访问域；
  • app.<你的域名> / dev.<你的域名>：托管应用与私有应用的运行域；
  • api.<你的域名>：API 入口（官方 compose 由 Caddy 统一分发）。

在本机体验时官方默认用 puter.localhost 等保留域名替代（浏览器把 *.localhost 解析到 127.0.0.1），因此单机体验不需要真实域名；生产部署则需要通配符解析。这一模型与「靠路径前缀区分」的传统网盘（如 /s/ 分享链接）完全不同，是选型时评估运维成本的必要输入。

3.3 puter.js 与驱动（Drivers）架构

Puter 后端把能力拆成一组「驱动」（drivers）——文件系统（puter.fs）、键值库（puter.kv）、AI（puter.ai）、认证（puter.auth）、托管（puter.hosting）等，统一由 /drivers/call 类 API 端点暴露；前端 SDK puter.js 是这组 API 的官方封装。第三方网页只需：

<script src="https://js.puter.com/v2/"></script>

即可在页面里调用 puter.fs.write()、puter.kv.set()、puter.ai.chat() 等方法——SDK 会自动完成认证跳转与令牌管理（对接的就是你自建实例的用户体系）。这使 Puter 同时是一个「个人云」和「给 Web 应用当后端的 BaaS 平台」。API 的完整调用方式见 《Puter 26.10.1 API 使用详解》。

四、功能特性

以下特性清单来自官方 README、官方文档站与仓库文档（2026-11-01 溯源）：

  1. 文件与网盘：上传/下载/拖拽、目录树、回收站、分享链接、配额管理（默认不限量，可按用户设 storage_capacity）。
  2. Web 桌面（WebOS）：窗口系统、桌面壁纸与图标、任务栏、开始菜单、深浅色主题、多语言（含中文翻译）。
  3. 内置应用套件：文本编辑器（Notepad）、终端（Terminal，含伪终端体验）、画板、相机、录音机、播放器、PDF 阅读器、电子表格等，官方 README 定位为「从记事本、录音机到电子表格、相机的全家桶」。
  4. 应用中心与开发者平台：apps.puter.com 应用商店；开发者可将 Web 应用/游戏上架，通过 puter.js 调用云能力，官方提供 AI、对象存储、KV 数据库、Serverless Workers 四类后端能力入口（developer.puter.com）。
  5. AI 网关：配置任一提供商的 API Key 即自动启用对应模型路由（OpenAI/Claude/Gemini/图像生成等），亦可接本地 Ollama（官方 compose 提供 ai profile 一键带起 Ollama 并拉取 tinyllama 默认模型）。
  6. 静态网站与应用托管：每个用户可将目录发布为 site.<域名> 下的静态站点，或将应用发布到 app.<域名> 运行。
  7. 多用户与账户体系：注册/登录、临时账户、用户组、配额、用量计量（metering）与预算控制；支持 Google/Apple/Microsoft OIDC 登录、Proof-of-Work 验证码、一次性邮箱域名黑名单、密码强度策略。
  8. 邮件能力（可选）：配置 SMTP 后支持密码重置/确认邮件；进阶可开启按域收信（每个账户获得 @你的域名 邮箱，由 smtp profile 接收）。
  9. 计量与预算（可关）：默认按「下行字节、对象存储请求、KV 容量、AI token」记账并有月度免费额度（自托管场景官方明确建议用 unlimitedMetering: true 关闭限制）。

五、快速开始（最小可用示例）

官方推荐的最高效上手路径是一键安装脚本（来源：仓库 README 与 doc/self-hosting.md，2026-11-01）：

# Linux/macOS 一键自托管（官方 README 推荐入口）
curl -fsSL https://puter.com/selfhost | sh

该脚本会：生成全部密钥 → 写 .env 与 puter/config/config.json → 下载官方 docker-compose.yml 与 caddy/Caddyfile → 执行 docker compose up -d。完成后访问 http://puter.localhost（脚本映射的宿主端口默认 80，可用 .env 的 HTTP_PORT 改）即可注册账号进入 Web 桌面。

Windows 用官方 PowerShell 入口：

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

前置条件只有一条：装好带 compose 插件的 Docker（官方文档明确「这是唯一需要你自己安装的东西」）。想逐行理解每个服务、端口与数据目录的编排细节，直接看 《Puter Docker Compose 部署指南》，该篇基于 26.10.1 在单机真实环境完整实测过从零部署到登录桌面的全流程。

六、适用场景与限制

6.1 适合的场景

  1. 个人/家庭自建「云电脑 + 网盘」：想要一个比传统网盘更像电脑的私有云，一台低配 VPS 或家用主机即可跑起完整栈。
  2. 团队内网文件中枢：内网部署后给每人一个桌面与独立存储空间，配合 OIDC 单点登录与配额，替代散落的共享目录。
  3. Web 应用轻后端（BaaS）：教学、原型、内部工具用 puter.js 直接获得文件/KV/AI 能力，不必自建一整套后端。
  4. AI 应用实验台：用自己的 OpenAI/Claude Key 或本地 Ollama，在自托管环境里统一给多个应用发 AI 能力。
  5. 静态站与应用托管：给团队或个人提供 site.<域名> 的静态发布通道。

6.2 当前的限制与注意点（来源：官方文档明示内容，2026-11-01）

  1. 生产部署需要通配符域名：子域名路由模型决定了没有通配符 DNS 就只能在本机 *.localhost 体验，公网生产必须配域名与（推荐的）TLS 证书。
  2. 官方编排面向单主机：官方 compose 把全部服务放一台主机上，「官方文档称之为单主机上最接近生产的部署形态」；多节点横向扩展无官方方案。
  3. PostgreSQL 支持为社区贡献：官方文档明确标注 PostgreSQL 引擎「由社区贡献、非 puter.com 生产运行路径」，生产自托管默认仍是 MariaDB/MySQL（SQLite 亦为受支持默认）。
  4. 自托管计量默认要关：不带云计费的自托管环境如果沿用默认计量，账户会在每月免费额度（官方标称 0.5 美元量级，约 2.5 GiB 下行）用尽后被 402 拒绝，官方建议显式 unlimitedMetering: true。
  5. AI 能力依赖外部 Key：除接 Ollama 本地推理外，puter.ai 的云端模型都需要你自己提供提供商密钥；无 Key 时 AI 功能不可用（其余功能不受影响）。

七、同类选型对比

下面把 Puter 放进自托管文件云赛道做横向对比。维度与结论依据各产品官方文档/仓库的公开定位整理（Puter 数据 2026-11-01 取证；其他产品为公开通用事实，星数量级不逐一列数以免失真，选型判断不依赖具体星数）：

维度PuterNextcloudownCloudCloudreveSeafile
一句话定位互联网操作系统/WebOS + 应用平台全能协作套件（文件+日历+办公+生态应用）文件同步与协作（企业向）国产轻量网盘（个人/小团队）高性能文件同步与团队协作
技术栈Node.js + React（WebOS）PHPPHP（Nextcloud 同源分支）Go + ReactC（Python 封装）+ Seafile 专有协议
许可AGPL-3.0AGPL-3.0AGPL-3.0（企业版闭源功能另计）AGPL-3.0（企业版另发）社区版开源 + 企业版专有
存储架构元数据入库 + 文件实体全量走 S3 兼容存储数据目录直写（可选外部 S3）数据目录直写（可选外部 S3）本地/S3/兼容存储可选块级去重专用存储（S3 为后端）
交互形态桌面/窗口/内置应用的全功能 WebOS网页文件列表 + 应用生态网页文件列表 + 同步客户端网页文件列表 + 分享中心同步盘体验优先 + Web 界面
特色能力puter.js BaaS、AI 网关、Serverless Workers、静态托管应用商店生态最全、协作办公（ONLYOFFICE 等）企业集成、Collective/关闭生态分享策略细腻、离线下载、极简部署增量同步性能强、大目录同步稳定
部署复杂度中（6 服务编排，一键脚本可用）中（单镜像即可起步，生态应用另加）中低（单二进制/单镜像）中低（两容器）
适用人群想要「云电脑」与开发者平台的人需要全家桶协作生态的团队企业合规与既有 ownCloud 用户个人/小团队的轻量分享站重同步性能与大文件的团队

选型解读：如果诉求是「老老实实的文件同步盘」，Seafile/Nextcloud 的同步链路更成熟；如果诉求是「给团队一个入口统一的文件+办公全家桶」，Nextcloud 生态无可替代；如果只想 5 分钟起一个分享站，Cloudreve 最省事。而当你想要的是「浏览器里的一台电脑」——文件只是起点，还想要终端、编辑器、应用运行环境、给网页发云能力的 API、统一 AI 网关——Puter 是这条赛道里唯一把「操作系统体验」做成了产品本体的开源实现。 Puter 与上述产品也并不互斥：把 Puter 当「个人云桌面/开发平台」、把 Nextcloud 当「团队协作盘」的双栈组合在自托管社区同样常见。

社区活跃度量化参考（Puter，2026-11-01 取证）：GitHub Stars 44,040、AGPL-3.0、月度发版节奏（近 3 个月发布 26.08.2 / 26.09 / 26.09.1 / 26.10 / 26.10.1 共 5 个版本），仓库由 Puter Technologies Inc. 商业主体持续维护并有托管服务 puter.com 反哺，属于「高星 + 商业持续投入」型开源项目。

八、参考链接

  1. GitHub 仓库（星数/许可取证）：https://github.com/HeyPuter/puter
  2. 官方网站：https://puter.com
  3. 官方自托管文档：https://github.com/HeyPuter/puter/blob/main/doc/self-hosting.md
  4. 版本发布源：https://github.com/HeyPuter/puter/releases.atom
  5. 开发者平台（puter.js）：https://developer.puter.com
  6. 应用商店：https://apps.puter.com

本专栏后续篇目：部署实操见 《Puter Docker Compose 部署指南》；配置项详解见 《Puter 26.10.1 配置参数详解》；API 调用实操见 《Puter 26.10.1 API 使用详解》。