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 中被忽略。

构建镜像（从源码）

在项目根运行：

docker compose build

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

启动服务

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 虚拟环境

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

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

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 模式）

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

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

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

• 启动前端开发服务器

cd web
npm run dev

调试提示：

• 修改 cloud/custom_nodes 中的自定义节点后，若后端未自动热重载，请重启后端服务以加载新节点。

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

如果你希望在与生产镜像更接近的环境中开发、避免在主机上直接安装依赖，我们提供 docker-compose.dev.yml，它会：

• 把仓库作为卷挂载到容器内，便于热重载与编辑
• 在容器内安装并运行 uvicorn --reload（后端）和 Vite dev server（前端）

在仓库根运行：

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. 激活虚拟环境

.\.venv\Scripts\Activate.ps1

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

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

脚本说明：

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

3. （可选）创建 release ZIP

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. 启动服务

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. 运行时检查

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 验证。

• 日志采集

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

--

6. 回滚 (Rollback)

步骤（快速）

1. 停止服务

docker compose down

2. 从历史 release 恢复

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

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

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

--

附录：常用命令速查

• 生成 dist：

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

• 生成 release zip：

python .\scripts\build_release.py

• 运行生产堆栈：

docker compose down
docker compose build
docker compose up -d

---

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