init

2026-04-08 16:30:42 +08:00
commit 313c036845
131 changed files with 22393 additions and 0 deletions
@@ -0,0 +1,174 @@
+# 服务器部署教程
+
+## 目标
+
+将 `order-site-workspace` 以 `Docker Compose + Caddy` 方式部署到 Linux 服务器。
+
+## 一、服务器准备
+
+建议服务器最低配置：
+
+- 2 vCPU
+- 4 GB 内存
+- 30 GB 可用磁盘
+
+系统建议：
+
+- Ubuntu 22.04 / Debian 12
+
+需要提前准备：
+
+1. 一个已经解析到服务器公网 IP 的域名
+2. 服务器开放端口：
+   - `80`
+   - `443`
+3. 已安装 Docker 和 Docker Compose
+
+## 二、上传项目
+
+将整个工作区上传到服务器，例如：
+
+```bash
+cd /srv
+git clone <your-repo-url> order-site-workspace
+cd order-site-workspace
+```
+
+如果不是 Git 部署，也可以直接上传整个目录。
+
+## 三、填写生产配置
+
+复制环境变量模板：
+
+```bash
+cp .env.example .env
+```
+
+然后重点修改：
+
+1. `APP_DOMAIN`
+   改成你的真实域名，例如 `order.example.com`
+2. `APP_BASE_URL`
+   改成 `https://你的域名`
+3. `CLAIM_BASE_URL`
+   改成 `https://你的域名/#/claim`
+4. `ADMIN_SESSION_SECRET`
+   换成高强度随机串
+5. `ADMIN_DEFAULT_USERS_JSON`
+   换成正式后台账号密码
+6. `ORDER_SKU_MAPPINGS_JSON`
+   改成你的真实商品映射
+7. `AGISO_*`
+   写入真实平台密钥
+
+参考文件：
+
+- [生产环境变量模板.env](/Users/yml/codes/order-site-workspace/docs/%E7%94%9F%E4%BA%A7%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E6%A8%A1%E6%9D%BF.env)
+
+## 四、首次构建与启动
+
+在服务器执行：
+
+```bash
+docker compose build
+docker compose up -d
+```
+
+查看运行状态：
+
+```bash
+docker compose ps
+docker compose logs -f
+```
+
+## 五、上线后检查
+
+先检查健康接口：
+
+```bash
+curl -k https://你的域名/health
+```
+
+预期返回：
+
+```json
+{"code":0,"msg":"ok","time":1234567890}
+```
+
+再检查前端页面：
+
+1. 打开 `https://你的域名`
+2. 打开后台登录页 `https://你的域名/#/admin/login`
+3. 使用 `.env` 中的管理员账号登录
+
+## 六、常用运维命令
+
+启动：
+
+```bash
+docker compose up -d
+```
+
+停止：
+
+```bash
+docker compose down
+```
+
+重建：
+
+```bash
+docker compose build
+docker compose up -d
+```
+
+查看日志：
+
+```bash
+docker compose logs -f backend
+docker compose logs -f web
+```
+
+## 七、升级流程
+
+更新代码后执行：
+
+```bash
+git pull
+docker compose build
+docker compose up -d
+```
+
+如果只更新前端：
+
+```bash
+docker compose build web
+docker compose up -d web
+```
+
+如果只更新后端：
+
+```bash
+docker compose build backend
+docker compose up -d backend
+```
+
+## 八、数据位置与备份
+
+当前后端数据通过 Docker 卷持久化，至少包含：
+
+- SQLite 数据库
+- 浏览器会话产物
+- 兑换截图/证明文件
+
+建议至少每日备份一次：
+
+1. `backend_data` 卷
+2. `.env`
+
+## 九、当前版本的注意事项
+
+1. 当前 HTTPS 由 Caddy 自动处理，域名必须先解析到服务器
+2. 领取页地址依赖 `CLAIM_BASE_URL`，域名变更后必须同步修改
+3. 后端使用 SQLite，单机部署没有问题，但后期并发增大时建议切换外部数据库
+4. Playwright 和 OCR 已在镜像中内置，首次构建时间较长，后续会快很多
@@ -0,0 +1,24 @@
+APP_DOMAIN=order.example.com
+APP_BASE_URL=https://order.example.com
+
+BACKEND_PORT=3000
+CLAIM_BASE_URL=https://order.example.com/#/claim
+DATABASE_FILE_PATH=/app/data/order-site.db
+OCR_PROJECT_ROOT=/app/subservices/ocr-worker
+TENCENT_REDEEM_PROOF_MODE=basic
+TENCENT_BROWSER_HEADLESS=true
+TENCENT_BROWSER_PREWARM=true
+TENCENT_BROWSER_KEEP_ALIVE=true
+TENCENT_SESSION_DEBUG=false
+
+ADMIN_SESSION_SECRET=replace-with-a-long-random-secret
+ADMIN_DEFAULT_USERS_JSON=[{"username":"admin","password":"replace-with-strong-admin-password","role":"admin"},{"username":"operator","password":"replace-with-strong-operator-password","role":"operator"}]
+
+ORDER_SKU_MAPPINGS_JSON={"32768":"dnf-cdk-a","dnf-cdk-a":"dnf-cdk-a"}
+
+AGISO_APP_SECRET=
+AGISO_MESSAGING_ENABLED=true
+AGISO_APP_ID=
+AGISO_ACCESS_TOKEN=
+AGISO_MESSAGE_APP_SECRET=
+AGISO_MESSAGE_TEMPLATE=您的订单 {platformOrderId} 已创建领取链接，请尽快打开并完成领取：{claimUrl}
@@ -0,0 +1,66 @@
+# 迁移与部署计划
+
+## 目标
+
+将现有两个项目整理为统一工作区：
+
+- `apps/backend`
+- `apps/frontend`
+
+并以 `Docker Compose + Caddy` 作为标准部署方式。
+
+## 已完成
+
+1. 新建统一工作区目录 `order-site-workspace`
+2. 将原后端迁移到 `apps/backend`
+3. 将原前端迁移到 `apps/frontend`
+4. 增加 `docker-compose.yml`
+5. 增加后端 Dockerfile
+6. 增加前端+Caddy Dockerfile
+7. 增加 Caddy 反代配置
+8. 增加根目录 `.env.example`
+9. 后端新增环境变量支持：
+   - `ADMIN_DEFAULT_USERS_JSON`
+   - `ORDER_SKU_MAPPINGS_JSON`
+   - `AGISO_MESSAGE_TEMPLATE`
+
+## 当前部署结构
+
+### backend
+
+- Node 运行主服务
+- Playwright 安装 Chromium
+- `uv` 管理 OCR 子服务
+- SQLite 与截图产物通过 Docker 卷持久化
+
+### web
+
+- 前端先构建
+- 最终由 Caddy 提供静态文件
+- `/api/*` 与 `/health` 反向代理到 backend
+
+## 上线前仍需确认
+
+1. `.env` 中的生产域名
+2. 后台默认账号密码
+3. Agiso 密钥与消息配置
+4. SKU 映射 JSON
+5. 是否继续使用 SQLite，或后续切换 MySQL/PostgreSQL
+
+## 建议的下一步
+
+1. 在新工作区本地执行一次：
+   - `docker compose build`
+   - `docker compose up -d`
+2. 验证：
+   - `/health`
+   - `/api/v1/admin/auth/login`
+   - 前台 claim 页面
+   - 后台管理页
+3. 再补服务器部署文档与备份策略
+
+## 已补充文档
+
+- [服务器部署教程](/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)
+- [生产环境变量模板.env](/Users/yml/codes/order-site-workspace/docs/%E7%94%9F%E4%BA%A7%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E6%A8%A1%E6%9D%BF.env)
@@ -0,0 +1,57 @@
+# 首次上线检查清单
+
+## 基础检查
+
+1. 域名已正确解析到服务器公网 IP
+2. 服务器已开放 `80/443`
+3. `.env` 已替换为真实生产配置
+4. 后台默认密码不是示例密码
+5. Agiso 密钥不是空值
+
+## 容器检查
+
+1. `docker compose ps` 显示 `backend` 和 `web` 都是 `Up`
+2. `docker compose logs --tail=100 backend` 没有持续报错
+3. `docker compose logs --tail=100 web` 没有持续报错
+
+## 接口检查
+
+1. `https://你的域名/health` 返回 `code=0`
+2. `https://你的域名/` 能打开前台首页
+3. `https://你的域名/#/admin/login` 能打开后台登录页
+
+## 后台检查
+
+1. 管理员账号可登录
+2. 订单页可打开
+3. 任务页可打开
+4. CDK 页可打开
+5. Webhook 页可打开
+
+## 业务检查
+
+1. SKU 映射正确
+2. 可手动新增 CDK
+3. 可创建测试订单并生成任务
+4. 领取链接能正常打开
+5. 用户绑定流程能走通
+6. 兑换成功后截图/结果文件能生成
+
+## 回调检查
+
+1. Agiso webhook 地址已配置为真实公网地址
+2. 订单创建通知可以写入系统
+3. 付款成功通知可以推进任务
+4. 确认收货通知可以完成订单状态
+
+## 消息检查
+
+1. Agiso 站内消息开关已确认
+2. 消息模板内容符合当前业务
+3. 领取链接能通过消息正确发给用户
+
+## 备份检查
+
+1. `.env` 已单独安全保存
+2. `backend_data` 卷已有备份方案
+3. 数据库文件可导出