Leon 1.0.0-beta.8 配置参数详解
Leon 1.0.0-beta.8 配置参数全解：25 个环境变量的作用与必改项、.env 生成机制、语音 STT/TTS、HTTP API 与 Python 桥端口、限流与遥测开关、改完配置的三步验证方法，全部取自 .env.sample 原文并在 Ubuntu 22.04.5 LTS 实测。
Leon 1.0.0-beta.8 配置参数详解
目标：把 Leon 1.0.0-beta.8 的配置面讲透——全部 25 个环境变量分别管什么、哪些是必改项、语音与 HTTP API 怎么开，以及改完之后用哪三个动作确认真的生效。本文的变量清单直接取自安装目录里的
.env.sample（45 行原文件），运行时版本1.0.0-beta.8、Node.jsv20.20.2、npm10.8.2均于 2026-10-28 在 Ubuntu 22.04.5 LTS 的服务上读取。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS |
| Leon | 1.0.0-beta.8（package.json 的 version） |
| Node.js | v20.20.2（engines 要求 >=16.0.0） |
| npm | 10.8.2（要求 >=8.0.0） |
| 安装目录 | /opt/leon |
| 服务端口 | 1337（HTTP + socket.io） |
| TCP 端口 | 1342（Python 技能桥） |
| 配置文件名 | .env（由 .env.sample 复制生成） |
Leon 没有数据库，也没有多份配置文件：server、app、Python 桥、热词节点全部读同一份 .env。这带来一个直接后果——改配置 = 改 .env + 重启服务，没有热加载。
二、配置文件从哪来
安装依赖时，postinstall 会执行 scripts/setup/setup.js，它检查 .env 是否存在，不存在就以 .env.sample 为模板生成，并把随机生成的 HTTP API Key 写进去。因此：
- 全新安装：
npm install结束后.env已就绪，只需按需修改变量； - 手工恢复：
cp .env.sample .env，再补LEON_HTTP_API_KEY（用第六节的命令生成）； - 不要删
.env：删了之后服务仍能启动，但 HTTP API 会因为缺少密钥而拒绝/api/query。
三、.env.sample 全文（45 行）
cat /opt/leon/.env.sample
实测回显：
# Main settings of Leon
# https://docs.getleon.ai/configuration
# Language currently used
LEON_LANG=en-US
# Server
LEON_HOST=http://localhost
LEON_PORT=1337
# Time zone (current one by default)
LEON_TIME_ZONE=
# Enable/disable after speech
LEON_AFTER_SPEECH=false
# Enable/disable Leon's speech-to-text
LEON_STT=false
# Speech-to-text provider
LEON_STT_PROVIDER=coqui-stt
# Enable/disable Leon's text-to-speech
LEON_TTS=false
# Text-to-speech provider
LEON_TTS_PROVIDER=flite
# Enable/disable skills to be available over HTTP
LEON_OVER_HTTP=true
# HTTP API key (use "npm run generate:http-api-key" to regenerate one)
LEON_HTTP_API_KEY=
# Language used for the HTTP API
LEON_HTTP_API_LANG=en-US
# Enable/disable telemetry
LEON_TELEMETRY=true
# Python TCP server
LEON_PY_TCP_SERVER_HOST=0.0.0.0
LEON_PY_TCP_SERVER_PORT=1342
# Path to the Pipfile
PIPENV_PIPFILE=bridges/python/src/Pipfile
# Path to the virtual env in .venv/
PIPENV_VENV_IN_PROJECT=true
整份文件就是 Leon 配置的全部官方参数，没有隐藏项。下文按功能分组逐项说明。
四、服务与语言
| 变量 | 示例值 | 作用 | 改动注意 |
|---|---|---|---|
LEON_LANG | en-US | 全局语言：核心文案、技能文案、前端文案 | 只支持仓库已内置语种；缺失语种的表现是「界面中文、回答英文」 |
LEON_HOST | http://localhost | 对外访问基址，用于 API 返回链接与前端请求 | 生产必须改为真实域名或 IP，如 http://192.168.1.71:8131 |
LEON_PORT | 1337 | HTTP 与 socket.io 监听端口 | 改端口要同步改反向代理与防火墙 |
LEON_TIME_ZONE | 空 | 时区（空 = 跟随系统） | 定时类技能按此时区计算；服务器时区为 UTC 时必须显式设置，如 Asia/Shanghai |
LEON_HOST 是最容易漏改的一项：保持 http://localhost 时，页面的 socket.io 连接在远程浏览器里会指向用户自己的机器，表现为「页面能打开、输入框一直转圈」。
五、语音：STT / TTS / 唤醒
| 变量 | 默认 | 作用 |
|---|---|---|
LEON_AFTER_SPEECH | false | 播报完成后自动重新开启聆听（连续对话） |
LEON_STT | false | 语音转文字总开关 |
LEON_STT_PROVIDER | coqui-stt | STT 提供方 |
LEON_TTS | false | 文字转语音总开关 |
LEON_TTS_PROVIDER | flite | TTS 提供方 |
语音能力默认全关，纯文字对话不需要任何语音依赖。开启顺序必须是：先准备好提供方依赖（npm run setup:offline-stt / setup:offline-tts 会拉取离线模型），再把对应开关置 true，最后重启。反过来先开开关，启动日志会出现模型缺失告警，助手仍能对话但语音不可用。
热词唤醒不走 .env，而是独立进程 npm run wake，它同样读 LEON_HOST/LEON_PORT。唤醒节点没启动时，.env 里怎么改都不会生效。
六、HTTP API
| 变量 | 示例值 | 作用 |
|---|---|---|
LEON_OVER_HTTP | true | 是否允许技能通过 HTTP 被调用 |
LEON_HTTP_API_KEY | 40 位十六进制串 | /api/query 的鉴权密钥 |
LEON_HTTP_API_LANG | en-US | 通过 HTTP 调用时使用的语言 |
LEON_OVER_HTTP=true 只代表「允许」，不代表「已授权」：POST /api/query 必须带 X-Api-Key（值为 LEON_HTTP_API_KEY），缺失或错误一律 401。重新生成密钥用官方脚本：
cd /opt/leon
npm run generate:http-api-key
该脚本会生成新的随机串并直接覆写 .env 里的 LEON_HTTP_API_KEY，重启服务后旧密钥立即失效。生产环境建议每季度轮换一次，轮换时先通知调用方。
七、Python TCP 服务
| 变量 | 示例值 | 作用 |
|---|---|---|
LEON_PY_TCP_SERVER_HOST | 0.0.0.0 | TCP 监听地址 |
LEON_PY_TCP_SERVER_PORT | 1342 | TCP 端口，核心进程按此端口连接 |
PIPENV_PIPFILE | bridges/python/src/Pipfile | Python 依赖清单路径 |
PIPENV_VENV_IN_PROJECT | true | 虚拟环境建在项目内 .venv/ |
这四项的正常值不要随意改：LEON_PY_TCP_SERVER_PORT 改了必须同步修改核心侧连接配置，否则页面一直卡在「正在连接」。PIPENV_VENV_IN_PROJECT=true 让虚拟环境与代码同目录，升级时不会误伤系统 Python。
八、遥测
| 变量 | 默认 | 作用 |
|---|---|---|
LEON_TELEMETRY | true | 是否上报匿名使用统计（技能命中次数、版本号） |
内网与合规环境关闭它：改成 false 并重启，之后不会再向官方端点发请求。关闭遥测不影响任何功能，唯一区别是作者拿不到该实例的使用数据。
九、改完配置怎么验证
三个动作按成本从低到高排列，任一步不通过就停在那一层排查：
# 1. 文件层：确认变量已写入且没有拼写错误
grep -nE '^(LEON_|PIPENV_)' /opt/leon/.env
# 2. 端口层：确认 HTTP 与 TCP 都在监听
ss -lntp | grep -E ':(1337|1342)\b'
# 3. 接口层：读版本与能力
curl -s http://192.168.1.71:8131/api/v1/info
判据：
- 第 1 步输出里
LEON_HOST必须是真实访问地址，不能是http://localhost； - 第 2 步应同时看到
1337与1342；只有 1337 说明 Python TCP 服务没起来，页面会一直转圈； - 第 3 步返回
success: true与版本号，说明 HTTP 服务存活；此时再用POST /api/query验证密钥。
/api/v1/info 不校验密钥，适合做存活探针；/api/query 校验密钥，适合做集成自检。
十、参数速查表
按「改不改」分三档，便于上线前逐项核对：
| 变量 | 默认值 | 生产建议 | 档位 |
|---|---|---|---|
LEON_HOST | http://localhost | 改成真实域名/IP | 必改 |
LEON_TIME_ZONE | 空 | Asia/Shanghai（系统 UTC 时必改） | 必改 |
LEON_HTTP_API_KEY | 空 | 用脚本生成，勿手填 | 必改（用 HTTP API 时） |
LEON_PORT | 1337 | 冲突时才改 | 按需 |
LEON_LANG | en-US | 有多语种需求才改 | 按需 |
LEON_TELEMETRY | true | 内网/合规环境改 false | 按需 |
LEON_OVER_HTTP | true | 不需要外部调用可关 | 按需 |
LEON_HTTP_API_LANG | en-US | 与 LEON_LANG 保持一致 | 按需 |
LEON_AFTER_SPEECH | false | 连续对话场景开 | 按需 |
LEON_STT / LEON_STT_PROVIDER | false / coqui-stt | 装好离线模型后再开 | 语音场景 |
LEON_TTS / LEON_TTS_PROVIDER | false / flite | 同上 | 语音场景 |
LEON_PY_TCP_SERVER_HOST | 0.0.0.0 | 保持默认 | 勿动 |
LEON_PY_TCP_SERVER_PORT | 1342 | 保持默认，改了核心侧也要改 | 勿动 |
PIPENV_PIPFILE | bridges/python/src/Pipfile | 保持默认 | 勿动 |
PIPENV_VENV_IN_PROJECT | true | 保持默认 | 勿动 |
核对方式：逐行比对 grep -nE '^(LEON_|PIPENV_)' /opt/leon/.env 的输出与上表「必改」列，缺一项就在上线清单上记一笔。
十一、五条常见故障
- 页面能开、输入无响应：
LEON_HOST仍是localhost，或 1342 端口未监听（TCP 桥没启动）。 /api/query一直 401：.env里的LEON_HTTP_API_KEY为空（手工复制.env.sample后最容易发生），跑一次npm run generate:http-api-key并重启。- 改了
.env没变化：没有重启服务。Leon 只在进程启动时读取配置。 - 语音开关打开后启动报模型缺失：先执行
npm run setup:offline-stt或setup:offline-tts拉取离线模型，再开开关。 - 定时提醒时间不对：
LEON_TIME_ZONE为空且系统时区是 UTC，显式设为Asia/Shanghai后重启。
十二、参考链接
- 官方配置文档：
https://docs.getleon.ai/configuration - 配置模板：安装目录
/.env.sample（45 行，随源码分发） - 同专栏：《Leon 介绍与选型指南》
- 同专栏：《Leon 1.0.0-beta.8 完整部署与实战指南》
- 同专栏：《Leon 1.0.0-beta.8 常用 CLI 与运维命令详解》