安装
在线安装
在 Ubuntu 22.04 LTS 或更新版本（x86_64）上，下载并执行在线安装脚本，
无需克隆仓库。以运行服务的用户执行，不要使用 sudo bash；
只有安装缺失的系统软件包时才会请求 sudo。
下载入口需要 Bash、curl 或 wget、CA 证书和 python3，缺失时可运行
sudo apt-get install curl ca-certificates python3。
将 VERSION 设为 main 安装开发版，或替换为实际发布 tag（如 vX.Y.Z）。
仅支持包含在线安装脚本的 tag。
使用 curl：
VERSION=main && curl -fsSL "https://raw.githubusercontent.com/llm-d-incubation/llm-d-lens/${VERSION}/scripts/LensInstaller-Ubuntu-x86_64-online.sh" | bash
或使用 wget：
VERSION=main && wget -qO- "https://raw.githubusercontent.com/llm-d-incubation/llm-d-lens/${VERSION}/scripts/LensInstaller-Ubuntu-x86_64-online.sh" | bash
安装器从 /dev/tty 读取交互输入。源码包验证成功后，会将脚本保存为当前目录中的
LensInstaller-Ubuntu-x86_64-online.<unique-id>.sh 并打印路径，不覆盖已有文件。
请在可写目录中运行。脚本主体完整接收后才会执行。
自动化 Bash 环境建议启用 set -o pipefail，让下载器失败也能使整个管道返回非零状态。
交互模式会询问安装目录（默认 $HOME/llm-d-lens）和
端口（应用端口 3000，内部后端端口 8081）；按回车即可接受每个默认值。
安装脚本下载固定到 commit 的源码包，然后配置 Node、Python 3.11+、
虚拟环境、PostgreSQL、应用构建和 TLS。缺少兼容 Python 时，使用固定版本的
uv 将独立的 Python 3.12 安装到安装目录的 .tools/，不替换系统 Python。
仅接受新目录或空目录，不覆盖已有安装。
版本选择
脚本内置源码版本，不需要也不接受版本参数。main 安装执行时的开发分支，
发布版本的脚本安装对应 tag。下载前会将版本解析成确定的 commit SHA；
安装目录内的 .lens-version.json 记录版本、SHA 和安装时间。
固定源码不代表所有间接 npm/Python 依赖都已锁定。
网络与失败处理
需允许访问 raw.githubusercontent.com、api.github.com、codeload.github.com、
Node.js 和软件包仓库，以及 Ubuntu 软件源；安装独立 Python 还需下载 GitHub release
资源。脚本继承 HTTP_PROXY、HTTPS_PROXY、NO_PROXY，不会关闭证书校验。
如果 sudo 过滤了代理变量，请单独配置 apt 代理。
日志以私有权限保存在 $LENS_LOG_DIR（默认 ~/.local/state/lens/logs/）。
日志可能包含安装器生成的数据库凭据，请勿公开。临时下载放在
$LENS_SCRATCH_DIR，退出时清理。下载及源码包检查完成前不会修改安装目录；
后续安装失败可能留下部分文件，这些文件会保留用于诊断，不会自动升级、
回滚或删除安装目录。网络失败或 GitHub API 限流会明确报错，不会切换版本。
无终端的脚本化或 CI 安装，请将命令末尾的 | bash 替换为
| bash -s -- --silent。
其他安装选项可追加在 --silent 后面。已保存的脚本仍可通过
bash <saved-script-path> [options] 直接运行。
常用选项：
| 选项 | 作用 |
|---|---|
--install-dir DIR | 安装位置（默认 $HOME/llm-d-lens）。 |
--app-port PORT | Web 应用/API 端口（默认 3000）。 |
--backend-port PORT | 内部 FastAPI 后端端口（默认 8081）。 |
--no-https | 提供纯 HTTP 服务，而不是自动 HTTPS（自签名证书）。 |
--no-start | 安装但不启动服务。 |
--db-mode embedded|external | 使用内置数据库或外部数据库。 |
-h, --help | 显示全部选项。 |
管理安装
安装脚本会在安装目录中写入 lensctl.sh：
"$HOME/llm-d-lens/lensctl.sh" start
"$HOME/llm-d-lens/lensctl.sh" status
"$HOME/llm-d-lens/lensctl.sh" stop
卸载请运行 "$HOME/llm-d-lens/lensctl.sh" uninstall，默认保留数据。
使用 --purge 可删除数据，或使用 --keep-data 跳过数据保留提示。
内嵌数据库通过 --keep-db / --purge-db 单独控制。
在线安装入口本身不接受卸载参数。
如果你要升级现有安装而不是全新安装，请参阅 升级指南。
从源码安装与运行
在仓库根目录使用本地源码启动器，而不是 Ubuntu 安装程序生成的打包部署：
scripts/lens-local.sh start
scripts/lens-local.sh status
启动器准备 Node.js、npm 依赖和 Python 环境，然后在端口 5173 运行源码前端、
在 3000 运行 Node API、在 8081 运行 Python 后端。这种方式通过 Vite
运行源码，并不替代下方的生产构建命令。若单独管理 Python 后端，
可使用 npm run dev:web。
scripts/lens-local.sh start 和 restart 会在更改服务之前重新生成并验证复用地图。
无效的注册项会阻止启动，但不会停止已有服务；待处理的用户决策只会提示警告，
不会被自动解决。若需限定部署节点，传入 --target-node NODE 和可选的
--kubeconfig FILE，或者设置 TARGET_NODE 与 KUBECONFIG；
不需要目标节点专用配置文件。预检查要求和各个子命令参见 CLI 参考。
构建与测试
npm run build
npm run type-check
make test-js
make test-python
文档站点
本站点使用 Docusaurus 构建。可在本地预览， 并支持热重载：
npm run docs:dev
校验配置和页面路径：
npm run docs:check
生成的 MCP 目录是助手和 Node 服务器所必需的。当后端路由发生变化时， 需要重新生成它；Docker 构建会自动完成这一步。