TraceStudio/DEPLOYMENT.md

# TraceStudio 部署说明（Windows + Docker Desktop）

本文档包含将 TraceStudio 部署到共享 Windows 机器（使用 Docker Desktop）的步骤、建议的卷挂载、端口说明、回滚方法与常见故障排查。

## 前提
- 已安装 Docker Desktop（Windows）并启用 WSL2 或 Hyper-V。确保 Docker Desktop 有权限访问 `D:` 驱动器（Settings → Resources → File Sharing）。
- 项目位于 `D:/XGame/TraceStudio`。
- 确认 `archive/`、`dist/` 在 `.gitignore` 中被忽略。

## 构建镜像（从源码）
在项目根运行：

```powershell
docker compose build
```

开关说明：`docker-compose.yml` 已配置将 `D:/XGame/TraceStudio/cloud` 挂载到容器内 `/opt/tracestudio/cloud`，以便 `server` 访问共享文件。

## 启动服务

```powershell
docker compose up -d

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

前端默认通过 `http://<host>` (80) 访问，后端 API 通过 `http://<host>:8000` 访问。根据部署时的 `docker-compose.yml` 端口映射调整。

# TraceStudio — 标准作业程序 (SOP)

此文档为 TraceStudio 的部署与运维标准作业程序（SOP），适用于在共享 Windows 服务器上使用 Docker Desktop 进行部署，以及本地开发和打包流程。它覆盖先决条件、开发指南、构建打包流程（`prepare_dist.py`）、生产部署（Windows + Docker Desktop）、常见故障排查与回滚步骤。

重要：请勿将 `dist/` 提交到版本库。`dist/` 是由 `scripts/prepare_dist.py` 生成的构建产物，仅作打包和发布之用。

文件速查：
- `scripts/prepare_dist.py` — 生成干净部署包（copy / archive 模式）
- `scripts/build_release.py` — 自动化生成 timestamped release zip
- `docker-compose.yml` — 推荐的本地与生产 compose 配置
- `server/Dockerfile` — 生产多阶段 Dockerfile（参考）
- `server/requirements.txt`、`server/dev-requirements.txt`
- `archive/` — 被归档的原始配置与脚本备份

**目录结构与约定**
- `cloud/`：数据与自定义节点（应作为主机卷挂载到容器）
- `dist/`：临时构建输出（不应加入 Git）
- `archive/`：备份被移除或替换的文件

**目录权限与挂载约定（默认）**
- Host path: `D:/XGame/TraceStudio/cloud` → Container path: `/opt/tracestudio/cloud`

**修订**: 2026-01-12

--

**1. 环境准备 (Prerequisites)**

- 操作系统：Windows 10/11 或 Windows Server 2019/2022
- Docker：Docker Desktop（最新稳定版），建议启用 WSL2 后端
- Docker Compose：v2（随 Docker Desktop 提供）
- Python：3.9+（建议 3.10 / 3.11）
- Node.js：16+（用于前端构建）
- Git：用于源码管理与回退

推荐硬件（最小 / 建议）：
- CPU：4 cores / 8 cores
- 内存：8 GB / 16 GB
- 磁盘：50 GB 可用（取决于 `cloud/` 数据大小，若存放大量 trace 数据请预留更多）

权限与网络
- 在 Docker Desktop 中允许对包含仓库与 `cloud/` 的主机驱动器授权（Settings → Resources → File Sharing）。
- 有权限运行 Docker Desktop、访问 `D:/XGame/TraceStudio` 路径，并写入 `archive/` 与 `dist/`。

--

**2. 开发指南 (Local Development)**

快速搭建本地开发环境：

1) 克隆仓库并创建 Python 虚拟环境

```powershell
git clone <repo-url> TraceStudio
cd TraceStudio
python -m venv .venv
.\.venv\Scripts\Activate.ps1   # PowerShell
```

2) 安装依赖（生产 + 开发）

```powershell
pip install -r server/requirements.txt
pip install -r server/dev-requirements.txt
cd web
npm install
cd ..
```

说明：`server/dev-requirements.txt` 包含开发工具（例如 `debugpy`, `pytest`, `black`, `mypy`, `pre-commit`, `flake8`）。用于本地调试与代码质量检查，不应被包含在生产镜像中。

3) 配置本地环境变量

- 参考 `web/.env.example` 创建 `web/.env`（不要把 `.env` 提交到 Git）。
- 根据需要调整 `server/system_config.yaml` 中非敏感设置。

4) 本地启动（Debug 模式）

- 启动后端（带自动重载）

```powershell
cd server
python -m uvicorn main:app --reload --host 127.0.0.1 --port 8000
```

- 使用 IDE 调试：`debugpy` 已包含在 `server/dev-requirements.txt`，可在 IDE 中设置远程调试端口并 attach。

- 启动前端开发服务器

```powershell
cd web
npm run dev
```

调试提示：
- 修改 `cloud/custom_nodes` 中的自定义节点后，若后端未自动热重载，请重启后端服务以加载新节点。

4.1) 基于 Docker 的开发（推荐）

如果你希望在与生产镜像更接近的环境中开发、避免在主机上直接安装依赖，我们提供 `docker-compose.dev.yml`，它会：
- 把仓库作为卷挂载到容器内，便于热重载与编辑
- 在容器内安装并运行 `uvicorn --reload`（后端）和 Vite dev server（前端）

在仓库根运行：

```powershell
docker compose -f docker-compose.dev.yml up --build
```

然后：
- 后端 API 在 `http://localhost:8000`
- 前端 dev server 在 `http://localhost:5173`（Vite）

开发注意事项：
- 第一次运行会在容器内执行 `pip install -r server/requirements.txt` 与 `npm install`，根据网络与依赖大小可能需要几分钟。
- `docker-compose.dev.yml` 将宿主 `cloud/` 挂载到容器，确保 Docker Desktop 授权访问所在驱动器（如 `D:`）。

--

**3. 构建与发布 (Build & Ship)**

目标：生成一个只包含运行时所需文件的 `dist/` 包并（可选）创建 release zip，供部署或镜像构建使用。

为什么需要 `dist/`？
- `dist/` 是受控的、最小化的部署快照。它避免将开发依赖、缓存、临时文件或本地大数据误打包进生产镜像，并为构建过程提供可复现的输入。

生成 `dist/`（推荐流程）

1. 激活虚拟环境

```powershell
.\.venv\Scripts\Activate.ps1
```

2. 运行准备脚本（copy 模式）

```powershell
python .\scripts\prepare_dist.py --mode copy
```

脚本说明：
- `--mode copy`：将需要的文件/目录复制到 `dist/`（不会删除源文件）。
- `--mode archive`：把标记为过大的或不应纳入 `dist/` 的文件移动到 `archive/`（脚本会记录操作并生成回滚信息）。
- 日志：脚本会将操作记录到 `scripts/prepare_dist.log`，包括回滚脚本路径。

3. （可选）创建 release ZIP

```powershell
python .\scripts\build_release.py
# 结果示例: release_20260112_202437.zip
```

4. 验证 `dist/` 内容
- `dist/` 应只包含：生产 `server/` 代码、构建后的 `web/dist`（或前端静态文件）、必要的配置（`system_config.yaml` 的非敏感部分）、`cloud/custom_nodes`（如果需要）。

安全建议：在运行 `prepare_dist.py --mode archive` 前，请确认 `archive/` 的访问与备份策略，以便在误移除时可恢复。

--

**4. 服务器部署 (Production Deploy) — 共享 Windows 服务器**

建议使用 Docker Compose 来管理 `server` 与 `web` 服务。以下步骤假定目标机器为共享的 Windows 主机，已安装 Docker Desktop 并允许访问托管驱动器。

1) 在目标机器上准备文件

- 选项 A（推荐）：在开发机上运行 `scripts/build_release.py`，将生成的 `release_*.zip` 复制到目标机器并解压。
- 选项 B：在目标机器上从 Git 克隆并运行 `scripts/prepare_dist.py --mode copy`。

2) 检查 Docker Desktop 文件共享

- 打开 Docker Desktop → Settings → Resources → File Sharing，确认包含 `D:`（或项目所在驱动器）的条目。

3) 启动服务

```powershell
cd <release-or-repo-root>
docker compose build
docker compose up -d
```

4) 卷挂载说明（重要）

- Compose 默认将 `D:/XGame/TraceStudio/cloud` 挂载到容器 `/opt/tracestudio/cloud`。若路径不同，请修改 `docker-compose.yml` 中的 volume 映射。
- 挂载为 read-write（:rw），并确保宿主机上的文件权限允许容器进程读写。

5) 运行时检查

```powershell
docker compose ps
docker compose logs -f server
```

--

**5. 故障排查 (Troubleshooting)**

- 容器无法访问主机卷
	- 确认 Docker Desktop 已授予驱动器访问权限并重启 Docker。
	- 检查宿主机目录权限（使用管理员权限查看）。

- 应用异常退出或 `uvicorn` 找不到 `main:app`
	- 查看 `server/Dockerfile` 是否将代码拷贝到镜像内部正确的路径。
	- 在容器内运行 `python -c "import main; print(main)"` 检查 import 错误。

- 端口被占用
	- 执行 `netstat -ano | findstr :8000` 查找占用进程，或修改 `docker-compose.yml` 端口映射。

- 构建失败因依赖
	- 检查 `server/requirements.txt` 是否包含生产所需的库。
	- 在本地虚拟环境运行 `pip install -r server/requirements.txt` 验证。

- 日志采集

```powershell
docker compose logs server --no-log-prefix --tail 200
docker compose logs web --no-log-prefix --tail 200
```

--

**6. 回滚 (Rollback)**

步骤（快速）

1. 停止服务

```powershell
docker compose down
```

2. 从历史 release 恢复

```powershell
Expand-Archive -Path .\release_<YYYYMMDD_HHMMSS>.zip -DestinationPath .\dist -Force
cd dist
docker compose build
docker compose up -d
```

3. 恢复被归档的文件（如适用）

- 检查 `archive/` 中的备份，按需复制回原位或使用脚本中记录的回滚路径。

--

**附录：常用命令速查**

- 生成 dist：

```powershell
python .\scripts\prepare_dist.py --mode copy
```

- 生成 release zip：

```powershell
python .\scripts\build_release.py
```

- 运行生产堆栈：

```powershell
docker compose down
docker compose build
docker compose up -d
```

---

若需把 SOP 定制为企业内部流程（例如 CI/CD、私有镜像仓库、自动化回滚或与公司监控系统整合），请告知要接入的工具/平台，我可继续为你扩展自动化脚本与 CI 配置。