JupyterLab 4.6.4 配置参数详解
JupyterLab 4.6.4 配置详解：两个配置文件的加载顺序、关键参数默认值与生产模板（监听、认证、内核回收、扩展策略、上传上限、日志排查）
JupyterLab 4.6.4 配置参数详解
目标：把 JupyterLab 4.6.4 的两个配置文件（
jupyter_server_config.py、jupyter_lab_config.py）讲透——配置从哪加载、优先级如何、每个关键参数的真实默认值与改动后果是什么，并给出一份可直接用于内网生产环境的配置模板。文中所有默认值均来自本机--help-all实查，生效值均来自--show-config实查。
一、环境信息
| 条目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS |
| Python | 3.12.16（/opt/jupyter/venv/bin/python） |
| JupyterLab | 4.6.4 |
| jupyter_server | 2.21.1 |
| 配置目录 | /etc/jupyter |
| 配置文件 | jupyter_server_config.py、jupyter_lab_config.py、jupyter_server_config.json |
| 数据目录 | /srv/jupyter |
| 服务监听 | 127.0.0.1:8888，base_url=/jupyter/ |
版本确认：
/opt/jupyter/venv/bin/jupyter --version
Selected Jupyter core packages...
jupyter_server : 2.21.1
jupyterlab : 4.6.4
jupyter_client : 8.10.0
jupyter_core : 5.9.1
traitlets : 5.16.1
💡 说明：JupyterLab 4.x 的配置体系分两层——服务端参数（
ServerApp.*）由jupyter_server定义，前端参数（LabApp.*）由jupyterlab扩展定义。两者写在不同的.py文件里，但最终合并到同一个进程的配置对象中。
二、前置条件
- 已完成 JupyterLab 4.6.4 安装，
/opt/jupyter/venv/bin/jupyter可执行； /etc/jupyter存在且属主为运行服务的系统用户（本例jupyter）；- 服务以 systemd 托管，改动配置后可
systemctl restart jupyter-lab； - 具备
sudo权限以便修改/etc/jupyter下的文件。
权限检查：
ls -l /etc/jupyter/
-rw------- 1 jupyter jupyter 162 Oct 27 17:41 jupyter_server_config.json
-rw-r----- 1 jupyter jupyter 1176 Oct 27 17:33 jupyter_lab_config.py
-rw-r----- 1 jupyter jupyter 74838 Oct 27 17:32 jupyter_server_config.py
⚠️ 注意：三个文件的属主必须一致且为服务运行用户。
jupyter_server_config.json权限应为600，因为它可能保存密码哈希。
三、配置文件的加载顺序与查看方式
3.1 加载路径
su - jupyter -c "JUPYTER_CONFIG_DIR=/etc/jupyter /opt/jupyter/venv/bin/jupyter --paths"
config:
/etc/jupyter
/opt/jupyter/venv/etc/jupyter
/usr/local/etc/jupyter
/etc/jupyter
data:
/home/jupyter/.local/share/jupyter
/opt/jupyter/venv/share/jupyter/labextensions
/usr/local/share/jupyter
/usr/share/jupyter
runtime:
/home/jupyter/.local/share/jupyter/runtime
config: 下列出的目录会按顺序被搜索，同名的 jupyter_server_config.py 若存在于多处会依次加载，后加载的覆盖先加载的。本文把全部配置集中在 /etc/jupyter，避免多目录叠加带来的不确定性。
3.2 查看真正生效的配置
su - jupyter -c "JUPYTER_CONFIG_DIR=/etc/jupyter /opt/jupyter/venv/bin/jupyter lab --show-config"
真实回显（节选）：
Loaded config files:
/etc/jupyter/jupyter_server_config.py
IdentityProvider
.token = ''
KernelSpecManager
.ensure_native_kernel = True
LabApp
.app_settings_dir = '/srv/jupyter/lab/settings'
.blocked_extensions_uris = ''
.collaborative = False
.extension_manager = 'pypi'
.news_url = ''
.workspaces_dir = '/srv/jupyter/lab/workspaces'
MappingKernelManager
.cull_connected = True
.cull_idle_timeout = 1800
.cull_interval = 300
PasswordIdentityProvider
.allow_password_change = False
.hashed_password = 'argon2:$argon2id$...'
.password_required = True
ServerApp
.allow_remote_access = False
.base_url = '/jupyter/'
.default_url = '/lab'
.file_url_prefix = '/lab/tree'
.ip = '127.0.0.1'
.log_level = 'INFO'
.max_body_size = 1073741824
.max_buffer_size = 1073741824
.open_browser = False
.port = 8888
.root_dir = '/srv/jupyter'
这是排查配置问题的第一手段：只认这里打印的值，不要靠肉眼检查 .py 文件。
3.3 查看默认值
/opt/jupyter/venv/bin/jupyter server --help-all | grep -A6 "^--ServerApp.max_body_size="
--ServerApp.max_body_size=<Int>
Sets the maximum allowed size of the client request body, specified in the
Content-Length request header field. If the size in a request exceeds the
configured value, a malformed HTTP message is returned to the client.
Note: max_body_size is applied even in streaming mode.
Default: 536870912
💡 说明：
--help-all的Default:行是判断「我到底改了什么」的基准。JupyterLab 的默认值随版本变化过（例如 4.x 的max_body_size已是 512 MB 而非更早的 100 MB），直接抄旧文档容易踩坑。
四、参数总览
下表列出生产环境最常调整的参数，默认值均取自 4.6.4 的 --help-all 实查结果。
| 所属类 | 参数 | 默认值 | 典型生产值 | 作用 |
|---|---|---|---|---|
| ServerApp | ip | localhost | 127.0.0.1 | 监听地址 |
| ServerApp | port | 8888 | 8888 | 监听端口 |
| ServerApp | base_url | / | /jupyter/ | URL 前缀 |
| ServerApp | allow_remote_access | False | False | Host 头校验 |
| ServerApp | root_dir | 启动目录 | /srv/jupyter | 文件根目录 |
| ServerApp | max_body_size | 536870912 | 1073741824 | 请求体上限 |
| ServerApp | max_buffer_size | 536870912 | 1073741824 | 内存缓冲上限 |
| ServerApp | open_browser | True | False | 启动时开浏览器 |
| ServerApp | log_level | INFO | INFO | 日志级别 |
| IdentityProvider | token | 自动生成 | '' | 一次性令牌 |
| PasswordIdentityProvider | hashed_password | 空 | argon2 哈希 | 登录密码 |
| PasswordIdentityProvider | password_required | True | True | 强制密码登录 |
| MappingKernelManager | cull_idle_timeout | 0 | 1800 | 空闲回收秒数 |
| MappingKernelManager | cull_interval | 300 | 300 | 扫描间隔 |
| MappingKernelManager | cull_connected | False | True | 连接中是否回收 |
| KernelSpecManager | ensure_native_kernel | True | True | 自动注册原生内核 |
| LabApp | extension_manager | pypi | pypi/readonly | 扩展管理策略 |
| LabApp | collaborative | False | False | 实时协作 |
| LabApp | app_settings_dir | <config>/lab/user-settings | /srv/jupyter/lab/settings | 用户设置目录 |
| LabApp | workspaces_dir | <config>/lab/workspaces | /srv/jupyter/lab/workspaces | 工作区目录 |
💡 技术拓展：Jupyter 服务端支持的认证方式不止「token/密码」一种，选型时按规模决定——
认证方式 配置入口 适用场景 一次性 token IdentityProvider.token临时验证、个人机器 固定密码 PasswordIdentityProvider.hashed_password小团队共用一台机器 反向代理头认证 自定义 Authenticator插件已有统一 SSO/网关 OAuth/OIDC 第三方 Authenticator 扩展 企业账号体系 JupyterHub 多用户 Hub 侧 Authenticator 数十人以上 本文采用「固定密码 + 反代」，理由是单机单服务、团队规模小，代价最低。
五、网络与访问控制参数
5.1 监听地址与端口
c.ServerApp.ip = "127.0.0.1"
c.ServerApp.port = 8888
ip设为127.0.0.1：只允许本机访问，外部必须经 Nginx；- 设为
0.0.0.0：直接对外监听，必须同时配置 TLS 与防火墙，否则密码在公网明文传输。
验证监听：
ss -ltnp | grep 8888
LISTEN 0 128 127.0.0.1:8888 0.0.0.0:* users:(("jupyter-lab",pid=5394,fd=6))
5.2 base_url 子路径
c.ServerApp.base_url = "/jupyter/"
改动后所有前端资源与 API 路径都会带 /jupyter/ 前缀。验证：
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" http://127.0.0.1:8888/jupyter/lab
302 http://127.0.0.1:8888/jupyter/login?next=%2Fjupyter%2Flab
若把 base_url 改成 /jupyter（不带尾斜杠），Jupyter 会自动补全，但 Nginx 的 location 必须同时是 /jupyter/，否则会出现静态资源 404。
5.3 Host 头校验
c.ServerApp.allow_remote_access = False
默认为 False，表示只接受 Host 头为 localhost、127.0.0.1 或服务器主机名的请求。通过 Nginx 反代时，proxy_set_header Host $host 传入的是真实域名/IP，若不在白名单会收到 403。
⚠️ 注意：若日志出现
Blocking request from unknown origin或 403，优先检查两处：allow_remote_access，以及是否需要配置c.ServerApp.allow_origin/c.ServerApp.base_url与反代一致。
5.4 root 运行限制
c.ServerApp.allow_root = False
默认拒绝以 root 身份启动。生产上应以专用用户运行（本例 jupyter），只有临时调试等场景才开 --allow-root。
六、身份认证参数
6.1 token 与密码的二选一
Jupyter 首次启动会自动生成一次性 token 并打印在日志里。长期使用有两种固化方式：
# 方式一：完全关闭 token，只用密码
c.IdentityProvider.token = ""
c.PasswordIdentityProvider.hashed_password = "argon2:$argon2id$..."
c.PasswordIdentityProvider.password_required = True
💡 说明：
IdentityProvider.token为空字符串表示「不使用 token」；留空（不写这一行）则会自动生成随机 token。二者语义不同，别混淆。
6.2 生成哈希的两种途径
途径一，命令行交互写入 JSON：
JUPYTER_CONFIG_DIR=/etc/jupyter /opt/jupyter/venv/bin/jupyter server password
真实回显：
Enter password:
Verify password:
[JupyterPasswordApp] Wrote hashed password to /etc/jupyter/jupyter_server_config.json
生成的文件内容：
{
"IdentityProvider": {
"hashed_password": "argon2:$argon2id$v=19$m=10240,t=10,p=8$Zy12uCaMy3s6MTuTOn/RIw$vvKPbSFrE9pj7L+wO35E/jrcaVLiDTevmrYtI1/DnIY"
}
}
途径二，直接算哈希后写进 .py：
/opt/jupyter/venv/bin/python -c "from jupyter_server.auth.security import passwd; print(passwd('q1w2e3r4'))"
argon2:$argon2id$v=19$m=10240,t=10,p=8$OtWoK5KRF4UNWbUgyn43nQ$yvbw/TjCn79WWMn83z/2mJFotHdXNq1zLpLBZde0llg
⚠️ 注意：用 root 执行
jupyter server password会把 JSON 写成 root 属主 600 权限，jupyter用户的服务读不到并直接启动失败（PermissionError）。务必chown jupyter:jupyter后重启；这一点在安装篇的常见问题里有完整排障记录。
6.3 登录验证
curl -s -o /dev/null -w "%{http_code}\n" -X POST -d "password=q1w2e3r4" \
http://127.0.0.1:8888/jupyter/login
403
直接 POST 会因缺少 XSRF 令牌被拒（403 是保护机制，不是配置错误）。带 _xsrf 的完整流程与回显见 《JupyterLab 4.6.4 Ubuntu 22.04 安装指南》第七章。
七、目录与存储参数
7.1 root_dir
c.ServerApp.root_dir = "/srv/jupyter"
这是文件浏览器能看到的根目录，也是 Notebook 默认保存位置。Jupyter 不会把访问限制在 root_dir 内的符号链接之外，因此不要把 / 或 /home 设为根目录。
验证当前根目录：
curl -s -b /tmp/ck.txt http://127.0.0.1:8888/jupyter/api/contents
[{"name": "demo-executed.ipynb", "path": "demo-executed.ipynb", "type": "notebook", ...}, {"name": "demo-quzuo.ipynb", ...}]
返回的 path 是相对 root_dir 的路径，不带 /srv/jupyter 前缀即证明生效。
7.2 内容管理器
c.ServerApp.contents_manager_class 决定文件如何读写，默认 FileContentsManager（本地磁盘）。可选实现包括对象存储版、只读版等，切换前需确认对应插件已安装。
💡 技术拓展：不同
ContentsManager的取舍——
实现 存储位置 适用场景 FileContentsManager 本地磁盘 单机默认，性能最好 只读 ContentsManager 本地磁盘 发布只读示例/教程 对象存储扩展 S3/MinIO 等 多实例共享数据 本文使用默认实现，数据落
/srv/jupyter，由系统备份策略统一保护。
7.3 用户设置与工作区
c.LabApp.app_settings_dir = "/srv/jupyter/lab/settings"
c.LabApp.workspaces_dir = "/srv/jupyter/lab/workspaces"
默认值分别在 <config_dir>/lab/user-settings 与 <config_dir>/lab/workspaces，即 /etc/jupyter/lab/ 下。改到数据目录的好处是：备份 /srv/jupyter 时把主题、快捷键、窗口布局一起带走，重装后可直接恢复。
⚠️ 注意：这两个目录必须对运行用户可写，否则前端保存设置时报 500。初始化：
mkdir -p /srv/jupyter/lab/settings /srv/jupyter/lab/workspaces
chown -R jupyter:jupyter /srv/jupyter/lab
八、内核管理参数
8.1 内核规格自动注册
c.KernelSpecManager.ensure_native_kernel = True
默认即为 True：当没有注册任何 Python kernelspec、但 ipykernel 可用时，自动补一个 python3。查看现有内核：
su - jupyter -c "JUPYTER_CONFIG_DIR=/etc/jupyter /opt/jupyter/venv/bin/jupyter kernelspec list"
Available kernels:
python3 /opt/jupyter/venv/share/jupyter/kernels/python3
如需限制可用内核（例如只允许 python3，不允许用户自装的内核），使用：
c.KernelSpecManager.allowed_kernelspecs = {"python3"}
8.2 空闲内核回收
c.MappingKernelManager.cull_idle_timeout = 1800
c.MappingKernelManager.cull_interval = 300
c.MappingKernelManager.cull_connected = True
三个参数的关系：
| 参数 | 默认值 | 本例 | 含义 |
|---|---|---|---|
cull_idle_timeout | 0（禁用） | 1800 | 内核空闲超过 30 分钟即回收 |
cull_interval | 300 | 300 | 每 5 分钟扫描一次 |
cull_connected | False | True | 即使浏览器仍连接也回收 |
改动效果验证：重启服务后，在界面打开 Notebook 并保持空闲超过 30 分钟，内核会被自动关闭；服务端日志出现内核关闭记录，/jupyter/api/status 的 kernels 计数回落。
⚠️ 注意：
cull_connected=True意味着用户开着页面但长时间不操作也会丢内核状态（未保存的运行结果会消失）。教学场景建议保持False，只回收「已断开连接」的内核。
8.3 IOPub 速率限制
大量输出（如循环打印）默认会被限流，相关参数在 ZMQChannelsWebsocketConnection 下：
| 参数 | 默认值 | 作用 |
|---|---|---|
iopub_data_rate_limit | 1000000 | 每秒数据字节数上限 |
iopub_msg_rate_limit | 1000 | 每秒消息条数上限 |
limit_rate | True | 是否启用限流 |
出现 IOPub data rate exceeded 报错时，按需调大前两项，或在 Notebook 里减少逐行打印。
九、扩展与前端参数
9.1 扩展管理策略
c.LabApp.extension_manager = "pypi"
pypi：界面上可直接搜索并安装 PyPI 上的预构建扩展（默认）；readonly：只展示已安装扩展，禁止在线安装——内网生产推荐。
9.2 扩展黑白名单
c.LabApp.blocked_extensions_uris = ""
c.LabApp.allowed_extensions_uris = ""
两者都留空表示不启用名单。启用白名单时填写扩展元数据的 JSON 地址（逗号分隔），只有白名单内的扩展才会被加载；黑白名单互斥，同时设置时以白名单为准。
9.3 实时协作与新闻链接
c.LabApp.collaborative = False
c.LabApp.news_url = ""
collaborative 需要额外的文档协作服务支撑，单机部署保持 False 可省去一组常驻进程；news_url 置空可避免内网页面加载外网资源。
9.4 扩展生效验证
/opt/jupyter/venv/bin/jupyter labextension list
JupyterLab v4.6.4
/opt/jupyter/venv/share/jupyter/labextensions
jupyterlab-execute-time v3.3.0 enabled OK (python, jupyterlab_execute_time)
jupyterlab_pygments v0.3.0 enabled OK (python, jupyterlab_pygments)
enabled OK 是扩展可用状态；若显示 disabled，用 jupyter labextension disable <name> / enable <name> 切换。
十、上传与请求体大小参数
10.1 服务端上限
c.ServerApp.max_body_size = 1073741824
c.ServerApp.max_buffer_size = 1073741824
默认值均为 536870912（512 MB）。max_body_size 限制单个请求体，max_buffer_size 限制 Tornado 的内存缓冲；上传大于 512 MB 的数据集时两者都要调大，且必须小于服务器可用内存。
10.2 反向代理上限
Nginx 侧还要同步设置，否则请求在代理层就被拒：
client_max_body_size 1024m;
⚠️ 注意：两层上限的生效顺序是「Nginx 先拦」。只改 Jupyter 不改 Nginx，浏览器会收到
413 Request Entity Too Large，而 Jupyter 日志里什么都看不到——这是排查上传问题时最容易走错的一步。
十一、日志与可观测参数
11.1 日志级别
c.ServerApp.log_level = "INFO"
可选 DEBUG / INFO / WARN / ERROR。排障时临时改 DEBUG，用 journalctl -u jupyter-lab -f 观察后改回。
11.2 通过 journald 查看
journalctl -u jupyter-lab --no-pager -n 8
Oct 27 17:41:01 lab-quzuo jupyter[8283]: [I ... ServerApp] Serving notebooks from local directory: /srv/jupyter
Oct 27 17:41:01 lab-quzuo jupyter[8283]: [I ... ServerApp] Jupyter Server 2.21.1 is running at:
Oct 27 17:41:01 lab-quzuo jupyter[8283]: [I ... ServerApp] http://127.0.0.1:8888/jupyter/lab
Oct 27 17:41:06 lab-quzuo jupyter[8283]: [I ... LabApp] 302 GET /jupyter/lab (@127.0.0.1) 0.46ms
Oct 27 17:41:06 lab-quzuo jupyter[8283]: [W ... ServerApp] wrote error: 'Forbidden'
Oct 27 17:41:06 lab-quzuo jupyter[8283]: [W ... ServerApp] 403 GET /jupyter/api/status (@127.0.0.1) 0.49ms
日志中的 302 是登录跳转、403 是未认证访问 API，属正常访问模式；真正异常关注 [E] 级别与 Traceback。
11.3 端口占用提示
若日志出现：
[W ServerApp] The port 8888 is already in use, trying another port.
说明已有一个实例在跑（常见于「systemd 已启动 + 手工又启动一次」）。此时新实例会退到 8889，反代会指向错误端口。处理：systemctl status jupyter-lab 确认服务状态，手工进程用 pkill -f "jupyter-lab" 结束后再重启服务。
十二、生产配置模板
适用场景：单机 8 核 / 32 GB 内存 / SSD，10 人以内数据团队，内网访问，Nginx 反代到 /jupyter/。
/etc/jupyter/jupyter_server_config.py 追加段：
c.ServerApp.ip = "127.0.0.1"
c.ServerApp.port = 8888
c.ServerApp.base_url = "/jupyter/"
c.ServerApp.open_browser = False
c.ServerApp.allow_remote_access = False
c.ServerApp.allow_root = False
c.ServerApp.root_dir = "/srv/jupyter"
c.ServerApp.max_body_size = 1073741824
c.ServerApp.max_buffer_size = 1073741824
c.ServerApp.log_level = "INFO"
c.IdentityProvider.token = ""
c.PasswordIdentityProvider.hashed_password = "argon2:$argon2id$v=19$m=10240,t=10,p=8$OtWoK5KRF4UNWbUgyn43nQ$yvbw/TjCn79WWMn83z/2mJFotHdXNq1zLpLBZde0llg"
c.PasswordIdentityProvider.password_required = True
c.PasswordIdentityProvider.allow_password_change = False
c.MappingKernelManager.cull_idle_timeout = 1800
c.MappingKernelManager.cull_interval = 300
c.MappingKernelManager.cull_connected = False
c.KernelSpecManager.ensure_native_kernel = True
/etc/jupyter/jupyter_lab_config.py：
c = get_config() # noqa
c.LabApp.app_settings_dir = "/srv/jupyter/lab/settings"
c.LabApp.workspaces_dir = "/srv/jupyter/lab/workspaces"
c.LabApp.extension_manager = "readonly"
c.LabApp.collaborative = False
c.LabApp.news_url = ""
c.LabApp.blocked_extensions_uris = ""
c.LabApp.allowed_extensions_uris = ""
模板取舍说明：cull_connected 取 False（教学中避免误杀正在讲解的会话）；extension_manager 取 readonly（内网不允许用户自行装包）；上传上限 1 GB 与 Nginx client_max_body_size 1024m 对齐。
应用模板：
systemctl restart jupyter-lab
systemctl is-active jupyter-lab
active
十三、常见问题
Q1：改了配置但没生效
先看 jupyter lab --show-config 的 Loaded config files 是否包含你改的那个文件。常见原因是配置写进了 ~/.jupyter/jupyter_server_config.py，而服务用 JUPYTER_CONFIG_DIR=/etc/jupyter 启动，二者不是同一份。
Q2：配置项名写错，服务启动即退出
现象：
Bad config encountered during initialization: Trait, expose_app_url, not found.
expose_app_url 在 4.6.4 中已不存在。用 jupyter lab --help-all | grep -i 关键字 确认参数名，再写入配置。
Q3：base_url 与 Nginx 路径不一致导致静态资源 404
base_url=/jupyter/ 必须与 location /jupyter/ 完全对应（含尾部斜杠）。改完两边后 nginx -t && systemctl reload nginx && systemctl restart jupyter-lab。
Q4：密码改了但登录还是旧密码
同时存在 .py 里的 hashed_password 与 .json 里的 hashed_password 时，后加载者生效。统一做法是只保留一处：要么删掉 JSON 只改 .py，要么只跑一次 jupyter server password 并删除 .py 中的哈希行。
Q5：内核无法启动，提示 No such kernel named python3
jupyter kernelspec list
若为空，说明 KernelSpecManager.ensure_native_kernel 被设为 False 或 ipykernel 丢失。恢复：
/opt/jupyter/venv/bin/pip install ipykernel
/opt/jupyter/venv/bin/python -m ipykernel install --prefix=/opt/jupyter/venv
systemctl restart jupyter-lab
十四、参考链接
- Jupyter Server 配置项全表：https://jupyter-server.readthedocs.io/en/latest/developers/config.html
- Jupyter Server 安全与认证：https://jupyter-server.readthedocs.io/en/latest/operators/security.html
- JupyterLab 前端设置与扩展：https://jupyterlab.readthedocs.io/en/stable/user/extensions.html
- 同系列：《JupyterLab 4.6.4 Ubuntu 22.04 安装指南》、《JupyterLab 4.6.4 常用 CLI 与运维命令详解》