112 lines
2.8 KiB
Markdown
112 lines
2.8 KiB
Markdown
# order-site-backend
|
|
|
|
腾讯活动浏览器会话后端。
|
|
|
|
当前主线只有一条：
|
|
|
|
- 后端托管 Playwright 浏览器
|
|
- 前端展示二维码并轮询会话状态
|
|
- 登录完成后，后端直接在活动页填写 CDK、识别验证码、执行兑换
|
|
- 兑换完成后返回状态，并按配置决定是否生成截图/证明产物
|
|
|
|
## 快速启动
|
|
|
|
先安装 Node 依赖：
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
首次使用前同步 OCR 子服务依赖：
|
|
|
|
```bash
|
|
cd /Users/yml/codes/order-site-backend/subservices/ocr-worker
|
|
uv sync
|
|
```
|
|
|
|
回到项目根目录启动：
|
|
|
|
```bash
|
|
cd /Users/yml/codes/order-site-backend
|
|
npm run dev
|
|
```
|
|
|
|
Linux 部署：
|
|
|
|
```bash
|
|
npm install
|
|
npm run browser:install:linux
|
|
npm run start
|
|
```
|
|
|
|
## 配置文件
|
|
|
|
现在推荐直接改配置文件，不需要每次在终端里手动拼环境变量。
|
|
|
|
- 默认配置：`config/default.cjs`
|
|
- 本地覆盖：`config/local.cjs`
|
|
- 参考模板：`config/local.example.cjs`
|
|
|
|
推荐做法：
|
|
|
|
1. 通用默认值放在 `config/default.cjs`
|
|
2. 你自己机器上的配置放在 `config/local.cjs`
|
|
3. 只有 CI、部署脚本、临时排查时再用环境变量覆盖
|
|
|
|
当前最常改的配置有：
|
|
|
|
- 服务端口
|
|
- 浏览器是否无头、是否预热、是否常驻、slowMo
|
|
- OCR 子服务目录
|
|
- 会话调试开关
|
|
- 兑换证明模式 `full | basic | off`
|
|
|
|
## 接口
|
|
|
|
- `POST /api/v1/tencent/browser/session`
|
|
创建浏览器会话，返回 `sessionId`、二维码和初始状态
|
|
- `GET /api/v1/tencent/browser/session/:sessionId`
|
|
返回完整会话状态
|
|
- `GET /api/v1/tencent/browser/session/:sessionId/summary`
|
|
轮询用轻量摘要接口，默认不返回二维码 base64
|
|
- `POST /api/v1/tencent/browser/session/:sessionId/refresh`
|
|
强制刷新后端活动页
|
|
- `POST /api/v1/tencent/browser/session/:sessionId/redeem`
|
|
执行兑换
|
|
- `GET /api/v1/tencent/browser/session/:sessionId/screenshot`
|
|
读取最近一次兑换截图
|
|
- `DELETE /api/v1/tencent/browser/session/:sessionId`
|
|
关闭浏览器会话
|
|
|
|
## 目录
|
|
|
|
- `src/index.js`
|
|
Express 入口
|
|
- `src/routes/tencent.js`
|
|
接口路由
|
|
- `src/services/session.js`
|
|
会话编排与浏览器生命周期
|
|
- `src/services/session-*.js`
|
|
登录、兑换、OCR、凭证产物等模块
|
|
- `subservices/ocr-worker`
|
|
内嵌 OCR 子服务
|
|
|
|
## 产物
|
|
|
|
浏览器会话产物默认保存在：
|
|
|
|
- `data/browser-sessions/<sessionId>/qq-qr.png`
|
|
- `data/browser-sessions/<sessionId>/session.json`
|
|
- `data/browser-sessions/<sessionId>/captcha-attempt-*.png`
|
|
- `data/browser-sessions/<sessionId>/redeem-result.png`
|
|
- `data/browser-sessions/<sessionId>/page.html`
|
|
- `data/browser-sessions/<sessionId>/result.json`
|
|
|
|
这些都是运行时产物，默认不提交 Git。
|
|
|
|
`TENCENT_REDEEM_PROOF_MODE` 对应的配置文件项会影响生成强度：
|
|
|
|
- `full`：完整证明
|
|
- `basic`：只保留最终截图和结果 JSON
|
|
- `off`：不生成证明文件
|