# 部署文档

本项目使用 Astro 构建静态站点，通过 Gitea Actions 自动部署到 Linux 服务器。

## 架构概览

```
本地开发 → Git Push → Gitea Actions → 构建 → SSH 部署 → 服务器
                                              ↓
                                         飞书通知
```

## 服务器信息

| 项目 | 值 |
|------|-----|
| IP | `45.32.105.53` |
| 用户名 | `root` |
| 部署路径 | `/var/www/publish` |
| Web 服务器 | Caddy |
| 站点域名 | `https://wuyouwulv.me` |

## 一次性服务器配置

1. 创建部署目录：
   ```bash
   mkdir -p /var/www/publish
   ```

2. 配置 Caddy（参考 `Caddyfile.example`）：
   ```bash
   sudo vim /etc/caddy/Caddyfile
   sudo systemctl reload caddy
   ```

3. 确保服务器已安装 `tar`（用于解压部署包）

## Gitea Actions 配置

### 仓库变量（vars）

在仓库设置 → Actions → Variables 中配置：

| 变量名 | 值 | 说明 |
|--------|-----|------|
| `SITE_URL` | `https://wuyouwulv.me` | 站点 URL，用于 Astro 构建 |
| `DEPLOY_SSH_HOST` | `45.32.105.53` | 服务器 IP |
| `DEPLOY_SSH_PORT` | `22` | SSH 端口 |
| `DEPLOY_SSH_USER` | `root` | SSH 用户名 |
| `DEPLOY_PATH` | `/var/www/publish` | 部署目录 |
| `WEBHOOK_URL` | 飞书 Webhook URL | 部署通知（可选） |

### 仓库密钥（secrets）

在仓库设置 → Actions → Secrets 中配置：

| 密钥名 | 说明 |
|--------|------|
| `DEPLOY_SSH_PASSWORD` | SSH 登录密码 |

### 通过 API 配置变量

```bash
# 设置变量
curl -X POST -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":"VALUE","value":"VALUE"}' \
  "https://gitea.refining.dev/api/v1/repos/OWNER/REPO/actions/variables/VAR_NAME"

# 设置密钥
curl -X PUT -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":"SECRET_VALUE"}' \
  "https://gitea.refining.dev/api/v1/repos/OWNER/REPO/actions/secrets/SECRET_NAME"
```

## 部署流程

1. **Checkout** - 检出代码
2. **Setup Node** - 安装 Node.js 20
3. **Cache npm** - 缓存 npm 依赖（使用 `actions/cache@v3`）
4. **Install** - `npm ci` 安装依赖
5. **Build** - `npm run build` 构建站点
6. **Install sshpass** - 安装 SSH 密码认证工具
7. **Add known_hosts** - 添加服务器到已知主机
8. **Deploy** - 通过 tar + SSH 部署到服务器
9. **通知** - 发送飞书通知（成功/失败）

## 手动部署

如需手动部署，可以在本地执行：

```bash
# 构建
npm run build

# 部署（需要 sshpass）
tar -C dist -czf - . | \
  sshpass -p 'PASSWORD' ssh -p 22 root@45.32.105.53 \
    "set -euo pipefail; tmp='/var/www/publish.tmp'; rm -rf \"\$tmp\"; mkdir -p \"\$tmp\"; tar -xzf - -C \"\$tmp\"; rm -rf '/var/www/publish'; mv \"\$tmp\" '/var/www/publish'"
```

## Caddy 配置示例

参考 `Caddyfile.example` 文件。

## 故障排查

### 构建失败：Invalid url

检查 `SITE_URL` 变量是否包含完整的 URL（包括 `https://` 前缀）。

### 部署失败：SSH 连接问题

1. 检查 `DEPLOY_SSH_PASSWORD` 密钥是否正确
2. 检查服务器 IP 和端口是否正确
3. 检查服务器是否允许密码登录

### 变量在 UI 中不显示

Gitea UI 可能有显示问题，可以通过 API 验证变量是否存在：

```bash
curl -s -H "Authorization: token YOUR_TOKEN" \
  "https://gitea.refining.dev/api/v1/repos/OWNER/REPO/actions/variables" | jq .
```