apps/
  backend/   Node + Express + Playwright + OCR worker
  frontend/  Vue 3 + Vite + Element Plus
deploy/
  caddy/     Caddy 配置
  docker/    Dockerfile
docs/        迁移与部署文档
docker-compose.yml

本地开发

前端：

cd apps/frontend
npm install
npm run dev

后端：

cp .env.mac-docker.example .env
cd apps/backend/subservices/ocr-worker
uv sync
cd apps/backend
npm install
npm run dev

Docker 部署

cp .env.server.example .env
mkdir -p deploy/data/backend
docker compose up -d

生产版 Compose 现在会把后端运行数据直接挂载到宿主机目录：

deploy/data/backend

这样服务器上可以直接查看和备份：

logs/
browser-sessions/
redeem-screenshots/
agiso-shops.json
order-fulfillment-bindings.json

如果你本地已经配好了店铺和履约绑定，首次上线前可以把这两份文件先放进去：

deploy/data/backend/agiso-shops.json
deploy/data/backend/order-fulfillment-bindings.json

后端启动时会自动执行数据库 migration、初始化默认管理员、同步履约目录；但 /app/data 下的业务配置文件仍以宿主机目录内容为准。

Docker 本地开发

cp .env.mac-docker.example .env
docker compose -f docker-compose.dev.yml up -d --build

开发环境现在不再把 Caddy 绑定到固定域名。这意味着：

本地直接访问 http://localhost 可用
用 ngrok / cloudflared 转发到 http://localhost:80 时，不需要因为随机子域名变化而改 Caddy 配置
如果要生成发给用户的公网领取链接，只需要更新 .env 里的 APP_BASE_URL

开发版 Compose 现在是热更新模式：

postgres 容器提供 PostgreSQL
后端源码挂载到容器里，运行 npm run dev
前端源码挂载到容器里，运行 vite
Caddy 只负责把 80/443 反代到前后端容器

通常只有首次启动、改 Dockerfile、改系统依赖时才需要 --build。

开发版 Compose 会把后端运行产物目录直接挂载到：

apps/backend/data

这样本地可以直接看到：

data/logs/*.log
浏览器会话产物
截图和证明文件

当 TENCENT_BROWSER_HEADLESS=false 时，开发版后端容器会自动启动 Xvfb + x11vnc + noVNC。默认可直接在本机访问：

http://127.0.0.1:6080/vnc.html

这样即使整个项目都跑在 Docker 里，也可以直接查看后端 Playwright 浏览器画面。

PostgreSQL 数据则保存在 Docker volume 里：

postgres_dev_data

当前 Dockerfile 已默认针对国内服务器优化以下下载源：

Debian apt 使用腾讯云镜像
npm 使用 npmmirror
Python pip 使用腾讯云 PyPI 镜像
后端 Playwright 固定为 1.42.1，浏览器下载使用 npmmirror

如果你的服务器网络环境不同，也可以在构建时覆盖：

docker compose build \
  --build-arg DEBIAN_MIRROR=mirrors.tuna.tsinghua.edu.cn \
  --build-arg NPM_REGISTRY=https://registry.npmjs.org \
  --build-arg UV_INDEX_URL=https://pypi.org/simple

默认入口：

前端与领取页：https://你的域名/
后端健康检查：https://你的域名/health
后端接口前缀：https://你的域名/api/v1/...

开发环境下的链接生成规则：

优先使用 CLAIM_BASE_URL
如果未设置 CLAIM_BASE_URL，后端会自动根据 APP_BASE_URL 推导为 APP_BASE_URL/#/claim

开发时如果只改业务代码，直接保留 docker compose -f docker-compose.dev.yml up -d 即可：

改后端 src/：容器内自动热重启
改前端 src/：Vite 自动热更新
改 OCR Python：后端下次调用时直接走挂载后的最新源码
改数据库 schema：后端启动时会自动执行 migration

详细文档：

迁移原则

不重写现有业务代码
先统一目录、部署和配置
生产环境优先使用 .env 和宿主机数据目录挂载
本机 Docker 调试优先使用 docker-compose.dev.yml

README.md Unescape Escape

order-site-workspace

目录结构

本地开发

Docker 部署

Docker 本地开发

迁移原则

README.md