131 lines
3.6 KiB
Markdown
131 lines
3.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.development.example .env
|
||
cd apps/backend/subservices/ocr-worker
|
||
uv sync
|
||
cd apps/backend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
## Docker 部署
|
||
|
||
```bash
|
||
cp .env.production.example .env
|
||
docker compose build
|
||
docker compose up -d
|
||
```
|
||
|
||
## Docker 本地开发
|
||
|
||
```bash
|
||
cp .env.development.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`
|
||
- 浏览器会话产物
|
||
- 截图和证明文件
|
||
|
||
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)
|
||
- [开发环境模板](/Users/yml/codes/order-site-workspace/.env.development.example)
|
||
- [生产环境模板](/Users/yml/codes/order-site-workspace/.env.production.example)
|
||
|
||
## 迁移原则
|
||
|
||
- 不重写现有业务代码
|
||
- 先统一目录、部署和配置
|
||
- 生产环境优先使用 `.env` 和 Docker 卷
|
||
- 本机 Docker 调试优先使用 [docker-compose.dev.yml](/Users/yml/codes/order-site-workspace/docker-compose.dev.yml)
|