Cloud in a Bottle 是什么？用自托管 Web 应用打造属于自己的云-平芜编程栈

【免费下载链接】cloud-in-a-bottle

Deploy, use, and share web apps on a server you control. Your apps, data, and infrastructure stay yours.

项目地址：https://gitcode.com/gh_mirrors/cl/cloud-in-a-bottle

Cloud in a Bottle（简称 bottle）是一个开源的自托管平台：它让你在一台自己控制的服务器上，一键部署、使用和分享 Web 应用。你的应用、数据和基础设施全部归你自己——不需要在几十个 SaaS 账号之间切换，也不用手动折腾 Docker、Nginx 和证书。

为什么需要"瓶子里的云" 🍾

大多数人能用的"云"，都隔着一家公司——它们有完全不同的商业诉求。开源 Web 软件虽然很多，但要把它们真正跑起来，意味着你要和基础设施搏斗：域名、反向代理、HTTPS、数据库、备份……

Cloud in a Bottle 把这些复杂度一次性吞掉：

✅应用安装像手机 App 一样简单——从应用目录（Catalog）一键安装，或粘贴一个 Git 仓库地址自动部署
✅数据留在你自己的硬件上——服务器、虚拟机还是家里的旧电脑，随你选
✅默认安全——每个应用都跑在 rootless Podman 容器沙箱里，默认只有你能访问
✅一个域名走天下——通配符 DNS + 自动 HTTPS，每个应用自动获得<应用名>.<你的域名>的公网地址

能部署什么应用？📦

个人小工具：AI 生成的应用、脚本、没有地方托管的各种 utility
开源软件：Matrix 聊天、Minecraft 服务器、笔记、项目管理工具
开发/创意工具：编码 Agent、绘图软件，或者你自己写的、想分享给别人的东西
任何容器化 Web 应用：只要仓库里有 Dockerfile，再加一个cloudinabottle.toml清单文件，就能部署

仓库里自带的示例应用可以参考 apps/test_app/，清单文件长这样（apps/test_app/cloudinabottle.toml）：

[app] name = "test-app" version = "0.1.0" [runtime.container] image = "Dockerfile" port = 5000

它是怎么工作的？⚙️

整个实例就是一台机器 + 一个核心服务——Python 路由程序（router），一切围绕它展开：

组件	职责
Router（`openhost.service`）	仪表盘 + API、按子域名代理请求、构建和运行应用容器、管理域名与证书
Caddy	443 端口终结 TLS，把请求转发给 router
CoreDNS	负责你整个域名的权威 DNS，提供通配符解析和证书签发
App 容器	每个应用一个 rootless Podman 容器，互不可见
System agent	无权限的`host`用户做不到的主机级操作

一次浏览器访问https://notes.mycooldomain.com/的完整链路：

DNS：通配符记录*.mycooldomain.com解析到服务器公网 IP
TLS：Caddy 用通配符证书终结连接
匹配：router 从Host头取出应用名notes
鉴权：默认所有路径都需要 owner 登录，未登录直接跳登录页
代理：请求转发到应用容器，WebSocket 同样支持

想深入了解，可阅读官方文档中的工作原理概览。

部署指南：三步跑起来 🚀

前置条件

一个你自己控制的域名（可以用子域名，如bottle.yourdomain.com）
一台带静态公网 IPv4的机器，全新安装Ubuntu 24.04
SSH root 访问权限
放行80、443和53（TCP/UDP）端口

第 1 步：把域名委托给服务器

Cloud in a Bottle 会运行自己的权威 DNS 服务器，所以要把它整个 zone 委托出去。在 DNS 服务商处创建两条记录：

类型	名称	值
`A`	`ns1.mycooldomain.com`	`203.0.113.10`
`NS`	`mycooldomain.com`	`ns1.mycooldomain.com`

委托生效前用dig +short NS mycooldomain.com确认一下。

第 2 步：运行安装脚本

SSH 到机器上，一条命令完成所有安装（对应 scripts/provision.sh）：

curl -fsSL https://raw.githubusercontent.com/cloud-in-a-bottle/cloud-in-a-bottle/main/scripts/provision.sh \ | sudo bash -s -- --domain mycooldomain.com --acme-email you@example.com

脚本会创建无权限的host用户、安装 Podman、克隆代码、写入配置、注册 Let's Encrypt 账号并启动openhost服务。

第 3 步：认领你的实例

公网实例采用 token 门控，防止陌生人抢先。安装结束时输出一个 Claim URL：

Claim URL: https://mycooldomain.com/setup?claim=<token>

打开它，创建你的 owner 账号——搞定！🎉 完整的云端部署步骤见 docs/src/setup/cloud_instance.md，家用服务器场景也有专门的指南。

日常使用：全在浏览器里完成 💻

打开https://<你的域名>/就是仪表盘：

Dashboard：所有应用、状态和入口链接
Catalog / Deploy app：两种安装方式——目录里一键装，或粘贴任意含cloudinabottle.toml的仓库 URL
Settings：账号、API token、域名、归档存储、平台更新
System info：内存、磁盘、每个应用的资源占用
Terminal：浏览器里直接开 shell，不用 SSH 客户端

新实例预装了一批实用应用：Catalog（应用商店）、Backup（加密备份）、Files（文件浏览器）、Secrets（密钥管理）、OAuth provider（托管你的 Google/GitHub token）、Community chat（Matrix 聊天）。全部是普通应用，随时可删。

安装前请注意 🛡️

安装页面会展示应用在其清单里声明的一切：需要多少内存、要访问哪些数据、是否要其他应用的数据、额外 Linux capabilities、宿主机设备或网络权限。更新时同样会显示变更并需要你批准——平台默认给应用最小权限，提权完全由你决定。

应用数据存哪里？🗄️

应用存储分三个层级，清单文件控制容器能访问哪些层：

层级	内容
持久数据	应用的永久数据（数据库等），存在你的实例上
临时数据	构建产物、容器日志等 scratch 空间
归档存储	大批量内容，可用本地磁盘，也可指向你配置的 S3 兼容存储

详细机制见数据文档。