Puter 安装与自托管部署指南本地开发、Docker 与 Docker Compose 全栈搭建【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter本文基于 Puter 仓库的官方多语言 READMEdoc/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磁盘空间1GBNode.js文档标注 16建议 22npm最新稳定版需要特别注意当前仓库的实际版本约束package.json 的engines字段声明node: 24.0.0且 Dockerfile 的构建与运行阶段均基于node:24-slim镜像。也就是说从当前仓库源码直接运行时请以 Node.js 24 为准文档中的 16/22 可视为历史下限说明以仓库实际内容为准。方式一本地开发LocalhostREADME 给出的本地启动流程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.mjsnpm run setupExtensions—— 通过 tools/extensionSetup.mjs 装配扩展包npm run build:ts—— 编译后端 TypeScript对应 package.json 中build:ts脚本产物位于dist/以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 --serverputer.com或npm start -- --serverhttp://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-jsSDK、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 4100Dockerfile健康检查为wget --spider http://puter.localhost:4100/testDockerfile。镜像内部是两段式构建node:24-slim构建阶段先复制各子项目的package.json/lockfile 以最大化npm ci缓存再并行编译后端 TS、GUI 与 puter-js 的 webpack 包运行阶段仅保留node:24-slimgit版本探针wgetHEALTHCHECK的精简环境Dockerfile。方式三Docker Compose 全栈部署README 区分了 Linux/macOS 与 Windows 两套操作步骤。Linux / macOSmkdir -p puter/config puter/data sudo chown -R 1000:1000 puter wget https://raw.githubusercontent.com/HeyPuter/puter/main/docker-compose.yml docker compose upWindowsPowerShellmkdir -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-caddycaddy:2.11-alpine反向代理80 端口配置 TLS 后含 443按 Host 分发并终结 TLSputerghcr.io/heyputer/puter:main应用本体仅expose 4100于 compose 网络内部puter-mariadbmariadb:11SQL 数据库首次启动自动应用 schemaputer-valkeyvalkey/valkey:8-alpineRedis 兼容缓存与限流后端以单节点集群模式运行以匹配 Puter 的 ioredis 集群客户端puter-dynamoamazon/dynamodb-localKV 存储启动时由 Puter 自建store-kv-v1表puter-s3rustfs/rustfsS3 兼容对象存储可替换为 MinIOputer-s3-initamazon/aws-cli一次性任务容器首启创建 bucket 后退出另有可选的 compose profileaiputer-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、Lets Encrypt 通配证书与 Caddy 的 TLS 接线、自有反向代理的规则不得改写Host、protocol与外部域名一致、trust_proxy跳数设置、PostgreSQL/SMTP/OIDC/AI 提供商/存储配额/计量等附加配置以及常见故障排查。两个容易踩的坑源自 compose 与配置源码Caddyfile 缺失会变成目录caddy/Caddyfile是只读绑定挂载若该文件不存在Docker 会在挂载点创建一个目录导致puter-caddy以 not a directory 崩溃。因此运行docker compose up前务必确认caddy/Caddyfile与.env同处一目录doc/self-hosting.md Step 4 有同样提醒。密码必须在.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_port4100/4100内部监听端口 / 外部可见端口置于反代之后时改为 80/443protocolhttp公开 scheme反代终结 TLS 后必须改为https否则会出现重定向循环与混合内容错误domainputer.localhost主域名Puter 完全按 Host 头路由api.*、site.*、app.*子域外部域名必须与此一致static_hosting_domain等site.puter.localhost等静态站/私有应用托管子域需要通配 DNSjwt_secret_v2/url_signature_secretchange-me认证令牌签名与 URL 签名密钥任何公开部署都必须用openssl rand -hex 64替换trust_proxyfalse反代跳数1 一层代理切勿设为true会信任所有跳使X-Forwarded-For可伪造支持与许可许可AGPL-3.0LICENSE.txt第三方库可能有各自许可问题反馈可通过仓库的 issue 渠道提交 bug 与功能请求社区渠道Discord、X (Twitter)、Reddit、Mastodon 上均有 Puter 官方/社区账号入口见各语言 README如 doc/i18n/README.he.md 的支持一节安全漏洞报告至securityputer.com一般性邮件联系hiputer.com。小结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 逐项落实。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Puter 安装与自托管部署指南：本地开发、Docker 与 Docker Compose 全栈搭建
Puter 安装与自托管部署指南本地开发、Docker 与 Docker Compose 全栈搭建【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter本文基于 Puter 仓库的官方多语言 READMEdoc/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磁盘空间1GBNode.js文档标注 16建议 22npm最新稳定版需要特别注意当前仓库的实际版本约束package.json 的engines字段声明node: 24.0.0且 Dockerfile 的构建与运行阶段均基于node:24-slim镜像。也就是说从当前仓库源码直接运行时请以 Node.js 24 为准文档中的 16/22 可视为历史下限说明以仓库实际内容为准。方式一本地开发LocalhostREADME 给出的本地启动流程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.mjsnpm run setupExtensions—— 通过 tools/extensionSetup.mjs 装配扩展包npm run build:ts—— 编译后端 TypeScript对应 package.json 中build:ts脚本产物位于dist/以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 --serverputer.com或npm start -- --serverhttp://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-jsSDK、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 4100Dockerfile健康检查为wget --spider http://puter.localhost:4100/testDockerfile。镜像内部是两段式构建node:24-slim构建阶段先复制各子项目的package.json/lockfile 以最大化npm ci缓存再并行编译后端 TS、GUI 与 puter-js 的 webpack 包运行阶段仅保留node:24-slimgit版本探针wgetHEALTHCHECK的精简环境Dockerfile。方式三Docker Compose 全栈部署README 区分了 Linux/macOS 与 Windows 两套操作步骤。Linux / macOSmkdir -p puter/config puter/data sudo chown -R 1000:1000 puter wget https://raw.githubusercontent.com/HeyPuter/puter/main/docker-compose.yml docker compose upWindowsPowerShellmkdir -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-caddycaddy:2.11-alpine反向代理80 端口配置 TLS 后含 443按 Host 分发并终结 TLSputerghcr.io/heyputer/puter:main应用本体仅expose 4100于 compose 网络内部puter-mariadbmariadb:11SQL 数据库首次启动自动应用 schemaputer-valkeyvalkey/valkey:8-alpineRedis 兼容缓存与限流后端以单节点集群模式运行以匹配 Puter 的 ioredis 集群客户端puter-dynamoamazon/dynamodb-localKV 存储启动时由 Puter 自建store-kv-v1表puter-s3rustfs/rustfsS3 兼容对象存储可替换为 MinIOputer-s3-initamazon/aws-cli一次性任务容器首启创建 bucket 后退出另有可选的 compose profileaiputer-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、Lets Encrypt 通配证书与 Caddy 的 TLS 接线、自有反向代理的规则不得改写Host、protocol与外部域名一致、trust_proxy跳数设置、PostgreSQL/SMTP/OIDC/AI 提供商/存储配额/计量等附加配置以及常见故障排查。两个容易踩的坑源自 compose 与配置源码Caddyfile 缺失会变成目录caddy/Caddyfile是只读绑定挂载若该文件不存在Docker 会在挂载点创建一个目录导致puter-caddy以 not a directory 崩溃。因此运行docker compose up前务必确认caddy/Caddyfile与.env同处一目录doc/self-hosting.md Step 4 有同样提醒。密码必须在.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_port4100/4100内部监听端口 / 外部可见端口置于反代之后时改为 80/443protocolhttp公开 scheme反代终结 TLS 后必须改为https否则会出现重定向循环与混合内容错误domainputer.localhost主域名Puter 完全按 Host 头路由api.*、site.*、app.*子域外部域名必须与此一致static_hosting_domain等site.puter.localhost等静态站/私有应用托管子域需要通配 DNSjwt_secret_v2/url_signature_secretchange-me认证令牌签名与 URL 签名密钥任何公开部署都必须用openssl rand -hex 64替换trust_proxyfalse反代跳数1 一层代理切勿设为true会信任所有跳使X-Forwarded-For可伪造支持与许可许可AGPL-3.0LICENSE.txt第三方库可能有各自许可问题反馈可通过仓库的 issue 渠道提交 bug 与功能请求社区渠道Discord、X (Twitter)、Reddit、Mastodon 上均有 Puter 官方/社区账号入口见各语言 README如 doc/i18n/README.he.md 的支持一节安全漏洞报告至securityputer.com一般性邮件联系hiputer.com。小结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 逐项落实。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考