Puter 入门与部署实践：从源码开发到 Docker 自托管的浏览器"互联网计算机"

本文基于 Puter 仓库的阿拉伯语版 README（doc/i18n/README.ar.md）撰写，完整覆盖该文档的核心内容：Puter 的项目定位与五大用途、本地开发启动流程、Docker 与 Docker Compose 部署方式、系统要求、支持渠道与许可证条款。在此基础上，结合 tools/start.mjs、Dockerfile、docker-compose.yml 等仓库源码进一步说明启动链路与部署细节。读完本文，你可以在 Linux/macOS/Windows 上以源码方式跑起 Puter，或用 Docker 一键自托管一套完整的"个人云电脑"，并理解其配置体系的关键开关。

Puter 是什么

Puter 是一个先进的、开源的互联网计算机（Internet Computer），目标是功能丰富、速度快、高度可扩展。按照项目文档的表述，它可以作为以下角色使用：

• 注重隐私的个人云：把所有文件、应用、游戏保存在一处，可从任何地方、任何时间访问；
• 发布平台：用于构建和发布网站、Web 应用与游戏；
• 云盘替代品：替代 Dropbox、Google Drive、OneDrive 等服务，提供全新界面与更强功能；
• 服务器/工作站的远程桌面环境；
• 学习与社区：一个友好的开源项目，适合学习 Web 开发、云计算、分布式系统等。

项目当前以 AGPL-3.0 协议开源（见文末"许可证"一节），同时以 puter.com 的形式提供托管服务。

本地开发启动

仓库文档给出的最小启动路径是：

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

启动后，Puter 会运行在 http://puter.localhost:4100（若该端口被占用，则使用下一个可用端口）。

npm start 背后做了什么

从源码 tools/start.mjs 可以看到，npm start 并非简单起一个服务器，而是一条完整的构建-运行链：

1. 执行 npm run setupExtensions（由 tools/extensionSetup.mjs 完成）；
2. 执行 npm run build:ts，用 tsc 编译后端 TypeScript 到 dist/；
3. 以 node --enable-source-maps -r ./dist/src/backend/telemetry.js ./dist/src/backend/index.js 启动后端进程（入口为 src/backend/index.ts）。

此外，start.mjs 还支持两个进阶模式（见 tools/start.mjs 头部注释）：

• npm start --server=puter.com：跳过本地后端，仅在本地启动 GUI，并连接到远端 Puter 后端（裸域名会被解析为 https://api.<domain> 约定）；
• npm start --extensions=<目录>[;<目录>...]：把仓库外的 GUI 扩展目录打包进本地 GUI，适合私有扩展开发。

Node.js 版本要求

阿拉伯语版 README 的系统要求列出 Node.js 16+（推荐 22+）。需要注意的是，以当前仓库实际为准：package.json 的 engines 字段声明了 "node": ">=24.0.0"，官方镜像也基于 node:24-slim 构建（见 Dockerfile）。因此从当前版本源码本地开发，直接使用 Node 24 是最稳妥的选择；文档中的 16+/22+ 是较早版本的要求口径。

Docker 单容器部署

仓库文档给出的单容器部署命令：

mkdir puter && cd puter && mkdir -p puter/config puter/data && sudo chown -R 1000:1000 puter && docker run --rm -p 4100:4100 -v `pwd`/puter/config:/etc/puter -v `pwd`/puter/data:/var/puter  ghcr.io/heyputer/puter

这条命令的每个部分都与 Dockerfile 中的定义对应：

• 端口 4100：镜像 EXPOSE 4100，应用监听该端口；
• /etc/puter 卷：自托管者把自己的 config.json 挂到此处。v2 配置加载器会将其深度合并（deep-merge）到内置的 config.default.json 之上，因此部分覆盖即可生效，缺失文件则全用默认值（镜像内通过 PUTER_CONFIG_PATH=/etc/puter/config.json 指定该路径，见 Dockerfile）；
• /var/puter 卷：持久化运行时数据（SQLite、本地 S3 对象存储文件等）；
• chown 1000:1000：容器以非 root 的 node 用户运行（Dockerfile 中 USER node，compose 中对应 PUID/PGID: 1000），宿主机目录属主不匹配会触发 EACCES；
• 健康检查：镜像内置 HEALTHCHECK，每 30 秒对 http://puter.localhost:4100/test 发 spider 请求探活。

单容器模式下 Puter 使用内置默认值（SQLite、进程内 S3 兼容存储等），适合快速体验；生产级自托管建议采用下文的 Compose 全栈方案。

Docker Compose 部署

文档给出的启动命令

阿拉伯语版 README 中 Linux/macOS 的方式：

mkdir -p puter/config puter/data
sudo chown -R 1000:1000 puter
wget https://raw.githubusercontent.com/HeyPuter/puter/main/docker-compose.yml
docker compose up

Windows（PowerShell）方式：

mkdir -p puter
cd puter
New-Item -Path "puter\config" -ItemType Directory -Force
New-Item -Path "puter\data" -ItemType Directory -Force
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/HeyPuter/puter/main/docker-compose.yml" -OutFile "docker-compose.yml"
docker compose up

当前仓库 Compose 方案的完整构成

以当前仓库 docker-compose.yml 为准，该 Compose 文件拉起的是一套"单主机生产级"全栈，而不只是应用容器：

容器	镜像	角色
puter	ghcr.io/heyputer/puter:main	应用本体，仅对内暴露 4100
puter-caddy	caddy:2.11-alpine	反向代理（80/443），按 Host 透传子域名路由
puter-mariadb	mariadb:11	SQL 数据库，首次启动自动应用 schema
puter-valkey	valkey/valkey:8-alpine	Redis 兼容缓存与限流后端（单节点集群模式）
puter-dynamo	amazon/dynamodb-local	KV 存储，Puter 启动时自建表
puter-s3	rustfs/rustfs	S3 兼容对象存储（可换 MinIO）
puter-s3-init	amazon/aws-cli	一次性容器，创建 bucket 后退出
puter-ollama / puter-ollama-init	ollama/ollama	可选（compose profile ai），本地 LLM

几个与源码对应的关键点：

• Caddy 只做透传：caddy/Caddyfile 中，s3. 子域名的流量转发到 s3:9000（保持 Host 头以通过 S3 签名校验），其余所有 Host 一律 reverse_proxy puter:4100，子域名路由（api.*、site.*、app.*）由 Puter 应用内部完成；代理还设置了 flush_interval -1 以支持 SSE 与 socket.io 流式响应；
• 依赖顺序与健康检查：puter 服务 depends_on 了 valkey/mariadb（service_healthy）、dynamo（service_started）、s3-init（service_completed_successfully），保证启动顺序正确；
• 可选本地 LLM：ollama 与 ollama-init 藏在 ai profile 后，需 docker compose --profile ai up -d 显式启用，同时在 config.json 中把 providers.ollama 指向 http://ollama:11434。

更省事的安装脚本

当前仓库还提供一个一键安装脚本 install.sh（对应 doc/self-hosting.md 中的说明）：

curl -fsSL https://raw.githubusercontent.com/HeyPuter/puter/main/install.sh | sh

它会生成密钥、写入 .env 与 puter/config/config.json、拉取 docker-compose.yml 和 caddy/Caddyfile，然后执行 docker compose up -d；重复执行是安全的，不会覆盖已有配置（设置 PUTER_FORCE=1 才强制轮换）。Windows 侧对应 irm https://puter.com/selfhost?os=windows | iex（见 README.md 的 Self-Hosting 小节）。

完整的分步自托管指南——包括密钥生成、DNS 泛解析、TLS 通配符证书、OIDC 登录（Google/Apple/Microsoft）、SMTP 邮件、存储配额与计量策略等——都在 doc/self-hosting.md 中，建议生产部署前通读。

托管服务 Puter.com

除自托管外，Puter 也作为托管服务运行在 puter.com。仓库中 npm start --server=puter.com 这种"本地 GUI + 远端后端"模式（见上文 tools/start.mjs 一节）就是为对接该托管环境设计的。

系统要求

阿拉伯语版 README 列出的系统要求如下：

项目	要求
操作系统	Linux、macOS、Windows
内存	最低 2 GB（推荐 4 GB）
磁盘空间	1 GB 空闲
Node.js	16+（推荐 22+；当前仓库实际要求见下）
npm	最新稳定版

需要说明的适用前提：如前所述，package.json 当前声明 engines.node >= 24.0.0，Dockerfile 使用 node:24-slim 双阶段构建（构建阶段安装 python3/make/g++ 以编译 bcrypt、sharp、better-sqlite3 等原生依赖，运行时阶段不带构建工具）。走 Docker 路线则无需关心宿主机 Node 版本。

配置体系速览

自托管的核心是把 config.json 放入 puter/config/（即容器内 /etc/puter/config.json）。仓库提供了一份带逐字段注释的完整模板 config.template.jsonc，每个键都是唯一规范键（无别名回退），未设置的键回落到内置默认值；逐字段的源码级定义见 src/backend/types.ts。

与日常自托管最相关的几个键：

• domain / protocol / pub_port：对外可见的域名、协议与端口。Puter 完全基于 Host 头做子域名路由，外部域名必须与 domain 一致，否则会以 Invalid Host header 拒绝请求；
• trust_proxy：反向代理跳数（1 = Caddy；2 = Cloudflare→Caddy）。切勿设为 true——它会信任所有跳，使 X-Forwarded-For 可伪造，破坏限流与审计；
• jwt_secret_v2 / url_signature_secret：任何公开部署都必须替换为随机值（模板建议 openssl rand -hex 64）；
• s3 / s3_bucket / s3_region：对象存储连接参数，本地 RustFS/MinIO 需要 forcePathStyle: true；
• meteringEnforcement / unlimitedMetering：自托管没有付费计划，通常要关闭订阅门槛或整体放开计量，否则部分 AI 端点会对所有人返回 402；
• providers：AI 供应商（含 ollama 本地模型）的启用开关与 API Key；未运行 Ollama 时务必设 providers.ollama.enabled: false，否则每次启动都会刷 ECONNREFUSED。

以上每一项的取舍理由（为什么这样设、错设会发生什么）在 doc/self-hosting.md 的 "Why these knobs" 部分有逐条解释，是本仓库少见的、把"配置→后果"讲透的文档。

支持与社区渠道

仓库文档列出的支持渠道包括：

• Bug 报告 / 功能请求：在仓库的 Issue 页面提交（Issue 模板提供分类选择）；
• 社区：Discord、Reddit（r/puter）、X（@HeyPuter）、Mastodon（@puter）；
• 安全问题：发送至 [e-mail]；
• 维护者：[e-mail]。

项目方明确表示"乐于回答任何问题"，遇到问题可直接通过上述渠道提问。仓库根目录还有 BUG-BOUNTY.md 与 SECURITY.md 说明漏洞赏金与安全披露流程。

许可证

该仓库（包括全部内容、子项目、模块与组件）除明确声明外，均采用 AGPL-3.0 许可证（见 LICENSE.txt）。仓库内包含的第三方外部库可能各自适用其独立许可证；各子目录（如 src/puter-js/APACHE_LICENSE.txt、src/cli/LICENSE.txt）附有各自的许可文件，使用前应留意。

附：多语言 README 体系

本文参照的 doc/i18n/README.ar.md 是 Puter 多语言文档体系的一员。README.md 的 "Translations" 一节索引了阿拉伯语、中文、法语、德语、日语、俄语等约 30 个语言的 README，全部位于 doc/i18n/ 目录下。各语言版本与英文主 README 同步维护，中文读者可直接阅读 doc/i18n/README.zh.md，英文完整版则以 README.md 为准。