JupyterLab 4.6.4 常用 CLI 与运维命令详解
JupyterLab 4.6.4 运维命令实测：版本与路径查询、服务启停、build/clean、workspace、server/kernelspec/labextension 管理、密码与日志排障、nbconvert 批量执行
JupyterLab 4.6.4 常用 CLI 与运维命令详解
目标：把 JupyterLab 4.6.4 日常运维真正会用到的命令行工具讲清楚——哪些命令查版本与路径、哪些命令管服务与实例、哪些命令管内核与扩展、密码和日志出问题时按什么顺序排查。文中每一条命令都在 Ubuntu 22.04.5 LTS 的实际部署环境执行，输出为原样回显；仅个别无法在不破坏服务的前提下执行的命令（如停止实例）标注为「预期结果」。
一、环境信息
| 条目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS |
| Python | 3.12.16（/opt/jupyter/venv/bin/python） |
| JupyterLab | 4.6.4 |
| jupyter_server | 2.21.1 |
| 命令行入口 | /opt/jupyter/venv/bin/jupyter |
| 配置目录 | /etc/jupyter（JUPYTER_CONFIG_DIR） |
| 数据目录 | /srv/jupyter（root_dir） |
| 服务监听 | 127.0.0.1:8888，base_url=/jupyter/ |
| systemd 单元 | jupyter-lab.service，运行用户 jupyter |
| Nginx 入口 | 80 端口，路径 /jupyter/ |
为了不让每条命令都写一长串绝对路径，下文默认先激活环境：
export PATH=/opt/jupyter/venv/bin:$PATH
export JUPYTER_CONFIG_DIR=/etc/jupyter
💡 说明：
JUPYTER_CONFIG_DIR必须与服务启动时一致，否则命令行工具读到的是~/.jupyter，会出现「配置文件明明改了、命令却看不到」的假象。systemd 单元里已经用Environment=固定了该变量，见 《JupyterLab 4.6.4 Ubuntu 22.04 安装指南》第五章。
二、命令族总览
JupyterLab 的命令行不是单一大命令，而是「一个全局入口 + 若干子命令组」。先记住职责边界，排障时才不会找错工具：
| 命令 | 职责 | 典型用途 |
|---|---|---|
jupyter | 全局入口 | 查版本、查路径、查配置目录 |
jupyter lab | 启动 Lab 服务、管理前端应用 | 前台启动、build、clean、path、workspace |
jupyter server | 管理服务端实例与扩展 | list、stop、password、extension |
jupyter kernelspec | 管理内核规格 | 列出、安装、删除内核 |
jupyter labextension | 管理前端扩展 | 列出、禁用、启用、加锁 |
jupyter nbconvert | Notebook 转换与批量执行 | 无界面跑批、导出 HTML |
systemctl / journalctl | 托管与日志 | 启停服务、看日志 |
jupyter lab --help 的真实回显（节选）：
JupyterLab - An extensible computational environment for Jupyter.
This launches a Tornado based HTML Server that serves up an HTML5/Javascript
JupyterLab client.
...
Subcommands
===========
Subcommands are launched as `lab cmd [args]`. For information on using
subcommand 'cmd', do: `lab cmd -h`.
build
clean
path
paths
jupyter server --help 的真实回显（节选）：
The Jupyter Server.
This launches a Tornado-based Jupyter Server.
Subcommands
===========
Subcommands are launched as `jupyter-server cmd [args]`. For information on
using subcommand 'cmd', do: `jupyter-server cmd -h`.
list
List currently running Jupyter servers.
stop
Stop currently running Jupyter server for a given port
password
Set a password for the Jupyter server.
extension
Work with Jupyter server extensions
⚠️ 注意：
jupyter labextension管的是前端插件，jupyter server extension管的是服务端扩展（如jupyter_lsp、jupyter_server_terminals）。两者容易混淆：装了jupyterlab-execute-time属于前者，装了jupyter-lsp属于后者。
三、前置条件
- JupyterLab 4.6.4 已安装在
/opt/jupyter/venv，jupyter可执行； - 服务由 systemd 托管，单元名
jupyter-lab； - 当前用户具备读取
/etc/jupyter与执行systemctl的权限（运维操作建议sudo）； - 已知服务监听
127.0.0.1:8888、子路径/jupyter/。
先确认命令来自正确的虚拟环境，避免误用系统级 jupyter：
which jupyter
jupyter --version
/opt/jupyter/venv/bin/jupyter
Selected Jupyter core packages...
IPython : 9.17.1
ipykernel : 7.4.0
ipywidgets : not installed
jupyter_client : 8.10.0
jupyter_core : 5.9.1
jupyter_server : 2.21.1
jupyterlab : 4.6.4
nbclient : 0.11.0
nbconvert : 7.17.2
nbformat : 5.11.1
notebook : not installed
qtconsole : not installed
traitlets : 5.16.1
这里有两个信息值得记住：notebook : not installed 说明只装了 Lab、没装经典 Notebook 外壳；jupyter_server : 2.21.1 是 Lab 4.x 的运行底座，二者版本必须匹配。
四、全局查询：jupyter 主命令
4.1 版本与组件清单
jupyter --version
jupyter lab --version
4.6.4
jupyter --version 打印全部核心包，jupyter lab --version 只打印 Lab 自身版本。升级前后各跑一次，确认 jupyterlab 与 jupyter_server 同步变化。
4.2 路径查询
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: 是配置文件搜索路径，data: 是扩展与内核的安装路径，runtime: 存放连接文件（*.json）与进程信息。排查「配置读的是哪一份」看第一段，排查「扩展装到哪去了」看第二段。
4.3 单项目录查询
jupyter --config-dir
jupyter --data-dir
/etc/jupyter
/home/jupyter/.local/share/jupyter
💡 技术拓展：Jupyter 的目录优先级是「用户级 > 环境级 > 系统级」。
/etc/jupyter属于系统级，/opt/jupyter/venv/etc/jupyter属于环境级，~/.jupyter属于用户级。同名配置文件会按--paths的顺序全部加载并后者覆盖前者，所以多份配置叠加时，用jupyter lab --show-config看最终生效值最可靠。
五、服务启停：jupyter lab 与 systemd
5.1 前台启动（调试用）
jupyter lab --no-browser --ip=127.0.0.1 --port=8888 --base-url=/jupyter/
前台启动的日志与 systemd 托管时一致，关键三行：
[I ... ServerApp] Serving notebooks from local directory: /srv/jupyter
[I ... ServerApp] Jupyter Server 2.21.1 is running at:
[I ... ServerApp] http://127.0.0.1:8888/jupyter/lab
前台模式的用途只有一个：临时验证参数。生产环境不要长期前台运行——终端一断，服务与所有内核一起消失。
5.2 常用启动参数
| 参数 | 作用 | 本环境取值 |
|---|---|---|
--ip | 监听地址 | 127.0.0.1 |
--port | 监听端口 | 8888 |
--base-url | URL 前缀 | /jupyter/ |
--no-browser | 不尝试打开浏览器 | 始终加 |
--ServerApp.root_dir | 文件根目录 | /srv/jupyter |
--allow-root | 允许 root 运行 | 默认不加 |
--debug | 日志级别 DEBUG | 排障时临时加 |
--generate-config | 生成默认配置文件 | 首次安装时用 |
--show-config | 打印生效配置 | 排障必用 |
5.3 systemd 托管
sudo systemctl start jupyter-lab
sudo systemctl stop jupyter-lab
sudo systemctl restart jupyter-lab
sudo systemctl status jupyter-lab --no-pager
● jupyter-lab.service - JupyterLab Server
Loaded: loaded (/etc/systemd/system/jupyter-lab.service; enabled; vendor preset: enabled)
Active: active (running) since ...
Main PID: 8920 (jupyter-lab)
systemctl restart 会同时终止所有内核进程，正在运行的计算会丢失。升级或改配置前先通知使用者保存。
5.4 状态判定
systemctl is-active jupyter-lab
systemctl is-enabled jupyter-lab
active
enabled
active 只代表进程活着，不代表能访问；真正可用与否用第十三章的健康检查确认。
六、目录定位：jupyter lab path
jupyter lab path
Application directory: /opt/jupyter/venv/share/jupyter/lab
User Settings directory: /etc/jupyter/lab/user-settings
Workspaces directory: /etc/jupyter/lab/workspaces
三行分别对应：前端静态资源目录、用户设置（主题/快捷键）目录、工作区目录。注意这里的 Settings 与 Workspaces 仍是 --paths 推导出的默认位置；本环境在 jupyter_lab_config.py 中把二者改到了 /srv/jupyter/lab/ 下，因此 jupyter lab path 显示的是「未读取 LabApp 覆盖项的默认值」，实际生效值以 jupyter lab --show-config 为准：
jupyter lab --show-config | grep -A6 "^LabApp"
LabApp
.app_settings_dir = '/srv/jupyter/lab/settings'
.blocked_extensions_uris = ''
.collaborative = False
.extension_manager = 'pypi'
.news_url = ''
.workspaces_dir = '/srv/jupyter/lab/workspaces'
⚠️ 注意：这是一个非常容易误判的点——
jupyter lab path与--show-config不一致时，以--show-config为准。两者差异来自「是否加载了 LabApp 的配置项」。
七、前端构建与清理：jupyter lab build / clean
7.1 build 的适用边界
JupyterLab 4.x 的扩展以「预构建」形式随 pip 包分发，常规安装不需要 jupyter lab build。只有源码安装（pip install -e .）或手工改前端资源时才需要重建：
jupyter lab build
缺少构建工具链时会直接失败，真实报错：
ValueError: Please install Node.js and npm
装好 Node.js 22 后仍可能遇到：
permission denied: rspack
原因是构建脚本调用 staging/node_modules/.bin 下的 rspack 时，该目录不在 PATH 中。补上后构建通过：
export PATH=/opt/jupyter/venv/share/jupyter/lab/staging/node_modules/.bin:$PATH
jupyter lab build
Build succeeded.
💡 说明：生产环境不建议把
build纳入常规流程。扩展一律用pip install安装预构建包，升级用pip install -U，可避免引入 Node 工具链与权限问题。
7.2 clean 的三种粒度
jupyter lab clean
[LabCleanApp] Cleaning /opt/jupyter/venv/share/jupyter/lab...
[LabCleanApp] Removing staging...
[LabCleanApp] Success!
不带参数只删 staging（构建中间产物），最安全。更彻底的三档：
| 命令 | 删除内容 | 使用场景 |
|---|---|---|
jupyter lab clean | staging/ | 释放构建缓存 |
jupyter lab clean --extensions | 预构建扩展的静态资源 | 扩展状态异常时重建 |
jupyter lab clean --settings | 用户设置 | 配置错乱、界面异常 |
jupyter lab clean --all | 整个 app 目录 | 彻底重置前端 |
--all 会删掉界面设置与已装扩展的静态资源，执行前确认可以重装扩展。
7.3 变更后生效
sudo systemctl restart jupyter-lab
前端有缓存，浏览器需强制刷新（Ctrl+Shift+R）才能看到新资源。
八、工作区管理：jupyter lab workspace
工作区（workspace）保存「打开了哪些文件、面板如何切分」，默认落在 workspaces_dir。
jupyter lab workspace list
真实回显为空——表示当前没有任何已保存的工作区（首次使用或从未命名保存）。空输出不是报错。
导出默认工作区：
jupyter lab workspace export
{"data": {}, "metadata": {"id": "/default"}}
导出指定名称的工作区：
jupyter lab workspace export quzuo-demo
{"data": {}, "metadata": {"id": "/quzuo-demo"}}
data 为空表示该工作区没有保存任何面板布局。导入与列出同理：
| 命令 | 作用 |
|---|---|
jupyter lab workspace list | 列出全部工作区名称 |
jupyter lab workspace export [name] | 导出为 JSON（默认工作区可省略 name） |
jupyter lab workspace import <file> | 从 JSON 导入 |
jupyter lab workspace import <file> --name <name> | 导入并命名 |
💡 说明：迁移服务器时，把
/srv/jupyter/lab/workspaces整个目录打包带走，比逐个export更省事；导出命令适合把某个工作区交给同事复现布局。
九、服务实例管理：jupyter server
9.1 列出运行中的实例
jupyter server list
Currently running servers:
http://127.0.0.1:8888/jupyter/ :: /srv/jupyter
9.2 结构化输出（脚本友好）
jupyter server list --json
{"base_url": "/jupyter/", "hostname": "127.0.0.1", "password": false, "pid": 8920, "port": 8888, "root_dir": "/srv/jupyter", "secure": false, "sock": "", "token": "", "url": "http://127.0.0.1:8888/jupyter/", "version": "2.21.1"}
各字段的运维含义：
| 字段 | 含义 | 排障价值 |
|---|---|---|
pid | 服务进程号 | 配合 ps/journalctl 定位进程 |
port / hostname | 监听位置 | 与 ss -ltnp 对照 |
base_url | 子路径 | 与 Nginx location 对照 |
root_dir | 文件根目录 | 确认工作区目录是否正确 |
token | 当前 token | 空串表示已关闭 token 认证 |
password | 是否启用密码 | 注意：该字段对写在 .py 中的哈希不敏感，本环境实际启用了密码却显示 false，不要以此判断密码是否生效 |
9.3 停止实例
jupyter server stop 8888
预期结果：输出停止信息并结束该端口上的服务进程。本环境未执行该命令（会中断正在运行的服务），生产上更推荐 sudo systemctl stop jupyter-lab，因为 systemd 能同时处理重启策略与子进程回收。
9.4 服务端扩展
jupyter server extension list
Config dir: /etc/jupyter
Config dir: /opt/jupyter/venv/etc/jupyter
jupyter_lsp enabled
- Validating jupyter_lsp...
jupyter_lsp 2.3.1 OK
jupyter_server_terminals enabled
- Validating jupyter_server_terminals...
jupyter_server_terminals 0.5.4 OK
jupyterlab enabled
- Validating jupyterlab...
jupyterlab 4.6.4 OK
notebook_shim enabled
- Validating notebook_shim...
notebook_shim OK
Config dir: /usr/local/etc/jupyter
OK 表示扩展可加载；若出现 X 或 error，按提示的模块名重装对应 pip 包。
十、内核管理：jupyter kernelspec
10.1 列出内核
jupyter kernelspec list
Available kernels:
python3 /opt/jupyter/venv/share/jupyter/kernels/python3
python3 是内核名（Notebook 里显示为 Python 3 (ipykernel)），右侧是内核规格目录。该目录下至少有 kernel.json，定义了启动命令：
cat /opt/jupyter/venv/share/jupyter/kernels/python3/kernel.json
{
"argv": ["python", "-m", "ipykernel_launcher", "-f", "{connection_file}"],
"display_name": "Python 3 (ipykernel)",
"language": "python"
}
10.2 结构化输出
jupyter kernelspec list --json
{
"kernelspecs": {
"python3": {
"resource_dir": "/opt/jupyter/venv/share/jupyter/kernels/python3",
"spec": {
"argv": ["python", "-m", "ipykernel_launcher", "-f", "{connection_file}"],
"env": {},
"display_name": "Python 3 (ipykernel)",
"language": "python",
"interrupt_mode": "signal",
"metadata": {"debugger": true, ...}
}
}
}
}
metadata.debugger: true 说明该内核支持调试器，JupyterLab 的断点调试依赖它。
10.3 安装与删除
安装新内核（以给另一个虚拟环境注册内核为例）：
/opt/jupyter/venv/bin/python -m ipykernel install --prefix=/opt/jupyter/venv --name py312-quzuo --display-name "Python 3.12 (quzuo)"
Installed kernelspec py312-quzuo in /opt/jupyter/venv/share/jupyter/kernels/py312-quzuo
删除：
jupyter kernelspec remove py312-quzuo
预期结果：提示确认后删除对应目录。删除前确认没有 Notebook 正在使用该内核，否则会话会报 No such kernel named ...。
⚠️ 注意：
jupyter kernelspec install用于安装一个已存在的 kernelspec 目录；要从 Python 环境生成规格，优先用python -m ipykernel install，它能自动写入正确的 argv 与路径。
十一、扩展管理：jupyter labextension
11.1 列出扩展
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 表示扩展已启用且校验通过；(python, ...) 表示它是 pip 安装的预构建扩展。
11.2 禁用与启用
jupyter labextension disable jupyterlab-execute-time
Starting with JupyterLab 4.1 individual plugins can be re-enabled in the user interface. While all plugins which were previously disabled have been locked, you need to explicitly lock any newly disabled plugins by using `jupyter labextension lock` command.
此时 jupyter labextension list 末尾出现：
Disabled extensions:
jupyterlab-execute-time (all plugins)
重新启用：
jupyter labextension enable jupyterlab-execute-time
（无输出）
再查列表：
jupyterlab-execute-time v3.3.0 enabled OK 🔒 (all plugins locked) (python, jupyterlab_execute_time)
🔒 表示该扩展被锁定，用户无法在界面里自行重新启用——这是防止误操作的有效手段，内网生产建议对关键扩展加锁。
11.3 安装与卸载
JupyterLab 4.x 不再使用 jupyter labextension install 安装第三方扩展，统一走 pip：
/opt/jupyter/venv/bin/pip install jupyterlab-execute-time
/opt/jupyter/venv/bin/pip uninstall -y jupyterlab-execute-time
装完执行 jupyter labextension list 确认 enabled OK，再重启服务生效。
⚠️ 注意：扩展必须装进服务所用的那个虚拟环境。本环境曾以
jupyter用户执行pip install报Permission denied: /opt/jupyter/venv/...，原因是 venv 属主为 root；正确做法是以 venv 属主执行安装，或先chown -R调整属主。
十二、密码与 token 运维
12.1 生成密码哈希
/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
把结果写入 c.PasswordIdentityProvider.hashed_password，并配 c.IdentityProvider.token = "" 关闭一次性 token，即得到「固定密码」认证。
12.2 交互式写密码
JUPYTER_CONFIG_DIR=/etc/jupyter jupyter server password
Enter password:
Verify password:
[JupyterPasswordApp] Wrote hashed password to /etc/jupyter/jupyter_server_config.json
生成的文件：
{
"IdentityProvider": {
"hashed_password": "argon2:$argon2id$..."
}
}
⚠️ 注意：这是本环境踩过的最贵的一个坑。以 root 执行该命令会把 JSON 写成
root:root 600，而服务以jupyter用户运行，启动直接失败：
PermissionError: [Errno 13] Permission denied: '/etc/jupyter/jupyter_server_config.json'
修复：
chown jupyter:jupyter /etc/jupyter/jupyter_server_config.json
chmod 600 /etc/jupyter/jupyter_server_config.json
systemctl restart jupyter-lab
systemctl is-active jupyter-lab
active
正确姿势是先切到运行用户再执行：su - jupyter -c "JUPYTER_CONFIG_DIR=/etc/jupyter /opt/jupyter/venv/bin/jupyter server password"。
12.3 两份哈希的优先级
.py 里的 hashed_password 与 .json 里的同名键会同时加载，后加载者生效。排查「改了密码却不生效」时，先用 --show-config 看当前值以哪个文件为准，再统一只保留一处。
12.4 token 的临时用法
不想固化密码时，可用一次性 token 启动：
jupyter lab --no-browser --ip=127.0.0.1 --port=8888 --IdentityProvider.token='quzuo-token-2026'
此时 jupyter server list --json 的 token 字段会显示该值，访问地址为 http://127.0.0.1:8888/jupyter/lab?token=quzuo-token-2026。生产环境不要用弱 token，也不要把它留在 shell 历史里。
十三、日志、进程与健康检查
13.1 查看服务日志
journalctl -u jupyter-lab --no-pager -n 10
Oct 27 17:42:38 lab-quzuo jupyter[8920]: [I ... LabApp] Extension Manager is 'pypi'.
Oct 27 17:42:38 lab-quzuo jupyter[8920]: [I ... ServerApp] jupyterlab | extension was successfully loaded.
Oct 27 17:42:38 lab-quzuo jupyter[8920]: [I ... ServerApp] Serving notebooks from local directory: /srv/jupyter
Oct 27 17:42:38 lab-quzuo jupyter[8920]: [I ... ServerApp] Jupyter Server 2.21.1 is running at:
Oct 27 17:42:38 lab-quzuo jupyter[8920]: [I ... ServerApp] http://127.0.0.1:8888/jupyter/lab
Oct 27 17:42:38 lab-quzuo jupyter[8920]: [I ... ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
Oct 27 17:42:45 lab-quzuo jupyter[8920]: [I ... LabApp] 302 GET /jupyter/lab (@127.0.0.1) 0.48ms
Oct 27 17:42:49 lab-quzuo jupyter[8920]: [I ... ServerApp] User bdd31159147747809afa9f2dfbe9381c logged in.
Oct 27 17:42:49 lab-quzuo jupyter[8920]: [I ... ServerApp] 302 POST /jupyter/login (bdd31159147747809afa9f2dfbe9381c@127.0.0.1) 26.80ms
持续跟踪：
journalctl -u jupyter-lab -f
日志阅读要点：302 GET /jupyter/lab 是未登录跳转、User ... logged in 是密码验证通过、302 POST /jupyter/login 是登录成功后的重定向，三者连起来就是一次正常登录。异常看 [E] 与 Traceback。
13.2 端口监听核对
ss -ltnp | grep 8888
LISTEN 0 128 127.0.0.1:8888 0.0.0.0:* users:(("jupyter-lab",pid=8920,fd=6))
若显示 0.0.0.0:8888 或 *:8888，说明配置里的 ip 不是 127.0.0.1，服务已直接对外监听，需立即检查防火墙与 TLS 配置。
13.3 HTTP 健康检查
未登录访问前端会得到 302：
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
未登录访问 API 会得到 403：
curl -s http://127.0.0.1:8888/jupyter/api/status
{"message": "Forbidden", "reason": null}
这两条同时成立，说明「服务在跑、认证在生效」。若要验证已登录状态，需要带 Cookie 访问：
{"connections": 0, "kernels": 0, "last_activity": "...", "started": "..."}
kernels 是当前活跃内核数，长期只增不减说明内核回收没生效，回看 cull_idle_timeout 配置。
13.4 端口冲突
日志出现：
[W ServerApp] The port 8888 is already in use, trying another port.
说明已有实例占用。先 jupyter server list 找到 PID，再决定是停掉旧实例还是换端口。不要直接 pkill -f jupyter-lab：本环境实测该命令会把与关键字匹配的当前 shell 一并杀掉（退出码 143）。正确做法是 sudo systemctl stop jupyter-lab，或按 PID 精确终止。
十四、批量执行：jupyter nbconvert
无界面跑批是数据管道里最常用的自动化手段：
cd /srv/jupyter
jupyter nbconvert --to notebook --execute demo-quzuo.ipynb --output /tmp/demo-cli.ipynb
真实回显（节选）：
[NbConvertApp] Converting notebook demo-quzuo.ipynb to notebook
[NbConvertApp] Writing 1891 bytes to /tmp/demo-cli.ipynb
执行结果写回 --output 指定的文件，.ipynb 里的输出单元格就是本次真实运行的结果。常用变体：
| 命令 | 作用 |
|---|---|
jupyter nbconvert --to notebook --execute x.ipynb --output y.ipynb | 执行并另存 |
jupyter nbconvert --to html x.ipynb | 导出静态 HTML 报告 |
jupyter nbconvert --to notebook --execute x.ipynb --inplace | 原地执行覆盖 |
jupyter nbconvert --to notebook --execute x.ipynb --ExecutePreprocessor.timeout=600 | 长任务放宽超时 |
💡 说明：
--inplace会覆盖源文件，把它放进自动化脚本前一定要先备份或纳入版本管理。默认超时较短，跑训练类任务必须显式调大--ExecutePreprocessor.timeout。
十五、常用命令速查表
| 场景 | 命令 |
|---|---|
| 查版本 | jupyter --version |
| 查配置/数据路径 | jupyter --paths |
| 查生效配置 | jupyter lab --show-config |
| 查前端目录 | jupyter lab path |
| 前台调试启动 | jupyter lab --no-browser --ip=127.0.0.1 --port=8888 |
| 启停服务 | sudo systemctl restart jupyter-lab |
| 查实例 | jupyter server list --json |
| 查服务端扩展 | jupyter server extension list |
| 查内核 | jupyter kernelspec list |
| 查前端扩展 | jupyter labextension list |
| 重置密码 | jupyter server password（以运行用户执行） |
| 看日志 | journalctl -u jupyter-lab -f |
| 查监听 | ss -ltnp | grep 8888 |
| 健康检查 | curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8888/jupyter/lab |
| 批量执行 | jupyter nbconvert --to notebook --execute x.ipynb --output y.ipynb |
十六、常见问题
Q1：jupyter 命令找不到或版本不对
which jupyter 确认解析到 /opt/jupyter/venv/bin/jupyter。若指向 /usr/bin/jupyter，说明 PATH 顺序不对，先 export PATH=/opt/jupyter/venv/bin:$PATH，或直接写绝对路径。
Q2：jupyter server list 里看不到实例
该命令依赖 runtime 目录下的连接文件。若服务以 jupyter 用户运行、而你在 root 下执行，读的是 /root/.local/share/jupyter/runtime，自然为空。用 su - jupyter -c "jupyter server list"，或 sudo -u jupyter 执行。
Q3：改动后 jupyter lab path 仍显示旧目录
见第六章说明：lab path 不读取全部 LabApp 覆盖项时以默认值展示，用 jupyter lab --show-config 复核真实生效值。
Q4：jupyter lab build 报 Node.js 缺失
4.x 的 prebuilt 扩展不需要构建。若确实要构建，先装 Node.js 22（node v22.23.4 / npm 10.9.9）并把 staging/node_modules/.bin 加进 PATH，再重试。
Q5：扩展显示 enabled 但界面没有效果
先 jupyter lab clean --extensions 再重启服务，并强制刷新浏览器。仍无效则检查扩展版本与 Lab 4.6.4 的兼容性（jupyter labextension list 的 OK 只代表加载成功，不代表功能一定可用）。
Q6：jupyter kernelspec remove 后 Notebook 报错
删除后旧会话无法恢复内核，需在界面里 Kernel → Restart 并选择新内核。生产上删除前先用 jupyter kernelspec list 与 Notebook 元数据核对使用情况。
十七、参考链接
- JupyterLab 官方文档：https://jupyterlab.readthedocs.io/
- Jupyter Server 命令行与配置：https://jupyter-server.readthedocs.io/en/latest/
- nbconvert 文档：https://nbconvert.readthedocs.io/
- 同系列：《JupyterLab 介绍与选型指南》、《JupyterLab 4.6.4 Ubuntu 22.04 安装指南》、《JupyterLab 4.6.4 配置参数详解》