Docker 部署

Kiln 提供三个 Docker 镜像版本，它们使用相同的配置模型和原生媒体模块。选择时只需考虑两点：是否需要 FFmpeg 兼容回退，以及是否需要数据库和管理控制台。

三个变体

latest 是 full 的别名。三个变体都以非 root 的 uid/gid 999 运行，默认监听 8080，入口命令固定为 -config /etc/kiln/kiln.toml，所以只要把配置挂到这个路径就不需要再传任何参数。

lite 不创建 SQLite，公开接口只有 /healthz、/readyz、/v1/auth/login、/v1/playlist.m3u 和 /v1/play/*。配置里出现 auto 或 ffmpeg packager、EPG、OTLP、pprof 时，进程会在启动时直接拒绝而不是静默忽略。变体之间的能力差异见 镜像变体对比。

拉取镜像

镜像发布在 GitHub Container Registry：

docker pull ghcr.io/babywbx/kiln:lite     # 无状态低内存变体
docker pull ghcr.io/babywbx/kiln:core     # 原生 packager，不含 ffmpeg
docker pull ghcr.io/babywbx/kiln:latest   # full，内置 ffmpeg

正式版本会同时推出精确版本号与浮动标签：

预发布版本只推出带完整版本号的那一个标签，不会移动 lite、core、latest 以及主次版本标签。core 覆盖 linux/amd64、linux/arm64、linux/arm/v7 与 linux/arm/v6，lite 与 full 覆盖 linux/amd64 与 linux/arm64。三个变体在发布时都会生成构建溯源证明并推送到镜像仓库。

最小运行命令

准备两个文件：一份 kiln.toml 和一份 kiln.keys。仓库里的 deploy/docker/kiln.docker.toml.example 已经按镜像的路径约定写好，data_dir 指向 /var/lib/kiln/data，keys_file 指向 /etc/kiln/kiln.keys，复制过来改上游和账号即可。

docker run --rm -p 8080:8080 \
  -v "$PWD/kiln.toml:/etc/kiln/kiln.toml:ro" \
  -v "$PWD/kiln.keys:/etc/kiln/kiln.keys:ro" \
  -v kiln-data:/var/lib/kiln/data \
  ghcr.io/babywbx/kiln:core

lite 面向固定配置的低资源播放节点，可以完全只读运行：

docker run --rm -p 8080:8080 --read-only \
  --cap-drop=ALL --security-opt=no-new-privileges \
  -v "$PWD/lite.toml:/etc/kiln/kiln.toml:ro" \
  -v "$PWD/kiln.keys:/etc/kiln/kiln.keys:ro" \
  -v kiln-lite-data:/var/lib/kiln \
  ghcr.io/babywbx/kiln:lite

deploy/docker/lite.docker.toml.example 是对应的最小配置样板。

Compose 模板

deploy/docker/compose.example.yaml 是可以直接改的起点。它默认从仓库源码构建 full 目标；使用已发布镜像时删掉 build 段，把 image 换成 ghcr.io/babywbx/kiln:core 即可。

services:
  kiln:
    image: ghcr.io/babywbx/kiln:core
    container_name: kiln
    ports:
      - "8080:8080"
    environment:
      KILN_PUBLIC_BASE_URL: "http://your-host:8080"
      KILN_LOG_FORMAT: "text"
      KILN_LOG_COLOR: "never"
    volumes:
      - ./kiln.toml:/etc/kiln/kiln.toml:ro
      - ./kiln.keys:/etc/kiln/kiln.keys:ro
      - kiln-data:/var/lib/kiln/data
    restart: unless-stopped

volumes:
  kiln-data:

几处值得留意：日志颜色设为 never，docker logs 里就不会混入 ANSI 转义；KILN_PUBLIC_BASE_URL 决定播放列表里写出去的地址，容器端口映射与对外域名不一致时必须设置；上游如果是同一个 Compose 网络里的另一个服务，把 base_url 写成 http://service-name:port 并让两者共享网络即可。

健康检查

/healthz 与 /readyz 都不需要凭据。/healthz 表示进程活着，/readyz 会额外检查兼容引擎的可用性，只有当配置里存在落到 ffmpeg 引擎的 DASH 频道而 ffmpeg 不可用时才返回 503。

三个镜像都自带 HEALTHCHECK：间隔 30 秒、超时 3 秒、启动宽限 10 秒、连续 3 次失败判定为 unhealthy。core 与 full 用 wget 探测 /healthz；lite 基于 scratch，没有任何外部命令，改用二进制自带的 -healthcheck 子命令完成同样的探测。这个子命令也可以在容器外单独使用：

docker exec kiln /usr/local/bin/kiln -healthcheck http://127.0.0.1:8080/healthz

容器内的资源自适应

server.resource_mode 默认为 auto。进程启动时会探测 cgroup 里的实际内存与 CPU 限制，据此收紧 Go 软内存目标、分片内存预算、单段上限与流水线并发。探测覆盖 cgroup v1 与 v2、嵌套 cgroup、父级继承的限制以及小数 CPU quota，也就是说 docker run --cpus 与 --memory 会被真实读到。

资源自适应只会降低限制，不会提高配置中已经较低的值。启动日志会显示探测结果、当前档位和全部预算，便于确认容器是否使用了预期档位。

# 复现低资源策略
docker run --rm --cpus=1 --memory=192m --memory-swap=192m \
  -v "$PWD/resource-smoke.toml:/etc/kiln/kiln.toml:ro" \
  ghcr.io/babywbx/kiln:core

宿主机探测不准时，用 KILN_RESOURCE_MEMORY_MB 与 KILN_RESOURCE_CPUS 覆盖探测结果；完全退出自适应用 resource_mode = "performance"。档位表与调优建议见 运维与调优。

出站代理

Kiln 不会改写线路里的代理地址，容器里填的地址必须从容器内部连得上。代理在宿主机上时用 host.docker.internal，并给容器加 extra_hosts 映射；代理是同一个 Docker 网络里的另一个容器时直接用服务名。两种拓扑的完整配置见 出站代理。

[egress].docker_proxy_host 是另一回事：它只在 [ffmpeg].mode = "docker" 时生效，告诉 Kiln 拉起的 ffmpeg 子容器怎么回连 Kiln 进程自己，与线路地址无关。默认值 host.docker.internal 由 Kiln 在创建子容器时自动映射到网关。

数据持久化

data_dir 是唯一需要持久化的目录，镜像里默认是 /var/lib/kiln/data。core 与 full 在其中放 SQLite 数据库 kiln.db、自动生成的会话密钥 auth/ed25519.pem，以及启用 EPG 缓存时的缓存目录。挂载点必须对 uid/gid 999 可写，否则首次启动会失败。

lite 不创建数据库，data_dir 只存自动生成的登录密钥和临时媒体文件；配合 --read-only 使用时，把可写卷挂在 /var/lib/kiln 上。

挂进容器的 kiln.toml 与 kiln.keys 建议一律加 :ro。密钥文件在启动时一次性完整校验，修改后需要重启容器才会生效。