Gemini-Balance 无 Docker 环境部署指南

内容目录

本指南将引导您在不使用 Docker 的情况下，在标准的 Linux/其他BSD/其他Unix 环境中部署 gemini-balance 应用程序。

1. 先决条件

在开始之前，请确保您的系统中已安装以下软件：

Git
Python 3.10 或更高版本
pip (通常随 Python 一起安装)
(可选) 如果您选择使用 MySQL，需要一个正在运行的 MySQL 或 MariaDB 数据库服务。

2. 部署步骤

第 1 步：获取代码

首先，克隆本仓库到您的本地计算机，并进入项目目录。

git clone https://github.com/snailyp/gemini-balance.git
cd gemini-balance

第 2 步：创建并激活 Python 虚拟环境

为了保持项目依赖的隔离，强烈建议您创建一个 Python 虚拟环境。

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
# 在 Linux 或 macOS 上:
source venv/bin/activate
# 在 Windows 上:
# venv\Scripts\activate

激活成功后，您应该会在终端提示符前看到 (venv) 字样。

第 3 步：安装依赖

使用 pip 安装 requirements.txt 文件中列出的所有 Python 依赖包。

pip install -r requirements.txt

第 4 步：配置应用程序

应用程序的配置通过项目根目录下的 .env 文件进行管理。

创建 .env 文件
通常项目会提供一个 .env.example 文件作为模板。您需要将其复制为 .env。
```
cp .env.example .env
```
编辑 .env 文件
使用您喜欢的文本编辑器（如 nano 或 vim）打开 .env 文件。
```
nano .env
```

配置数据库
您有两种选择：使用 SQLite（简单，推荐用于快速启动）或 MySQL（更强大，适用于生产环境）。

选项 A (推荐): 使用 SQLite
SQLite 是一个无服务器的数据库，数据会存储在一个文件中，无需额外配置。这是最简单的启动方式。

在 .env 文件中，进行如下修改：

# 将 DATABASE_TYPE 设置为 sqlite
DATABASE_TYPE=sqlite
# 确保 MYSQL 相关配置被注释掉（在行首添加 #）
# MYSQL_HOST=...
# MYSQL_PORT=...
# MYSQL_USER=...
# MYSQL_PASSWORD=...
# MYSQL_DATABASE=...

选项 B: 使用 MySQL
如果您有正在运行的 MySQL 服务，可以进行如下配置。

DATABASE_TYPE=mysql
# 重要：将 MYSQL_HOST 设置为你的数据库地址。
# 如果数据库和应用程序在同一台服务器上，通常使用 localhost 或 127.0.0.1
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=your_mysql_user         # 替换为你的 MySQL 用户名
MYSQL_PASSWORD=your_mysql_password # 替换为你的 MySQL 密码
MYSQL_DATABASE=your_mysql_database # 替换为你的数据库名称

配置 API 密钥
在 .env 文件中找到 API_KEYS 变量，并填入您的 Gemini API 密钥。
```
API_KEYS=["AIzaSy...key1", "AIzaSy...key2"]
```

第 5 步：启动应用程序

我们提供两种启动模式：开发模式（代码修改后自动重启）和生产模式（性能更高，更稳定）。

开发模式 (用于调试和开发)

此模式下，uvicorn 会监控 app/ 目录下的文件变化，并在您修改代码后自动重启服务。我们使用 --reload-dir app 来避免因监控庞大的虚拟环境目录而导致 "Too many open files" 错误。

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload --reload-dir app

生产模式 (用于稳定部署)

此模式下，服务不会自动重启，性能更高。

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

第 6 步：访问应用

应用成功启动后，您会看到类似 Uvicorn running on http://0.0.0.0:8000 的输出。

现在，您可以在浏览器中通过 http://<您的服务器IP地址>:8000 来访问应用程序。

3. 常见问题排查 (Troubleshooting)

错误: OSError: Too many open files (os error 24)
- 原因: uvicorn 的 --reload 功能尝试监控项目下的所有文件，包括虚拟环境中的大量文件，超出了系统允许单个进程打开的文件描述符限制。
- 解决方案:
  1. 在启动命令中添加 --reload-dir app，仅监控 app 目录。
  2. 如果问题仍然存在，可以尝试在当前终端会话中提高文件描述符限制：ulimit -n 8192，然后再运行启动命令。
错误: sqlalchemy.exc.OperationalError: (2003, "Can't connect to MySQL server on '...' ...)
- 原因: 应用程序无法连接到您在 .env 文件中配置的 MySQL 数据库。
- 解决方案:
  1. 确认您的 MySQL 服务正在运行。
  2. 检查 .env 文件中的 MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE 是否完全正确。
  3. 确保 MYSQL_HOST 设置为 localhost 或 127.0.0.1，而不是 Docker 容器名（如 gemini-balance-mysql）。
  4. 检查防火墙设置，确保应用程序可以访问 MySQL 的端口（默认为 3306）。
警告: VERSION file not found at '...'
- 原因: 应用程序在项目根目录找不到 VERSION 文件，该文件用于版本检查。
- 解决方案 (可选): 这是一个无害的警告。如果您想消除它，可以在项目根目录创建一个 VERSION 文件并写入版本号。
```
echo "1.0.0" > VERSION
```
问题: 网页显示异常，没有样式或背景
- 原因: 浏览器未能成功加载 CSS 或其他静态文件。
- 解决方案:
  1. 在浏览器中按下 F12 打开开发者工具。
  2. 切换到 "Console" (控制台) 和 "Network" (网络) 选项卡，刷新页面。
  3. 检查是否有任何资源（特别是 .css 文件）加载失败（状态码为 404 或其他错误）。根据错误信息排查静态文件路径或服务器配置。