refactor: align repo layout and logging safeguards
This commit is contained in:
qzl
@@ -1,38 +0,0 @@
|
||||
# 技术栈选择
|
||||
|
||||
## 背景
|
||||
|
||||
本项目需要构建一个跨平台社交应用，支持本地开发和云端部署。
|
||||
|
||||
## 决策
|
||||
|
||||
1. **前端框架：Flutter**
|
||||
- 跨平台支持（iOS / Android / Web）
|
||||
- 高性能原生渲染
|
||||
- 丰富的 UI 组件
|
||||
|
||||
2. **后端框架：FastAPI**
|
||||
- 高性能异步框架
|
||||
- 自动生成 OpenAPI 文档
|
||||
- 类型安全
|
||||
|
||||
3. **数据库：Supabase（PostgreSQL）**
|
||||
- 开箱即用的 PostgreSQL
|
||||
- 内置认证和权限管理
|
||||
- 实时订阅功能
|
||||
|
||||
4. **缓存：Redis**
|
||||
- 高性能键值存储
|
||||
- 支持多种数据结构
|
||||
|
||||
5. **向量数据库：Milvus**
|
||||
- 高性能向量检索
|
||||
- 支持大规模向量存储
|
||||
- 适合 RAG 和推荐场景
|
||||
|
||||
## 后续考虑
|
||||
|
||||
根据业务发展，可能需要评估：
|
||||
- CDN 方案
|
||||
- 消息队列
|
||||
- 监控和日志系统
|
||||
@@ -1,17 +0,0 @@
|
||||
# 系统架构概述
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **前端**：Flutter
|
||||
- **后端**：FastAPI
|
||||
- **数据库**：Supabase（PostgreSQL）
|
||||
- **缓存**：Redis
|
||||
- **向量数据库**：Milvus
|
||||
- **部署**：Docker + 火山云（未来）
|
||||
|
||||
## 架构特点
|
||||
|
||||
- Monorepo 结构
|
||||
- 微服务架构（API + Worker）
|
||||
- 云原生设计
|
||||
- 支持本地 Docker 开发和云端部署
|
||||
@@ -0,0 +1,147 @@
|
||||
# Plan: FastAPI + Celery 日志管理器系统
|
||||
|
||||
**Date:** 2026-01-29
|
||||
**Author:** AI Assistant
|
||||
**Status:** Draft
|
||||
|
||||
## Overview
|
||||
|
||||
构建一个统一、可扩展的日志管理器系统，覆盖 FastAPI 与 Celery worker 的运行时日志，提供结构化 JSON 输出、错误分离、日志轮转与上下文追踪。目标是满足生产环境可观测性需求，便于检索、关联与故障排查，并与当前项目配置体系保持一致。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional
|
||||
- [ ] 统一管理 FastAPI 与 Celery worker 日志
|
||||
- [ ] 日志持久化到 `logs/`，错误日志单独输出到 `logs/errors/`
|
||||
- [ ] 支持按大小或按时间进行日志轮转
|
||||
- [ ] 结构化日志（JSON），包含时间戳、级别、模块/函数、消息与上下文
|
||||
- [ ] ERROR/CRITICAL 记录完整堆栈与错误上下文
|
||||
- [ ] 支持环境差异化配置（dev/test/prod）
|
||||
|
||||
### Non-Functional
|
||||
- [ ] 性能：日志写入对请求延迟影响可控，支持异步队列化扩展
|
||||
- [ ] 安全：避免记录敏感信息，支持字段脱敏
|
||||
- [ ] 可维护性：模块化、可测试、与现有配置体系一致
|
||||
|
||||
## Technical Approach
|
||||
|
||||
### 调研摘要
|
||||
- Python 官方建议使用 `logging` + `dictConfig` 管理多 handler、多 formatter 与过滤器，适用于生产环境配置化管理。
|
||||
- FastAPI 通常通过中间件注入 request_id 和上下文，并使用结构化日志输出以便集中检索。
|
||||
- Celery 官方文档建议在自定义场景下关闭 `worker_hijack_root_logger`，通过信号配置自定义 handler。
|
||||
- 结构化日志库中，structlog 更贴近标准 logging，可与 `logging` 生态协同；loguru 简化配置但替换性强、与 Celery 深度集成时可控性较弱。
|
||||
- 生产环境推荐 JSON 结构化日志 + 轮转 + 错误分离，并通过外部系统聚合与告警（如 Sentry）。
|
||||
|
||||
### 方案对比（至少两种）
|
||||
| 方案 | 描述 | 优点 | 缺点 | 结论 |
|
||||
|------|------|------|------|------|
|
||||
| 方案 A：stdlib logging + 自定义 JSON Formatter | 纯标准库实现 JSON formatter + handler/filters | 依赖最少，符合标准库，易与 Celery/FastAPI 集成 | 结构化上下文绑定与 request_id 传递需手写 | 可作为备选最小方案 |
|
||||
| 方案 B：stdlib logging + structlog | 用 structlog 生成结构化事件，输出到 logging handler | 结构化上下文与 contextvars 支持好，兼容 logging handler | 引入第三方依赖与配置复杂度 | 推荐主方案 |
|
||||
| 方案 C：loguru | 直接使用 loguru logger | 配置简单、体验好 | 与 Celery/标准 logging 生态整合成本高 | 不推荐作为主方案 |
|
||||
|
||||
### 选型结论
|
||||
- 采用方案 B：`logging` 作为底座，structlog 负责结构化事件与上下文绑定；保留可切换到方案 A 的最小实现路径。
|
||||
- 通过 `dictConfig` 做环境配置，使用 Rotating/TimedRotating handler 支持按大小或时间轮转。
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
### Phase 1: 基础日志骨架与配置 (3 hours)
|
||||
1. 新增日志配置模型（Settings 扩展），支持环境、轮转方式与路径配置。
|
||||
2. 创建日志模块骨架：formatter、handler、filter、context。
|
||||
3. 集成 `dictConfig` 初始化入口，支持 dev/test/prod 配置切换。
|
||||
|
||||
### Phase 2: FastAPI 集成与上下文 (4 hours)
|
||||
1. 实现请求中间件：生成 `request_id`，绑定用户与请求上下文（IP、路径、方法）。
|
||||
2. 定义异常处理器：捕获未处理异常并记录堆栈与上下文。
|
||||
3. 添加应用启动时日志初始化流程。
|
||||
|
||||
### Phase 3: Celery 集成 (3 hours)
|
||||
1. 在 Celery 应用配置中设置 `worker_hijack_root_logger = False`。
|
||||
2. 使用 Celery 信号（`setup_logging`、`after_setup_task_logger`）初始化日志并注入 task 上下文。
|
||||
3. 统一日志格式、error 处理与 request_id 关联（如 task_id）。
|
||||
|
||||
### Phase 4: 错误分离与轮转策略 (3 hours)
|
||||
1. 添加 error handler：仅接受 ERROR/CRITICAL，输出到 `logs/errors/`。
|
||||
2. 实现轮转策略配置（按大小、按时间），并提供统一切换配置项。
|
||||
3. 增加字段脱敏与敏感字段黑名单过滤器。
|
||||
|
||||
### Phase 5: 可选增强功能 (4 hours)
|
||||
1. 日志查询与过滤接口（基础 API + 分页）。
|
||||
2. 日志聚合统计（按级别/模块/时间窗口）。
|
||||
3. Sentry 集成与异常告警。
|
||||
|
||||
## Files to Modify
|
||||
|
||||
| File | Changes |
|
||||
|------|---------|
|
||||
| api/src/core/config/settings.py | 扩展日志相关配置模型 |
|
||||
|
||||
## Files to Create
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| api/src/core/logging/__init__.py | 模块导出与初始化入口 |
|
||||
| api/src/core/logging/config.py | dictConfig 构建与环境配置 |
|
||||
| api/src/core/logging/formatters.py | JSON formatter 与字段规范 |
|
||||
| api/src/core/logging/handlers.py | 文件、控制台、错误 handler |
|
||||
| api/src/core/logging/filters.py | 等级过滤、敏感字段脱敏 |
|
||||
| api/src/core/logging/context.py | contextvars 绑定与获取 |
|
||||
| api/src/core/logging/middleware.py | FastAPI 请求中间件 |
|
||||
| api/src/core/logging/celery.py | Celery 日志信号集成 |
|
||||
| api/src/core/logging/examples.py | 使用示例（可选） |
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [ ] structlog: 结构化日志与 contextvars 支持
|
||||
- [ ] python-json-logger（备选）: 若需要纯 logging JSON formatter
|
||||
- [ ] sentry-sdk（可选）: 异常告警与追踪
|
||||
|
||||
## 配置示例
|
||||
|
||||
```toml
|
||||
# .env 示例（通过 pydantic settings 读取）
|
||||
SOCIAL_RUNTIME__LOG_LEVEL=INFO
|
||||
SOCIAL_RUNTIME__LOG_JSON=true
|
||||
SOCIAL_RUNTIME__LOG_ROTATION=TIME
|
||||
SOCIAL_RUNTIME__LOG_ROTATION_WHEN=midnight
|
||||
SOCIAL_RUNTIME__LOG_ROTATION_BACKUP_COUNT=14
|
||||
SOCIAL_RUNTIME__LOG_DIR=logs
|
||||
SOCIAL_RUNTIME__LOG_ERROR_DIR=logs/errors
|
||||
```
|
||||
|
||||
## 使用示例代码
|
||||
|
||||
```python
|
||||
from core.logging import configure_logging, get_logger
|
||||
|
||||
configure_logging()
|
||||
logger = get_logger(__name__)
|
||||
|
||||
logger.info("user login", extra={"user_id": "u_123"})
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- **Unit Tests:** formatter 输出结构、filter 脱敏规则、context 绑定行为
|
||||
- **Integration Tests:** FastAPI 中间件注入的 request_id 与错误分离写入
|
||||
- **E2E Tests:** 关键流程触发错误，验证 error 日志输出与轮转
|
||||
|
||||
## Risks & Mitigations
|
||||
|
||||
| Risk | Impact | Likelihood | Mitigation |
|
||||
|------|--------|------------|------------|
|
||||
| Celery 日志被自动劫持导致重复或丢失 | High | Medium | 设置 `worker_hijack_root_logger=False` 并通过信号统一配置 |
|
||||
| 结构化字段不一致导致下游解析失败 | Medium | Medium | 统一 schema，增加单元测试与校验 |
|
||||
| 误记录敏感信息 | High | Medium | 增加脱敏过滤器与字段黑名单 |
|
||||
| 日志量过大影响性能 | Medium | Medium | 轮转 + 级别控制 + 可选异步队列化 |
|
||||
|
||||
## Estimated Effort
|
||||
|
||||
| Phase | Effort |
|
||||
|-------|--------|
|
||||
| Phase 1 | 3 hours |
|
||||
| Phase 2 | 4 hours |
|
||||
| Phase 3 | 3 hours |
|
||||
| Phase 4 | 3 hours |
|
||||
| Phase 5 | 4 hours |
|
||||
| **Total** | **17 hours** |
|
||||
@@ -1,203 +0,0 @@
|
||||
# 配置规则与使用原则
|
||||
|
||||
## 配置文件组织
|
||||
|
||||
### 1. 环境变量规范（真相源）
|
||||
|
||||
**文件位置**：`configs/env/.env.example`
|
||||
|
||||
**作用**：
|
||||
- 定义应用层环境变量的名称、类型、用途和敏感级别
|
||||
- 作为应用配置的"真相源"（source of truth）
|
||||
- 不可直接用于运行，仅作为参考和规范
|
||||
- Docker/Supabase 栈配置不在本文件，使用 `infra/local/env/.env.example`
|
||||
- 本文件仅包含应用层连接配置（如 `SUPABASE_URL`、`DATABASE_URL`），不包含 Supabase 栈运行变量
|
||||
- 不得在 `infra/local/env/.env.example` 中添加应用层变量（如 `PUBLIC_`、`API_`）
|
||||
|
||||
**变量分类**：
|
||||
- `public`：可公开的信息，如服务地址、端口号
|
||||
- `secret`：敏感信息，如密钥、密码、连接串
|
||||
|
||||
**变量块说明**：
|
||||
- A. 通用环境（APP_ENV、LOG_LEVEL、TZ）
|
||||
- B. Flutter 配置（仅 PUBLIC_ 变量）
|
||||
- C. FastAPI 服务配置
|
||||
- D. Supabase / Postgres 连接配置
|
||||
- E. Redis 配置
|
||||
- F. Milvus 配置
|
||||
- G. 对象存储配置（可选）
|
||||
- H. 其他配置
|
||||
|
||||
### 2. 本地开发配置
|
||||
|
||||
**文件位置**：`configs/env/.env`
|
||||
|
||||
**作用**：
|
||||
- 本地应用层的实际配置文件
|
||||
- 从 `configs/env/.env.example` 复制后填入真实值
|
||||
- **禁止提交到 Git 仓库**
|
||||
|
||||
**创建方式**：
|
||||
```bash
|
||||
cp configs/env/.env.example configs/env/.env
|
||||
# 编辑 configs/env/.env，填入实际值
|
||||
```
|
||||
|
||||
### 3. 本地 Supabase 栈配置
|
||||
|
||||
**文件位置**：`infra/local/env/.env`
|
||||
|
||||
**作用**：
|
||||
- 本地 Supabase + 周边依赖的实际配置文件
|
||||
- 从 `infra/local/env/.env.example` 复制后填入真实值
|
||||
- **禁止提交到 Git 仓库**
|
||||
|
||||
**创建方式**：
|
||||
```bash
|
||||
cp infra/local/env/.env.example infra/local/env/.env
|
||||
```
|
||||
|
||||
### 4. 云端部署配置
|
||||
|
||||
**方式一：环境文件**
|
||||
- 文件位置：`infra/cloud/volcano/env/.env`（不提交）
|
||||
- 从 `infra/cloud/volcano/env/.env.example` 复制后填入云端真实值
|
||||
- 仅用于本地测试云端连接
|
||||
|
||||
**方式二：Secret 注入（推荐）**
|
||||
- 使用火山云或其他云平台的 Secret 管理服务
|
||||
- 通过 CI/CD 或容器运行时注入环境变量
|
||||
- 代码无需修改，通过环境切换
|
||||
|
||||
### 5. 应用特定配置
|
||||
|
||||
**Flutter 配置**：
|
||||
- `configs/flutter/dev.json` —— 开发环境
|
||||
- `configs/flutter/prod.json` —— 生产环境
|
||||
- 通过 `--dart-define` 在构建时注入
|
||||
|
||||
## 安全原则
|
||||
|
||||
### Public vs Secret
|
||||
|
||||
**Public 变量**：
|
||||
- 可公开的服务地址和端口号
|
||||
- 前端可直接使用的配置
|
||||
- 示例：`PUBLIC_API_BASE_URL`、`API_PORT`
|
||||
|
||||
**Secret 变量**：
|
||||
- 密钥、密码、连接串
|
||||
- 仅服务端使用的敏感信息
|
||||
- 示例：`DATABASE_URL`、`REDIS_URL`、`JWT_SECRET`
|
||||
|
||||
### Flutter 配置限制
|
||||
|
||||
**严格规则**：
|
||||
- Flutter 只能使用以 `PUBLIC_` 开头的变量
|
||||
- 严禁将任何 secret 信息注入到 Flutter
|
||||
- 通过 `--dart-define` 在构建时注入，运行时不可修改
|
||||
|
||||
**示例**：
|
||||
```bash
|
||||
# ✅ 正确：Flutter 使用 PUBLIC_ 变量
|
||||
flutter run --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000
|
||||
|
||||
# ❌ 错误：Flutter 不能使用 secret
|
||||
flutter run --dart-define=DATABASE_URL=postgresql://user:pass@localhost/db
|
||||
```
|
||||
|
||||
### 后端配置读取
|
||||
|
||||
**严格规则**：
|
||||
- `apps/api` 和 `apps/worker` 只能通过环境变量读取配置
|
||||
- 不得直接读取 `infra/local/*.env` 文件路径
|
||||
- 使用 Python 的 `os.getenv()` 或环境变量库
|
||||
|
||||
**示例**：
|
||||
```python
|
||||
# ✅ 正确：通过环境变量读取
|
||||
import os
|
||||
|
||||
database_url = os.getenv("DATABASE_URL")
|
||||
|
||||
# ❌ 错误：直接读取本地配置文件
|
||||
from dotenv import load_dotenv
|
||||
load_dotenv("configs/env/.env") # 禁止
|
||||
```
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 1. 本地开发
|
||||
|
||||
1. 复制环境变量模板：
|
||||
```bash
|
||||
make env
|
||||
```
|
||||
|
||||
2. 启动依赖服务：
|
||||
```bash
|
||||
make up
|
||||
```
|
||||
|
||||
3. 启动后端服务：
|
||||
```bash
|
||||
make api-dev
|
||||
```
|
||||
|
||||
4. 启动 Flutter 应用：
|
||||
```bash
|
||||
make flutter-dev
|
||||
```
|
||||
|
||||
### 2. 云端部署
|
||||
|
||||
1. 准备云端环境变量：
|
||||
- 将 `.env.example` 中的变量映射到云平台 Secret
|
||||
- 或创建 `infra/cloud/volcano/env/.env`（仅用于本地测试）
|
||||
|
||||
2. 修改配置指向云端：
|
||||
```bash
|
||||
# 示例：修改 .env 指向火山云托管地址
|
||||
REDIS_URL=redis://volcano-redis:6379/0
|
||||
MILVUS_URI=https://volcano-milvus:19530
|
||||
DATABASE_URL=postgresql://user:pass@volcano-postgres/db
|
||||
```
|
||||
|
||||
3. 部署应用：
|
||||
- 通过 CI/CD 自动注入环境变量
|
||||
- 或通过云平台控制台配置
|
||||
|
||||
## 配置优先级
|
||||
|
||||
从高到低：
|
||||
1. 运行时环境变量（最高）
|
||||
2. 环境文件（`.env`）
|
||||
3. 配置文件（`configs/flutter/*.json`）
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 如何切换环境？
|
||||
|
||||
**本地开发**：使用 `configs/env/.env`
|
||||
**云端部署**：使用云平台 Secret 注入
|
||||
|
||||
### Q: 如何确保 secret 不泄露？
|
||||
|
||||
- 所有 secret 变量使用 `CHANGE_ME` 占位符
|
||||
- 本地配置文件（`configs/env/.env`、`infra/local/env/.env`）添加到 `.gitignore`
|
||||
- 云端使用密钥管理服务注入
|
||||
|
||||
### Q: 如何测试云端配置？
|
||||
|
||||
1. 在本地创建 `infra/cloud/volcano/env/.env`（不提交）
|
||||
2. 修改变量指向云端地址
|
||||
3. 导出环境变量测试：
|
||||
```bash
|
||||
export $(cat infra/cloud/volcano/env/.env | xargs)
|
||||
```
|
||||
|
||||
### Q: Compose 如何读取配置？
|
||||
|
||||
- 使用 `--env-file infra/local/env/.env` 注入本地 Supabase 栈变量
|
||||
- Compose 文件为 `infra/local/docker-compose.yml`
|
||||
- 应用代码通过 `os.getenv()` 读取本地应用变量
|
||||
@@ -1,21 +0,0 @@
|
||||
# 目录结构规则
|
||||
|
||||
## 顶层目录（必须遵守）
|
||||
|
||||
仓库根目录只能包含以下目录：
|
||||
|
||||
- `apps/` —— 可运行应用（Flutter / FastAPI / Worker）
|
||||
- `infra/` —— 基础设施（本地 docker / 云部署 / 迁移）
|
||||
- `configs/` —— 配置规范与公共配置模板（不含密钥）
|
||||
- `tools/` —— 脚本与生成器
|
||||
- `docs/` —— 文档与规则
|
||||
- `.github/`（可选，用于 CI/CD）
|
||||
- `README.md`
|
||||
- `Makefile`（可选）
|
||||
|
||||
## 禁止事项
|
||||
|
||||
- 禁止在根目录直接出现：`backend/`、`ui/`、`docker/`、`scripts/` 等非规范目录
|
||||
- 所有业务代码必须放在 `apps/` 目录下
|
||||
- 所有配置文件必须放在 `configs/` 目录下
|
||||
- 所有基础设施相关代码必须放在 `infra/` 目录下
|
||||
@@ -1,25 +0,0 @@
|
||||
# 火山云部署指南
|
||||
|
||||
## 准备工作
|
||||
|
||||
1. 火山云账号
|
||||
2. 配置云端环境变量
|
||||
3. 准备镜像仓库
|
||||
|
||||
## 环境变量模板
|
||||
|
||||
云端模板文件位置：
|
||||
|
||||
```bash
|
||||
cp infra/cloud/volcano/env/.env.example infra/cloud/volcano/env/.env
|
||||
```
|
||||
|
||||
## 部署流程
|
||||
|
||||
待补充详细步骤...
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 确保所有敏感信息使用环境变量或密钥管理
|
||||
- 遵循最小权限原则
|
||||
- 配置适当的监控和日志
|
||||
@@ -1,272 +0,0 @@
|
||||
# 本地开发指南
|
||||
|
||||
## 前置要求
|
||||
|
||||
- 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`
|
||||
Reference in New Issue
Block a user