GETTING STARTED

体验部署流程

项目当前仍处于 dev 阶段，尚未提供公开发行包。可以使用开发构建的 JAR 在本机启动，也可以交给 Docker 完成源码构建和运行；两种方式任选其一，不需要同时准备两套环境。

最短体验路径：选择 JAR 或 Docker → 启动 Lingxi 和 Demo → 初始化管理员 → 配置模型与 Runtime → 导入能力和场景 → 运行第一条任务。
01

环境要求

JAR 方式JDK 17、lingxi.jar 和 resource-demo.jar
Docker 方式Docker 及 Docker Compose
Python仅 JAR 方式运行示例 Skill 时需要 3.10+
Git仅访问代码仓库时需要
Codex CLI仅 Codex Runtime 需要，可在页面安装
源码构建工具Docker 方式由镜像构建，不安装到宿主机

两种启动方式任选其一。JAR 方式不需要 Maven、Node.js 或 Yarn；Docker 方式不要求宿主机安装 JDK 和 Python，但必须先安装 Docker。当前 dev 阶段不提供线上自动下载。

02

启动 Lingxi 和 Demo

仓库根目录提供两种一键启动方式。JAR 方式只运行已有构建产物；Docker 方式会在镜像中完成前后端构建，并同时启动 Lingxi 和 Demo。

已有 JDK 17

将两个 JAR 分别命名为根目录的 lingxi.jar 和 examples/resource-demo/resource-demo.jar。

使用 JAR
./start-all.sh

已有 Docker

不需要在宿主机安装 JDK、Python、Node.js、Yarn 或 Maven，首次构建需要下载基础镜像和依赖。

使用 Docker
docker compose up --build -d

启动后，Lingxi 位于 http://localhost:8080，Demo 位于 http://localhost:8091。两个服务的前端页面都已经打进各自 JAR，不需要单独启动前端开发服务。

只启动 Lingxi：JAR 方式执行 ./start.sh；Docker 方式执行 docker compose up --build -d lingxi。
03

启动后先完成首次可用配置

服务成功启动只代表页面和 API 可访问。至少完成管理员、模型供应商和模型配置后，首页才有可选的运行方式；使用 Codex Runtime 时还要安装 Codex CLI。

1

设置首个管理员

第一次打开 Lingxi 登录页会显示“首次初始化”。设置管理员密码后，系统创建账号 admin 并自动登录。以后直接用该账号和密码登录。

2

添加模型供应商并检测连接

  1. 进入“管理端 → 模型管理”，点击“供应商”标题右侧的加号。
  2. 选择供应商类型，填写名称、服务地址和 API Key。
  3. 点击“检测连接并获取模型”；看到检测通过和模型列表后保存。

连接检测由 Lingxi 服务发起。服务地址必须能从运行 Lingxi 的机器访问，只在当前浏览器能打开不算连通。

3

在供应商下添加模型

  1. 在左侧选中刚保存的供应商，点击模型区域的“添加模型”。
  2. 填写显示名称、模型标识、协议和上下文窗口，并保持“启用”。检测得到的模型标识可以直接选择。
  3. 保存后确认模型列表显示兼容的 Runtime。协议必须与模型服务实际支持的协议一致。
4

准备 Runtime

Lingxi Runtime · 最少安装步骤不需要安装本地 CLI。保存兼容模型后即可在任务首页选择，适合先验证部署和 Demo 流程。
Codex Runtime · 需要 Codex CLI进入“管理端 → 系统设置 → Codex CLI 维护”，点击“安装 Codex CLI”，等待安装状态变为“已安装”。Codex Runtime 同样需要前面配置的兼容模型。

Runtime 不是在系统设置中预先选定的。返回任务首页后，点击输入框下方的“选择运行方式”，为当前任务选择 Runtime 和模型。

平台模型管理页面
模型管理：先添加供应商并检测，再添加启用的模型。
系统设置中的 Codex CLI 维护
系统设置：使用 Codex Runtime 时在这里安装和检查 Codex CLI。
无人值守初始化：启动前设置 LINGXI_USER_DEFAULT_PASSWORD 可以自动创建管理员。已有用户时不会覆盖密码。
04

导入公开 Demo

Demo 是单独的项目、Markdown 文档和日志资源服务，不是 Lingxi 本体。它提供公开 Skill、场景、真实开源 Agent 仓库和配套示例数据，便于验证完整流程。使用上一节的一键命令后，Demo 已经启动。

  1. 打开 http://localhost:8091/#/setup。
  2. Lingxi 页面地址填写 http://localhost:8080。
  3. 选择能力和场景，点击“导入已选”。
  4. 在 Lingxi 场景管理页确认来源和安装清单。

默认可用“业务问答”“文档分析”“故障分析”验证 Demo 数据。

跨服务器部署：DEMO_PUBLIC_BASE_URL 必须是浏览器和 Lingxi Runtime 都能访问的 Demo 地址。根目录 Compose 通过共享网络处理了本机体验时的连通性；拆分到不同服务器时需要改为实际服务地址。
05

运行第一条任务

完成模型配置并导入 Demo 后，用“文档分析”验证最短闭环：

  1. 进入“管理端 → 分析情境”，编辑“测试环境”。在“可见场景”中选择“文档分析”；在“文档分析”的场景情境参数里，将“项目管理上下文 · 应用”填写为“OpenAI Codex”，然后保存。
  2. 返回任务首页，点击输入框下方的场景入口，选择“测试环境 · 文档分析”。
  3. 点击“选择运行方式”，选择已经可用的 Runtime 和模型。
  4. 输入“Codex 项目建议从哪些方向分析？请给出文档依据”，然后发起分析。
  5. 任务页会持续显示模型判断、能力调用和文档证据；完成后可以基于同一任务继续追问。
首页没有场景或运行方式：先检查场景是否已经在 Demo 导入并启用、当前情境是否允许该场景、模型是否启用；Codex Runtime 还要确认 Codex CLI 状态为“已安装”。更完整的页面说明见使用说明。
06

连接 GitHub / GitLab 私有仓库

这一步只在访问私有 SSH 仓库时需要。私钥留在 Lingxi 服务器，公钥添加到 Git 平台；情境填写的是 Lingxi 进程能看到的目录，不是 Key 内容。

data/git-keys/
├── config
├── github_lingxi
├── github_lingxi.pub
├── gitlab_lingxi
├── gitlab_lingxi.pub
└── known_hosts

在 Lingxi 仓库根目录生成 Key

私钥目录
mkdir -p data/git-keys
chmod 700 data/git-keys
ssh-keygen -t ed25519 -f data/git-keys/github_lingxi -C lingxi@github
ssh-keygen -t ed25519 -f data/git-keys/gitlab_lingxi -C lingxi@gitlab
ssh-keyscan github.com gitlab.com > data/git-keys/known_hosts
chmod 600 data/git-keys/github_lingxi data/git-keys/gitlab_lingxi data/git-keys/known_hosts
cat data/git-keys/github_lingxi.pub
cat data/git-keys/gitlab_lingxi.pub
realpath data/git-keys

把对应 .pub 输出添加到 GitHub/GitLab 仓库的只读 Deploy Key。不要上传无 .pub 后缀的私钥。自建 GitLab 要把域名替换为实际地址。

创建 data/git-keys/config

OpenSSH config
Host github.com
  HostName github.com
  User git
  IdentityFile /path/visible/to/lingxi/data/git-keys/github_lingxi
  IdentitiesOnly yes
  UserKnownHostsFile /path/visible/to/lingxi/data/git-keys/known_hosts

Host gitlab.com
  HostName gitlab.com
  User git
  IdentityFile /path/visible/to/lingxi/data/git-keys/gitlab_lingxi
  IdentitiesOnly yes
  UserKnownHostsFile /path/visible/to/lingxi/data/git-keys/known_hosts

JAR 方式将示例路径替换为 realpath data/git-keys 输出；Docker 方式固定替换为 /app/data/git-keys。最后执行 chmod 600 data/git-keys/config。

在情境中指定目录

进入“分析情境 → 新增/编辑 → 场景情境参数 → 能力参数 · 代码仓库 → Git Key 目录”。JAR 方式填写 realpath data/git-keys 的输出，Docker 方式填写 /app/data/git-keys。参数键为 gitKeyDirectory，仓库地址必须使用 SSH 格式。

不填写时：Git 会读取 Lingxi 服务运行用户的 ~/.ssh；Docker 中指的是容器用户目录，不是宿主机的 ~/.ssh。隐式环境配置不利于迁移和故障排查，建议始终填写。
07

当前部署边界

项目尚未发布稳定版本，也没有 GitHub Release 自动发布流程。当前 JAR 和本地构建的 Docker 镜像只用于开发和内部体验，不应包装成“最新版”提供给生产环境。

  • lingxi.jar 已包含页面、API、默认情境和默认 Skill，不依赖源码目录。
  • 每个 dev JAR 或镜像都应记录对应 Commit，避免无法确认实际运行代码。
  • 内部试用使用反向代理时，应统一转发到 Lingxi 端口并提供 HTTPS。
  • 持久化并备份 data/，限制数据库、任务工作区和凭证目录权限。
  • 启用 HTTPS 后设置 LINGXI_SESSION_COOKIE_SECURE=true。
  • 不要启用 H2 Console，也不要把 Demo 暴露到不可信网络。
08

验收清单

能够登录管理员初始化完成，页面能够访问后端 API。
模型可用供应商检测通过，模型已启用，并能在首页选择兼容的 Runtime。
场景已安装场景管理中能看到 Demo 选择的原场景和对应 Skill。
任务能够完成“文档分析”能读取 Demo 文档并返回带来源的结果。