安装与部署指南

这页只做一件事：先把项目跑起来。
细节配置、排障、Docker 放在后面按需看。

一分钟快速启动（推荐）

如果你只想快速上线，直接执行：

1) 克隆项目

git clone https://gitee.com/blackfox/geekai-ppt.git
cd geekai-ppt/docker

2) 配置环境变量

打开 docker-compose.yaml 文件，修改 API_KEY 和 BASE_URL：

services:
  # Backend API 服务
  api:
    image: registry.cn-shenzhen.aliyuncs.com/geekmaster/geekai-ppt-api:v1.0.0
    container_name: geekai-ppt-api
    ports:
      - '8002:8002'
    environment:
      - API_KEY=${API_KEY:-}
      - BASE_URL=${BASE_URL:-https://api.geekai.pro}
      - MODEL_LOGIC=${MODEL_LOGIC:-gemini-3-pro-preview}
      - MODEL_IMAGE=${MODEL_IMAGE:-gemini-3-pro-image-preview}
      - PORT=8002
    ...

2) 启动容器

docker-compose up -d

3) 访问前端

访问地址：http://localhost:3000 账号：18888888888 密码：12345678
管理后台地址：http://localhost:3000/admin 账号：admin 密码：admin123

从源码安装

1) 克隆项目

git clone https://gitee.com/blackfox/geekai-ppt.git
cd geekai-ppt

2) 最小配置（先能跑）

cp backend/.env.example backend/.env

修改 API Key 和 Base URL：

API_KEY=你的Key
BASE_URL=https://api.geekai.pro

3) 后端一键启动（`start.sh`）

cd backend
./start.sh

脚本会自动完成：

创建并激活 venv
安装/更新依赖
自动创建 storage 目录
启动后端（默认 http://localhost:8002）

首次运行会检查 .env；如果不存在会生成模板，补上 API_KEY 即可。

3) 启动前端

cd ../web
pnpm install # 或者 npm install
npm run dev

默认访问地址：http://localhost:3000

4) 手动启动（不走一键启动脚本）

如果你想自己控制每一步：

cd backend
python3 -m venv venv # 创建虚拟环境
source venv/bin/activate # 激活虚拟环境
pip install -r requirements.txt # 安装依赖
python main.py # 启动后端

前端仍然是：

cd web
pnpm install # 或者 npm install
npm run dev

常见问题（最短排查）

前端能打开但报 API 错误：先确认 backend 在运行，再核对 VITE_API_BASE_URL。
API Key 报错：先核对 backend/.env 的 API_KEY、BASE_URL。
Docker 502：先看 docker-compose logs -f，再检查反向代理配置。