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