Puter 安装与自托管部署指南：本地开发、Docker 与 Docker Compose 全栈搭建

本文基于 Puter 仓库的官方多语言 README（doc/i18n/README.he.md 的希伯来语版，内容与主 README 对应）整理成文，覆盖 Puter 的定位与适用场景、系统要求，以及三种落地方式：源码本地开发（npm start）、Docker 单容器部署、Docker Compose 全栈部署。读完之后，你可以按仓库当前实际代码完成一次可验证的本地运行或自托管部署，并理解每种方式背后 start.mjs、Dockerfile、docker-compose.yml 的真实行为。

Puter 是什么：可自托管的"互联网操作系统"

根据 README 的表述，Puter 是一个开源、内容丰富、高性能且可扩展的操作系统库（"The Internet Computer!"，免费、开源、可自托管）。它既可以作为一个完整的浏览器内桌面环境使用，也可以作为构建上层应用的基础库。README 列出的典型使用方式包括：

• 私有云：以最大隐私保存文件、应用与游戏，随时随地可访问的统一安全位置；
• 构建与发布平台：用于构建和发布网站、应用与游戏；
• 网盘替代品：Dropbox、Google Drive、OneDrive 等的替代方案，提供刷新感的界面与强功能；
• 远程工作环境：为服务器和工作站提供远程办公环境；
• 开源学习项目：面向社区，用于学习 Web 开发、云开发、分布式系统等主题。

整个仓库（包括子项目、模块与组件）在 LICENSE.txt 声明的 AGPL-3.0 许可下授权（package.json 中 license 字段为 AGPL-3.0-only），除非个别文件另有明确说明；随附的第三方库可能各自带独立许可。

系统要求

README 给出的运行环境要求如下：

项目	要求
操作系统	Linux、macOS、Windows
内存	最低 2GB，建议 4GB
磁盘空间	1GB
Node.js	文档标注 16+（建议 22+）
npm	最新稳定版

需要特别注意当前仓库的实际版本约束：package.json 的 engines 字段声明 "node": ">=24.0.0"，且 Dockerfile 的构建与运行阶段均基于 node:24-slim 镜像。也就是说，从当前仓库源码直接运行时，请以 Node.js 24+ 为准；文档中的 16+/22+ 可视为历史下限说明，以仓库实际内容为准。

方式一：本地开发（Localhost）

README 给出的本地启动流程：

git clone https://gitcode.com/GitHub_Trending/pu/puter
cd puter
npm install
npm start

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

从源码看，npm start 的真实入口是 tools/start.mjs。它在默认路径下依次执行三步（见 tools/start.mjs）：

1. npm run setupExtensions —— 通过 tools/extensionSetup.mjs 装配扩展包；
2. npm run build:ts —— 编译后端 TypeScript（对应 package.json 中 build:ts 脚本，产物位于 dist/）；
3. 以 node --enable-source-maps -r ./dist/src/backend/telemetry.js ./dist/src/backend/index.js 启动自托管后端进程。

此外 start.mjs 还支持两个命令行标志（tools/start.mjs 的注释有完整说明）：

• --server=<域名或地址>：完全跳过本地后端，仅在本机用开发服务器托管 GUI，并对接远程 Puter 后端。裸域名会解析为生产约定 https://api.<domain>；完整 origin（或带 api. 前缀的主机）则原样使用。例如 npm start --server=puter.com 或 npm start -- --server=http://puter.localhost:4100；
• --extensions=<目录>[;<目录>...]：把仓库外的 GUI 扩展目录打包进被服务的 GUI（等价于 PUTER_GUI_EXTENSION_PATHS），仅在 --server 模式下有效，否则会被忽略并打印警告。

端口与域名默认值可在 config.template.jsonc 中得到印证："port": 4100（内部监听端口）、"domain": "puter.localhost"，以及由协议/域名/公网端口组合计算出的 "origin": "http://puter.localhost:4100"。仓库采用 npm workspaces 组织多子项目（package.json 中 "workspaces": ["src/*"]），即 src/gui（前端界面）、src/puter-js（SDK）、src/backend（后端）、src/worker、src/docs、src/dev-center 等，npm install 会一并安装这些工作区的依赖。

方式二：Docker 单容器部署

README 提供的单容器命令：

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

这条命令做了四件事：创建 config 与 data 两个持久化目录；把目录属主改为 1000:1000（与容器内运行用户对应）；发布宿主端口 4100 到容器 4100；把两个目录分别挂载到容器的 /etc/puter 与 /var/puter，然后启动 ghcr.io/heyputer/puter 镜像。

结合 Dockerfile 可以确认该部署模式的配置约定：

• 自托管者把 config.json 挂载到 /etc/puter/config.json（环境变量 PUTER_CONFIG_PATH 固定指向该路径，见 Dockerfile）；该文件会与镜像内置的 config.default.json 做深度合并，因此部分键覆盖即可，文件不存在时全部使用默认值；
• 运行时以非 root 的 node 用户运行，/var/puter 用于持久化运行时数据；
• 镜像 EXPOSE 4100（Dockerfile），健康检查为 wget --spider http://puter.localhost:4100/test（Dockerfile）。

镜像内部是两段式构建：node:24-slim 构建阶段先复制各子项目的 package.json/lockfile 以最大化 npm ci 缓存，再并行编译后端 TS、GUI 与 puter-js 的 webpack 包；运行阶段仅保留 node:24-slim + git（版本探针）+ wget（HEALTHCHECK）的精简环境（Dockerfile）。

方式三：Docker Compose 全栈部署

README 区分了 Linux/macOS 与 Windows 两套操作步骤。

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

两种方式的核心都是：准备 puter/config 与 puter/data 目录（配置与数据）、取得仓库中的 docker-compose.yml，然后启动 compose 栈。

这个 compose 文件不是只跑一个应用容器——它把 Puter 依赖的全部外部服务一并拉起并在单主机内组网（docker-compose.yml 顶部注释有完整说明）：

容器	镜像	角色
puter-caddy	caddy:2.11-alpine	反向代理（80 端口，配置 TLS 后含 443），按 Host 分发并终结 TLS
puter	ghcr.io/heyputer/puter:main	应用本体，仅 expose 4100 于 compose 网络内部
puter-mariadb	mariadb:11	SQL 数据库，首次启动自动应用 schema
puter-valkey	valkey/valkey:8-alpine	Redis 兼容缓存与限流后端（以单节点集群模式运行以匹配 Puter 的 ioredis 集群客户端）
puter-dynamo	amazon/dynamodb-local	KV 存储，启动时由 Puter 自建 store-kv-v1 表
puter-s3	rustfs/rustfs	S3 兼容对象存储（可替换为 MinIO）
puter-s3-init	amazon/aws-cli	一次性任务容器，首启创建 bucket 后退出

另有可选的 compose profile ai（puter-ollama 与 puter-ollama-init，需 docker compose --profile ai up -d 显式启用，用于本地 LLM）。所有服务的状态都落在 ./puter/data/<service>/ 下，puter 容器通过 depends_on 等待各依赖健康检查通过后才启动（docker-compose.yml）。

仓库还提供了一条更省事的单行安装路径，见 doc/self-hosting.md：执行根目录的 install.sh 会自动生成密钥、写入 .env 与 puter/config/config.json、从仓库拉取 docker-compose.yml 与 caddy/Caddyfile 并执行 docker compose up -d；重复执行安全（不会覆盖已有配置）。该文档还系统覆盖了生产级细节：域名与通配 DNS（*.your-domain.com）、Let's Encrypt 通配证书与 Caddy 的 TLS 接线、自有反向代理的规则（不得改写 Host、protocol 与外部域名一致、trust_proxy 跳数设置）、PostgreSQL/SMTP/OIDC/AI 提供商/存储配额/计量等附加配置，以及常见故障排查。

两个容易踩的坑（源自 compose 与配置源码）

1. Caddyfile 缺失会变成目录：caddy/Caddyfile 是只读绑定挂载，若该文件不存在，Docker 会在挂载点创建一个目录，导致 puter-caddy 以 "not a directory" 崩溃。因此运行 docker compose up 前务必确认 caddy/Caddyfile 与 .env 同处一目录（doc/self-hosting.md "Step 4" 有同样提醒）。
2. 密码必须在 .env 与 config.json 间一致：MariaDB 密码与 S3 密钥如果两处不一致，会出现 ER_ACCESS_DENIED_ERROR；且首次初始化后修改 .env 中的密码不会更新已落盘的 MariaDB 凭据（doc/self-hosting.md Step 1 有专门警告）。

关键配置项速览

自托管的核心配置文件是挂载到 /etc/puter/config.json 的 JSON。完整键列表与逐键注释见 config.template.jsonc（每个键只有一个规范位置，无回退别名；未设置的键回落到文档化默认值），逐字段类型定义以 src/backend/types.ts 为准。与部署最相关的几项（均可在 config.template.jsonc 找到）：

键	默认示例	说明
port / pub_port	4100 / 4100	内部监听端口 / 外部可见端口（置于反代之后时改为 80/443）
protocol	"http"	公开 scheme；反代终结 TLS 后必须改为 "https"，否则会出现重定向循环与混合内容错误
domain	"puter.localhost"	主域名；Puter 完全按 Host 头路由（api.*、site.*、app.* 子域），外部域名必须与此一致
static_hosting_domain 等	site.puter.localhost 等	静态站/私有应用托管子域，需要通配 DNS
jwt_secret_v2 / url_signature_secret	"change-me"	认证令牌签名与 URL 签名密钥，任何公开部署都必须用 openssl rand -hex 64 替换
trust_proxy	false	反代跳数（1 = 一层代理）；切勿设为 true（会信任所有跳，使 X-Forwarded-For 可伪造）

支持与许可

• 许可：AGPL-3.0（LICENSE.txt），第三方库可能有各自许可；
• 问题反馈：可通过仓库的 issue 渠道提交 bug 与功能请求；
• 社区渠道：Discord、X (Twitter)、Reddit、Mastodon 上均有 Puter 官方/社区账号（入口见各语言 README，如 doc/i18n/README.he.md 的"支持"一节）；
• 安全漏洞：报告至 [e-mail]；一般性邮件联系：[e-mail]。

小结

Puter 的部署路径按复杂度递增分为三级：npm start 源码运行（适合二次开发与调试，入口逻辑在 tools/start.mjs）、Docker 单容器（适合只想快速起一个实例的场景，配置约定见 Dockerfile）、Docker Compose 全栈（caddy + MariaDB + Valkey + DynamoDB-local + RustFS S3，最接近可自管的"生产级"单机部署）。生产环境的密钥、DNS、TLS、OIDC、SMTP 与故障排查，请直接对照 doc/self-hosting.md 与 config.template.jsonc 逐项落实。