Files

T

broccoliandClaude Sonnet 5 1d17b5e20d Rework layout engine around exact-glyph collision, add tests and docs sync

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>

2026-07-26 18:32:25 +08:00

3.4 KiB

Raw Blame History

部署说明

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

本地开发

系统要求

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

一键前后端联调

./start-all.sh

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

单独启动后端

cd backend
./start-dev.sh

脚本行为：

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

单独启动前端

cd frontend
npm install
npm run dev

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

Docker 部署

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

构建并启动

docker compose up -d --build

常用命令

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

Ubuntu 服务器部署

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

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

脚本行为：

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

可选环境变量：

变量	说明
`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 中的贴纸库和画布文档不会自动同步到服务器

3.4 KiB Raw Blame History Unescape Escape