TraceStudio/DEPLOYMENT.md

# TraceStudio 部署说明

本文档说明本地开发调试和 Docker 部署的方式。

## 目录
1. [本地调试模式](#本地调试模式)
2. [Docker 部署](#docker-部署)
3. [故障排查](#故障排查)

---

## 本地调试模式

**前置条件**：虚拟环境已激活，依赖已安装
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r server/requirements.txt
pip install -r server/dev-requirements.txt
cd web && npm install && cd ..
```

**启动后端**（终端 1）
```powershell
cd server
python -m uvicorn main:app --reload --host 127.0.0.1 --port 8000
```

**启动前端**（终端 2）
```powershell
cd web
npm run dev
```

访问地址：
- 后端 API：`http://localhost:8000`
- 前端：`http://localhost:5173`

**VS Code 调试**（可选）
- Ctrl+Shift+D 打开 Run and Debug
- 选择 **"FastAPI: Uvicorn (Local Debug)"**
- F5 启动，支持打断点

**调试配置**（`.vscode/launch.json`）
- **FastAPI: Uvicorn (Local Debug)** ⭐ 推荐
- **FastAPI: Debug Mode (debugpy wait)**
- **Attach to debugpy (5678)**

---

## Docker 部署

**启动 Docker 服务**
```powershell
docker compose build
docker compose up -d
```

访问地址：
- 后端 API：`http://localhost:8000`
- 前端：`http://localhost:5173`

**查看日志**
```powershell
docker compose logs -f server
docker compose logs -f web
```

**停止服务**
```powershell
docker compose down
```

---

## 故障排查

| 问题 | 解决方案 |
|------|--------|
| 端口 8000 被占用 | `netstat -ano \| findstr :8000` 找到进程后关闭 |
| 容器启动失败 | `docker compose logs server` 查看错误日志 |
| 虚拟环境找不到依赖 | 重新激活并运行 `pip install -r server/requirements.txt` |
| 自定义节点未加载 | 本地：重启后端；Docker：`docker compose restart server` |

---

**最后更新**：2026-01-13