Leon 1.0.0-beta.8 常用 CLI 与运维命令详解
Leon 1.0.0-beta.8 命令面全解：npm run 脚本清单、安装初始化、build/build:app/build:server 内部构建链路、train 与 skills-endpoints 生成、npm start 启动与 systemd 托管、日志与端口检查、升级回滚，命令均在 Ubuntu 22.04.5 LTS 实测。
Leon 1.0.0-beta.8 常用 CLI 与运维命令详解
目标：把 Leon 的「命令面」一次讲清——它没有独立的
leon可执行文件，全部操作都通过npm run <script>驱动。本文按安装、构建、训练、运行、检查五组给出命令、参数与执行顺序，并标注每一步的真实回显。环境：Ubuntu 22.04.5 LTS、Leon 1.0.0-beta.8、Node.js v20.20.2、npm 10.8.2，命令于 2026-10-28 实测。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS |
| Leon | 1.0.0-beta.8 |
| Node.js | v20.20.2 |
| npm | 10.8.2 |
| 安装目录 | /opt/leon |
| 服务端口 | 1337（HTTP/socket.io）、1342（Python TCP） |
先确认运行时满足 package.json 的 engines（node >=16.0.0、npm >=8.0.0）：
node -v && npm -v
实测回显：
v20.20.2
10.8.2
版本低于 16 时，安装阶段就会失败，不需要等到运行期才发现。
二、命令总览
Leon 的 npm 脚本就是它的 CLI。列出当前可用的脚本：
cd /opt/leon
npm run
实测回显（节选，已略去与本篇无关的测试类脚本）：
Lifecycle scripts included in leon@1.0.0-beta.8:
preinstall
node scripts/setup/preinstall.js
postinstall
ts-node scripts/setup/setup.js
start
cross-env LEON_NODE_ENV=production node server/dist/pre-check.js && node server/dist/index.js
available via `npm run-script`:
build
npm run build:app && npm run build:server
build:app
cross-env LEON_NODE_ENV=production ts-node scripts/app/run-build-app.js
build:server
npm run delete-dist:server && npm run train && npm run generate:skills-endpoints && tsc --project tsconfig.json && resolve-tspaths && shx rm -rf server/dist/core server/dist/package.json && shx mv -f server/dist/server/src/* server/dist && shx rm -rf server/dist/server && shx mkdir -p server/dist/tmp
check
ts-node scripts/check.js
train
ts-node scripts/train/run-train.js
generate:http-api-key
ts-node scripts/generate/run-generate-http-api-key.js
generate:skills-endpoints
ts-node scripts/generate/run-generate-skills-endpoints.js
start:tcp-server
cross-env PIPENV_PIPFILE=tcp_server/src/Pipfile pipenv run python tcp_server/src/main.py
python-bridge
cross-env PIPENV_PIPFILE=bridges/python/src/Pipfile pipenv run python bridges/python/src/main.py server/src/intent-object.sample.json
wake
cross-env LEON_HOST=http://localhost LEON_PORT=1337 node hotword/index.js
dev:server
npm run train && npm run generate:skills-endpoints && cross-env LEON_NODE_ENV=development tsc-watch --noClear --onSuccess "nodemon"
从这份清单能读出三个关键事实：
npm start先跑pre-check.js再跑index.js——启动前的环境自检是强制的，自检不过服务不会起来；build:server内部先train再generate:skills-endpoints——构建与「NLU 训练」「技能端点生成」是绑定的，跳过训练直接编译会得到一个无法识别意图的包；- Python 侧没有编译步骤，靠
pipenv run python直接启动，依赖由Pipfile管理。
三、安装与初始化
cd /opt/leon
npm install
npm install 会按顺序触发两个生命周期脚本：
preinstall→node scripts/setup/preinstall.js，只做环境提示与预检，回显很短：
node scripts/setup/preinstall.js
➡ Running Leon's installation...
postinstall→ts-node scripts/setup/setup.js，负责生成.env、下载 TCP 服务与 Python/Node 桥的可执行文件、跑一次初始 NLU 训练。
因此判断安装是否完整，不看 npm install 的退出码，而看三样东西：
ls -l /opt/leon/.env # 配置文件已生成
ls /opt/leon/server/dist | head # 服务端构建产物存在
ls /opt/leon/bridges/python/bin # Python 桥可执行文件存在
任一缺失都说明 postinstall 没跑完，重装用 npm install 而不是只补某一项。
四、构建
# 一次构建前端与服务端
npm run build
# 只构建前端（Vite 产物写到 app/dist）
npm run build:app
# 只构建服务端（TypeScript 编译 + 产物重排）
npm run build:server
build:server 的完整链路值得记住，因为出问题时要知道停在哪一步：
delete-dist:server # 清掉旧产物，避免旧文件混入
→ train # 训练 NLU 模型
→ generate:skills-endpoints # 扫描技能目录，生成 HTTP 端点映射
→ tsc # TypeScript 编译
→ resolve-tspaths # 把 @/ 别名重写为相对路径
→ 产物搬移 # server/dist/server/src/* → server/dist
常见现象：不跑 train 直接 tsc，服务能启动、页面能打开，但任何输入都命不中技能——因为意图模型还是旧的或不存在。构建次数的经验值是每改一次技能或语言就要重跑 npm run build:server，而改 .env 不需要构建，只需重启。
五、训练与生成
# 训练 NLU（默认语言取自 LEON_LANG，也可显式传语种）
npm run train
npm run train en
# 生成/轮换 HTTP API Key（直接写入 .env）
npm run generate:http-api-key
# 只重新生成技能 HTTP 端点映射
npm run generate:skills-endpoints
train 的输出是模型文件，generate:skills-endpoints 的输出是端点映射清单——两者都不进版本库、都可重复生成。新增技能后的标准动作是：npm run build:server（内部已含 train 与 generate），或分步执行 train → generate:skills-endpoints → 重启。
六、运行
生产启动（单进程，含启动自检）：
cd /opt/leon
npm start
它等价于：
LEON_NODE_ENV=production node server/dist/pre-check.js && node server/dist/index.js
因此不要绕过 pre-check.js 直接跑 index.js：自检会核对 .env 关键项与产物完整性，绕过它只会把问题推迟到运行中暴露。
配套进程：
| 命令 | 用途 | 何时需要 |
|---|---|---|
npm run start:tcp-server | 启动 Python TCP 服务（1342） | 使用 Python 技能时；不启动则页面一直转圈 |
npm run python-bridge | 单独跑 Python 桥（调试意图对象） | 排查 Python 技能不执行 |
npm run wake | 启动热词唤醒节点 | 需要「喊名字唤醒」时；它连接 1337 的服务 |
长期运行建议交给 systemd，而不是 nohup：
[Unit]
Description=Leon assistant server
After=network-online.target
[Service]
Type=simple
User=leon
WorkingDirectory=/opt/leon
Environment=LEON_NODE_ENV=production
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
systemctl daemon-reload
systemctl enable --now leon
journalctl -u leon -n 50 --no-pager
Type=simple + Restart=on-failure 是这套组合的关键：Leon 崩溃时由 systemd 拉起，日志统一进 journal。
七、检查与测试
# 环境自检（OS、tar/make 等构建工具、依赖完整性）
npm run check
# 分层测试
npm run test:json # 技能 JSON 结构校验，最快的门禁
npm run test:unit # 单元测试（会先 train）
npm run test:e2e # 端到端（含 NLP 模块与真实技能调用）
npm run check 是部署后的第一道检查：它按操作系统类型给出结论，缺 tar/make 之类的构建工具会直接报出名字。test:json 不依赖运行中的服务，适合放进提交前钩子；test:e2e 会占用端口并起真实服务，不要在正在对外服务的实例上执行。
八、日常运维命令
# 1. 存活：HTTP 服务
curl -s http://192.168.1.71:8131/api/v1/info
# 2. 监听：两个端口都要在
ss -lntp | grep -E ':(1337|1342)\b'
# 3. 日志：systemd 托管时看 journal，直接运行时看 logs/
journalctl -u leon -n 100 --no-pager
tail -n 100 /opt/leon/logs/leon.log
# 4. 端口占用排查
ss -lntp | grep 1337
判据：第 1 步返回 success: true 说明 HTTP 层正常；第 2 步缺 1342 说明 Python 技能链路断了；日志里出现「TCP server is not connected」时，先确认 npm run start:tcp-server 是否在跑，再查 1342 是否被防火墙拦截。
升级与回滚：
cd /opt/leon
git fetch --tags
git checkout v1.0.0-beta.8 # 锁定稳定标签，不要跟 develop
npm install && npm run build
systemctl restart leon
升级前先备份 .env（里面含 API Key），升级后按 npm run check → api/v1/info → 一次真实对话三步验证。
九、典型场景的命令组合
把命令按「一次要做完什么」打包，比单独记命令更实用：
| 场景 | 命令序列 | 完成判据 |
|---|---|---|
| 首次部署 | npm install → npm run check → npm start | 1337 与 1342 均在监听，页面可对话 |
| 只改配置 | 编辑 .env → systemctl restart leon | /api/v1/info 返回新值对应的行为 |
| 新增或修改技能 | npm run build:server → systemctl restart leon | 用新技能触发语句能命中 |
| 轮换 API Key | npm run generate:http-api-key → 重启 → 通知调用方 | 旧 Key 401、新 Key 200 |
| 升级版本 | 备份 .env → git checkout <tag> → npm install && npm run build → 重启 | npm run check 通过且对话正常 |
| 排查无响应 | ss -lntp | grep 1342 → npm run start:tcp-server | 页面恢复「正在聆听/可输入」 |
两条纪律：改代码或技能必须重新构建，改 .env 只需重启；任何构建之后都要重启，因为 npm start 加载的是 server/dist 里的产物，不是源码。
十、排障速查
| 现象 | 首查命令 | 常见根因 |
|---|---|---|
| 页面打开但输入无响应 | ss -lntp | grep 1342 | TCP 服务未启动，或 LEON_PY_TCP_SERVER_PORT 被改 |
npm start 立刻退出 | npm start 前台跑一次看输出 | pre-check 发现缺产物或缺 .env |
| 任何输入都命不中技能 | ls -l server/dist | 构建时漏了 train |
/api/query 401 | grep LEON_HTTP_API_KEY .env | 密钥为空或与调用方不一致 |
| 语音无反应 | `grep -E 'LEON_(STT | TTS)' .env` |
| 端口被占 | ss -lntp | grep -E ':(1337|1342)' | 旧进程未退出，先 systemctl stop leon 再启 |
十、参考链接
- 官方文档：
https://docs.getleon.ai - 脚本定义来源：安装目录
package.json的scripts段 - 同专栏：《Leon 介绍与选型指南》
- 同专栏：《Leon 1.0.0-beta.8 完整部署与实战指南》
- 同专栏：《Leon 1.0.0-beta.8 配置参数详解》