publish/AGENTS.md

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 登录密码

常见操作

查看构建日志

# 获取最近的运行
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"

设置仓库变量

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"

手动部署

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