# 服务器部署教程

## 目标

将 `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
```

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

- Debian `apt`：腾讯云镜像
- `npm`：`npmmirror`
- `uv` 通过 `pip` 安装，`uv` / `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.npmmirror.com \
  --build-arg UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
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 已在镜像中内置，首次构建时间较长，后续会快很多