Puter 入门与部署实践从源码开发到 Docker 自托管的浏览器互联网计算机【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter本文基于 Puter 仓库的阿拉伯语版 READMEdoc/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并非简单起一个服务器而是一条完整的构建-运行链执行npm run setupExtensions由 tools/extensionSetup.mjs 完成执行npm run build:ts用tsc编译后端 TypeScript 到dist/以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 --serverputer.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 nodecompose 中对应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 upWindowsPowerShell方式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 文件拉起的是一套单主机生产级全栈而不只是应用容器容器镜像角色puterghcr.io/heyputer/puter:main应用本体仅对内暴露 4100puter-caddycaddy:2.11-alpine反向代理80/443按 Host 透传子域名路由puter-mariadbmariadb:11SQL 数据库首次启动自动应用 schemaputer-valkeyvalkey/valkey:8-alpineRedis 兼容缓存与限流后端单节点集群模式puter-dynamoamazon/dynamodb-localKV 存储Puter 启动时自建表puter-s3rustfs/rustfsS3 兼容对象存储可换 MinIOputer-s3-initamazon/aws-cli一次性容器创建 bucket 后退出puter-ollama/puter-ollama-initollama/ollama可选compose profileai本地 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/mariadbservice_healthy、dynamoservice_started、s3-initservice_completed_successfully保证启动顺序正确可选本地 LLMollama与ollama-init藏在aiprofile 后需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_FORCE1才强制轮换。Windows 侧对应irm https://puter.com/selfhost?oswindows | iex见 README.md 的 Self-Hosting 小节。完整的分步自托管指南——包括密钥生成、DNS 泛解析、TLS 通配符证书、OIDC 登录Google/Apple/Microsoft、SMTP 邮件、存储配额与计量策略等——都在 doc/self-hosting.md 中建议生产部署前通读。托管服务 Puter.com除自托管外Puter 也作为托管服务运行在 puter.com。仓库中npm start --serverputer.com这种本地 GUI 远端后端模式见上文 tools/start.mjs 一节就是为对接该托管环境设计的。系统要求阿拉伯语版 README 列出的系统要求如下项目要求操作系统Linux、macOS、Windows内存最低 2 GB推荐 4 GB磁盘空间1 GB 空闲Node.js16推荐 22当前仓库实际要求见下npm最新稳定版需要说明的适用前提如前所述package.json 当前声明engines.node 24.0.0Dockerfile 使用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 Caddy2 Cloudflare→Caddy。切勿设为true——它会信任所有跳使X-Forwarded-For可伪造破坏限流与审计jwt_secret_v2/url_signature_secret任何公开部署都必须替换为随机值模板建议openssl rand -hex 64s3/s3_bucket/s3_region对象存储连接参数本地 RustFS/MinIO 需要forcePathStyle: truemeteringEnforcement/unlimitedMetering自托管没有付费计划通常要关闭订阅门槛或整体放开计量否则部分 AI 端点会对所有人返回 402providersAI 供应商含ollama本地模型的启用开关与 API Key未运行 Ollama 时务必设providers.ollama.enabled: false否则每次启动都会刷ECONNREFUSED。以上每一项的取舍理由为什么这样设、错设会发生什么在 doc/self-hosting.md 的 Why these knobs 部分有逐条解释是本仓库少见的、把配置→后果讲透的文档。支持与社区渠道仓库文档列出的支持渠道包括Bug 报告 / 功能请求在仓库的 Issue 页面提交Issue 模板提供分类选择社区Discord、Redditr/puter、XHeyPuter、Mastodonputer安全问题发送至 securityputer.com维护者hiputer.com。项目方明确表示乐于回答任何问题遇到问题可直接通过上述渠道提问。仓库根目录还有 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 为准。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考