安装与部署

本文说明 flintrix-online 在生产环境下的安装、系统依赖、MCP 与 Skills 配置。

门户下载页提供的 DEB、RPM、tar.gz 均为同一套生产客户包（预编译二进制 + 初始化脚本），仅安装载体不同；默认安装根目录 /opt/flintrix。非源码编译、非开发沙箱用途。

1. 安装包（生产环境）

从下载页获取安装包（须登录且订阅有效）。三种格式面向同一生产部署目标，区别仅在安装载体：

格式	安装方式	生产环境说明
DEB	自动安装（推荐）	`apt install` 一条命令；`postinst` 自动执行 `post-install.sh`
RPM	自动安装（推荐）	`dnf install` 一条命令；`%post` 自动执行 `post-install.sh`
tar.gz	脚本安装	解压到 `/` 后须手动执行 `post-install.sh`（无包管理器时的生产部署方式）

安装根目录均为 /opt/flintrix。与 flintrix-offline 不可同机安装。

DEB — 自动安装（Ubuntu / Debian）

sudo apt install ./flintrix-online_<version>_amd64.deb
source /etc/profile.d/flintrix.sh

无需再跑 post-install.sh（postinst 已自动调用）。

RPM — 自动安装（RHEL / CentOS / Fedora / Rocky / AlmaLinux）

sudo dnf install ./flintrix-online-<version>-1.x86_64.rpm
# 旧系统无 dnf 时：sudo yum install ./flintrix-online-<version>-1.x86_64.rpm
source /etc/profile.d/flintrix.sh

无需再跑 post-install.sh（%post 已自动调用）。

tar.gz — 脚本安装（生产环境）

适用于无法使用 deb/rpm 的 Linux 生产机（如无 apt/dnf 的定制发行版）。生产标准路径仍为 /opt/flintrix：

sudo tar -xzf flintrix-online-<version>-linux-x64.tar.gz -C /
sudo /opt/flintrix/post-install.sh    # 必须手动执行
source /etc/profile.d/flintrix.sh

解压只展开文件；初始化（local/、公钥同步、profile 等）由 post-install.sh 完成。三种格式安装后的目录布局与运行行为一致。

2. 目录布局

路径	用途
`bin/`	`klymora-run`、`klymora-mcp`、`klymora-sweep`、`kay-license-runtime`
`setup/install-deps.sh`	系统依赖（Verilator、Rust 等）
`setup/install-klymora-agent.sh`	依赖 + MCP + Skills + Agent 规程
`setup/install-agent-integration.sh`	仅 MCP / Skills（依赖已满足时）
`skills/`	内置 Skills 源
`agent-rules/`	Agent 操作规程
`scripts/`	仿真器辅助脚本
`local/`	用户自定义文件（升级保留）
`kay-license-runtime.toml`	内置门户与授权配置（随包分发，用户无需修改）
`flintrix.toml`	在线 SKU 标识（`license_mode=online`）

3. 环境要求

操作系统

项	要求
架构	x86_64 (amd64)
发行版	Debian 11+ / Ubuntu 20.04+（推荐 22.04）；或 RHEL 8+ / CentOS Stream / Fedora / Rocky / AlmaLinux
内存	≥ 8 GB（大型测台建议 16 GB+）
磁盘	≥ 5 GB 可用

仿真器（至少一种）

仿真器	版本	环境变量
Verilator	≥ 5.025	`PATH` 含 `verilator`
Icarus	≥ 11.0	`iverilog`
VCS	S-2021.09+	`$VCS_HOME`
Questa	2021.3+	`$QUESTA_HOME`
Xcelium	21.3+	`$XCELIUM_HOME`

系统依赖（可选一键安装）

sudo /opt/flintrix/setup/install-deps.sh

脚本依次检查：glibc、运行时库、Verilator、Icarus、locale、Rust 1.92.0（仅当你从源码构建测台时需要）。

客户 deb / rpm 自带预编译二进制，日常只需仿真器，不必装 Rust。

门户连接（在线版）

门户地址在出包时写入安装包，与下载页站点一致，用户无需配置环境变量或 ~/.config 文件。

安装后由以下文件提供（只读，随包升级；请勿自行修改）：

文件	作用
`/opt/flintrix/kay-license-runtime.toml`	`server_url`、离线宽限等
`/opt/flintrix/flintrix.toml`	`license_mode=online`、`portal_url`

source /etc/profile.d/flintrix.sh 后即可使用 CLI / MCP；云端校验由软件自动完成。

4. Agent / MCP 安装（多端）

sudo /opt/flintrix/setup/install-klymora-agent.sh
bash /opt/flintrix/setup/install-klymora-agent.sh --agent-only
sudo /opt/flintrix/setup/install-klymora-agent.sh --tb /path/to/your_tb

install-agent-integration.sh（由上一脚本调用）会：

执行 klymora-mcp install，写入各 IDE 的 MCP 配置
将 /opt/flintrix/skills 软链到各 Agent 的 Skills 目录
同步 agent-rules 到 Cursor / Claude / Codex 等规则路径
运行 klymora-mcp doctor

支持的 Agent / IDE

类别	配置位置（全局或测台）
Cursor	`~/.cursor/mcp.json`、`.cursor/mcp.json`
OpenCode	`~/.config/opencode/opencode.json`、`opencode.json`
Kimi Code	`~/.kimi-code/mcp.json`、`~/.kimi/mcp.json`
Claude Code	`claude mcp add`
Claude Desktop	`~/.config/Claude/claude_desktop_config.json`
VS Code / Lingma / Trae	`~/.config/Code/User/settings.json`、`.vscode/mcp.json`
VS Code Continue	`~/.config/Continue/config.json`
Qoder（通义灵码）	`.qoder/rules/klymora-rules.md`
Codex / Claw 系	`~/.codexrules`、`~/.clawrules` 等

完整表格与验收步骤：MCP 与 Skills。

验证：

klymora-mcp doctor
cat /opt/flintrix/local/agent-integration.json

重启各 IDE 使 MCP / Skills / 规则生效。

多人共用同一台机器时：包只需装一次；每位使用者用自己的 Linux 用户执行 kay-license-runtime login 与上面的 --agent-only（授权与计费写在各自 HOME，互不覆盖）。细则见 CLI 登录与设备关联中「共享主机上的多用户」。

5. Skills 安装

Skills 源目录：/opt/flintrix/skills/。安装脚本会为 Cursor、OpenCode、Kimi Code、Claude Code 创建用户级软链，例如：

~/.cursor/skills
~/.opencode/skills
~/.kimi-code/skills
~/.claude/skills

项	说明
更新	升级 deb / rpm 后 `install-klymora-agent.sh --agent-only`
测台规程	`--tb <测台根>` 生成测台 `AGENTS.md`
MCP 读取	`klymora_list_skills`、`klymora_get_skill`

6. 安装后检查清单

source /etc/profile.d/flintrix.sh
klymora-run --help
klymora-mcp doctor
verilator --version

并在账户确认订阅有效。全部通过后参见快速开始。

7. 升级与卸载

升级：

DEB：sudo apt install ./flintrix-online_<new>_amd64.deb
RPM：sudo dnf upgrade ./flintrix-online-<new>-1.x86_64.rpm（或 dnf install 同路径新包）

升级后建议 install-klymora-agent.sh --agent-only 刷新 MCP/Skills。自定义文件请放在 /opt/flintrix/local/（升级保留）。

卸载：

DEB：sudo apt remove flintrix-online（/opt/flintrix 可能残留）
RPM：sudo dnf remove flintrix-online（会删除整个 /opt/flintrix，卸载前请备份 local/）

用户配置（如 ~/.config/klymora/）不会随包删除。

排错见常见问题。