157 lines
4.6 KiB
Markdown
157 lines
4.6 KiB
Markdown
# order-site-workspace
|
||
|
||
统一工作区版本的订单自动兑换系统。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
apps/
|
||
backend/ Node + Express + Playwright + OCR worker
|
||
frontend/ Vue 3 + Vite + Element Plus
|
||
deploy/
|
||
caddy/ Caddy 配置
|
||
docker/ Dockerfile
|
||
docs/ 迁移与部署文档
|
||
docker-compose.yml
|
||
```
|
||
|
||
## 本地开发
|
||
|
||
前端：
|
||
|
||
```bash
|
||
cd apps/frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
后端：
|
||
|
||
```bash
|
||
cp .env.mac-docker.example .env
|
||
cd apps/backend/subservices/ocr-worker
|
||
uv sync
|
||
cd apps/backend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
## Docker 部署
|
||
|
||
```bash
|
||
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 本地开发
|
||
|
||
```bash
|
||
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](/Users/yml/codes/order-site-workspace/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`
|
||
|
||
如果你的服务器网络环境不同，也可以在构建时覆盖：
|
||
|
||
```bash
|
||
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
|
||
|
||
详细文档：
|
||
|
||
- [服务器部署教程](/Users/yml/codes/order-site-workspace/docs/%E6%9C%8D%E5%8A%A1%E5%99%A8%E9%83%A8%E7%BD%B2%E6%95%99%E7%A8%8B.md)
|
||
- [首次上线检查清单](/Users/yml/codes/order-site-workspace/docs/%E9%A6%96%E6%AC%A1%E4%B8%8A%E7%BA%BF%E6%A3%80%E6%9F%A5%E6%B8%85%E5%8D%95.md)
|
||
- [mac 本地 Docker 调试模板](/Users/yml/codes/order-site-workspace/.env.mac-docker.example)
|
||
- [服务器部署模板](/Users/yml/codes/order-site-workspace/.env.server.example)
|
||
|
||
## 迁移原则
|
||
|
||
- 不重写现有业务代码
|
||
- 先统一目录、部署和配置
|
||
- 生产环境优先使用 `.env` 和宿主机数据目录挂载
|
||
- 本机 Docker 调试优先使用 [docker-compose.dev.yml](/Users/yml/codes/order-site-workspace/docker-compose.dev.yml)
|