Puter 快速上手与自托管全栈部署：本地开发、Docker 与 Docker Compose 实战指南

Puter 是一个开源、可自托管的"互联网操作系统"（Internet OS），以浏览器为桌面，将文件、应用与游戏统一收纳在个人云中。本文以仓库内 doc/i18n/README.nl.md（荷兰语版项目 README）为核心骨架，完整覆盖其四种启动方式（本地开发、Docker、Docker Compose、托管服务）与系统要求，并结合仓库源码与部署文档展开纵深解析。读完本文，你将掌握从源码启动、单容器运行到多服务全栈自托管的完整路径，并理解关键配置项背后的实现原理。

Puter 是什么：一个开源的"互联网操作系统"

根据项目 README 的定义，Puter 是一个功能丰富、速度出色且高度可扩展的开源互联网操作系统（advanced, open-source internet operating system），它可以在多种场景下使用：

• 隐私优先的个人云：把文件、应用和游戏统一存放在一个安全的位置，随时随地访问；
• 建站与发布平台：用于构建并发布网站、Web 应用和游戏；
• 云盘替代品：作为 Dropbox、Google Drive、OneDrive 等服务的替代方案，提供全新的界面与强大功能；
• 远程桌面环境：作为服务器和工作站的远程桌面；
• 学习社区：一个友好的开源项目，可用于学习 Web 开发、云计算、分布式系统等。

仓库根目录的 package.json 将项目描述为 "Desktop environment in the browser!"（浏览器中的桌面环境），README.md 则进一步阐述了面向普通用户（一站式应用集合，从记事本、录音机到电子表格、相机）与面向开发者（AI、云存储、键值数据库、Serverless Workers、应用商店分发变现）的双重定位。

系统要求

在开始之前，先对照 README.nl.md 中列出的系统要求确认环境：

项目	要求
操作系统	Linux、macOS、Windows
内存（RAM）	最低 2GB（推荐 4GB）
磁盘空间	1GB 可用空间
Node.js	版本 16+（推荐 22+）
npm	最新稳定版

需要留意的是：仓库当前 package.json 的 engines 字段已经声明 node >= 24.0.0，因此以源码方式运行时，建议直接使用 Node.js 24+ 或更新版本，README 中 "16+/22+" 属于较宽松的历史指引，两者并不冲突——版本越新兼容性越有保障。

方式一：本地开发（源码运行）

README 给出的本地开发方式是标准的 npm 工作流：

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

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

npm start 背后发生了什么

从源码角度看，npm start 实际执行的是 tools/start.mjs 这个入口脚本，它依次完成三件事：

1. 运行 npm run setupExtensions，通过 tools/extensionSetup.mjs 安装/链接扩展目录（对应 extensions/ 下的 appTelemetry、whoami、metering 等扩展）；
2. 运行 npm run build:ts，执行 TypeScript 编译（tsc -p tsconfig.build.json）产出 dist/；
3. 启动后端进程 node --enable-source-maps -r ./dist/src/backend/telemetry.js ./dist/src/backend/index.js。

此外，start.mjs 还支持两种实用参数：

• npm start --server=puter.com：跳过本地后端，仅以本地 GUI 直连远程 Puter 后端；裸域名按生产约定解析为 https://api.<domain>，完整 origin 则原样使用；
• npm start --extensions=<dir>[;<dir>...]：把仓库外的 GUI 扩展目录打包进所服务的界面（等价于 PUTER_GUI_EXTENSION_PATHS）。

配置加载机制：config.json 如何生效

后端的配置加载逻辑位于 src/backend/index.ts，优先级从高到低为：

1. 环境变量 PUTER_CONFIG_PATH 指定的配置文件（生产/容器场景使用）；
2. 仓库根目录的 config.json（用户运行时覆盖文件，通过深合并覆盖默认值）；
3. 仓库根目录的 config.default.json（内置 OSS 默认配置）。

config.json 无需写全所有键——缺失的键会自动回落到默认配置，这一"深合并"机制让单文件部署成为可能。完整的可配置键清单见仓库根目录的 config.template.jsonc，逐字段的权威说明则记录在 src/backend/types.ts。

方式二：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

逐段拆解这条命令的含义：

• mkdir -p puter/config puter/data：创建配置目录与数据目录；
• sudo chown -R 1000:1000 puter：把目录属主改为 UID/GID 1000——容器内进程以此身份运行，否则会因权限不足无法写入数据；
• -p 4100:4100：把容器的 4100 端口映射到宿主机；
• -v .../config:/etc/puter：把宿主配置目录挂载为容器内配置路径，Puter 会读取 /etc/puter/config.json；
• -v .../data:/var/puter：把宿主数据目录挂载为容器内数据路径；
• ghcr.io/heyputer/puter：官方镜像。

方式三：Docker Compose 全栈部署

单容器方案适合快速体验；若要运行接近生产形态的完整栈，README 推荐 Docker Compose。注意：Compose 启动前需要 docker-compose.yml（以及配套的 caddy/Caddyfile）位于工作目录中，这两个文件已经存在于仓库根目录与 caddy/Caddyfile，克隆仓库后直接复制到目标目录即可，无需再从外部下载。

Linux / macOS

mkdir -p puter/config puter/data
sudo chown -R 1000:1000 puter
# 将仓库中的 docker-compose.yml 与 caddy/Caddyfile 放到当前目录
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
# 将仓库中的 docker-compose.yml 与 caddy/Caddyfile 放到当前目录
docker compose up

Compose 栈中到底跑了哪些服务

查看仓库根目录的 docker-compose.yml，可以发现 README 的"一行 Compose"背后其实是一个完整的服务编排：

服务	镜像	职责
caddy	caddy:2.11-alpine	反向代理，负责 Host 分流并把流量转发给 Puter（模拟生产环境的 ALB）
puter	ghcr.io/heyputer/puter	应用本体，监听容器内 4100 端口
mariadb	mariadb:11	SQL 数据库，首次启动时自动应用 schema
valkey	valkey/valkey:8-alpine	Redis 兼容的缓存与限流后端（以单节点集群模式运行，供 ioredis Cluster 客户端连接）
dynamo	amazon/dynamodb-local	本地 DynamoDB，作为 KV 存储，表由 Puter 首次启动时自动创建
s3	rustfs/rustfs	S3 兼容对象存储（文件可替换为 MinIO）
s3-init	amazon/aws-cli	一次性初始化容器，负责创建 bucket 后退出

此外还有一个可选的 ai compose profile（ollama 与 ollama-init），用于在本地拉起大模型推理服务，默认不启用。所有有状态数据都落在 ./puter/data/<service>/ 目录下，因此备份时只需打包这一个目录。

Compose 文件在服务编排上做足了容错设计：puter 服务通过 depends_on 等待 valkey、mariadb 健康检查通过、s3-init 成功退出后才启动；mariadb 首次冷启动约需 20~30 秒。首次启动时 Puter 会在日志中打出迁移信息（形如 [mysql] applied mysql_mig_1.sql (...)），迁移文件具备幂等性，重启时重复执行是安全的。

用安装脚本一键自托管

如果希望跳过手工写 .env 与 config.json 的步骤，仓库根目录还提供了 install.sh 一键安装脚本：它会自动生成随机密钥、写入 .env 与 puter/config/config.json、下载 Compose 与 Caddyfile 并执行 docker compose up -d，首次启动时还会在日志中打印管理员临时密码。重复执行不会覆盖已有配置（设置 PUTER_FORCE=1 可强制重新生成）。更完整的自托管指南参见 doc/self-hosting.md。

方式四：Puter.com 托管服务

如果不想自建基础设施，Puter 官方在 puter.com 提供托管版本，可直接注册使用，功能与自托管版本一致。

自托管进阶：核心配置项详解

自托管时，puter/config/config.json 是决定部署形态的关键文件。以下配置项来自 doc/self-hosting.md 与 config.template.jsonc，适用于上述 Docker Compose 全栈方案：

网络与域名

{
    "domain": "puter.localhost",
    "protocol": "http",
    "pub_port": 80,
    "env": "prod",
    "static_hosting_domain": "site.puter.localhost",
    "private_app_hosting_domain": "app.puter.localhost"
}

• domain 必须是用户实际访问的域名；Puter 完全依据 Host 头做子域名路由（api.*、site.*、app.*），因此不认识的 Host 会被以 Invalid Host header 拒绝；
• protocol / pub_port 决定 Puter 构造回源 URL、重定向与签名 S3 URL 时使用的公开协议与端口。若代理终止了 TLS，必须设为 "protocol": "https"，否则会出现重定向循环与混合内容错误；
• env: "prod" 让首页直接引用预构建的 /dist/bundle.min.css；dev 模式则期望 webpack-dev-server 产出的 manifest，适用于源码开发流程。

密钥与安全

{
    "jwt_secret_v2": "<openssl rand -hex 64>",
    "url_signature_secret": "<openssl rand -hex 64>",
    "trust_proxy": 1
}

• jwt_secret_v2 是 Puter 签发与校验认证 token 的 HMAC 密钥（JWT 头 kid: 'v2'）；旧格式 v1 token 已退役，升级时若配置里残留 jwt_secret 可删除（会被忽略）；
• trust_proxy 表示 Puter 前面的反向代理跳数，1 即代表只信任 Caddy 这一跳；置为 true 会信任所有跳数，使 X-Forwarded-For 可被伪造，生产环境严禁如此设置。

数据库（MariaDB / MySQL）

"database": {
    "engine": "mysql",
    "host": "mariadb",
    "port": 3306,
    "user": "puter",
    "password": "<与 .env 一致>",
    "database": "puter",
    "migrationPaths": ["/opt/puter/dist/src/backend/clients/database/migrations/mysql"]
}

migrationPaths 让 Puter 在启动时自动应用仓库内 src/backend/clients/database/migrations 下携带的 schema 迁移（MySQL 与 PostgreSQL 各有独立目录），迁移幂等，重启可保留。.env 中的 MARIADB_PASSWORD 必须与 config.json 中的 database.password 完全一致，否则首次初始化后 MariaDB 与 Puter 会因密码不一致而报 ER_ACCESS_DENIED_ERROR。若想改用 PostgreSQL，把 engine 改为 postgres、端口改为 5432、迁移路径指向 postgres 目录即可（仓库内注明该支持为社区贡献，生产环境默认仍推荐 MariaDB/MySQL 与 SQLite）。

对象存储（S3）

"s3": {
    "s3Config": {
        "endpoint": "http://s3:9000",
        "publicEndpoint": "http://s3.puter.localhost",
        "accessKeyId": "puter",
        "secretAccessKey": "<与 .env 一致>",
        "region": "us-east-1",
        "forcePathStyle": true
    }
}

• endpoint 仅在 Docker 网络内部可解析；浏览器使用的预签名上传/下载 URL 需要 publicEndpoint（由 Caddy 将 s3.<domain> 路由到 RustFS 并保持 Host 头不变，以通过 S3 签名校验）；
• forcePathStyle: true 适用于 RustFS / MinIO / fauxqs 这类需要路径风格 URL 的实现；换用真实 AWS S3 时应删除该字段。

其他常用开关

"providers": { "ollama": { "enabled": false } },
"meteringEnforcement": { "subscriptions": false }

• providers.ollama.enabled: false：Puter 默认会在启动时探测 127.0.0.1:11434 的本地 Ollama，未运行时会刷出 ECONNREFUSED 日志；关闭探测可避免噪音，启用本地模型则按 doc/self-hosting.md 中的 ai profile 配置；
• meteringEnforcement.subscriptions: false：自托管没有付费套餐，关闭套餐闸门才能让 OpenAI/Anthropic 兼容的 AI 端点对所有账号开放（否则一律返回 402 subscription_required）。

反向代理规则要点

自托管文档还强调了几条"搞错就会重定向循环或 Invalid Host header"的硬规则：不要改写 Host 头；config.json 的 domain 必须等于用户实际访问的域名；protocol 要与公开 scheme 一致；转发 X-Forwarded-Proto、X-Forwarded-For 以及 WebSocket 所需的 Upgrade/Connection 头；通配子域 *.<domain> 与 *.site.<domain> 都要指向 Puter。

支持渠道与社区

README 列出了官方支持渠道，遇到问题可以通过以下途径联系维护者与社区：

• 缺陷报告或功能请求：在 GitHub 仓库提交 issue；
• 社区交流：Discord 服务器、X (Twitter)、Reddit、Mastodon；
• 安全问题：发送邮件至 [e-mail]；
• 一般咨询：发送邮件至 [e-mail]。

许可证

仓库及其全部内容、子项目、模块和组件默认采用 AGPL-3.0 许可证（除非另有明确声明）；其中包含的第三方库可能受各自许可证约束。

总结

本文以 README.nl.md 为骨架，完整覆盖了 Puter 的四种启动路径：源码开发（npm install && npm start）、Docker 单容器、Docker Compose 全栈以及托管服务，并下探到 tools/start.mjs 的启动链路、src/backend/index.ts 的配置加载机制、docker-compose.yml 的服务编排以及 doc/self-hosting.md 的关键配置项。实际部署时，建议按需组合：快速体验选 Docker 单容器，正式自托管选 Compose 全栈（配合 install.sh 一键初始化），并务必替换默认密钥、按需开启 TLS。更多配置细节可随时查阅 config.template.jsonc 与 src/backend/types.ts。