银河麒麟V10安装CodeBuddy：x86与飞腾ARM架构适配指南-开发者社区

单位最近要做国产化终端适配，开发组提了个需求：在银河麒麟V10上装一套AI编程助手，机器既有x86的，也有飞腾D2000这种arm64架构的，最后选定用CodeBuddy。本来以为就是个安装包的活，结果从依赖库、权限模型到GPU渲染，一路踩了不少坑。我把整条路重新走了一遍，记录在这里，给同样要在麒麟V10上跑CodeBuddy的兄弟省点时间。

先说结论：CodeBuddy在麒麟V10上完全能跑，但前提是你得先把系统的版本、CPU架构、包管理方式、运行依赖这四个变量搞清楚。下面按实操顺序讲。

1. 为什么偏偏是CodeBuddy和麒麟V10这个组合

1.1 CodeBuddy到底是什么，和WorkBuddy怎么区分

CodeBuddy是腾讯云推出的AI编程助手，形态上有三种：一是基于VS Code内核改造的独立AI IDE，二是可以装进现有VS Code里的扩展插件，三是命令行工具（CLI）和Agent SDK。核心能力包括代码补全、仓库级问答，以及现在大家讨论比较多的Agent模式——你给它一个任务描述，它能自己读代码、改文件、执行命令，像一个能帮忙干活的AI开发助理。

很多人在搜索里问“CodeBuddy和WorkBuddy有什么区别”，我实际对比下来的感受是：两者定位完全不同，别混为一谈。CodeBuddy是给开发者用的，面向IDE、代码补全、代码审查、自动修bug、仓库理解这些工程链路；WorkBuddy更偏向通用办公和业务自动化，面向的是非开发人员也能用的场景，比如周报生成、材料整理、业务流程机器人。底层可能共享了部分平台能力，但账号体系、安装包、产品定位都是分开的。如果你是要写代码，装CodeBuddy就对了，WorkBuddy解决不了你编译报错的问题。

1.2 麒麟V10不是一套系统，先弄清版本再动手

麒麟V10这个名字听起来像是一个系统，实际上一头扎进去才发现它分很多种。最常见的是银河麒麟桌面版和银河麒麟服务器版，两者包管理方式完全不同。桌面版通常走Debian系，软件包以deb为主，用apt和dpkg来装；服务器版则偏向RPM系，用yum或dnf。不同SP版本之间内核版本、库的版本也有差异，有的SP3已经升级了底层基础库，导致同一个deb包在不同版本上表现不一样。

更要命的是CPU架构。国产终端里x86_64很常见，但还有大量的aarch64设备，比如飞腾D2000、飞腾S2500、鲲鹏920，这些ARM芯片只能跑arm64的包。搜热词里频繁出现“银河麒麟v10 cpud2000 cpu内核架构”，说明很多人就是在飞腾D2000上卡住了。x86的安装包和arm64的安装包绝对不能互换，就算强行装上，启动也会报各种诡异错误。

判断方法很简单，两条命令搞定：

cat /etc/os-release uname -m

uname -m输出x86_64就下载amd64包，输出aarch64就下载arm64包。这一条不确认，后面全白干。

2. 安装前的三步准备：架构、源、依赖

2.1 先把系统基础信息查一遍

我建议新建一个机器之后，不要急着下载软件，先用下面一组命令把环境摸清楚：

# 系统版本和代号 cat /etc/os-release # CPU架构 uname -m arch # CPU核数和内存 nproc free -h # 磁盘空间，CodeBuddy这类Electron应用装完加缓存，个位数GB空间是至少的 df -h

输出结果里重点看两个字段：一是/etc/os-release里的版本信息，确认是桌面版还是服务器版；二是uname -m，确认架构。比如我测试机输出类似Kylin V10 Desktop release加aarch64，那我后面所有操作都按“Debian系包管理 + arm64架构”来处理。

2.2 软件源是前置条件，源不好后面全是坑

麒麟系统默认自带的软件源有时候不太稳，源配置不对，依赖库装不上，CodeBuddy装了也白装。我的建议是：在线环境下，优先保留麒麟官方源，不要图快随便换CentOS或Ubuntu源，因为麒麟对部分基础库做过定制，乱换源轻则更新冲突，重则把桌面环境搞崩。

源配好之后先刷新缓存：

# 桌面版/deb系 sudo apt update # 服务器版/rpm系 sudo yum makecache

对于离线内网环境，情况更复杂。热词里有人搜“linux 麒麟v10搭建yum源”，说的就是这种场景——把麒麟安装镜像挂载到本地，做一个本地仓库地址，让yum或apt都指向本地目录。这套东西在服务器版上尤其常见，因为很多内网机器根本拉不到外部源。实际操作上就是挂载ISO、配置repo文件里的baseurl指向挂载目录、然后yum clean all && yum makecache。deb系离线环境则要麻烦一些，需要提前下载好依赖的deb包，用dpkg -i配合apt-get install -f组合拳来打补丁。

2.3 把Electron应用的公共依赖一次性装齐

CodeBuddy本质上是Electron应用，底层是Chromium，在Linux上要跑起来需要一堆图形、音频、安全相关的库。这也是为什么很多人安装包装好了，双击图标却没反应，跑终端一看全是缺so文件。

我整理了最常缺的一批依赖。

# 桌面版/deb系 sudo apt-get install -y \ libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 \ libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \ libxrandr2 libgbm1 libasound2 libgtk-3-0 libpango-1.0-0

# 服务器版/rpm系，包名可能略有差异，缺什么再补什么 sudo yum install -y \ nss nspr atk at-spi2-atk cups-libs \ libdrm libxkbcommon libXcomposite libXdamage libXfixes \ libXrandr libgbm alsa-lib gtk3 pango

为什么要装这一堆？简单解释一下：libnss3是Chromium网络安全模块的依赖，不装直接报找不到库；libgbm和libdrm是GPU图形分配相关的库，不装可能黑屏或渲染异常；libgtk-3-0和libatk系列是Electron做UI集成和辅助功能用的；libasound2负责音频输出。在arm64环境下，系统源里能拉到对应架构的版本，一般不用手动指定架构。

我踩过最深的坑就是依赖没装齐就急着装主程序，结果启动时报错一次补一个库，来回折腾半天。正确方式是把依赖一次装齐，再装CodeBuddy本体，后面会顺利得多。

3. CodeBuddy安装实操：从下载到桌面图标

3.1 下载哪个安装包：deb、rpm还是tar.gz

确认架构之后，去CodeBuddy官网或对应的GitHub Release页面下载安装包。文件名里通常有架构标识，比如amd64、x86_64代表x86，arm64、aarch64代表ARM。别只看文件名，下载回来立刻用命令验一下：

# deb包查看架构信息 dpkg-deb --info codebuddy_xxx_arm64.deb | grep Architecture # rpm包查看架构信息 rpm -qip codebuddy-xxx.aarch64.rpm | grep Architecture

选哪种包？我个人建议按场景来：

机器上已经有比较完备的图形依赖，想省事就装deb或rpm包，系统帮你管理文件位置和菜单项；
离线内网、不想污染系统目录、希望随下随用，就选tar.gz绿色版或AppImage，解压到/opt下就能跑；
如果只是想在一两台机器上测试，便携版优势最大，删掉目录就等于卸载，不会在系统里留一堆东西。

3.2 deb、rpm、tar.gz三种安装方式

deb系安装：

sudo dpkg -i codebuddy_xxx_arm64.deb

如果报依赖错误，不要慌，这是dpkg不自动处理依赖的典型表现。执行修复命令：

sudo apt-get install -f

它会自动把缺失的依赖补齐，之后再确认一下CodeBuddy是否安装成功。

rpm系安装：

sudo rpm -ivh codebuddy-xxx.aarch64.rpm

或者用dnf安装，dnf会自动处理依赖：

sudo dnf install ./codebuddy-xxx.aarch64.rpm

tar.gz绿色版安装：

sudo mkdir -p /opt/codebuddy sudo tar -zxvf codebuddy-xxx-linux-arm64.tar.gz -C /opt/codebuddy sudo ln -s /opt/codebuddy/codebuddy /usr/local/bin/codebuddy

软链接的意思是以后在任意目录敲codebuddy都能启动程序，不需要进安装目录找启动脚本。

安装完成后，命令行验证：

codebuddy --version

能输出版本号，说明程序本身没问题，剩下就是图形环境的事了。

3.3 Electron启动失败的经典三连：沙箱、缺库、GPU

这是CodeBuddy在麒麟V10上最容易翻车的三个地方，我一个个说。

第一，SUID沙箱权限问题。Chromium的沙箱机制需要chrome-sandbox文件有特殊权限，很多情况下解压或安装后这个文件权限不对，启动就会报“The SUID sandbox helper binary was found, but is not configured correctly”。解决办法是修正属主和权限：

sudo chown root:root /opt/codebuddy/chrome-sandbox sudo chmod 4755 /opt/codebuddy/chrome-sandbox

注意路径要换成你自己的安装目录。如果是deb安装，可能在/usr/lib/codebuddy/下。

第二，缺动态库。启动后报libxxx.so: cannot open shared object file，直接看缺的是哪个库，用包管理器补。排查一条命令就够：

ldd /opt/codebuddy/codebuddy | grep "not found"

输出里列出哪些库没找到，按名字装对应包就行。

第三，GPU渲染问题。飞腾D2000这类ARM机器集成显卡驱动在Chromium里兼容性一般，表现为启动后白屏、黑屏、界面闪烁。解决办法是软件渲染或关闭GPU加速：

codebuddy --disable-gpu

如果还是不行，加一条环境变量：

LIBGL_ALWAYS_SOFTWARE=1 codebuddy

如果这些参数能解决问题，建议直接写进桌面快捷方式里，避免每次手动敲。

3.4 没有桌面图标？自己生成快捷方式

部分场景下，安装完才发现桌面菜单里找不到CodeBuddy图标。不用重新装，自己手动建一个.desktop文件就行：

[Desktop Entry] Name=CodeBuddy Comment=AI Code Assistant Exec=/opt/codebuddy/codebuddy --no-sandbox --disable-gpu Icon=/opt/codebuddy/resources/app/icon.png Terminal=false Type=Application Categories=Development;

把内容保存到~/.local/share/applications/codebuddy.desktop，然后刷新桌面数据库：

update-desktop-database ~/.local/share/applications/

如果麒麟桌面本身有开始菜单消失或图标不刷新的毛病，重启一下面板进程一般能解决，这是UKUI环境的通用问题，和CodeBuddy关系不大。

4. 登录、模型通道与Agent配置

4.1 账号登录和服务连通性

安装完成、能启动界面之后，第一次打开需要登录账号。CodeBuddy走的是云端账号体系，登录后会调用官方模型服务，所以机器必须能连通CodeBuddy的服务端。

到这里有人会问：我的麒麟机器在隔离内网里，根本连不上外网怎么办？两个思路：要么通过单位允许的网络出口访问服务，要么走本地模型通道。在隔离内网里，最靠谱的方案是把模型能力内网化，也就是下面的本地模型接入。

4.2 接本地vLLM部署的Qwen3，tool-call-parser到底填什么

热门问题里有一个特别具体：“CodeBuddy接入本地vLLM部署Qwen3，tool-call-parser填什么”。这确实是很多人在内网落地的真实场景：用内网GPU服务器部署一个开源模型，再让CodeBuddy对接这个本地服务。

先看vLLM侧怎么启动。比如用Qwen3-8B模型，命令行如下：

python -m vllm.entrypoints.openai.api_server \ --model /data/models/Qwen3-8B \ --served-model-name Qwen3-8B \ --host 0.0.0.0 \ --port 8000 \ --tool-call-parser qwen3

这里面的--tool-call-parser qwen3就是关键。vLLM需要把模型输出的文本解析成结构化的工具调用（function call），才能让Agent去真正执行“读文件、改代码、跑命令”这些动作。Qwen3系列的对话模板和工具调用格式跟Qwen2.5不一样，所以在较新版本的vLLM里直接用qwen3这个解析器就行。如果你用的vLLM版本比较老，启动时提示不支持qwen3parser，那就得先升级vLLM，别硬填别的解析器，容易导致工具调用解析失败。

服务起来之后，用curl验证一下：

curl http://127.0.0.1:8000/v1/models

能看到返回的模型列表，说明服务正常。接下来在CodeBuddy的模型设置里，新增一个自定义/兼容OpenAI的模型通道：

服务地址（Base URL）：http://127.0.0.1:8000/v1
模型名称：Qwen3-8B，必须和vLLM启动时--served-model-name保持一致
API Key：vLLM默认不校验，随便填一个非空字符串即可

这里有一个很容易被忽略的点：CodeBuddy的Agent模式要真正干活，光有对话能力不够，还得让模型正确使用工具。所以除了模型本身要支持function calling，解析器也必须匹配。如果哪天发现模型在对话框里“说得头头是道”，但工具就是不执行，十有八九是tool-call-parser没配对。

4.3 关于Skills和扩展能力

CodeBuddy支持Skills机制，相当于给Agent预置一些技能包，比如代码规范检查、特定框架生成、单元测试生成等。在设置里导入下载好的Skill文件就能用。这块在企业统一推广时很实用，把团队规范沉淀成Skill，所有人共享一套AI行为标准。

5. 高频问题排查速查表（全部实测过）

我把这段时间在麒麟V10上遇到的和同行交流过的高频问题统一整理成一张速查表，方便你直接对照处理。

现象	常见原因	解决办法
双击图标无反应	Electron依赖缺失或启动参数异常	终端直接跑`codebuddy`看报错，优先排查缺库
提示libnss3.so找不到	nss库未安装	按上文批量装依赖库
SUID sandbox helper配置不正确	chrome-sandbox权限错	`chown root:root`+`chmod 4755`
打开后白屏/黑屏	ARM GPU驱动兼容性问题	启动加`--disable-gpu`或`LIBGL_ALWAYS_SOFTWARE=1`
中文输入法打不出候选词	输入法模块环境变量没传给Electron	启动前设`GTK_IM_MODULE=fcitx`、`QT_IM_MODULE=fcitx`、`XMODIFIERS=@im=fcitx`
使用本地模型时Agent不执行工具	tool-call-parser与模型不匹配	改用`qwen3`解析器或升级vLLM
离线环境依赖装不上	没有可用软件源	挂载本地ISO搭建本地yum/apt源
麒麟桌面开始菜单消失	UKUI面板进程异常，与CodeBuddy无关	重启面板进程或注销重新登录

这里再说两个容易被忽略的实操点。

第一，Electron应用启动异常时，一定要先在终端里用命令行跑一遍。图形界面只会弹“无法启动”，终端能把缺失的动态库路径、权限错误全部打出来。这一条比任何排查工具都管用。

第二，中文输入法的问题。麒麟桌面常用fcitx输入法框架，但Electron应用如果没继承到输入法相关环境变量，就会出现“能打字但看不到候选词”的尴尬情况。解决办法是在启动命令前加环境变量，或者直接改进.desktop文件里的Exec行。如果你用的是ibus，把fcitx换成ibus即可。

6. 让CodeBuddy在麒麟上跑得更顺的几条建议

如果你的终端是飞腾D2000这种ARM设备，图形IDE全开确实吃力——目录索引、模型请求渲染、代码高亮都是开销。我测试下来的体验是：在小机上跑完整IDE能用，但流畅度谈不上好。这种情况建议切换工作模式。

第一，把重活交给远程服务器。在同一内网里找一台性能好的x86服务器安装CodeBuddy，本地麒麟机器通过VS Code Remote-SSH连过去开发。本地只做显示和输入，索引、编译、Agent跑命令全在远程完成，体验会质变。这种方式对麒麟终端要求很低，老旧ARM设备也能流畅。

第二，善用CLI模式。CodeBuddy的命令行工具适合快速问答、批量代码审查、脚本集成这类轻量任务，不占GUI资源，在服务器版麒麟上尤其好用。比如在CI流程里对接CodeBuddy Agent SDK，让AI自动做静态检查的初步分析，这些场景根本不需要图形界面。

第三，版本升级前先在测试机上验证。麒麟V10的库版本和主流Ubuntu/CentOS有差异，CodeBuddy升级后有可能引入新的依赖需求。我个人的习惯是：任何版本变更，先在备机上把“卸载旧版—装新版—验证启动—验证Agent”全流程跑一遍，确认没问题再推生产机。别拿生产环境当试验田。

最后再分享一个小技巧：内网离线交付时，不要只给一个安装包。把安装包、依赖库、chrome-sandbox权限修复命令、启动参数、.desktop配置全部放进一个交付脚本里，一键执行。你永远不知道客户机器的软件源状态，与其让他在缺库报错里原地打转，不如把环境一起打包交付。这样一套流程下来，CodeBuddy在麒麟V10上从安装到稳定使用就不再是什么玄学问题了。