social-app/docs/runbooks/local-dev.md

本地开发指南

前置要求

• Docker 和 Docker Compose
• Flutter SDK
• Python 3.11+

快速开始

1. 配置环境变量

make env

按照提示创建并编辑应用配置 configs/env/.env，并创建 Supabase 本地栈配置 infra/local/env/.env。

创建配置文件：

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. 启动依赖服务

make up

这将启动以下服务：

• Redis：端口 6379
• Milvus：端口 19530 (gRPC) / 19111 (HTTP)
• Postgres：端口 54322

3. 检查服务状态

make ps

确保所有服务显示为 Up 状态。

4. 查看服务日志

# 查看所有服务日志
make logs

# 查看特定服务日志
make logs SERVICE=redis
make logs SERVICE=milvus
make logs SERVICE=db

启动应用

启动 FastAPI 后端

make api-dev

或手动启动：

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 应用

make flutter-dev

或手动启动：

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：

flutter build apk --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000

初始化 Milvus

make milvus-init

或手动运行初始化脚本：

bash tools/scripts/init_milvus.sh

常用命令

依赖服务管理

# 启动服务
make up

# 停止服务
make down

# 重启服务
make down && make up

# 查看状态
make ps

# 查看日志
make logs

# 清理数据（警告：会丢失数据）
make clean

应用管理

# 启动后端
make api-dev

# 启动前端
make flutter-dev

# 配置环境变量
make env

常见问题

端口冲突

如果启动依赖服务时出现端口冲突：

1. 检查端口占用：

   # 检查 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. 查看服务日志：

   make logs SERVICE=<service_name>
   

2. 检查依赖服务是否正常启动：

   make ps
   

3. 重启服务：

    docker compose -f infra/local/docker-compose.yml --env-file infra/local/env/.env restart <service_name>
   

后端无法连接数据库

1. 检查 Postgres 是否正常启动：

   make ps
   

2. 检查环境变量配置：

    cat configs/env/.env | grep DATABASE_URL
   

3. 确保数据库 URL 格式正确：

   postgresql://postgres:postgres@localhost:54322/postgres
   

Flutter 无法连接后端

1. 确保后端服务已启动并监听在 8000 端口：

   curl http://localhost:8000/docs
   

2. 检查 Flutter 的 API_BASE_URL 是否正确注入：

   flutter run --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000
   

3. 如果使用模拟器，确保能访问 localhost：

   • Android 模拟器：使用 10.0.2.2 代替 localhost
   • iOS 模拟器：使用 localhost 即可

Milvus 连接失败

1. 检查 Milvus 服务是否健康：

   make ps
   

2. 等待 Milvus 完全启动（可能需要 1-2 分钟）：

   make logs SERVICE=milvus
   

3. 测试连接：

   curl http://localhost:19530/healthz
   

清理环境

# 停止所有服务
make down

# 清理数据卷（警告：会丢失所有数据）
make clean

# 完全清理（包括未使用的镜像）
docker system prune -a

下一步

• 阅读架构文档：docs/architecture/overview.md
• 了解配置规则：docs/rules/config-rules.md
• 查看技术栈决策：docs/adr/0001-tech-stack.md