本地开发环境搭建
本文档介绍如何在本地机器上搭建完整的 RadStudio 开发环境，适合希望参与二次开发的工程师。
选择适合你的方式
- Docker 方式（推荐）— 一键启动所有依赖，源码挂载热更新
- 混合方式 — Docker 运行基础设施，本地运行前后端（调试灵活）
- 纯本地方式 — 所有服务都在本地运行（不推荐，配置复杂）
方式一：Docker 全栈开发（推荐）
前置要求
| 工具 | 最低版本 | 说明 |
|---|---|---|
| Docker | 24.0+ | 容器运行环境 |
| Docker Compose | v2 | 多容器编排 |
| Git | — | 拉取代码 |
| Node.js | 18+ | 依赖安装和脚本运行（可选） |
| Python | 3.11+ | 依赖安装和脚本运行（可选） |
步骤
# 1. 克隆代码
git clone https://github.com/radstudio/radstudio.git
cd radstudio
# 2. 初始化配置
./scripts/radstudioctl.py init
# 3. 编辑 .env，填入必要的密钥
# vim .env 或直接使用默认值（仅限本地开发）
# 4. 启动全部服务
./scripts/radstudioctl.py up
首次启动会拉取镜像并构建容器，约需 3-5 分钟。启动后访问：
| 服务 | 地址 | 热更新 |
|---|---|---|
| 前端 | http://localhost:5173 | 源码挂载，保存即刷新 |
| 管理后台 | http://localhost:8080 | 源码挂载 |
| 后端 API | http://localhost:8000 | --reload，代码改动自动重载 |
| API 文档 | http://localhost:8000/docs | — |
| MinIO 控制台 | http://localhost:9001 | — |
方式二：混合开发模式
如果你希望更灵活的调试体验（如使用 IDE 断点调试），可以采用混合模式：Docker 运行基础设施，本地运行前后端。
1. 启动基础设施
# 仅启动 PostgreSQL、Redis、MinIO
./scripts/radstudioctl.py up --profile infra
# 或
docker compose -f deploy/docker-compose.yml --profile infra up -d
2. 启动前端
# 从项目根目录
npm install
npm -w frontend run dev
# 前端运行在 http://localhost:5173
如果需要前端连接本地后端，修改 apps/frontend/vite.config.ts 中的代理配置：
// vite.config.ts
export default defineConfig({
server: {
proxy: {
'/api': {
target: 'http://localhost:8000',
changeOrigin: true,
},
},
},
});
3. 启动后端
cd apps/backend
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux / macOS
# .venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt
# 修改 .env 中的连接地址为 localhost
# POSTGRES_HOST=localhost
# REDIS_HOST=localhost
# MINIO_ENDPOINT=localhost:9000
# 启动开发服务器
uvicorn app.main:app --reload --port 8000
4. 启动管理后台
# 从项目根目录
npm -w admin run dev
# 管理后台运行在 http://localhost:8080
5. 启动 Worker（可选）
# CPU Worker
cd apps/backend
celery -A app.core.celery_app worker -Q cpu --concurrency=2 -l info
# 文件处理 Worker
celery -A app.core.celery_app worker -Q files --concurrency=1 -l info
方式三：纯本地开发（不推荐）
不推荐纯本地运行，因为需要手动安装和配置 PostgreSQL、Redis、MinIO 等服务。如果确实需要：
| 服务 | 安装方式 | 默认端口 |
|---|---|---|
| PostgreSQL 16 | 官方安装包 | 5432 |
| Redis 7 | 官方安装包 | 6379 |
| MinIO | 官方文档 | 9000/9001 |
安装后分别创建数据库和用户，然后在 .env 中将所有 *_HOST 设为 localhost。
开发环境验证
前端检查
curl -s http://localhost:5173 | head
后端检查
curl http://localhost:8000/health
# -> {"status":"healthy"}
数据库检查
docker compose -f deploy/docker-compose.yml exec postgres psql -U radstudio -d radstudio
存储检查
# MinIO 控制台: http://localhost:9001
# 默认账号/密码: minioadmin / minioadmin
常用开发工作流
修改前端代码
- 修改
apps/frontend/src/中的文件 - 浏览器自动热更新
修改后端代码
- 修改
apps/backend/app/中的文件 - Uvicorn
--reload自动重载
数据库迁移
cd apps/backend
# 创建迁移文件
alembic revision --autogenerate -m "描述你的修改"
# 应用迁移
alembic upgrade head
# 回滚一步
alembic downgrade -1
运行测试
# 前端测试
npm -w frontend test
# 后端测试
cd apps/backend
pytest
pytest -m "no_db"
故障排查
端口被占用
# Windows
netstat -ano | findstr :5173
# Linux / macOS
lsof -i :5173
依赖安装失败
# 前端 - 清除缓存重新安装
rm -rf node_modules package-lock.json
npm install
# 后端 - 重建虚拟环境
rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Docker 构建失败
# 清除 Docker 构建缓存
docker builder prune -af
docker compose -f deploy/docker-compose.yml build --no-cache