# 部署说明

本文档覆盖本地开发、Docker 和 Ubuntu 服务器部署。

## 本地开发

### 系统要求

- Python 3.9+
- Node.js 16+ + npm
- C++ 编译器（macOS: Xcode CLI Tools；Linux: `build-essential`）

### 一键前后端联调

```bash
./start-all.sh
```

- 后端：http://localhost:8000
- 前端：http://localhost:3000
- 后端端口可在环境变量 `BACKEND_PORT` 中覆盖（默认 `8000`）

### 单独启动后端

```bash
cd backend
./start-dev.sh
```

脚本行为：

1. 探测 Python 3.9+（优先系统 Python，否则创建 `.venv`）
2. 检查依赖：`fastapi uvicorn python-multipart pydantic pandas openpyxl pillow numpy matplotlib`
3. 在外部 Python 中复用 `scipy`（ABI 匹配时），避免网络安装
4. C++ 扩展 `ewc_core` 源码有更新时自动重新编译
5. 确保运行时目录：`service_workspace`、`service_assets`、`service_projects`
6. 自动释放被占用的端口
7. 以 `uvicorn --reload` 启动 FastAPI 服务

### 单独启动前端

```bash
cd frontend
npm install
npm run dev
```

前端通过 Vite 代理访问后端，配置见 `frontend/vite.config.ts`。

## Docker 部署

项目根目录包含 `Dockerfile` 和 `docker-compose.yml`。

### 构建并启动

```bash
docker compose up -d --build
```

- 前端：http://localhost:3000
- 后端：http://localhost:8000
- 后端文档：http://localhost:8000/docs

### 常用命令

```bash
docker compose logs -f    # 查看日志
docker compose down       # 停止服务
docker compose restart    # 重启服务
```

## Ubuntu 服务器部署

使用 `install-ubuntu.sh` 一键部署：

```bash
chmod +x install-ubuntu.sh
./install-ubuntu.sh
```

脚本行为：

1. 检查并安装 Docker（Ubuntu/Debian 自动安装）
2. 确保 `docker compose` 可用
3. 调用 `docker compose up -d --build`
4. 打印访问地址

可选环境变量：

| 变量 | 说明 |
|------|------|
| `SKIP_DOCKER_INSTALL=1` | 跳过 Docker 安装检测 |
| `NO_BUILD=1` | 不强制 `--build`（沿用已有镜像） |

首次部署会编译 C++ 扩展和前端，可能需要几分钟。

### release 包

`scripts/pack-release.sh` 用于打包 release 包，包含：

- 预编译前端（无 Node 环境也能运行）
- Docker 部署脚本
- 简化版 `install-ubuntu.sh`

## 产物目录

运行时产生的数据和文件保存在以下目录（已加入 `.gitignore`）：

| 目录 | 用途 |
|------|------|
| `backend/service_workspace/` | 任务产物（输入/输出/配置） |
| `backend/service_assets/` | 后端素材库 |
| `backend/service_projects/` | 后端工程项目 |
| `backend/service_design_templates/` | 设计模板 |
| `backend/service_fonts/` | 上传字体 |
| `backend/.runtime/` | 运行时日志 |
| `backend/benchmark_outputs/` | 基准测试结果 |

## 环境变量

| 变量 | 影响范围 | 说明 |
|------|----------|------|
| `BACKEND_PORT` | 本地开发 | 后端监听端口，默认 `8000` |
| `SKIP_DOCKER_INSTALL` | Ubuntu 部署 | 跳过 Docker 自动安装 |
| `NO_BUILD` | Ubuntu 部署 | 不强制 Docker 重建 |
| `WORDCLOUD_SCIPY_SITE` | 本地开发 | 外部 SciPy 路径加速启动 |

## 注意事项

- 重启后端服务会导致内存中的任务状态丢失，但 `service_workspace` 中的文件产物不受影响
- 首次启动时 C++ 扩展编译需要系统编译器；如果失败请检查 `build-essential` 或 Xcode CLI Tools
- 前端 `localStorage` 中的贴纸库和画布文档不会自动同步到服务器