cloudinabottle.toml 清单规范全解:基础字段、端口与权限逐项说明指南

原创2026-10-14 05:01:181,440 阅读

cloudinabottle.toml 清单规范全解:基础字段、端口与权限逐项说明指南

Cloud in a Bottle 是一个让你在自己掌控的服务器上部署、使用和分享 Web 应用的自托管平台。你的应用、数据和基础设施都归你所有。而 cloudinabottle.toml 正是平台读懂你应用的"说明书"——把它放在 Git 仓库根目录,router 就会自动构建容器、注入数据目录、配置路由与权限。这篇指南逐项讲解清单中的基础字段、端口映射、资源配额和权限声明,帮你快速写出第一个合法的 manifest。

Cloud in a Bottle 个人计算空间面板,展示 cloudinabottle.toml 清单部署后的应用列表

一、cloudinabottle.toml 是干什么的?

每个应用仓库只需在根目录放一个 cloudinabottle.toml,平台就能完成部署。完整的官方规范见 docs/src/creating_an_app/manifest_spec.md。

几个值得知道的小细节:

  • 文件名兼容旧项目:平台会先找 cloudinabottle.toml,找不到时回退到旧名 openhost.toml,两者共存时以前者为准(见 compute_space/src/compute_space/core/manifest.py)。
  • 解析即校验:清单在解析阶段就会做安全校验,不合法的权限声明会直接报错,而不是运行时才失败(见 manifest.py 解析入口)。
  • 更新需审批:涉及端口、资源、数据权限等能力类字段的变更,更新应用时会触发 owner 审批流程。

二、最小可用示例:30 秒看懂整体结构

以下是最精简的合法清单,仓库自带的测试应用就是这样写的(apps/test_app/cloudinabottle.toml):

[app]
name = "my-app"
version = "0.1.0"
description = "A simple web app"

[runtime.container]
image = "Dockerfile"
port = 8080

[resources]
memory_mb = 128
cpu_cores = 0.1

[data]
sqlite = ["main"]

必填的只有 [app] 的 name、version 和 [runtime.container] 的 image、port,其余都有默认值。下面逐项拆解。

三、[app] 基础字段

字段 类型 必填 说明
name string ✅ 唯一应用标识,全小写,可用连字符。它会成为应用的子域名前缀
version string ✅ 版本号,惯例用 semver(如 0.1.0),系统只检查非空
description string ❌ 简短描述,展示在面板上
authors string[] ❌ 作者列表
hidden boolean ❌ 设为 true 时该应用不在面板中展示

💡 name 决定了应用的访问地址:https://{name}.{你的域名}/,所以命名要有意义。

四、[runtime.container] 容器与端口

字段 类型 必填 说明
image string ✅ Dockerfile 相对仓库根目录的路径,通常为 "Dockerfile"
port integer ✅ 应用容器内监听 HTTP 的端口
command string ❌ 覆盖容器的 CMD,例如 "/data -A"
capabilities string[] ❌ 额外授予的 Linux 权限,仅限安全白名单
devices string[] ❌ 透传的主机设备,仅限白名单路径
shm_mb integer ❌ 共享内存大小(MiB),重浏览器负载应用需要调大
network_host boolean ❌ 使用宿主机网络命名空间,⚠️ 会禁用网络隔离,仅 VPN 等应用适用

关于 capabilities 和 devices:由于所有应用都跑在 rootless podman 中,平台采用"白名单"而非"黑名单"策略——不在 SAFE_CAPABILITIES / SAFE_DEVICE_PATHS 白名单里的权限(如 SYS_ADMIN、/dev/kvm)会在解析时直接拒绝。常见合法值:网络类 NET_ADMIN、NET_RAW;设备类 /dev/net/tun(WireGuard/Tailscale)、/dev/fuse 等。

五、[[ports]] 额外端口映射(进阶)

大多数应用不需要这一段:HTTPS 流量会经由 router 代理进入容器,自动映射到 runtime.container.port。只有需要非 HTTP 协议(如 SMTP、游戏服务器)时才用 [[ports]]:

[[ports]]
label = "metrics"
container_port = 9090
host_port = 9090        # 留空或写 0 表示从 9000-9999 自动分配

[[ports]]
label = "debug"
container_port = 5005
host_port = 0          # 自动分配,推荐,避免端口冲突

规则要点(见 manifest.py 端口解析):

  • label 和 container_port 必填且不能重复;
  • host_port = 0 表示自动分配,强烈优先使用,避免多应用抢同一端口;
  • 宿主机端口必须 ≥ 25(rootless 限制);
  • 80 和 443 被 router 保留,应用不能绑定。

六、[routing] 路由与 [[links]] 快捷链接

字段 说明
health_check 健康检查路径,用于判断应用是否启动完成
public_paths 无需登录即可访问的路由前缀(如 ["/webhook", "/callback"])

[[links]] 则用于在应用详情页额外展示快捷入口(如管理控制台):

[[links]]
name = "admin"
path = "/_openhost/admin"

📌 默认情况下所有路由都需要 owner 登录;需要开放的路径请明确写入 public_paths,参考真实用例 apps/oauth_provider/cloudinabottle.toml。

七、[resources] 资源配额

字段 默认值 说明
memory_mb 128 运行内存上限(MB)
build_memory_mb = memory_mb 构建镜像时的内存上限。构建比运行更耗内存,构建 OOM 被杀时需显式调大
cpu_cores 0.1 CPU 核数,小数表示比例(1.0 = 1 核)
gpu false 是否分配 GPU

一个真实案例:test-app 运行只要 64 MB,但 pip install 构建远超此值,因此显式声明了 build_memory_mb = 1024(apps/test_app/cloudinabottle.toml#L20-L26)——这是新手最常踩的坑。

八、[data] 数据目录与数据权限

Cloud in a Bottle 提供三级存储,通过 [data] 显式申请:

字段 默认 说明
app_data true 永久数据目录,通过 BOTTLE_APP_DATA_DIR 暴露给应用
app_temp_data false 临时数据目录(重建数据用),BOTTLE_APP_TEMP_DIR
app_archive false 归档存储(视频、照片等大数据),可配置为 S3 后端,BOTTLE_APP_ARCHIVE_DIR
sqlite [] 自动预置 SQLite 数据库,如 ["main"] 会生成 sqlite/main.db 并通过 BOTTLE_SQLITE_MAIN 暴露
access_all_app_data false 挂载所有应用的数据目录(读写),文件浏览器、备份类应用专用

例如 apps/file_browser/cloudinabottle.toml 就申请了 access_all_app_data = true。⚠️ 旧字段 access_all_data、access_all_archive 已弃用,请统一使用新字段。

九、[[services.v2]] 跨应用服务与权限声明 🗝️

这是清单中最"高级"的部分:应用之间不直接通信,全部经 router 中转,权限由 owner 审批。

消费服务(申请别人):

[[services.v2.consumes]]
service = "github.com/imbue-openhost/openhost/services/secrets"
shortname = "secrets"          # 调用时用的别名,小写字母开头
version = ">=0.1.0"            # SemVer 版本约束
grants = [{ key = "TEST_SECRET" }]   # 申请的权限,owner 安装时审批

提供服务(开放给别人):

[[services.v2.provides]]
service = "github.com/imbue-openhost/openhost/services/oauth"
version = "0.1.0"
endpoint = "/oauth_service/"

要点(完整机制见 docs/src/creating_an_app/cross_app_services.md):

  • shortname 必须匹配 ^[a-z][a-z0-9_-]{0,31}$ 且清单内唯一;
  • grants 可以是字符串或对象,结构由服务方定义;
  • 清单中新增的权限不会自动生效——每次应用更新,新声明的权限都会与上一版清单比对,需要 owner 审批(见 manifest_newly_declared_permissions_v2)。

十、新手避坑清单 ✅

症状 原因与对策
提示 port is required 忘了写 [runtime.container] 的 port,它不是宿主机端口,是容器内监听端口
构建阶段 OOM 被杀 调大 build_memory_mb,它默认等于 memory_mb
capabilities 解析报错 该权限不在安全白名单,属 rootless 环境禁止项,换用白名单内的权限
host_port 绑定失败 端口必须 ≥25,且避开 router 保留的 80/443;建议 host_port = 0 自动分配
权限 403 grants 未被 owner 批准,或提供方未安装,检查更新审批页

十一、总结:一张表记住必填项

必填:[app].name、[app].version、[runtime.container].image、[runtime.container].port
常用:[resources].memory_mb / cpu_cores、[data].sqlite、[routing].public_paths
进阶:[[ports]](非 HTTP 端口)、[data].access_all_app_data、[[services.v2.*]](跨应用权限)

官方文档目录:docs/src/creating_an_app/,清单源码实现:compute_space/src/compute_space/core/manifest.py。写好 cloudinabottle.toml,你的应用就能在属于自己的服务器上跑起来 🚀

登录后查看全文
cloud-in-a-bottle