# 部署说明

## 自动部署（推送到 Gitea）

推送 `master` / `main` 分支后，`.gitea/workflows/deploy.yml` 会自动：

1. SFTP 上传代码到服务器  
2. SSH 执行 `npm install --production`  
3. `pm2 restart wc26`（或首次 `pm2 start`）  
4. **`npm run refresh`** — 从 Wikipedia 更新 `data/` 缓存  

**要求：** SFTP 账号需同时允许 **SSH 密码登录**（与手动 SSH 相同用户）。CI 超时设为 15 分钟（refresh 约 30–90 秒）。

### Gitea 配置（你已设置）

| 类型 | 名称 | 说明 |
|------|------|------|
| 组织 Secret | `SFTP_HOST` | SFTP 主机 |
| 组织 Secret | `SFTP_USERNAME` | SFTP 用户名 |
| 组织 Secret | `SFTP_PASSWORD` | SFTP 密码 |
| 仓库 Variable | `SFTP_REMOTE_PATH_S` | `/var/www/html/apps/wc26` |
| 仓库 Secret（可选） | `GITEA_TOKEN` | 用于 CI 拉取 archive；无则用 workspace |

## 本地一键部署

### 方式 A：Node（推荐，Windows 可用）

```bash
# 首次：复制并填写 SFTP 凭据
copy .env.deploy.example .env.deploy

npm install
npm run deploy
```

### 方式 B：lftp（Git Bash / WSL / Linux）

```bash
export SFTP_HOST=...
export SFTP_USERNAME=...
export SFTP_PASSWORD=...
export SFTP_REMOTE_PATH=/var/www/html/apps/wc26

npm run deploy:lftp
```

## 服务器首次初始化（SSH 登录后执行一次）

```bash
cd /var/www/html/apps/wc26
npm install --production

# 可选：Google 主教练搜索
# cp .env.example .env && nano .env

# 用 pm2 守护进程
sudo npm install -g pm2
pm2 start ecosystem.config.js
pm2 save
pm2 startup
```

## 每次部署后（若依赖有变）

```bash
cd /var/www/html/apps/wc26
npm install --production
pm2 restart wc26
```

## 数据存在哪里（服务器）

所有**比赛与球队数据**都在服务器目录 `data/` 下，**不在 Git 仓库里**（`.gitignore` 已忽略，部署也不会上传本地的 `data/`）：

| 文件 | 内容 |
|------|------|
| `data/worldcup.json` | 赛程、比分、进球、小组积分、淘汰赛 |
| `data/teams/*.json` | 每队阵容、教练、俱乐部等 |
| `data/match-lineups.json` | ESPN 首发阵容缓存（按场次） |

### 代码更新会不会把数据打回老版本？

**不会**从 Git 恢复旧 `data/`——部署只上传代码，**不上传** `data/`。

但 CI 部署最后会执行 **`npm run refresh`**，会从 Wikipedia / ESPN 逻辑**重新拉最新**并**覆盖** `worldcup.json` 与各队 `teams/*.json`。这是「用最新网络数据更新」，不是回退到仓库里的旧文件。

- **首发阵容缓存** `match-lineups.json`：`refresh` **不会删除**；只有代码里 `LINEUP_CACHE_VERSION` 升级时才会视为过期并重新拉 ESPN。
- 若只想更新代码、**暂不**重拉 Wikipedia：部署后在服务器跳过 refresh，或改 CI 去掉最后一步 `npm run refresh`（可手动 `npm run refresh`）。

手动刷新数据（与网页「刷新数据」相同）：

```bash
cd /var/www/html/apps/wc26
npm run refresh
```

## 上传内容说明

- **会上传**：`server.js`、`lib/`、`public/`、`scripts/`、`package.json` 等
- **不会上传**：`node_modules/`、`data/`（缓存）、`.git/`、`.env`

数据缓存首次访问时在服务器上点「刷新数据」或运行 `npm run refresh` 生成。

## 反向代理（可选）

若需通过 80/443 访问，在 Nginx 中把 `/wc26/` 反代到 `http://127.0.0.1:3847/`（注意末尾斜杠会去掉 `/wc26` 前缀）。前端已自动识别 `/wc26` 子路径。

```nginx
location /wc26/ {
    proxy_pass http://127.0.0.1:3847/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 300s;
}
```

## 刷新失败排查

网页「刷新数据」采用异步抓取（避免 Nginx 60 秒超时）。若仍失败，SSH 执行：

```bash
cd /var/www/html/apps/wc26
# 确保 ubuntu 用户可写 data 目录
sudo chown -R ubuntu:ubuntu /var/www/html/apps/wc26
npm run refresh
pm2 logs wc26 --lines 30
```

测试 Wikipedia 连通：

```bash
curl -sI "https://en.wikipedia.org/w/api.php?action=parse&page=2026_FIFA_World_Cup&prop=text&format=json"
```