napoler/geminicli repository overview

⁠Gemini CLI Docker 环境使用指南

本文档介绍了如何使用基于 Docker 的 Gemini CLI 环境。该环境预装了 Node.js 20、Gemini CLI、Jules 以及一系列精选的 Gemini 扩展插件。

您可以直接使用预构建的 Docker 镜像，无需本地构建。

⁠📋 前置要求

• Docker Desktop⁠ 或 Docker Engine
• Docker Compose⁠

⁠🚀 快速开始

⁠1. 准备配置文件

在您的项目根目录下创建一个 docker-compose.yml 文件，并粘贴以下内容：

version: "3.8"
services:
  gemini:
    image: napoler/geminicli:latest
    container_name: gemini-cli
    # 启用交互模式
    stdin_open: true
    tty: true
    environment:
      # 设置容器内的 HOME 目录为工作区，方便权限管理
      - HOME=/workspace
      # 可选：设置默认 Gemini 模型
      # - GEMINI_MODEL=gemini-2.0-flash
    volumes:
      # 1. 挂载当前目录到容器的工作区
      - .:/workspace
      
      # 2. 持久化 Gemini 配置和登录状态
      - gemini_config:/workspace/.gemini
      
      # 3. 持久化 Jules 登录状态
      - jules_config:/workspace/.jules
      
      # 4. (可选) 挂载 gcloud 凭据，如果需要访问 Google Cloud 资源
      # - ~/.config/gcloud:/workspace/.config/gcloud
    
    # 这里的 command 会覆盖 Dockerfile 中的默认启动命令
    # 如果您想保留默认行为（自动配置并启动 gemini），可以注释掉下面这行
    # command: /bin/bash

volumes:
  gemini_config:
  jules_config:

⁠2. 启动环境

在包含 docker-compose.yml 的目录下运行：

docker compose run --rm gemini

这将拉取最新镜像 napoler/geminicli 并启动交互式终端。

⁠🔑 身份验证与使用

⁠1. Jules 登录

由于 Docker 容器内没有图形界面，您需要使用无浏览器模式进行 Google 账号 身份验证：

1. 进入容器终端后，运行：

   jules login --no-launch-browser
   

   Copy
2. 终端会显示一个 验证码 和一个 验证链接（通常指向 Google 登录页面）。
3. 在您的宿主机浏览器中打开该链接，并输入终端显示的验证码。
4. 授权完成后，返回终端，Jules 会自动检测并提示登录成功。
5. 由于配置了 volumes，登录状态会保存到本地宿主机，下次启动容器无需再次登录。

⁠2. Gemini 使用

Gemini CLI 是一个强大的交互式 AI 辅助工具，主要操作如下：

• 启动交互模式: 直接运行 gemini。
• 执行任务: 在交互模式下，您可以直接描述您的需求，例如 "帮我重构这个函数" 或 "为 src/main.js 添加单元测试"。
• 常用命令:
  • /help: 查看所有可用命令。
  • /extensions: 管理已安装的扩展。
  • /jules: 调用 Jules 进行复杂的代码库分析和修改。
• YOLO 模式: 默认入口点使用了 --yolo 标志，这意味着 Gemini 在执行命令前不会逐一询问。如果您需要更谨慎的操作，可以手动启动 gemini（不带 --yolo）。

⁠🛠️ 环境说明

⁠文件挂载

docker-compose.yml 默认将当前目录 (.) 挂载到容器内的 /workspace。这意味着您在容器内对 /workspace 下的文件修改会直接反映到您的本地文件系统中。

⁠预装内容

该镜像 (napoler/geminicli) 基于 Debian Bookworm (Node.js 20)，预装了以下工具：

• 系统工具: git, curl, procps, python3 (及依赖)
• 核心工具:
  • gemini-cli (Latest)
  • jules (Latest)
• 预装扩展:
  • github-mcp-server
  • workspace
  • security
  • mcp-toolbox
  • 以及更多... (均已通过 --consent 自动确认安装)

⁠⚠️ 常见问题

Q: 如何更新镜像？ A: 运行 docker compose pull 获取最新版本的镜像。

Q: 为什么我修改了文件但容器里没变？ A: 请确保您是在 docker-compose.yml 所在的目录下运行命令，并且正确挂载了 - .:/workspace。

Q: 遇到权限问题？ A: 容器默认以 root 权限运行，挂载的文件可能会变为 root 所有。如果在 Linux 上使用，可以在 docker-compose.yml 中添加 user: "${UID}:${GID}" 配置（需要确保宿主机环境变量存在）。