order_site/docs/服务器部署教程.md

服务器部署教程

目标

将 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

二、上传项目

将整个工作区上传到服务器，例如：

cd /srv
git clone <your-repo-url> order-site-workspace
cd order-site-workspace

如果不是 Git 部署，也可以直接上传整个目录。

三、填写生产配置

复制环境变量模板：

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

四、首次构建与启动

在服务器执行：

docker compose build
docker compose up -d

如果服务器在国内，当前版本默认已启用国内镜像源加速：

• Debian apt：腾讯云镜像
• npm：npmmirror
• uv 通过 pip 安装，uv / 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.npmmirror.com \
  --build-arg UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
docker compose up -d

查看运行状态：

docker compose ps
docker compose logs -f

五、上线后检查

先检查健康接口：

curl -k https://你的域名/health

预期返回：

{"code":0,"msg":"ok","time":1234567890}

再检查前端页面：

1. 打开 https://你的域名
2. 打开后台登录页 https://你的域名/#/admin/login
3. 使用 .env 中的管理员账号登录

六、常用运维命令

启动：

docker compose up -d

停止：

docker compose down

重建：

docker compose build
docker compose up -d

查看日志：

docker compose logs -f backend
docker compose logs -f web

七、升级流程

更新代码后执行：

git pull
docker compose build
docker compose up -d

如果只更新前端：

docker compose build web
docker compose up -d web

如果只更新后端：

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 已在镜像中内置，首次构建时间较长，后续会快很多