banana-slides

环境要求

• Docker 与 Docker Compose（Windows/macOS 需安装 Docker Desktop 并保持运行，推荐启用 WSL 2 后端）
• 端口 3011（前端）和 5011（后端）未被占用
• 至少一个大模型厂商的 API Key（如 Gemini / OpenAI / 豆包 / DeepSeek / 通义千问 / 智谱 GLM 等）
• 源码部署需额外安装 uv、Node.js 与 npm

安装与启动步骤

1. 1克隆代码仓库

   把项目源码下载到本地并进入项目根目录，后续所有命令都在该目录下执行。

   git clone https://github.com/Anionex/banana-slides
   cd banana-slides

   复制

2. 2生成环境变量文件

   从模板复制出 .env，稍后在里面填写 API 密钥。默认 .env 不包含真实密钥，必须自己配置。

   cp .env.example .env

   复制

3. 3填写 API 密钥

   编辑 .env，按需设置 AI_PROVIDER_FORMAT 及各厂商 API Key；也可跳过，启动后在界面里配置。

4. 4启动容器服务

   推荐用预构建镜像快速启动，跳过本地构建；也可用 docker compose up -d 从头构建镜像。

   docker compose -f docker-compose.prod.yml up -d

   复制

5. 5访问应用

   浏览器打开前端地址即可使用，后端 API 在 5011 端口，两者都需正常监听。

6. 6源码部署后端

   不使用 Docker 时：安装 uv、同步 Python 依赖、执行数据库迁移并启动后端服务。

   curl -LsSf https://astral.sh/uv/install.sh | sh
   uv sync
   cd backend
   uv run alembic upgrade head && uv run python app.py

   复制

7. 7源码部署前端

   进入 frontend 目录安装 npm 依赖并启动开发服务器，通过 Vite proxy 连接默认后端 5011。

   cd frontend
   npm install
   npm run dev

   复制

关键配置

如何确认成功

执行 curl http://localhost:5011/health 验证后端正常，浏览器访问 http://localhost:3011 能打开前端界面即成功。

常见问题

注意事项

• Google nano banana pro 模型接口调用费用较高，请留意成本。
• 项目中大模型接口以 AIHubMix 平台格式为标准，推荐使用 AIHubMix 获取 API 密钥以减少迁移成本。
• 预构建镜像为 anoinex/banana-slides-frontend:latest 与 anoinex/banana-slides-backend:latest，同步主分支最新版本。
• 启动后可在应用内「设置 → 关于 → 检查更新」按当前版本 SHA 判断是否有可用更新。