部署前先明确适用场景

Gemini CLI 是一款面向终端的 AI 命令行工具，特别适用于在 Linux 服务器上执行脚本解释、日志摘要、文档整理、命令生成、批量文本处理等任务。相较于网页端工具，它在运维、开发和内容生产流程中优势明显：可直接在 SSH 会话中调用，也能嵌入 Shell 脚本、定时任务或 CI 流程，有效减少工具切换成本。

在服务器上部署该工具，核心目标远不止“装上能用”。你需要确保环境可复现、凭证不外泄、进程可后台运行、日志可追踪、异常可恢复。强烈建议先在测试机或普通用户账号下完成验证，再迁移至生产服务器，避免将试验性配置直接暴露在关键业务环境中。

环境准备与版本检查

部署前，建议准备一台能正常访问外部 AI 服务接口的 Linux 服务器，常见发行版如 Ubuntu、Debian、CentOS Stream、Rocky Linux 均可胜任。服务器需具备基础命令工具，包括 curl、git、tar、systemctl 等。若系统为最小化安装，可先执行软件源更新，再补齐常用工具。

Gemini CLI 通常依赖 Node.js 运行环境，推荐使用 Node.js 18 或 20 以上版本。通过运行 node -v 和 npm -v 检查当前版本。如果系统自带版本过旧，建议使用 nvm 管理 Node 版本，方便后续升级与回滚。安装 nvm 后执行 nvm install 20，再执行 nvm use 20，最后用 node -v 确认生效。在生产环境中，不要频繁切换全局 Node 版本，最好固定到一个明确版本，降低依赖变动带来的风险。

安装 Gemini CLI

不同发行渠道的包名可能略有差异，部署时应以项目官方说明或可信软件源为准。常见方式是通过 npm 安装命令行工具，例如使用 npm install -g 安装对应 CLI 包。安装完成后，执行 gemini --version 或相应帮助命令，确认终端能够识别该命令。

如果出现 command not found，通常是 npm 全局目录未加入 PATH。可执行 npm config get prefix 查看安装前缀，再检查该目录下的 bin 路径是否在环境变量中。对于使用 nvm 的用户，重新登录 SSH 会话或执行 source ~/.bashrc、source ~/.profile，通常能解决路径未刷新的问题。

生产服务器不建议直接使用 root 账号长期运行 CLI。更稳妥的做法是创建一个专用普通用户，例如 aiworker，在该用户环境下安装工具，并仅授予任务所需的目录读写能力。这样即使脚本配置错误，也能将影响范围控制在最小。

配置 API 凭证与默认参数

Gemini CLI 调用模型服务通常需要配置 API Key 或类似凭证。建议将凭证写入环境变量，而不是硬编码到脚本中。例如在用户目录下创建 .env 文件，写入 GEMINI_API_KEY=你的凭证，并设置文件权限为 600，确保只有当前用户可读写。若工具支持配置文件，也应确认配置文件权限，避免被其他系统用户读取。

为便于日常使用，可在 Shell 配置文件中导出环境变量，但生产环境更推荐由 systemd 或任务脚本显式加载，减少误操作导致的凭证暴露。凭证应定期轮换，在离职交接、服务器迁移、日志异常时都要及时更新。切勿将 API Key 提交到 Git 仓库，也不要张贴到工单、群聊或公开文档中。

首次测试建议使用简短提示词，例如让工具输出一句系统状态说明，以确认认证、网络、模型响应均正常。随后再测试长文本、中文输入、文件读取等场景，观察响应时间、字符限制与错误提示。

命令行基本用法与脚本化思路

Gemini CLI 最常见的使用方式是在终端中直接输入提示词，例如让它解释某段日志、生成 Shell 脚本草案、总结 README 内容。对于文件处理，可以通过管道把内容传入 CLI，例如 cat app.log | gemini "请总结异常原因"。这种方式适合临时排查，也便于与 grep、awk、sed 等传统命令组合。

在脚本化场景中，建议将提示词模板、输入文件、输出文件分离。脚本只负责读取输入、调用 CLI、保存结果，不要将复杂业务规则全部写进一行命令。这样后续调整提示词、切换模型或增加重试逻辑时更容易维护。对于批量任务，应加入速率控制和失败重试，避免短时间内发起大量请求导致接口报错或费用不可控。

使用 systemd 实现后台运行

如果只是偶尔使用，SSH 会话中直接运行即可；如果需要长期驻留、定时处理或作为内部服务调用，就应使用 systemd 管理。可以创建一个工作目录，例如 /opt/gemini-cli-worker，放置脚本、配置和日志目录。脚本中读取 .env，执行具体的 CLI 任务，并把输出写入日志文件。

创建 systemd 服务时，应设置 User 为专用普通用户，WorkingDirectory 指向工作目录，EnvironmentFile 指向 .env 文件，ExecStart 指向启动脚本。Restart 可设置为 on-failure，RestartSec 设置为 10 到 30 秒，避免异常后频繁重启。保存服务文件后执行 systemctl daemon-reload，再执行 systemctl enable 服务名 和 systemctl start 服务名，即可实现开机自启与后台运行。

查看状态可使用 systemctl status 服务名，查看实时日志可使用 journalctl -u 服务名 -f。如果日志量较大，应配置 logrotate 或在脚本中按日期分文件，防止磁盘被日志占满。不要把完整输入内容、API Key、客户资料等敏感信息直接写入日志。

定时任务与队列处理

对于每天固定时间生成摘要、扫描日志、整理文档的场景，cron 比常驻服务更简单。可以把命令写成脚本，再通过 crontab 配置执行周期。cron 环境变量较少，常见问题是找不到 node 或 gemini 命令，因此脚本中最好写完整路径，或在开头显式加载 nvm 环境。

如果任务量较大，建议不要让多个 cron 任务同时调用模型。更稳妥的做法是把待处理文件放入队列目录，由一个后台进程按顺序处理，并记录成功、失败和重试状态。这样便于限流，也便于定位某个文件为何处理失败。

升级、回滚与兼容性注意事项

升级前应记录当前 Node 版本、CLI 版本、关键配置和服务文件内容。可以先在测试目录安装新版本，运行同样的输入样例，对比输出格式、错误码和参数兼容性。确认无误后再切换生产环境。

如果通过 npm 全局安装，回滚时可指定旧版本重新安装；如果使用 nvm，也可以快速切回旧 Node 版本。服务化部署时，升级后要执行 systemctl restart 服务名，并观察 journalctl 日志至少数分钟。不要在业务高峰期直接升级核心任务，尤其是已经与自动化流程绑定的脚本。

常见问题排查

一是认证失败。通常与 API Key 未加载、变量名写错、凭证失效有关。可在同一用户下执行 env | grep GEMINI 确认环境变量是否存在，但排查结束后不要把输出截图外传。

二是命令在手动执行时正常，放到 systemd 或 cron 后失败。多半是 PATH、工作目录或权限不同。解决思路是使用绝对路径，明确 WorkingDirectory，并检查脚本是否具有可执行权限。

三是响应很慢或偶发超时。可增加超时时间、减少单次输入长度、加入重试机制，并记录失败原因。若任务对时效要求很高，应在流程中设计降级方案，例如失败时先保存原文，稍后再次处理。

四是中文输出不稳定。可以在提示词中明确要求输出语言、格式和字段，不要只写模糊指令。对于需要机器解析的结果，应要求返回固定结构，并在脚本中做格式校验。

安全边界与实用建议

AI 命令行工具适合辅助分析与生成，但不应直接接管关键系统操作。让它生成脚本后，必须由人工审阅再执行，尤其是涉及删除文件、修改配置、批量替换、重启服务等动作。对于生产日志，应先脱敏再提交，避免将账号、密钥、客户信息、内部域名等内容发送到外部模型服务。

建议为 Gemini CLI 建立专用目录、专用用户、专用凭证和专用日志策略。脚本中加入输入大小限制、超时限制和错误处理；服务中加入重启策略但不要无限高频重启；文档中记录安装方式、版本号、负责人和回滚步骤。这样部署出来的 AI 命令行工具才不只是临时玩具，而是可维护、可审计、可持续使用的服务器能力。