qzl
273 lines
4.5 KiB
Markdown
273 lines
4.5 KiB
Markdown
# 本地开发指南
|
||
|
||
## 前置要求
|
||
|
||
- Docker 和 Docker Compose
|
||
- Flutter SDK
|
||
- Python 3.11+
|
||
|
||
## 快速开始
|
||
|
||
### 1. 配置环境变量
|
||
|
||
```bash
|
||
make env
|
||
```
|
||
|
||
按照提示创建并编辑应用配置 `configs/env/.env`，并创建 Supabase 本地栈配置 `infra/local/env/.env`。
|
||
|
||
创建配置文件：
|
||
|
||
```bash
|
||
cp configs/env/.env.example configs/env/.env
|
||
cp infra/local/env/.env.example infra/local/env/.env
|
||
```
|
||
|
||
确保以下变量配置正确：
|
||
- `DATABASE_URL`（连接到 localhost:54322）
|
||
- `REDIS_URL`（连接到 localhost:6379）
|
||
- `MILVUS_URI`（连接到 localhost:19530）
|
||
|
||
### 2. 启动依赖服务
|
||
|
||
```bash
|
||
make up
|
||
```
|
||
|
||
这将启动以下服务：
|
||
- **Redis**：端口 6379
|
||
- **Milvus**：端口 19530 (gRPC) / 19111 (HTTP)
|
||
- **Postgres**：端口 54322
|
||
|
||
### 3. 检查服务状态
|
||
|
||
```bash
|
||
make ps
|
||
```
|
||
|
||
确保所有服务显示为 `Up` 状态。
|
||
|
||
### 4. 查看服务日志
|
||
|
||
```bash
|
||
# 查看所有服务日志
|
||
make logs
|
||
|
||
# 查看特定服务日志
|
||
make logs SERVICE=redis
|
||
make logs SERVICE=milvus
|
||
make logs SERVICE=db
|
||
```
|
||
|
||
## 启动应用
|
||
|
||
### 启动 FastAPI 后端
|
||
|
||
```bash
|
||
make api-dev
|
||
```
|
||
|
||
或手动启动：
|
||
|
||
```bash
|
||
cd apps/api
|
||
|
||
# 创建虚拟环境（首次）
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
|
||
# 安装依赖（首次）
|
||
pip install -r requirements.txt
|
||
|
||
# 启动服务
|
||
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
|
||
```
|
||
|
||
后端启动后，访问：
|
||
- API 文档：http://localhost:8000/docs
|
||
- ReDoc：http://localhost:8000/redoc
|
||
|
||
### 启动 Flutter 应用
|
||
|
||
```bash
|
||
make flutter-dev
|
||
```
|
||
|
||
或手动启动：
|
||
|
||
```bash
|
||
cd apps/mobile
|
||
|
||
# 安装依赖（首次）
|
||
flutter pub get
|
||
|
||
# 启动开发服务器
|
||
flutter run --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000
|
||
|
||
# 或指定设备
|
||
flutter run -d chrome --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000
|
||
```
|
||
|
||
构建 Android APK：
|
||
|
||
```bash
|
||
flutter build apk --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000
|
||
```
|
||
|
||
## 初始化 Milvus
|
||
|
||
```bash
|
||
make milvus-init
|
||
```
|
||
|
||
或手动运行初始化脚本：
|
||
|
||
```bash
|
||
bash tools/scripts/init_milvus.sh
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
### 依赖服务管理
|
||
|
||
```bash
|
||
# 启动服务
|
||
make up
|
||
|
||
# 停止服务
|
||
make down
|
||
|
||
# 重启服务
|
||
make down && make up
|
||
|
||
# 查看状态
|
||
make ps
|
||
|
||
# 查看日志
|
||
make logs
|
||
|
||
# 清理数据（警告：会丢失数据）
|
||
make clean
|
||
```
|
||
|
||
### 应用管理
|
||
|
||
```bash
|
||
# 启动后端
|
||
make api-dev
|
||
|
||
# 启动前端
|
||
make flutter-dev
|
||
|
||
# 配置环境变量
|
||
make env
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 端口冲突
|
||
|
||
如果启动依赖服务时出现端口冲突：
|
||
|
||
1. 检查端口占用：
|
||
```bash
|
||
# 检查 6379（Redis）
|
||
lsof -i :6379
|
||
|
||
# 检查 54322（Postgres）
|
||
lsof -i :54322
|
||
|
||
# 检查 19530（Milvus）
|
||
lsof -i :19530
|
||
```
|
||
|
||
2. 停止占用端口的进程，或修改 `infra/local/docker-compose.yml` 中的端口映射
|
||
|
||
### 容器未健康
|
||
|
||
如果服务状态显示 `Up (health: starting)` 但一直未变成 `Up (healthy)`：
|
||
|
||
1. 查看服务日志：
|
||
```bash
|
||
make logs SERVICE=<service_name>
|
||
```
|
||
|
||
2. 检查依赖服务是否正常启动：
|
||
```bash
|
||
make ps
|
||
```
|
||
|
||
3. 重启服务：
|
||
```bash
|
||
docker compose -f infra/local/docker-compose.yml --env-file infra/local/env/.env restart <service_name>
|
||
```
|
||
|
||
### 后端无法连接数据库
|
||
|
||
1. 检查 Postgres 是否正常启动：
|
||
```bash
|
||
make ps
|
||
```
|
||
|
||
2. 检查环境变量配置：
|
||
```bash
|
||
cat configs/env/.env | grep DATABASE_URL
|
||
```
|
||
|
||
3. 确保数据库 URL 格式正确：
|
||
```
|
||
postgresql://postgres:postgres@localhost:54322/postgres
|
||
```
|
||
|
||
### Flutter 无法连接后端
|
||
|
||
1. 确保后端服务已启动并监听在 8000 端口：
|
||
```bash
|
||
curl http://localhost:8000/docs
|
||
```
|
||
|
||
2. 检查 Flutter 的 API_BASE_URL 是否正确注入：
|
||
```bash
|
||
flutter run --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000
|
||
```
|
||
|
||
3. 如果使用模拟器，确保能访问 localhost：
|
||
- Android 模拟器：使用 `10.0.2.2` 代替 `localhost`
|
||
- iOS 模拟器：使用 `localhost` 即可
|
||
|
||
### Milvus 连接失败
|
||
|
||
1. 检查 Milvus 服务是否健康：
|
||
```bash
|
||
make ps
|
||
```
|
||
|
||
2. 等待 Milvus 完全启动（可能需要 1-2 分钟）：
|
||
```bash
|
||
make logs SERVICE=milvus
|
||
```
|
||
|
||
3. 测试连接：
|
||
```bash
|
||
curl http://localhost:19530/healthz
|
||
```
|
||
|
||
## 清理环境
|
||
|
||
```bash
|
||
# 停止所有服务
|
||
make down
|
||
|
||
# 清理数据卷（警告：会丢失所有数据）
|
||
make clean
|
||
|
||
# 完全清理（包括未使用的镜像）
|
||
docker system prune -a
|
||
```
|
||
|
||
## 下一步
|
||
|
||
- 阅读架构文档：`docs/architecture/overview.md`
|
||
- 了解配置规则：`docs/rules/config-rules.md`
|
||
- 查看技术栈决策：`docs/adr/0001-tech-stack.md`
|