简介:本文面向个人电脑开发者,按核查、安装、密钥、初始化、回滚的顺序完成命令行工具的本地部署。你会学到版本矩阵的核对方法,如何用用户级目录安装而不依赖sudo,如何把密钥放进环境变量并确认配置目录中没有明文,以及如何备份配置并演练回滚。文末列出常见报错的定位思路。
本文适用于64位Windows 10/11、macOS和主流Linux发行版。工具通过npm分发。文中示例包名为ai-cli,配置目录为~/.ai-cli,密钥变量名为AI_CLI_API_KEY。这些值只是示例,实际的包名、命令名、配置目录和密钥变量名以该工具的官方文档为准。阅读命令前,请先把示例值替换为你所用工具的实际值。
全文流程分为六步:核查环境、用户级安装、设置密钥、初始化与验收、备份与回滚演练、排错与维护。
完成本文后,应满足以下验收标准:
本文面向单机使用。多人共用、长期对外提供服务或高并发场景,应改用服务器部署,并增加进程守护、统一日志和访问控制。
安装前先核对现有环境。版本不符时,安装过程常出现语法错误或依赖解析失败,而错误信息通常不直接指向版本问题,所以应先核对版本。
| 组件 | 最低版本 | 推荐版本 | 核对命令 | 说明 |
|---|---|---|---|---|
| Node.js | 18.17 | 20.x或22.x LTS | node -v |
18.x可以使用,但新版本更稳定 |
| npm | 10.x | 随Node.js 20及以上版本捆绑的10.x | npm -v |
Node 18捆绑的npm可能是9.x,需要单独升级 |
| Git | 2.30 | 2.30及以上 | git --version |
仅在工具要求从Git仓库拉取技能或插件时需要 |
| Python | 3.8 | 3.11或3.12 | python3 --version(Windows用python --version或py --version) |
3.8已于2024年10月结束支持,仅运行依赖Python脚本的技能时需要 |
Node.js与npm的对应关系需要注意两点。
npm -v显示9.x,请先把Node.js升级到18.17以上,再执行npm install -g npm@10,然后重新核对版本。最新的LTS版本号以Node.js官方网站为准。Windows用户在PowerShell中若提示找不到命令,通常是因为刚安装的程序尚未加入当前会话的PATH。关闭终端并重新打开即可。若提示脚本执行被禁用,可以先在PowerShell中执行Get-ExecutionPolicy查看当前策略,再按公司或个人设备的规定调整。
硬件要求按两档规划。下表数值是规划参考,不是官方指标,实际需求以工具文档为准。
| 资源项 | 基础运行档(仅安装和运行命令) | 本地模型档(运行本地模型) |
|---|---|---|
| 处理器 | x86_64或arm64,四核及以上 | 八核及以上 |
| 内存 | 8 GB及以上 | 16 GB及以上,模型越大需求越高 |
| 可用磁盘 | 2 GB及以上 | 按模型文件大小预留,通常需要数十GB |
| 显卡 | 不需要 | 视模型和推理框架而定 |
只使用云端模型服务的读者,可以只参考基础运行档。本地模型档适用于需要离线推理的场景。
全局安装的默认目录通常需要管理员权限。直接使用sudo npm install -g会让包文件归属root,后续更新和卸载都容易出错。更稳妥的做法是把npm的全局目录改到当前用户可写的位置。
Windows通常无需修改。Node.js安装程序默认把全局目录设为%APPDATA%\npm,并自动加入PATH。若你之前改过这个设置,可以在PowerShell中执行下面的命令恢复:
npm config set prefix "$env:APPDATA\npm"
macOS和Linux需要手动设置。以下命令以bash或zsh为例:
mkdir -p "$HOME/.npm-global"npm config set prefix "$HOME/.npm-global"
然后把全局命令目录加入PATH。在~/.zshrc(bash用户写入~/.bashrc)末尾加入一行:
export PATH="$HOME/.npm-global/bin:$PATH"
保存后执行source ~/.zshrc,或者直接开一个新终端。用echo $PATH确认输出中包含该目录。
接下来安装工具。下面的命令以示例包名为准:
npm install -g ai-cli
安装完成后,用下面的命令确认命令可以被找到,并查询版本:
command -v ai-cliai-cli --version
Windows PowerShell中对应的命令是Get-Command ai-cli和ai-cli --version。如果找不到命令,检查全局目录是否在PATH中。
密钥不要写进命令行参数,也不要写进工具的配置文件。命令行参数会留在shell历史中,配置文件则容易被备份、同步或提交到代码仓库。推荐做法是把密钥保存在用户级环境变量中,并让工具从环境变量读取。
macOS和Linux使用下面的方式输入密钥。read -rs在输入时不回显,也不会把值留在屏幕上:
read -rs AI_CLI_API_KEY_INPUTprintf 'export AI_CLI_API_KEY="%s"\n' "$AI_CLI_API_KEY_INPUT" >> "$HOME/.zshrc"unset AI_CLI_API_KEY_INPUTchmod 600 "$HOME/.zshrc"
这样密钥会以明文形式保存在shell启动文件中。它只在你的账户下可读,但仍然是明文。如果你的系统提供钥匙串或密码管理器,并且工具支持从中读取,优先使用那种方式。
Windows使用PowerShell,把密钥保存为用户级环境变量:
$secure = Read-Host "输入密钥" -AsSecureString$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)$key = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)[Environment]::SetEnvironmentVariable("AI_CLI_API_KEY", $key, "User")[Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)Remove-Variable key, secure, ptr
设置后,打开新的终端窗口。用下面的命令确认变量存在,但不要打印它的值:
[ -n "$AI_CLI_API_KEY" ] && echo "已设置" || echo "未设置"if ($env:AI_CLI_API_KEY) { "已设置" } else { "未设置" }执行初始化命令。以下以示例命令为准,实际子命令请查看官方文档:
ai-cli init
初始化会在~/.ai-cli下生成配置。接下来逐条检查验收标准。
第一,确认配置目录可写。在macOS和Linux上执行touch ~/.ai-cli/.write-test && rm ~/.ai-cli/.write-test,两条命令都返回0即可。Windows可以用New-Item "$env:USERPROFILE\.ai-cli\.write-test"创建测试文件,再用Remove-Item删除。
第二,收紧目录权限。配置目录只应由当前用户访问:
chmod 700 ~/.ai-clifind ~/.ai-cli -type f -exec chmod 600 {} +
第三,确认配置文件中没有明文密钥。在macOS和Linux上执行:
[ -n "$AI_CLI_API_KEY" ] && grep -rlF -- "$AI_CLI_API_KEY" ~/.ai-cli
命令没有输出,说明没有找到包含密钥的文件。如果输出了文件路径,打开该文件,删除明文密钥,改用环境变量引用,然后轮换这个密钥,因为它已经暴露在文件中。Windows可以在同一个PowerShell会话中执行:
Get-ChildItem -Recurse "$env:USERPROFILE\.ai-cli" -File | Select-String -Pattern ([regex]::Escape($env:AI_CLI_API_KEY)) -List
第四,确认版本查询返回正确的版本号,并检查返回码。bash或zsh中执行ai-cli --version; echo $?,返回码为0表示命令正常退出。PowerShell中使用ai-cli --version; $LASTEXITCODE。
第五,记录当前状态。把版本号和配置目录位置写入你的部署记录,例如:
ai-cli --version > "$HOME/ai-cli-deploy-record.txt"npm ls -g ai-cli >> "$HOME/ai-cli-deploy-record.txt"
升级工具前,先备份配置。不同版本之间的配置格式可能不兼容,没有备份就无法安全回退。备份命令如下:
mkdir -p "$HOME/ai-cli-backups"tar czf "$HOME/ai-cli-backups/ai-cli-config-$(date +%Y%m%d-%H%M%S).tar.gz" -C "$HOME" .ai-cli
备份文件位于你的用户目录中。它不应包含密钥,但仍然包含配置信息,请不要上传到公共网络或共享仓库。
查看可用的历史版本:
npm view ai-cli versions --json
回滚到指定版本时,把版本号替换为你记录的值:
npm install -g ai-cli@<旧版本号>
恢复配置时,先停止正在运行的工具进程,再解压备份:
mv "$HOME/.ai-cli" "$HOME/.ai-cli.bak-$(date +%s)"tar xzf "$HOME/ai-cli-backups/你的备份文件.tar.gz" -C "$HOME"
解压前先把当前配置改名保留,而不是直接覆盖。确认旧版本能正常运行后,再删除保留的目录。
建议至少完整演练一次:备份,升级到另一个版本,恢复旧版本和旧配置,再执行ai-cli --version和一次简单的命令调用。演练通过后,把步骤和结果记入部署记录。
如果回滚涉及的旧版本曾在日志或截图中暴露过密钥,应在服务商后台轮换密钥,并更新环境变量。
下表列出常见报错的定位思路。
| 现象