国产化支持下的首启动 麒麟桌面安装察元AI的几个坑
国产 OS 上装第三方软件这件事，每装一次都有新坑。麒麟桌面 V10 是政企里覆盖率最高的国产桌面发行版之一，察元AI 桌面单机版在它上面有一份专门的发行包。这一篇把我自己装那一台麒麟笔记本的过程记下来，给同事们一份预案。
那台机器是某品牌的国产化笔记本，CPU 是飞腾 D2000，8 核 aarch64，内存 16G，磁盘 SSD，预装麒麟桌面 V10 SP1。之前装过一些办公软件，整体环境干净。我从内部资源拿到 chayuan-desktop_x.y.z_arm64.deb，目标是装上、跑通、做 RAG。
第一坑是依赖。麒麟自带的 webkit2gtk 版本对 Tauri 2 有点旧。dpkg -i 的时候报缺 libwebkit2gtk-4.1。麒麟的官方源里有 4.0，没有 4.1。我从麒麟开发者社区找到一份 4.1 的 deb 包，先装这个，再装 chayuan-desktop。整个过程没有联外网，全部从内部镜像拿。
第二坑是字体渲染。chayuan-desktop 的 React 前端用了几款常见英文字体加思源黑体做中文渲染。麒麟默认字体集对部分 emoji 字符不全，导致主界面有几个 unicode 显示成豆腐块。打开主界面之前先确认 fc-list :lang=zh 能列出思源系列，缺了就装 fonts-noto-cjk。这一步处理掉之后界面正常。
第三坑是 sidecar 启动。chayuan-server 是 PyInstaller 打的 onedir 形态，二进制依赖 glibc 2.31 以上。麒麟 V10 SP1 的 glibc 是 2.28。第一次启动报 GLIBC_2.31 not found。这个问题没有简单办法绕开，要么换 SP2 系统，要么在 chayuan-desktop 仓库里 build 一个 glibc 兼容版本。我们最终选了 SP2 升级的方案，IT 部门做了一次系统升级，问题消失。这个细节是国产 OS 装包的常见硬骨头，发行版差异很大。
第四坑是 sqlite-vec 扩展。chayuan-desktop 的本地离线知识库 默认走 sqlite-vec。这个扩展在 aarch64 上的预编译版需要专门提供。release 包里已经带了 aarch64 的 .so，但首次加载时被麒麟的安全模块拦了。日志里看到 SELinux 拒绝，需要用 audit2allow 生成策略，再 semodule -i 加载。或者在 IT 允许的前提下临时把 SELinux 设为 permissive 跑测试。
第五坑是端口监听。chayuan-desktop 默认 sidecar 监听 127.0.0.1:62581。麒麟默认有一个本地防火墙，对回环监听不限制，但部分企业版本会改默认策略。如果你看到 sidecar 起来了但前端连不上，先 ss -ltnp | grep 62581 看下监听是否成功，再 firewall-cmd --list-all 看防火墙规则。
第六坑是模型权重下载。首启动时 chayuan-desktop 需要把内嵌的 bge-m3-onnx 和 RapidOCR 权重落到 CHAYUAN_ROOT/models。如果是无外网环境，提前把权重文件准备好放到对应目录，跳过下载。文件大约一个 G。
第七坑是国产模型接入。这台麒麟笔记本主要给客户演示察元AI 怎么用国产 LLM。我配了文心一言和智谱清言两家厂商，钥匙填好后自动探测正常。视觉模型一栏选了通义千问 VL，对话也走通了。整个全模型支持 在国产 OS 上没遇到额外问题。
最后做了一次 RAG 演示。拖一份内部技术规范 PDF 进对话，文档解析、嵌入、入库、检索全部在本机完成，引用气泡能跳回原文。客户当场问我们 chayuan-wps WPS AI 插件 在麒麟版 WPS 上能不能跑。这个事 WPS Linux 版的加载项支持目前还在演进，建议在 Windows 客户端先用起来，麒麟桌面版做演示和单机使用，效果最稳。
国产化支持的一个重要心态是：发行版差异即工程差异。每碰到一个新发行版要预留半天时间做对账，之后的所有客户复制就快了。
