aihot/README_STARTUP.md

🚀 启动指南

快速开始

方式一：本地开发 (推荐)

前置条件：

• Python 3.9+
• Node.js 18+
• PostgreSQL 14+ (需要单独启动)

Windows PowerShell:

.\start.ps1

Windows CMD:

start.bat

Mac/Linux:

chmod +x start.sh
./start.sh

然后选择选项 1 进行本地开发。

访问地址：

• 前端: http://localhost:5173
• 后端: http://localhost:8000
• API文档: http://localhost:8000/docs

---

方式二：Docker Compose (完全隔离)

前置条件：

• Docker Desktop (包含 Docker Compose)

启动：

.\start-docker.ps1

或直接使用 docker-compose:

docker-compose up --build

访问地址：

• 前端: http://localhost:3000
• 后端: http://localhost:8000
• API文档: http://localhost:8000/docs
• 数据库: localhost:5432 (用户: pharma / 密码: pharma123)

---

详细说明

方式一：本地开发

Windows

1. 启动脚本：

   • PowerShell: .\start.ps1
   • CMD: start.bat

2. 脚本会自动：

   • 检查 Python 和 Node.js
   • 创建虚拟环境 (如需要)
   • 安装依赖包
   • 在新窗口启动后端和前端

3. 手动启动（可选）：

   后端：

   cd backend
   python -m venv venv
   .\venv\Scripts\Activate.ps1
   pip install -r requirements.txt
   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
   

   前端（新终端）：

   cd frontend
   npm install
   npm run dev
   

4. PostgreSQL 配置：

   • 确保 PostgreSQL 已启动
   • 默认连接: postgresql://pharma:pharma123@localhost/pharma_news
   • 如需修改，编辑 .env 文件

Mac/Linux

# 给脚本执行权限
chmod +x start.sh

# 运行脚本
./start.sh

---

方式二：Docker Compose

基本命令

# 启动所有服务（首次需要构建）
docker-compose up

# 重新构建并启动
docker-compose up --build

# 在后台运行
docker-compose up -d

# 查看日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f backend
docker-compose logs -f frontend

# 停止服务
docker-compose down

# 完全清理（包括数据）
docker-compose down -v

常见问题

问：如何修改端口？

编辑 docker-compose.yml:

ports:
  - "8080:8000"  # 后端: 外部:内部
  - "3001:80"    # 前端: 外部:内部

问：如何在容器内执行命令？

# 后端
docker-compose exec backend python -m alembic upgrade head

# 前端
docker-compose exec frontend npm run build

问：如何清理 Docker 数据？

# 停止并删除所有容器和卷
docker-compose down -v

# 重新启动会创建新的数据库
docker-compose up --build

---

环境变量配置

后端 (.env)

# PostgreSQL
DATABASE_URL=postgresql://pharma:pharma123@localhost:5432/pharma_news

# LLM 服务
LLM_API_KEY=your_api_key
LLM_MODEL=gpt-4

# 其他配置
LOG_LEVEL=INFO

前端 (.env.local)

VITE_API_BASE_URL=http://localhost:8000/api

---

故障排除

后端无法启动

# 1. 检查端口是否被占用
netstat -ano | findstr :8000  # Windows
lsof -i :8000                  # Mac/Linux

# 2. 检查 Python 和依赖
python --version
pip list | grep fastapi

# 3. 检查数据库连接
# 确保 PostgreSQL 已启动，用户名和密码正确

前端无法启动

# 1. 清理依赖
rm -rf node_modules package-lock.json
npm install

# 2. 检查 Node 版本
node --version
npm --version

# 3. 清理 Vite 缓存
rm -rf dist .vite

Docker 容器无法启动

# 查看详细错误日志
docker-compose logs

# 重建镜像
docker-compose build --no-cache

# 清理所有容器和镜像
docker system prune -a

---

开发建议

热重载

• 后端: Uvicorn 自动热重载 (修改文件后自动重启)
• 前端: Vite 自动热重载 (修改代码后自动更新浏览器)

调试

后端：

# 在代码中添加断点
import pdb; pdb.set_trace()

# 或使用 IDE 的调试功能

前端：

• 使用浏览器 DevTools (F12)
• VS Code Debugger (需要配置 launch.json)

性能监测

# 后端性能
docker-compose stats backend

# 前端性能
npm run build  # 检查构建体积

---

生产部署

使用 Docker

# 构建生产镜像
docker-compose -f docker-compose.yml -f docker-compose.prod.yml build

# 启动生产环境
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

本地生产预览

# 后端
uvicorn app.main:app --host 0.0.0.0 --port 8000

# 前端
npm run build
npm run preview

---

脚本文件说明

文件	说明	环境
start.ps1	本地开发启动脚本	Windows PowerShell
start.bat	本地开发启动脚本	Windows CMD
start.sh	本地开发启动脚本	Mac/Linux
start-docker.ps1	Docker Compose 启动脚本	Windows PowerShell

---

更多帮助

• FastAPI 文档: https://fastapi.tiangolo.com/
• Vue.js 文档: https://vuejs.org/
• Vite 文档: https://vitejs.dev/
• PostgreSQL 文档: https://www.postgresql.org/docs/
• Docker 文档: https://docs.docker.com/