ishenwei/nexus

Fork 0

Files

admin e01ca79bdc 文档更新

2026-06-04 14:34:32 +08:00

7.3 KiB

Raw Blame History

For AI assistants: Read this entire file before writing any code. All decisions here are final.

本地开发手册 (Local Development Manual)

本手册为 Fonrey 项目本地环境搭建与开发验证的权威指南。旨在帮助新入场开发人员或 AI agent 快速启动项目并确保开发环境与生产环境的技术决策一致。

§0 文档定位 + 变更历史表

日期	变更人	变更内容	版本
2026-06-04	Sisyphus-Junior	初始化本地开发手册，整合 ADR 与技术总纲决策	v1.0

§1 前置依赖

运行 Fonrey 前，请确保本地环境已安装以下基础组件：

操作系统: 推荐 Linux (Ubuntu 22.04+) 或 macOS。Windows 用户建议使用 WSL2。
Python: 3.12+
Node.js: 20.x+ (用于 Tailwind CSS 编译)
Docker & Docker Compose: 必须，用于运行数据库、缓存与消息队列。
PostgreSQL: 16.x (通过 Docker 运行)
Redis: 7.x (通过 Docker 运行)
浏览器: 最新版 Google Chrome 或 Chromium (用于 Playwright E2E 测试)

§2 仓库初始化

按照以下步骤克隆仓库并安装依赖：

# 克隆仓库
git clone <repository_url> fonrey
cd fonrey

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
# .\venv\Scripts\activate  # Windows

# 安装 Python 依赖
pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements/test.txt  # 仅开发环境需要

# 安装前端依赖
npm install

§3 环境变量 (`.env`)

在项目根目录创建 .env 文件。以下为必需项清单及示例值：

# Django 基础配置
DEBUG=True
SECRET_KEY=django-insecure-development-key-change-me
ALLOWED_HOSTS=localhost,127.0.0.1,.fonrey.test

# 数据库配置 (需配合 Docker Compose)
DATABASE_URL=postgres://fonrey_user:fonrey_password@localhost:5432/fonrey_db
# 如果使用 PgBouncer
# DATABASE_URL=postgres://fonrey_user:fonrey_password@localhost:6432/fonrey_db

# Redis 配置
REDIS_URL=redis://localhost:6379/0

# Celery 配置
CELERY_BROKER_URL=redis://localhost:6379/1
CELERY_RESULT_BACKEND=redis://localhost:6379/1

# Cloudflare R2 / S3 存储 (本地开发推荐使用 MinIO)
AWS_ACCESS_KEY_ID=minio_admin
AWS_SECRET_ACCESS_KEY=minio_password
AWS_STORAGE_BUCKET_NAME=fonrey-media
AWS_S3_ENDPOINT_URL=http://localhost:9000
AWS_S3_REGION_NAME=auto

# Sentry (本地开发可选)
SENTRY_DSN=

# 加密密钥 (AES-256-GCM，必须为 32 字节 Base64)
FIELD_ENCRYPTION_KEY=your-32-byte-base64-encoded-key

§4 数据库与缓存启动

推荐使用 Docker Compose 快速拉起基础服务。项目根目录应包含 docker-compose.yml：

# 启动 PostgreSQL, Redis, MinIO
docker-compose up -d

# 验证服务状态
docker-compose ps

PgBouncer 提示: 生产环境强制使用 PgBouncer 进行连接池管理。本地开发环境下，如果需要模拟高并发连接，可开启 docker-compose 中的 pgbouncer 服务并将 DATABASE_URL 指向 6432 端口。

§5 django-tenants 初始化

由于项目采用 django-tenants 多租户架构，必须先初始化公共 Schema (public schema)：

# 1. 运行公共 Schema 的迁移
python manage.py migrate_schemas --shared

# 2. 创建第一个租户 (手动交互或使用脚本)
# 注意：在本地开发时，建议将租户域名映射到 .fonrey.test

§6 测试租户与种子数据

目前项目尚未完成自动化 seed 命令。建议通过以下方式手动创建测试环境：

6.1 创建初始租户 (建议命令)

预期放置位置: apps/tenant/management/commands/setup_dev_tenant.py

# 尚未实现，需后续补写。目前请进入 python shell 手动创建：
python manage.py shell
>>> from apps.tenant.models import Tenant, Domain
>>> tenant = Tenant.objects.create(schema_name='test_tenant', name='测试经纪公司')
>>> Domain.objects.create(domain='test.fonrey.test', tenant=tenant, is_primary=True)

6.2 导入枚举种子数据

# 导入 ENUMS.md 定义的公共枚举值
python manage.py loaddata shared/fixtures/enum_labels.json

§7 后端启动

本地开发环境直接使用 Django 开发服务器即可。生产环境必须使用 Gunicorn + Uvicorn。

# 本地开发模式
python manage.py runserver 8000

§8 Celery 与 Celery Beat 启动

涉及异步任务（如图片处理、导出、配房）时，必须启动 Worker 和 Beat：

# 启动 Worker
celery -A core worker -l info

# 启动 Beat (定时任务)
celery -A core beat -l info

§9 前端资源

Fonrey 依赖 Tailwind CSS 进行样式构建。

# 开发模式：监听文件变化并实时编译
npm run dev

# 生产构建
npm run build

§10 静态资源与对象存储本地替代方案

本地开发建议使用 MinIO 替代 Cloudflare R2。

修改 .env 中的 AWS_S3_ENDPOINT_URL 指向 MinIO 地址。
确保已手动或通过脚本创建了 media 和 releases 桶。
访问 http://localhost:9001 进入 MinIO 控制台。

§11 测试运行手册

所有测试基于 pytest 运行。

11.1 运行单元与集成测试

# 运行全量测试
pytest

# 按目录跑集成测试
pytest tests/integration/property/

# 查看覆盖率
pytest --cov=apps --cov=core

11.2 运行 E2E 测试 (Playwright)

# 安装浏览器驱动 (仅需一次)
playwright install chromium

# 运行 E2E
pytest tests/e2e/

§12 dev / staging / production 配置差异表

配置项	Local Dev	Staging	Production
DEBUG	True	False	False
多租户驱动	django-tenants	django-tenants	django-tenants
数据库	Postgres 16	Postgres 16 (RDS/Self-host)	Postgres 16 + PgBouncer
存储服务	MinIO (本地)	Cloudflare R2	Cloudflare R2
任务队列	Redis	Redis	Redis (Cluster/Sentinel)
缓存	Redis	Redis	Redis
静态资源	本地处理	Cloudflare CDN	Cloudflare CDN
错误日志	控制台	Sentry	Sentry + Grafana
服务运行器	runserver	Gunicorn + Uvicorn	Gunicorn + Uvicorn + Nginx

§13 常见故障排查

schema 切换失败: 检查 django-tenants 中间件是否已启用，且 ALLOWED_HOSTS 包含对应的子域名。
R2 401: 验证 .env 中的 AWS 凭证是否正确，桶是否存在。
Celery 任务不执行: 检查 Redis 是否连通，Worker 是否已启动，且任务是否使用了 @tenant_task 装饰器。
HTMX 局刷 404: 确认视图是否处理了 HX-Request 头，且 URL 路由配置正确。

§14 关联文档索引

AGENTS.md, 技术栈总览与禁止项
ADR.md, 关键技术决策追溯
TECH_STACK/测试规范.md, 详细测试要求
DATA_MODEL/DATA_MODEL.md, 数据架构定义

§15 待澄清/待补项

种子数据脚本: 尚未实现 setup_dev_tenant 命令，目前需手动在 Shell 创建租户。
MinIO 预设: 需要一个初始化脚本自动创建所需的 S3 桶（media, releases）。
Playwright 浏览器环境: 尚未在 CI 配置中固定特定 Chromium 版本，本地开发建议使用最新版。
系统配置 DDL: AGENTS.md 提到系统配置 PRD 暂为空，对应的 DDL 迁移可能不完整。

7.3 KiB Raw Blame History Unescape Escape