文档 · 1.0

kcell 应用

这一章讲 kcell 菜单：在 keelOS 上跑 Docker 应用。你想装的是 Jellyfin、Nextcloud 这样的应用，不是一台虚拟机，所以日常只要"选应用、填几项、点创建"，kcell 由 keel 来建。

1. kcell 和应用

• kcell 是 keelOS 上专门跑 Docker 的小虚拟机。卷（应用的数据）是主机存储池里的数据集，容器发布的端口在 kcell 自己的 LAN 地址上。
• 应用是 kcell 里的一个 compose 项目（一个或几个容器）。可以从模板建（一张表单，不用写 YAML），也可以自己写 compose 文件。
• 新建应用时，应用可以放进一台已有的 kcell，也可以让 keel 新建一台专门的 kcell 来放它。第一次什么都没有，直接新建应用就行，不用先建 kcell。

注意：kcell 要有存储池（见存储）。下载模板、拉镜像还需要 kcell 能上网，见 §9。

打开左边菜单的 kcell。页面上方是一张总卡片（标题 kcell，右边是 新建应用… 和 新建 kcell… 两个按钮），下面每台 kcell 一张卡片。

每张 kcell 卡片的第一行是名字、状态（运行、已停、已停（检查点）、失败）、LAN 地址，右边是 设置、开（运行中是 停、重启）和 删除。卡片里有两个标签：应用 和 镜像。

2. 新建应用

1. 点页面上方的 新建应用…（或某台 kcell 卡片里的 在这台 kcell 里新建应用…）。
2. 在 新建应用 对话框里选一个模板，或选 自定义 compose…（自己写 compose 文件，见 §8）。
3. 填表单。第一项是应用名，后面按模板不同：数据放哪里（挂载）、环境变量、要不要经前门打开、要不要用 keelAuth 登录。每个模板填什么见它自己的说明。
4. 选这个应用放在哪台 kcell：已有的某一台，或 新建 kcell（名字同应用）。选新建时，其余的（网络、地址、CPU、内存、Docker 盘、卷）keel 用缺省值，点 高级 可以改。
5. 点 创建（放进已有的 kcell 时是 保存并启动）。keel 建好 kcell、起来、拉镜像、启动应用，过程在 部署 对话框里显示。

内置模板有：Jellyfin、Emby、Plex、Navidrome、Audiobookshelf（媒体和音乐）、Nextcloud、Paperless-ngx、Immich、Vaultwarden、Syncthing（文件、文档、照片、密码）、Home Assistant、Uptime Kuma、Frigate、AdGuard Home、Pi-hole、qBittorrent、Open WebUI、Samba、前门，以及照片收件箱（photo-inbox）。更新的模板、新增的模板从市场装，见 §10。

模板列表里，本机没有、市场里有的模板是灰的，角上有 安装：点一下就只下载这一个模板（几 KB），装好后可以用。没有网络、读不到市场目录时只列本机已有的。

注意：要从外面访问的应用（Vaultwarden、Nextcloud、Paperless-ngx、Immich、前门）keel 一个应用给一台单独的 kcell（页面上写"……对外提供服务：keel 给它单独建一台 kcell"），不和别的应用放在一起；这样一个应用出问题，不会连累另一个。已有的 kcell 里已经有别的应用时，这类应用会被拒绝放进去，请选 新建 kcell。

3. 数据放在哪里：挂载

应用表单里的 挂载 列出这个应用要用的目录，每个目录有一个角色：配置、缓存、资料（媒体库、文档库这类用户自己的数据）。每个挂载可以选：

• 不挂载（可有可无的目录）；
• 这台 kcell 的卷：keel 自动建一个卷（显示为"卷 xxx（自动建）"），或 新建卷… 并起名字；
• 主机上别的 dataset：主机存储池里已有的数据集，作为 kcell 的一个卷挂进来；keel 不建也不删它。点 打开文件浏览 能看里面的文件；
• keelNAS 共享：挂一个 keelNAS 上的共享。keel 在 keelNAS 里没有账号，要填一个能读这个共享的 keelNAS 用户 和 密码，密码存在这个应用的 compose 文件里。keelNAS 见 NAS。

资料类的挂载可以勾 只读（比如 Jellyfin 只需要读媒体库）。

卷是新建的，会立刻加进运行中的 kcell，已经在跑的容器不动，不需要重启。一台升级前开机的老 kcell，第一次加卷要冷重启一次（页面会这样提示），之后就不用了。

如果应用的名字和以前删掉的应用相同，原来的卷还在，会接着用里面的旧数据，表单里会提示。想从头开始，先删掉应用时勾上 也删除它的卷，见 §7。

4. 内存检查

模板会声明应用大概需要多少内存。往一台 kcell 里加应用时，keel 把这台 kcell 已有应用的需求加起来：

• 内存够，表单里显示"应用需要 … / kcell 有 …"；
• 不够，会提示"请先在 kcell 的设置里把内存改到至少 …，再添加应用"，不让添加。到 设置 里把内存加大，再回来；或者选 新建 kcell。
• 新建 kcell 时，keel 按应用需要的内存给它定大小。

不要硬把内存压得比应用需要的小：容器会因内存不够被杀掉。

5. 核显转码和经前门打开

iGPU 转码：Jellyfin 等应用的表单里有 iGPU 转码 一项（主机的核显支持分出 VF 时才有）。勾上，这台 kcell 拿到主机核显的一个 VF，容器里有 /dev/dri。要注意：

• 有核显 VF 的 kcell，停 等于关机，不存检查点；容器会退出，下次开机时按重启策略重新起来。
• 加上或拿掉核显 VF 需要 kcell 冷重启一次才生效，保存时 keel 会重启它再启动应用。
• Jellyfin 里的转码要自己打开：控制台、播放、转码，硬件加速选 VA-API，设备 /dev/dri/renderD128，勾上硬件编码。

经前门打开（https）：对外的 web 应用可以经"前门"用 https 访问。前门本身是一个模板应用（前门，基于 Caddy），一台主机上只能装一个。

1. 先在某台 kcell 里装 前门 应用。可选填一个域名和邮箱（有域名和邮箱时用 Let's Encrypt）；不填就用前门自己的 CA，浏览器里装一次 http://<前门地址>/ca.crt。
2. 之后新建 Vaultwarden、Nextcloud、Paperless-ngx、Immich 时，表单里 经前门打开（https） 默认是勾上的，应用会得到一个 https 地址。
3. 勾上以后，应用本身只接受来自前门的连接，直接访问它的 LAN 地址会被防火墙拦下。

还没有前门时，表单里写着"这台主机还没有前门：在一台 kcell 里先装"前门"应用……"。

用 keelAuth 登录：有些模板有 用 keelAuth 登录 一项（主机上要有 keelAuth，见账号、令牌与权限）。勾上，keel 在 keelAuth 里为这个应用建一个登录客户端和两个组（应用名，以及"应用名-admins"），把地址、密钥和 CA 写进应用的配置。选 谁能用（keelAuth 的组），所选组里的人都能用；再由管理员把人加进"…-admins"成为应用的管理员。没有可用的 keelAuth 时这一项提示"这台主机没有可用的 keelAuth"。

注意：Vaultwarden 的网页端只在 https 下工作，所以用 keelAuth 登录要和 经前门打开 一起用。

6. 应用列表、快照和回到更新前

kcell 卡片的 应用 标签是应用列表，每行有应用名（点开能看它的容器和挂载）、容器数、端口，以及这些按钮：

• 更改：模板建的应用打开表单；手改过 compose 文件的应用打开 YAML 编辑器；
• 启动、停止、拉镜像：对应 docker compose up、down、pull，输出显示在对话框里；
• 快照、删除。

端口是链接，点它打开 http://<kcell 的 LAN 地址>:<端口>/。端口缺省只发布在 kcell 自己的 LAN 地址上，不在主机的地址上；要在主机地址上也有，到 kcell 的新建/设置里勾 也发布到主机地址。

快照

点应用的 快照，看到这个应用的快照列表：时间、原因（更新前、kcell 换系统前、每天、手动）、涉及的数据集。

• keel 在应用要更新之前自动拍一个：compose 文件改了、或拉了新镜像之后的下一次启动；kcell 换上新系统（keelOS 升级之后）之前，每个应用也拍一个。快照包括应用自己的配置类卷和 compose 文件。不包括 资料 类的库（媒体库之类）和主机上的数据集：那是你的数据，回滚不应该丢掉更新以后新加的东西。
• 每天（按 UTC 日期）另外拍一个，keel 配置 kcell_daily_snap=false 可以关掉。每个应用保留最近 5 个更新前快照、7 个每日快照。
• 这些快照有 已锁定 标记：在主机上用 zfs destroy 也删不掉，kcell 里的 root 更碰不到。
• 现在拍一个 手动拍。

回到更新前

应用更新坏了，在快照列表里点想回到的那一行的 回到更新前，确认。keel 先停应用，把它的卷和 compose 文件回滚到那个快照，再启动。回滚以后写进这些卷里的数据会丢失，比它新的快照也会删掉；过程显示在输出框里。

7. 删除应用和 kcell

删除应用：应用要先停止（容器数为 0），点 删除。对话框里 也删除它的卷 默认不勾：卷留着，以后再建同名应用会接着用里面的旧数据；勾上则数据一起删除，不能恢复。

删除 kcell：点卡片上的 删除。运行中的 kcell 要选 停止并删除（先正常关机）。卷也删除 默认不勾：卷和应用目录留下，挪到一个保留位置，以后新建应用时在"主机上别的 dataset"里能选回来；勾上则全部删除。

8. 自己写 compose

选 自定义 compose…，在编辑器里写 compose 文件（YAML），给它起个 应用名，点 保存 或 保存并启动。相对路径（./data）落在主机的 stacks/<应用名>/ 下；kcell 的卷在容器里是 /vols/<卷名>。

在你自己的电脑上也可以用 docker：kcell 的 设置（高级） 里加你的 SSH 公钥并冷重启这台 kcell，卡片上的 从你的电脑用 docker 就会给出一条可以复制的命令（docker context）。局域网上没有 2375/2376 端口，只有 SSH（只认密钥）。

镜像 标签列出这台 kcell 里的镜像（拉取…、清理没用的镜像）。镜像是容器运行时的底层文件，不是安装包：有容器在用的镜像不能删；应用升级后留下的旧版本没有容器用，可以清理。

9. 网络和防火墙

• 新建 kcell 时，如果主机上有多个网络，可以选 网络（LAN 网卡）。没有上联口的网络，拿不到地址，也拉不了镜像，列表里会标明。地址默认 DHCP，也可以选 固定，填 地址/前缀长度（如 192.168.1.20/24）和 网关。
• 模板自带 kcell 网卡的防火墙：入站只放模板声明的端口（比如 Vaultwarden 只放 tcp/80，经前门打开时只放前门的地址），出站缺省只放互联网和 DNS，局域网不通；用 keelAuth 登录的应用额外放行到 keelAuth。你不用配置。
• Jellyfin、Plex 这类要在局域网里被发现的媒体应用，和 Home Assistant、Uptime Kuma 这类要连局域网设备的应用，模板不设限制。
• 自己写 compose 建的 kcell 没有这些规则。

10. 更新模板

keelOS 自带上面那些基础模板。新增的、更新的模板在 市场 的 应用模板 里一个一个装，也可以在新建应用的模板列表里直接点灰色模板的 安装。装了的模板包只在比当前 keelOS 新的时候才会替换同名的内置模板；删掉包就回到内置的。已经建好的应用不受影响。

11. kcell 设置

点 kcell 卡片上的 设置，打开 设置（高级）：

• Docker 盘：只能扩大（扩大到）。会显示 Docker 已经用了多少；
• SSH 公钥：见 §8；
• CPU、内存、LAN 地址、备注、也发布到主机地址 等。每项旁边标明 立即生效 或 冷重启后生效；要冷重启的，保存后 keel 问你现在重启吗，重启时容器会退出，再按重启策略起来。

内存设得比应用需要的小，会提示"比应用需要的 … 少：容器会因内存不够被杀掉"。

开 / 停：停 会把 kcell 的内存存进检查点，容器不退出，下次 开 接着跑；有核显 VF 的 kcell 例外，见 §5。重启 会让容器退出再按重启策略起来。

12. 1.0 的限制

• 一台主机只能有一个前门。
• kcell 的 Docker 应用里的账号由应用自己管，keel 不管（除了用 keelAuth 登录的应用，keel 建组和客户端）。
• 热迁移存储池之后，新位置上的快照没有锁定标记。