# AI 代理指南

本文档为 AI 代理提供项目上下文和操作指南。

## 项目概述

- **类型**：Astro 静态博客站点
- **域名**：https://wuyouwulv.me
- **仓库**：voson/publish（Gitea）
- **部署**：Gitea Actions → SSH → Vultr 服务器

## 技术栈

- **框架**：Astro 5.x
- **语言**：TypeScript
- **样式**：全局 CSS
- **部署**：Gitea Actions + SSH 密码认证

## 目录结构

```
publish/
├── .gitea/workflows/deploy.yml  # CI/CD 部署工作流
├── deploy/                       # 部署文档和配置示例
├── public/                       # 静态资源
├── src/
│   ├── components/              # Astro 组件
│   ├── content/blog/            # 博客文章（Markdown）
│   ├── layouts/                 # 页面布局
│   ├── pages/                   # 页面路由
│   └── styles/                  # 全局样式
└── astro.config.mjs             # Astro 配置
```

## 服务器配置

| 项目 | 值 |
|------|-----|
| 服务器 IP | `45.32.105.53` |
| SSH 用户 | `root` |
| SSH 端口 | `22` |
| 部署路径 | `/var/www/publish` |
| Web 服务器 | Caddy |

服务器配置文件位置：`/Users/voson/Library/Mobile Documents/com~apple~CloudDocs/refining/config.toml`

## Gitea 配置

- **实例**：https://gitea.refining.dev
- **仓库**：voson/publish（注意：不是 refining/publish）
- **Token**：见 `config.toml` 中的 `[services.gitea]`

### Actions 变量（vars）

| 变量 | 说明 |
|------|------|
| `SITE_URL` | 站点 URL，必须包含 `https://` |
| `DEPLOY_SSH_HOST` | 服务器 IP |
| `DEPLOY_SSH_PORT` | SSH 端口 |
| `DEPLOY_SSH_USER` | SSH 用户名 |
| `DEPLOY_PATH` | 部署目录 |
| `WEBHOOK_URL` | 飞书通知 Webhook |

### Actions 密钥（secrets）

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

## 常见操作

### 查看构建日志

```bash
# 获取最近的运行
curl -s -H "Authorization: token TOKEN" \
  "https://gitea.refining.dev/api/v1/repos/voson/publish/actions/runs?limit=1" | jq .

# 获取 job 日志
curl -s -H "Authorization: token TOKEN" \
  "https://gitea.refining.dev/api/v1/repos/voson/publish/actions/jobs/JOB_ID/logs"
```

### 设置仓库变量

```bash
curl -X POST -H "Authorization: token TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":"VALUE","value":"VALUE"}' \
  "https://gitea.refining.dev/api/v1/repos/voson/publish/actions/variables/VAR_NAME"
```

### 手动部署

```bash
cd /Users/voson/publish
npm run build
tar -C dist -czf - . | sshpass -p 'PASSWORD' ssh 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'"
```

## 注意事项

1. **仓库路径**：仓库是 `voson/publish`，不是 `refining/publish`
2. **SITE_URL**：必须包含 `https://` 前缀，否则 Astro 构建会报 "Invalid url"
3. **SSH 认证**：使用密码认证（sshpass），不是 SSH 密钥
4. **Gitea Cache**：Gitea 不支持 `actions/cache@v4`，必须使用 `v3`
5. **变量 vs 密钥**：敏感信息（密码）用 secrets，其他用 vars