MBE Monorepo - 开发环境设置指南

本文档详细说明如何设置 MBE Monorepo 的开发环境。

📋 目录

• 前置要求
• 快速开始
• 开发环境设置
• 代码结构
• 开发工作流
• 测试
• 调试
• 代码规范
• 常见问题

🔧 前置要求

必需软件

• Python >= 3.11
• Docker >= 20.10
• Docker Compose >= 2.0
• Git >= 2.30
• 代码编辑器: VS Code / Cursor（推荐）

可选工具

• Postman / Insomnia: API 测试
• pgAdmin / DBeaver: 数据库管理
• Redis Insight: Redis 管理

🚀 快速开始

1. 克隆仓库

git clone https://github.com/zenglx1978/mbe-monorepo.git
cd mbe-monorepo

2. 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑环境变量（开发环境可以使用默认值）
# 但建议修改数据库密码
nano .env

3. 启动开发环境

# 启动所有服务（包括数据库和 Redis）
docker compose -f docker-compose.dev.yml up -d

# 查看服务状态
docker compose -f docker-compose.dev.yml ps

# 查看日志
docker compose -f docker-compose.dev.yml logs -f mbe-api-dev

4. 验证环境

# 检查 API 是否运行
curl http://localhost:8000/api/health

# 访问 API 文档
# 浏览器打开: http://localhost:8000/docs

💻 开发环境设置

本地 Python 环境（可选）

如果你不想使用 Docker，可以设置本地 Python 环境：

# 创建虚拟环境
python3.11 -m venv venv

# 激活虚拟环境
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# 安装依赖
pip install -r shared/requirements.txt
pip install -r private/core/requirements.txt
pip install -r private/platform/requirements.txt

# 设置 PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)/private/core/src:$(pwd)/private/platform/src:$(pwd)/shared/src"
# Windows PowerShell:
$env:PYTHONPATH = "$(pwd)\private\core\src;$(pwd)\private\platform\src;$(pwd)\shared\src"

VS Code / Cursor 配置

推荐扩展：

• Python
• Pylance
• Ruff（代码检查和格式化）
• Docker
• GitLens

工作区设置（.vscode/settings.json）：

{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
  "python.analysis.extraPaths": [
    "${workspaceFolder}/private/core/src",
    "${workspaceFolder}/private/platform/src",
    "${workspaceFolder}/shared/src"
  ],
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "python.formatting.provider": "ruff",
  "editor.formatOnSave": true,
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true
  }
}

数据库连接

开发环境数据库：

• Host: localhost
• Port: 5432
• Database: mbe_dev
• User: mbe
• Password: dev_password（在 .env 中配置）

连接字符串：

postgresql+asyncpg://mbe:dev_password@localhost:5432/mbe_dev

Redis 连接

开发环境 Redis：

• Host: localhost
• Port: 6379
• Password: dev_redis（在 .env 中配置）

连接字符串：

redis://:dev_redis@localhost:6379/0

📁 代码结构

目录说明

mbe-monorepo/
├── private/
│   ├── core/src/          # 核心算法（HOPE、TITANS、MOE）
│   │   ├── core/         # 核心引擎
│   │   ├── moe/         # Mixture of Experts
│   │   ├── knowledge/   # 知识库管理
│   │   └── llm/         # LLM 客户端
│   └── platform/src/      # 平台服务
│       ├── users/       # 用户管理
│       ├── payments/    # 支付服务
│       └── market/      # 应用市场
│
├── shared/src/            # 共享基础设施
│   ├── interfaces/       # 接口抽象层
│   ├── storage/         # 数据库/Redis
│   ├── api/             # API 路由
│   ├── tasks/           # Celery 任务
│   └── ...
│
└── public/               # 开源模块
    ├── sdk-python/      # Python SDK
    └── mcp-server/      # MCP Server

模块依赖规则

1. Public 模块不能直接导入 Private 模块
2. Public 模块通过 interfaces 层访问 Private 服务
3. Shared 模块可以被所有模块使用
4. Private 模块可以导入 Shared 模块

检查模块边界：

python tools/dev-workspace/check_boundaries.py

🔄 开发工作流

1. 创建功能分支

# 从 main 分支创建新分支
git checkout main
git pull origin main
git checkout -b feature/your-feature-name

2. 开发代码

# 启动开发环境（如果未启动）
docker compose -f docker-compose.dev.yml up -d

# 代码会自动热重载（如果使用 Docker）
# 或手动重启服务
docker compose -f docker-compose.dev.yml restart mbe-api-dev

3. 运行测试

# 运行所有测试
docker compose -f docker-compose.dev.yml exec mbe-api-dev pytest

# 运行特定模块测试
pytest shared/tests/ -v
pytest private/core/tests/ -v

# 运行并查看覆盖率
pytest --cov=shared/src --cov=private/core/src --cov-report=html

4. 代码检查

# 检查代码规范
ruff check private/core/src/ shared/src/

# 格式化代码
ruff format private/core/src/ shared/src/

# 检查模块边界
python tools/dev-workspace/check_boundaries.py --strict

5. 提交代码

# 添加更改
git add .

# 提交（遵循 Conventional Commits）
git commit -m "feat: add new feature"
# 或
git commit -m "fix: fix bug in module X"
# 或
git commit -m "docs: update README"

# 推送分支
git push origin feature/your-feature-name

6. 创建 Pull Request

1. 在 GitHub 上创建 Pull Request
2. CI 会自动运行检查和测试
3. 等待代码审查
4. 合并到 main 分支

🧪 测试

运行测试

# 运行所有测试
pytest

# 运行特定目录的测试
pytest shared/tests/
pytest private/core/tests/

# 运行特定测试文件
pytest shared/tests/test_storage.py

# 运行特定测试函数
pytest shared/tests/test_storage.py::test_database_connection

# 详细输出
pytest -v

# 显示打印输出
pytest -s

测试配置

pytest.ini（项目根目录）：

[pytest]
testpaths = shared/tests private/core/tests private/platform/tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
asyncio_mode = auto

编写测试

示例测试文件（shared/tests/test_storage.py）：

import pytest
from storage.database import get_db

@pytest.mark.asyncio
async def test_database_connection():
    """测试数据库连接"""
    async for db in get_db():
        assert db is not None
        break

🐛 调试

Docker 开发环境调试

使用 debugpy（已配置）：

1. 在代码中添加断点：

import debugpy
debugpy.listen(5678)
debugpy.wait_for_client()  # 可选：等待调试器连接

2. 在 VS Code 中附加调试器：
   • 打开调试面板（F5）
   • 选择 "Python: Attach" 配置
   • 设置端口为 5678
   • 开始调试

日志调试

from loguru import logger

logger.debug("Debug message")
logger.info("Info message")
logger.warning("Warning message")
logger.error("Error message")

查看日志：

# 查看实时日志
docker compose -f docker-compose.dev.yml logs -f mbe-api-dev

# 查看最近 100 行
docker compose -f docker-compose.dev.yml logs --tail 100 mbe-api-dev

数据库调试

# 连接到数据库
docker compose -f docker-compose.dev.yml exec postgres psql -U mbe -d mbe_dev

# 执行 SQL 查询
SELECT * FROM users LIMIT 10;

Redis 调试

# 连接到 Redis
docker compose -f docker-compose.dev.yml exec redis redis-cli -a dev_redis

# 查看所有键
KEYS *

# 查看特定键的值
GET key_name

📏 代码规范

Python 风格

• 遵循 PEP 8 风格指南
• 使用 ruff 进行代码检查和格式化
• 行长度限制：100 字符（可配置）

代码检查

# 检查代码
ruff check private/core/src/ shared/src/

# 自动修复可修复的问题
ruff check --fix private/core/src/ shared/src/

# 格式化代码
ruff format private/core/src/ shared/src/

提交前检查

使用 pre-commit hook：

# 安装 pre-commit
pip install pre-commit

# 安装 git hooks
pre-commit install

# 手动运行
pre-commit run --all-files

pre-commit 配置（.pre-commit-config.yaml）：

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

命名规范

• 模块名: 小写，下划线分隔（user_service.py）
• 类名: 驼峰命名（UserService）
• 函数名: 小写，下划线分隔（get_user_by_id）
• 常量: 大写，下划线分隔（MAX_RETRIES）

❓ 常见问题

1. 端口被占用

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

# 停止占用端口的进程或修改 docker-compose.dev.yml 中的端口

2. 数据库连接失败

# 检查数据库是否运行
docker compose -f docker-compose.dev.yml ps postgres

# 检查环境变量
docker compose -f docker-compose.dev.yml exec mbe-api-dev env | grep DATABASE_URL

# 重启数据库
docker compose -f docker-compose.dev.yml restart postgres

3. 热重载不工作

# 检查 volume 挂载
docker compose -f docker-compose.dev.yml config

# 重启服务
docker compose -f docker-compose.dev.yml restart mbe-api-dev

4. 导入错误

# 检查 PYTHONPATH
docker compose -f docker-compose.dev.yml exec mbe-api-dev env | grep PYTHONPATH

# 验证模块路径
docker compose -f docker-compose.dev.yml exec mbe-api-dev python -c "import sys; print(sys.path)"

5. 测试失败

# 检查测试数据库连接
docker compose -f docker-compose.dev.yml exec postgres psql -U mbe -d mbe_dev -c "SELECT 1;"

# 清理测试数据
pytest --clean-db

# 查看详细错误
pytest -v --tb=long

📚 相关资源

• Python 官方文档
• FastAPI 文档
• Docker 文档
• Ruff 文档

🤝 获取帮助

• 查看项目 README.md
• 查看 部署指南
• 提交 GitHub Issue（仅限公开模块）
• 联系项目维护者

最后更新：2026-02-06