Gemini-CLI-Termux 自动化部署工具

💡 项目声明 本项目基于 geminicli2api 进行二次开发，提供 Termux 环境下的自动化部署和管理功能。

📌 项目简介

Gemini-CLI-Termux 是一个专为 Android Termux 环境设计的自动化部署工具，让你能够轻松在手机上运行 Gemini API 反向代理服务。通过交互式菜单界面，无需复杂的命令行操作，即可完成服务的安装、配置和管理，并使用 OpenAI 兼容接口调用 Google Gemini 2.5 系列模型。

✨ 为什么选择本项目？

• 🚀 一键部署：单条命令完成所有安装配置
• 🎯 零门槛：交互式菜单，无需命令行基础
• 🔧 易于管理：可视化配置修改，实时生效
• 🌐 局域网支持：多设备共享，手机变身API服务器
• 📱 移动优先：专为 Termux 环境深度优化
• 🔄 持续更新：菜单内一键更新到最新版本

🎯 核心功能亮点

🤖 Gemini 模型全系列支持

• Gemini 3.1 Pro: 🌟 最新一代高级多模态模型，支持超长上下文（1M tokens）
• Gemini 3 Pro: 🌟 新一代高级多模态模型，支持超长上下文（1M tokens）
• Gemini 3 Flash: 🌟最新一代快速高效的多模态模型
• Gemini 2.5 Pro: 高级多模态模型，支持超长上下文（1M tokens）
• Gemini 2.5 Flash: 快速高效的多模态模型
• 多版本支持:
  • Gemini 3.1 Pro Preview
  • Gemini 3 Pro Preview
  • Gemini 3 Flash Preview
  • Gemini 2.5 Pro
  • Gemini 2.5 Flash
• 模型变体: 支持 search（搜索增强）、nothinking/maxthinking（思考模式）等变体
• 灵活配置: 可调节温度、top_p、top_k 等生成参数

🔐 多种认证方式

• HTTP Basic Auth: 用户名密码认证
• Bearer Token: 标准 OAuth 2.0 令牌认证
• API Key 查询参数: URL 参数传递密钥
• Google API Key 头: x-goog-api-key 头部认证
• 默认密钥: 123（可通过 .env 文件修改）

🌐 双 API 接口支持

• OpenAI 兼容接口: /v1/chat/completions, /v1/models
• 原生 Gemini 接口: /v1beta/models/*, /v1/models/*
• 流式响应: 完整支持 streaming 响应模式（SSE）
• 批量处理: 支持非流式批量请求处理

📖 目录

• 项目简介
• 核心功能亮点
• 快速开始
• 前置要求
• 功能特性
• API 文档
• 默认配置
• 故障排查
• 更新与维护
• 使用示例
• 项目结构
• 技术栈
• 许可证
• 致谢
• 问题反馈

⚡ 快速开始

📺 视频教程

强烈推荐先观看视频教程： B站完整演示

🚀 一键安装

在 Termux 中执行：

curl -O https://raw.githubusercontent.com/print-yuhuan/Gemini-CLI-Termux/main/Setup.sh && bash Setup.sh

📋 安装流程

脚本将自动完成以下步骤：

安装完成后将自动进入交互式主菜单。

📋 前置要求

1️⃣ Termux 应用

⚠️ 重要提示：请从官方渠道下载，避免使用 Google Play 版本（已停止维护）

2️⃣ Google Cloud 配置

💡 新手提示：配置 Google Cloud 是使用本项目的必要步骤，但非常简单！脚本会自动打开浏览器帮助你完成配置。

📝 配置步骤

🌐 便捷功能：使用菜单选项 4. 谷歌云项 可自动打开相应的 Google Cloud 页面（通过 termux-open-url 命令）

✅ 快速验证

使用菜单选项 4. 谷歌云项 可以快速访问：

• 获取项目 ID
• 管理 Gemini for Google Cloud API
• 管理 Gemini Cloud Assist API

🚀 功能特性

🎛️ 交互式管理菜单

==== Gemini-CLI-Termux 主菜单 ====
0. 退出脚本
1. 启动服务         - 运行 OpenAI 兼容 API 服务
2. 重新授权         - 清理缓存并重新登录 Google Cloud
3. 修改配置         - 修改密码/项目ID/端口/局域网等
4. 谷歌云项         - 快速访问 Google Cloud 控制台
5. 系统管理         - 更新/重新部署/卸载服务
6. 关于脚本         - 查看作者信息和联系方式

🔧 配置管理功能

通过 主菜单 → 3. 修改配置 进入配置菜单：

🌐 局域网访问功能

通过 主菜单 → 3. 修改配置 → 5. 局域网配置项 进入局域网配置：

🔐 系统管理功能

通过 主菜单 → 5. 系统管理 进入管理菜单：

📖 API 文档

🔌 基础信息

🔑 认证方式

支持以下 4 种认证方式（默认密码：123）：

curl -u admin:123 http://127.0.0.1:8888/v1/models

curl -H "Authorization: Bearer 123" http://127.0.0.1:8888/v1/models

curl http://127.0.0.1:8888/v1/models?key=123

curl -H "x-goog-api-key: 123" http://127.0.0.1:8888/v1/models

🎯 API 端点

OpenAI 兼容接口

可用模型列表：

原生 Gemini 接口

📊 HTTP 状态码

🔧 默认配置

📝 配置文件说明

项目包含两个主要配置文件：

⚙️ 默认配置参数

⚠️ 配置注意事项

📍 配置示例

# .env 配置文件示例
GEMINI_AUTH_PASSWORD=your_secure_password_here  # 默认：123
HOST=127.0.0.1
PORT=8888
GOOGLE_CLOUD_PROJECT=my-cloud-project-123456    # 必须修改为你的项目 ID
GOOGLE_APPLICATION_CREDENTIALS=oauth_creds.json
# GEMINI_CREDENTIALS={"refresh_token":"..."}    # 可选：直接提供凭证 JSON

🐛 故障排查

🔍 常见问题分类

🛠️ 排查步骤

按照以下顺序进行问题排查：

1. 📺 观看视频教程
   └─> B站教程：https://b23.tv/JKAqkEv
       包含完整安装和配置流程

2. ✅ 验证前置条件
   ├─> Termux 版本 >= v0.118.3
   ├─> 两个 API 均已启用
   └─> 项目 ID 已正确配置

3. 🔄 尝试重新授权
   └─> 主菜单 → 2. 重新授权

4. 📋 检查配置文件
   ├─> 主菜单 → 3. 修改配置
   └─> 确认所有配置项正确

5. 📝 查看详细日志
   └─> 服务启动时的错误信息

6. 🆘 寻求帮助
   ├─> 提交 Issue：https://github.com/print-yuhuan/Gemini-CLI-Termux/issues
   └─> 加入 QQ 群：807134015

💡 常见问题快速解答

Q: 首次安装后无法启动服务？ A: 请确保已配置项目 ID（主菜单 → 3 → 3）并完成授权（主菜单 → 2）。

Q: 局域网其他设备无法访问？ A: 使用 主菜单 → 3 → 5 → 1 开启网络监听，然后通过选项 3 获取内网 IP。

Q: 提示 403 权限错误？ A: 检查三个关键点：① 项目 ID 是否正确 ② 两个 API 是否都已启用 ③ 登录账号是否与项目匹配。

Q: 如何修改 API 密码？ A: 使用 主菜单 → 3 → 4 修改连接秘钥（默认密码：123）。

Q: 授权页面无法自动打开？ A: 脚本使用 termux-open-url 命令自动打开浏览器。如果无法打开，请手动复制终端显示的链接到浏览器中访问。

Q: 服务更新后出现问题？ A: 尝试使用 主菜单 → 5 → 2 重新部署（会清除配置，请备份重要数据）。

🔄 更新与维护

🔧 维护操作说明

通过 主菜单 → 5. 系统管理 访问维护功能：

1. 自动备份配置文件
   ├─> .env (环境配置)
   └─> oauth_creds.json (授权凭证)

2. 拉取最新代码
   ├─> 重置 Git 仓库
   └─> 切换到最新版本

3. 恢复配置文件
   └─> 还原备份的配置

4. 更新依赖
   └─> 重新安装 Python 包

1. 删除项目目录
   └─> 清除所有文件和配置

2. 重新下载安装脚本
   └─> 获取最新版本

3. 执行完整安装流程
   └─> 从零开始安装

1. 确认卸载操作
   └─> 二次确认防止误操作

2. 删除项目目录
   └─> 完全移除所有文件

3. 清理自启动配置
   └─> 移除 .bashrc 中的启动项

📅 维护建议

📝 项目结构

📂 目录结构说明

Gemini-CLI-Termux/
├── 📜 Setup.sh                     # 自动化部署和管理脚本
├── 🐍 run.py                       # 主程序入口
├── ⚙️ .env                         # 环境变量配置文件
├── 🔐 oauth_creds.json             # Google OAuth 授权凭证
├── 📋 requirements.txt             # Python 依赖列表
├── 🔤 MapleMono.ttf               # Termux 终端字体
├── 📄 LICENSE                      # MIT 开源协议
├── 🚫 .gitignore                   # Git 忽略文件配置
├── 📘 README.md                    # 项目文档
└── 📦 src/                         # 源代码目录
    ├── __init__.py                 # Python 包初始化
    ├── main.py                     # FastAPI 应用主文件
    ├── auth.py                     # OAuth 认证和用户授权
    ├── config.py                   # 配置常量和模型定义
    ├── gemini_routes.py            # 原生 Gemini API 路由
    ├── openai_routes.py            # OpenAI 兼容接口路由
    ├── google_api_client.py        # Google API 客户端封装
    ├── openai_transformers.py      # OpenAI/Gemini 格式转换
    ├── models.py                   # Pydantic 数据模型
    └── utils.py                    # 工具函数

🗂️ 核心文件说明

🛠️ 技术栈

🔧 核心技术

📦 Python 依赖包

fastapi<0.100           # 高性能异步 Web 框架
uvicorn                 # ASGI 服务器实现
requests                # HTTP 请求处理
python-dotenv           # .env 文件加载
google-auth-oauthlib    # Google OAuth 2.0 认证
pydantic<2.0           # 数据验证和序列化

🌟 技术特性

📄 许可证

本项目基于 MIT 协议 开源，详见 LICENSE 文件。

📋 许可证要点

• ✅ 可自由使用、复制、修改
• ✅ 可用于商业用途
• ✅ 需保留原始版权声明
• ⚠️ 软件按"原样"提供，不提供任何保证

🙏 致谢与贡献

💖 特别鸣谢

🤝 参与贡献

欢迎各种形式的贡献：

• 🐛 提交 Bug 报告
• 💡 提出新功能建议
• 📝 改进文档说明
• 🔧 提交代码改进

📮 联系与反馈

🆘 获取帮助

遇到问题时请按以下顺序寻求帮助：

1️⃣ 查看文档
   └─> 阅读本 README 和常见问题部分

2️⃣ 观看教程
   └─> B站视频：https://b23.tv/JKAqkEv

3️⃣ 搜索 Issue
   └─> 查看是否有相同问题已被解决

4️⃣ 提交 Issue
   └─> 详细描述问题和环境信息
   └─> https://github.com/print-yuhuan/Gemini-CLI-Termux/issues

5️⃣ 加入交流群
   └─> QQ群：807134015

📧 联系方式

• GitHub Issues: 提交问题
• QQ 交流群: 807134015
• 作者主页: @print-yuhuan