Livebook 0.19.10 配置参数详解

目标：完整梳理 Livebook 0.19.10 的配置体系——它没有传统配置文件，全部配置通过 LIVEBOOK_* 环境变量在启动时注入。本文给出官方收录的全量参数表（默认值、取值约束）、七组核心参数的逐项详解与实测验证、面向 16GB 内存团队数据分析场景的生产配置模板。部署步骤见 《Livebook 0.19.10 Docker Compose 部署指南》，软件背景见 《Livebook 0.19.10 介绍与选型指南》。参数语义依据官方 README「Environment variables」章节（查询日期 2026-10-31），开关行为、长度校验、日志形态均在 0.19.10 实测环境（Docker Server 29.9.2 + Compose v5.6.1）验证，测试日期 2026-10-31。

一、环境信息

二、前置条件

1. 已按 《Livebook 0.19.10 Docker Compose 部署指南》 部署实例并可登录（演示口令 q1w2e3r4q1w2e3r4）；
2. 能查看启动日志（docker logs livebook-0.19.10）与重建服务（docker compose up -d）——这是参数生效验证的两条主路径；
3. 如需测试集群/分发参数，实例需注入 LIVEBOOK_NODE/LIVEBOOK_COOKIE（本文 §5.5）。

三、参数查看与修改方式

3.1 查看当前生效参数

docker exec livebook-0.19.10 env | grep LIVEBOOK

实测回显：

LIVEBOOK_PASSWORD=q1w2e3r4q1w2e3r4
LIVEBOOK_DATA_PATH=/data
LIVEBOOK_NODE=livebook@127.0.0.1
LIVEBOOK_COOKIE=livebook-cookie-2026
LIVEBOOK_IP=::
LIVEBOOK_HOME=/data

其中 LIVEBOOK_IP=:: 与 LIVEBOOK_HOME=/data 并非 compose 注入，而是官方镜像内置默认值（docker inspect 的 Config.Env 实测可见）。

3.2 修改方式：环境变量注入 + 重建

Livebook 参数在启动时读取，修改 = 改 compose 的 environment 后重建服务：

docker compose up -d

实测回显（有配置变化时触发重建）：

 Container livebook-0.19.10 Recreated
 Container livebook-0.19.10 Starting
 Container livebook-0.19.10 Started

3.3 生效验证：启动日志行

启动日志的 [Livebook] Application running at ... 行直接暴露端口与认证模式，是每个参数改动的第一验证点：

docker logs livebook-0.19.10 2>&1 | head -3

实测回显（密码认证模式）：

[Livebook] Application running at http://localhost:8080/

3.4 CLI 形态参数（escript 安装场景）

通过 mix escript.install hex livebook 直装时，可用 livebook server 的 CLI 参数替代部分环境变量（官方 README）：--cookie、--ip、--name、-p, --port 四项，分别对应 LIVEBOOK_COOKIE、LIVEBOOK_IP、LIVEBOOK_NODE、LIVEBOOK_PORT。环境变量优先在编排层管理，容器化部署统一走 environment 注入。

四、参数总览

官方 README 收录的全量 LIVEBOOK_* 变量（默认值为官方标注，查询日期 2026-10-31）：

另有 Erlang/Vm 层变量：ERL_AFLAGS/ERL_ZFLAGS 作用于 Livebook 与 notebook 运行时，ELIXIR_ERL_OPTIONS 仅作用于 Livebook 本体（不转发给运行时）。

💡 关键差异：与「配置文件 + 热加载」型软件不同，Livebook 所有参数都是启动期一次性读取（§3.2），改任何一项都要重建实例；同时配置持久化在 LIVEBOOK_DATA_PATH 的 livebook_config.v1.ets 中（UI 内改动）与环境变量并存，环境变量覆盖启动期行为。

五、核心参数分类详解

5.1 访问认证组（PASSWORD / TOKEN_ENABLED / IDENTITY_PROVIDER）

Livebook 提供两套内置认证，二选一：

• token 认证（默认）：不设 LIVEBOOK_PASSWORD 时启用，访问令牌随机生成并打印在启动日志，首访 URL 必须携带 ?token=。实测日志回显：

[Livebook] Application running at http://localhost:8080/?token=y3ccqyaz4zjazx36bodfgkn5n3rhyu7v

• 密码认证：设置 LIVEBOOK_PASSWORD 后启用（token 自动关闭），登录页为 /authenticate。实测日志回显（不再出现 token）：

[Livebook] Application running at http://localhost:8080/

长度强制校验实测（8 位密码直接拒绝启动）：

ERROR!!! [Livebook] cannot start Livebook because LIVEBOOK_PASSWORD must be at least 12 characters

• LIVEBOOK_TOKEN_ENABLED=false 可在未设密码时关闭 token 认证（官方语义：默认开启，除非已设密码）；
• LIVEBOOK_IDENTITY_PROVIDER 面向零信任网关部署，官方取值：basic_auth:<username>:<password>、cloudflare:<team-domain>、google_iap:<aud>、tailscale:<socket-path>、custom:<模块名>（官方 README，2026-10-31）。

生产建议：一律设强密码（≥12 位，本文演示取 q1w2e3r4q1w2e3r4），token 模式仅适合本机试用。

5.2 网络监听组（PORT / IP / IFRAME_PORT / BASE_URL_PATH）

• LIVEBOOK_PORT：Web 端口，默认 8080。实测设为 9090 后启动行同步变化：

[Livebook] Application running at http://localhost:9090/?token=lvpvkpwjr3ltasscrkdc7ephvanpgzu6

官方语义：设 0 则随机取端口，实测（未设密码故带 token）：

[Livebook] Application running at http://localhost:44517/?token=b4upvep5zq5hoq2qbhssad4xz2dedfe3

多实例共用同域同凭据时需同时固定 LIVEBOOK_SECRET_KEY_BASE（否则会话互不相认）。

• LIVEBOOK_IP：监听地址。直装默认 127.0.0.1（仅本机，官方安全设计）；官方镜像内置 ::（双栈任意地址），容器场景无需再改，实测 ss 同时出现 IPv4/IPv6 两条 LISTEN。
• LIVEBOOK_IFRAME_PORT：iframe 资源端口，默认 8081，仅无 TLS 场景相关；容器部署需要与 Web 端口一起映射（本文 8138:8081）。
• LIVEBOOK_BASE_URL_PATH：反代子路径挂载。实测设 /livebook 后，根路径请求被重定向到子路径登录页：

GET / -> 302 redirect=http://127.0.0.1:18082/livebook/authenticate

⚠️ 实测注意：子路径模式下直接探测 /livebook/、/livebook/public/health 在未配置反代的裸端口场景返回 404——该参数定位是「置于反向代理之后」的部署形态，反代需按前缀整段转发；上线路前务必按实际反代拓扑做端到端验证。

• LIVEBOOK_FORCE_SSL_HOST：设值后非 HTTPS 请求重定向到该主机（localhost 例外）；LIVEBOOK_PROXY_HEADERS 反代场景按需设 x-forwarded-for,x-forwarded-proto；LIVEBOOK_PUBLIC_BASE_URL_PATH 用于让 /public/* 静态路由绕开需认证的反代（官方语义）。

5.3 安全密钥组（SECRET_KEY_BASE）

会话与签名载荷的加密密钥，≥64 字符，官方默认每次启动随机。短值实测直接拒绝启动：

ERROR!!! [Livebook] cannot start Livebook because LIVEBOOK_SECRET_KEY_BASE must be at least 64 characters. Invoke `openssl rand -base64 48` to generate an appropriately long secret.

生成方式（官方建议命令）：

openssl rand -base64 48

生产建议：必须显式固定并纳入密钥管理（${LIVEBOOK_SECRET_KEY_BASE} 注入），否则每次重启全部登录会话失效；保持默认随机的唯一好处是「重启即全员下线」的应急语义。

5.4 数据存储组（DATA_PATH / HOME / APPS_PATH / AWS_CREDENTIALS）

• LIVEBOOK_DATA_PATH：内部配置/状态目录。官方启动检查不创建目录——v0.19.10 源码 lib/livebook/config.ex 的 writable_dir?/1 仅 File.stat 且要求目录已存在、权限 read_write（查询日期 2026-10-31）。实测指向不存在的 /data/.livebook-data 时无限崩溃重启：

ERROR!!! [Livebook] expected LIVEBOOK_DATA_PATH to be a writable directory: /data/.livebook-data

正确做法是直接指向挂载点 /data（官方 Dockerfile 模板同款做法）。落盘文件实测为 /data/livebook_config.v1.ets（配置持久化 ETS）。

• LIVEBOOK_HOME：笔记本默认目录，文件选择器与保存的根；镜像内置 /data。
• LIVEBOOK_APPS_PATH：应用化部署目录，设值后启动时自动把目录内 notebook 部署为 Apps；受保护应用默认收随机密码，可用 LIVEBOOK_APPS_PATH_PASSWORD 统一指定；LIVEBOOK_APPS_PATH_WARMUP=auto|manual 控制预热时机（manual 用于镜像构建期 RUN /app/bin/warmup_apps，官方语义）。
• LIVEBOOK_AWS_CREDENTIALS：开启后允许从环境变量/AWS 凭据链/EC2-ECS 元数据读取凭据，供 S3 文件系统配置使用；LIVEBOOK_CACERTFILE 为自签 CA 场景指定证书文件。

5.5 集群与运行时组（NODE / COOKIE / CLUSTER / DEFAULT_RUNTIME）

• LIVEBOOK_NODE：Erlang 长名节点名，必须 FQDN 或 IP（官方明确 Livebook 始终用 long names）；本文取 livebook@127.0.0.1。
• LIVEBOOK_COOKIE：分发 cookie，默认每次启动随机；多节点互联必须一致。本文取 livebook-cookie-2026。
• 两者设好后，释放运维命令族的可用性——实测远程取版本与节点名：

/app/bin/livebook rpc 'IO.puts("node=" <> to_string(node()))'

实测回显：

node=livebook@127.0.0.1

• LIVEBOOK_CLUSTER：多实例集群发现策略（官方 clustering 文档），配合 Kubernetes/平台发现使用；官方镜像启动脚本对 Fly.io/ECS 有 auto 加速路径。
• LIVEBOOK_DEFAULT_RUNTIME：notebook 未显式选运行时时的默认值，取 standalone（独立实例）/attached:NODE:COOKIE（接入既有节点）/embedded（嵌入宿主项目），默认 standalone。

5.6 日志组（LOG_LEVEL / LOG_FORMAT / LOG_METADATA）

• LIVEBOOK_LOG_LEVEL：默认 warning，可取 error/warning/notice/info/debug。实测设 info 后可见 Bandit/IframeEndpoint 启动信息级日志。
• LIVEBOOK_LOG_FORMAT=json：结构化日志，实测回显（每行一个 JSON 对象，节选两行）：

{"message":"    :alarm_handler: {:set, {:system_memory_high_watermark, []}}","time":"2026-10-31T03:08:23.568Z","metadata":{},"severity":"notice"}
{"message":"Running LivebookWeb.IframeEndpoint with Bandit 1.11.1 at :::8081 (http)","time":"2026-10-31T03:08:24.023Z","metadata":{},"severity":"info"}

接入日志采集系统（Loki/ELK）时推荐 json + info 组合。

• LIVEBOOK_LOG_METADATA：向日志追加元数据键，Livebook 专属键有 users（谁在执行）、session_mode（default/app）、code（被求值代码）、event（恒为 code.evaluate），默认仅含 request_id（官方语义）。

5.7 其他功能组（SHUTDOWN_ENABLED / APP_SERVICE / 链接策略 / 镜像源）

六、生产配置模板

适用场景：16GB 内存、NVMe SSD、团队内部数据分析与内部工具（Apps）部署，置于反向代理之后。compose 环境段模板（口令/密钥按演示约定给出，真实部署替换为强值）：

services:
  livebook:
    image: ghcr.io/livebook-dev/livebook:0.19.10
    restart: unless-stopped
    ports:
      - "8137:8080"
      - "8138:8081"
    environment:
      LIVEBOOK_PASSWORD: q1w2e3r4q1w2e3r4        # 登录口令（≥12 字符）
      LIVEBOOK_SECRET_KEY_BASE: ${LIVEBOOK_SECRET_KEY_BASE}   # 会话密钥（系统级密钥，注入方式见下）
      LIVEBOOK_DATA_PATH: /data                  # 内部配置目录（必须已存在）
      LIVEBOOK_HOME: /data                       # 笔记本目录（镜像内置，显式声明便于审计）
      LIVEBOOK_LOG_LEVEL: info                   # 运维期信息级日志
      LIVEBOOK_LOG_FORMAT: json                  # 供日志采集解析
      LIVEBOOK_PROXY_HEADERS: x-forwarded-for,x-forwarded-proto   # 反代透传头
      LIVEBOOK_NODE: livebook@127.0.0.1          # 分发节点名（运维命令用）
      LIVEBOOK_COOKIE: livebook-cookie-2026      # 分发 cookie
    volumes:
      - livebook-data:/data
volumes:
  livebook-data:

逐项要点：

0. 会话密钥属系统级真实密钥，不在文档落明文：在部署机执行 export LIVEBOOK_SECRET_KEY_BASE="$(openssl rand -base64 48)" 生成（≥64 字符），compose 会从宿主环境变量读取 ${LIVEBOOK_SECRET_KEY_BASE} 完成注入，并纳入密钥管理系统保管；

1. 密码 + 固定密钥是上反代前的底线（Livebook 可执行任意代码，官方安全章节定性）；

2. LIVEBOOK_DATA_PATH 与 LIVEBOOK_HOME 合一于 /data，备份 = 备份这一个卷；

3. LOG_FORMAT=json + LOG_LEVEL=info 为日志采集标配，排障期临时升 debug；

4. 单实例定位（官方 K8s 指南 replicas=1），扩协作用「多实例 + 每用户一实例」，不做纵向堆叠；

5. 公网暴露必须叠加反代 HTTPS（LIVEBOOK_FORCE_SSL_HOST 视拓扑启用）。

模板实测验证（等价配置的实例启动行 + 健康端点）：

[Livebook] Application running at http://localhost:8080/

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8137/public/health

实测回显：

200

七、常见问题

Q1：改了环境变量不生效？ Livebook 启动期读参，必须重建实例：docker compose up -d，观察输出出现 Recreated 行（实测回显见 §3.2）才算应用新值；仅 restart 不重建、配置不变时不会重读。

Q2：启动报 must be at least 12 characters？ LIVEBOOK_PASSWORD 不足 12 位（实测回显见 §5.1），加长即可；演示口令按惯例取 8 位口令翻倍。

Q3：启动报 expected LIVEBOOK_DATA_PATH to be a writable directory？ 该目录不存在——Livebook 不自动创建（根因见 §5.4）。改为挂载点 /data 或先建目录。

Q4：每次重启都要重新登录？ LIVEBOOK_SECRET_KEY_BASE 默认随机（官方语义），固定 64+ 位密钥即可（§5.3）。

Q5：多实例共用同域登录，会话互相踢？ 同域同凭据多实例必须给每个实例配同一个 LIVEBOOK_SECRET_KEY_BASE（官方 PORT 条目明确说明），否则 Cookie 签名各不相同。

Q6：反代后面登录后跳转异常/静态资源 404？ 按 LIVEBOOK_BASE_URL_PATH 整段前缀转发并透传 x-forwarded-*（§5.2），必要时为 /public/* 单独开白名单路由（LIVEBOOK_PUBLIC_BASE_URL_PATH）。

八、参考链接

1. 《Livebook 0.19.10 Docker Compose 部署指南》——部署与升级回滚全流程
2. 《Livebook 0.19.10 介绍与选型指南》——架构与选型背景
3. 官方 README「Environment variables」章节（全量参数语义来源）：https://github.com/livebook-dev/livebook （查询日期 2026-10-31）
4. 官方源码 lib/livebook/config.ex（启动校验逻辑，v0.19.10）：https://github.com/livebook-dev/livebook/blob/v0.19.10/lib/livebook/config.ex （查询日期 2026-10-31）
5. 官方 Docker 部署指南（模板与单实例定位）：https://github.com/livebook-dev/livebook/blob/v0.19.10/docs/deployment/docker.md （查询日期 2026-10-31）