ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Puter(The Internet OS)入门与部署指南:本地开发、Docker 容器化与自托管实践

Puter(The Internet OS)入门与部署指南:本地开发、Docker 容器化与自托管实践 PuterThe Internet OS入门与部署指南本地开发、Docker 容器化与自托管实践【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter本指南依据仓库内的 Odiaଓଡ଼ିଆ语言版项目文档 doc/i18n/README.od.md 整理成文并结合仓库源码与配置还原了 Puter 的完整上手路径它是一款免费、开源、可自托管的互联网操作系统可用作隐私优先的个人云盘、Web 应用与游戏发布平台、Dropbox/Google Drive 类网盘的替代品以及学习 Web 开发、云计算的开放项目。读完本文你将掌握从npm start本地开发到 Docker 单容器、Docker Compose 全栈编排与自托管部署的完整操作方法并了解其系统要求、目录结构与许可证边界。Puter 是什么Puter 是一款特性丰富、运行快速且高度可扩展的开源互联网操作系统互联网 OS。Odia 版 README 将其定位描述为一个高级、开源、注重隐私privacy-first的互联网操作系统免费、开放源码并且可以自行托管。围绕这一定位官方文档列举了五种典型使用场景隐私优先的个人云把全部文件、应用与游戏存放在一个安全的地方随时随地访问Web 应用与游戏发布平台用于构建并发布网站、Web 应用和游戏网盘的替代品作为 Dropbox、Google Drive、OneDrive 等服务的替代提供全新的界面与更强的功能远程桌面环境为服务器与工作站提供远程桌面环境学习型开源社区一个友好的开源项目用于学习 Web 开发、云计算、分布式系统等知识。从仓库结构看Puter 是一个典型的 npm workspaces monorepo见 package.json顶层按src/*组织核心子项目包括后端服务 src/backend、浏览器端桌面 GUI src/gui、JavaScript SDK src/puter-js、无服务器 Worker 运行时 src/worker 以及可插拔扩展 extensions。若想快速了解后端各层Controller–Service–Repository 依赖注入如何协作可阅读 doc/architecture.md。系统要求System RequirementsOdia 版 README 给出的运行环境基线如下项目要求操作系统Linux、macOS、Windows内存RAM最低 2GB建议 4GB磁盘空间至少 1GB 空闲空间Node.js版本 20.19.5建议 23npm最新稳定版需要提醒的是这是文档给出的推荐基线。对于当前仓库的快照package.json 中的engines字段实际声明为node: 24.0.0因此以源码方式构建运行时建议使用不低于 24 的较新 Node.js 版本。此外文档中的内存/磁盘数值针对基础运行场景如果采用下文的全栈 Docker Compose附带数据库、缓存与对象存储实际占用会高于该基线属于可推断的常规部署情形。快速开始本地开发模式拉取代码并启动Odia 文档给出的本地开发四步曲git clone 仓库地址 cd puter npm install npm start启动完成后浏览器访问http://puter.localhost:4100若 4100 被占用则自动使用下一个可用端口访问域名采用puter.localhost而非裸localhost这与 Puter 按 Host/子域名路由的设计一致后续自托管部分会看到api.*、site.*、app.*等子域名都被用来区分不同功能面。npm start背后发生了什么直接查看启动入口 tools/start.mjs 可以了解这条命令的真实调用链。在不带额外参数时npm start依次执行npm run setupExtensions——初始化 extensions 扩展环境npm run build:ts——用tsc编译 TypeScript 后端以--enable-source-maps并预加载dist/src/backend/telemetry.js的方式运行dist/src/backend/index.js拉起后端进程对应 tools/start.mjs。值得注意的是npm start还支持一种GUI-only 模式当传入--server地址时例如npm start --serverputer.com本地不再启动后端而是仅由 src/gui/dev-server.js 承载界面对接一个远程 Puter 后端便于前端开发者联调还可用--extensions目录把仓库外的 GUI 扩展打包进被服务的界面对应 tools/start.mjs。如果首次运行遇到问题Odia 文档提示查阅 First Run Issues。在当前仓库中与之对应的排障与部署细节集中在 doc/self-hosting.md 的 Troubleshooting 一节如502 Bad Gateway、admin password not set等问题的处理。Docker 单容器运行不搭建本地 Node 环境直接用 Docker 拉起一个自包含实例是最快的尝鲜方式。Odia 文档给出如下命令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 puter cd puter mkdir -p puter/config puter/data在当前目录创建宿主侧的目录骨架其中puter/config存放配置文件将被挂载到容器内/etc/puterputer/data存放运行时数据挂载到容器内/var/putersudo chown -R 1000:1000 puter把目录属主改为 UID/GID1000与镜像内运行用户对齐。这一约定同样体现在 docker-compose.yml 中——puter服务通过环境变量注入PUID: 1000、PGID: 1000并把./puter/config:/etc/puter、./puter/data/puter:/var/puter做成数据卷docker run --rm -p 4100:4100映射默认 HTTP 端口 4100--rm表示容器退出即删除ghcr.io/heyputer/puter官方发布的 OCI 镜像地址。启动后同样访问http://puter.localhost:4100或下一个可用端口。容器内持久化数据落在/var/puter与配置落在/etc/puter因此重新创建容器不会丢失状态。Docker Compose 启动文档给出的快速步骤Linux / macOSmkdir -p puter/config puter/data sudo chown -R 1000:1000 puter wget 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 docker-compose.yml 下载地址 -OutFile docker-compose.yml docker compose up两种方式都在先准备好puter/config、puter/data两个挂载目录之后把docker-compose.yml放到.env同级的目录下再up。就本仓库而言docker-compose.yml 与 caddy/Caddyfile 已随源码就位可以直接作为编排依据。当前仓库的全栈编排结构需要说明当前仓库根目录的 docker-compose.yml 是全栈形态——它不只运行 Puter 单容器而是把 Puter 运行所依赖的外部服务一并拉起最接近可在单台主机上自管的类生产部署。文件头注释归纳了整套服务对应 docker-compose.yml容器镜像职责puterghcr.io/heyputer/puter应用本体内部监听 4100 端口puter-caddycaddy:2.11-alpine反向代理80/443承担 TLS 与 Host 分发等价于生产环境的 ALBputer-mariadbmariadb:11SQL 数据库首次启动自动应用 schemaputer-valkeyvalkey/valkey:8-alpineRedis 兼容缓存与限流后端以单节点 cluster 模式运行puter-dynamoamazon/dynamodb-localKV 存储DynamoDB 本地版表由 Puter 启动时自建puter-s3rustfs/rustfsS3 兼容对象存储文件内注明 MinIO 是备选替代puter-s3-initamazon/aws-cli一次性初始化容器首启时创建 bucket 后退出另有随 compose profileai可选启用的本地 LLM 服务puter-ollama与puter-ollama-init默认拉取tinyllama模型。所有有状态数据统一存放在宿主机的./puter/data/service/目录下。由于全栈编排需要数据库口令、S3 密钥等敏感参数保持.env与puter/config/config.json一致最省事的启动路径是直接执行仓库自带的安装脚本 install.sh它会生成密钥、写好.env与puter/config/config.json并执行docker compose up -d逐项手动的完整流程、参数含义与故障排查请阅读 doc/self-hosting.md。其中对易错点例如jwt_secret_v2的作用、env: prod之于静态资源、dynamo.aws使用蛇形命名而s3.s3Config使用驼峰命名等均有逐键说明。自托管Self-HostingOdia 文档将自托管部署指向了专门的部署文档。在当前仓库中这份指南就是 doc/self-hosting.md。它基于上文的全栈 docker-compose.yml 展开核心流程可概括为四步准备.env与puter/config/config.json用openssl rand -hex 32/64生成MARIADB_ROOT_PASSWORD、MARIADB_PASSWORD、S3_SECRET_KEY、JWT_SECRET_V2、URL_SIGNATURE_SECRET等密钥同时写入两个文件且必须保持一致否则首启时 MariaDB 初始化密码与 Puter 登录密码漂移会报ER_ACCESS_DENIED_ERROR配置 DNS由于 Puter 依赖子域名路由api.*、site.*、app.*、s3.*等需要为主域名及各子域名添加指向服务器 IP 的A记录含通配符*.domain可选开启 TLSPuter 会为每个用户动态生成name.site.domain、name.app.domain这类子域名必须使用通配符证书DNS-01 方式申请。因此仓库内 caddy/Caddyfile 显式设置了auto_https off由运维者把fullchain.pem、privkey.pem放入./puter/tls/后取消注释:443站点块并在config.json中把protocol切到https、pub_port设为 443拉起与登录docker compose up -d后首启约 30 秒随后在 puter 容器日志中通过docker compose logs puter | grep tmp_password查找一次性临时管理员密码用户名为admin首次登录后请在设置中修改。文档还覆盖了额外配置PostgreSQL 数据库引擎社区贡献文档明确标注可能尚不完善、SMTP 邮件用于密码找回/邮箱确认/通知可配合 MailHog 本地调试、Google/Apple/Microsoft 的 OIDC 第三方登录、AI 提供商密钥、每用户存储配额默认 100MB、计量与预算自托管建议unlimitedMetering: true、内置工作量证明验证码、禁用新用户注册、密码长度策略等。所有配置键的权威出处可对照 config.template.jsonc约 500 行的全量模板以及类型定义 src/backend/types.ts。反向代理注意事项若不用自带 Caddy 而把 Puter 放在自己的 nginx/Traefik/HAProxy 之后doc/self-hosting.md 强调了几条关键规则不要改写Host头Puter 完全依靠 Host 做子域名路由外部域名必须与config.json的domain一致protocol必须匹配公网 schemeHTTPS 代理后面应设https转发X-Forwarded-Proto、X-Forwarded-For与 WebSocket 所需的Upgrade/Connectiontrust_proxy设置为 Puter 前面的代理跳数如 1 或 2绝不能设成true否则X-Forwarded-For可被伪造、限流与审计失效。云托管版 Puter.com若不想自建Puter 也以托管服务形式提供。官方维护的站点即puter.com用户可以直接在线体验而不必关心安装运维。对于开发者而言托管版与自托管版共享同一套架构与接口约定本地代码可平滑迁移。支持与社区遇到问题或希望参与讨论时Odia 文档列出的渠道包括Bug 或新功能请求在项目 Issue 系统提交社区聊天Discord社交账号X (Twitter)、Reddit、Mastodon安全问题通过邮件securityputer.com私下报告维护者邮箱hiputer.com。此外仓库内还准备了 CONTRIBUTING.md、SECURITY.md、BUG-BOUNTY.md 等协作与安全文档供贡献者与研究者进一步查阅。许可证根据 Odia 文档的声明本仓库连同其全部子项目、模块与组件默认采用AGPL-3.0许可证对应根目录 LICENSE.txt仓库内包含的第三方库可能适用其各自的许可证。实际浏览目录可以发现这种主仓 AGPL 组件独立授权的结构确实存在例如 SDK 目录 src/puter-js 下就附带了自己的APACHE_LICENSE.txt。在二次开发、分发或商业化使用前建议逐个子项目核对各自的许可证文本。面向读者的补充资料Odia 文档与多语言生态本指南所依据的 doc/i18n/README.od.md 是项目 README 的 Odiaଓଡ଼ିଆ印度奥里亚语翻译版。类似的翻译分布在 doc/i18n 目录下共数十种语言中文版为 doc/i18n/README.zh.md根目录 README.md 的 Translations 一节即为这些语言的索引入口。这篇 Odia 文档相对于英文版还额外附带了一组面向后端读者的模块文档链接指引阅读PuterAI 模块后端 AI 能力的对外 API对应实现位于 src/backend/controllers/puterai如PuterAIController.ts与 src/backend/drivers 下的ai-chat、ai-image、ai-tts、ai-ocr等驱动目录计量Metering服务负责记录并约束账户的资源消耗当前实现位于 src/backend/services/metering自托管场景请关注上文unlimitedMetering开关扩展开发指南Puter 把非核心能力做成可插拔扩展参考 extensions 目录下的metering.ts、thumbnails.ts、serverInfo.ts等示例扩展如何注册进分层架构可参见 doc/architecture.md。上述文档与源码路径均为当前仓库中真实存在的位置可作为在 Odia README 基础上继续深挖 Puter 后端模块的起点。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表