broccoliandClaude Sonnet 5
1d17b5e20d
Replace the old bbox/heuristic placement (scale search rounds, large-font capping, stratified sampling, fill-retry ladders) with an area-model font sizing pass feeding a C++ exact-glyph collision engine (centroid-biased spiral + random probing, HD clearance refinement, density/hole optimization). Simplify the frontend advanced-params panel and JobParams type to match the surviving config surface, add a layout-constraints test suite and a repeatable benchmark tool, and bring docs/*.md back in sync with current code (plus new TESTING.md and DEPLOYMENT.md). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
133 lines
3.4 KiB
Markdown
133 lines
3.4 KiB
Markdown
# 部署说明
|
||
|
||
本文档覆盖本地开发、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` 中的贴纸库和画布文档不会自动同步到服务器
|