109 lines
3.2 KiB
Markdown
109 lines
3.2 KiB
Markdown
# 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
|