chore: remove README.md and update deploy documentation with Chinese localization and detailed setup instructions [skip ci]
This commit is contained in:
voson
108
AGENTS.md
Normal file
108
AGENTS.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# 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
|
||||
62
README.md
62
README.md
@@ -1,62 +0,0 @@
|
||||
# Astro Starter Kit: Blog
|
||||
|
||||
```sh
|
||||
npm create astro@latest -- --template blog
|
||||
```
|
||||
|
||||
> 🧑🚀 **Seasoned astronaut?** Delete this file. Have fun!
|
||||
|
||||
Features:
|
||||
|
||||
- ✅ Minimal styling (make it your own!)
|
||||
- ✅ 100/100 Lighthouse performance
|
||||
- ✅ SEO-friendly with canonical URLs and OpenGraph data
|
||||
- ✅ Sitemap support
|
||||
- ✅ RSS Feed support
|
||||
- ✅ Markdown & MDX support
|
||||
|
||||
## 🚀 Project Structure
|
||||
|
||||
Inside of your Astro project, you'll see the following folders and files:
|
||||
|
||||
```text
|
||||
├── public/
|
||||
├── src/
|
||||
│ ├── components/
|
||||
│ ├── content/
|
||||
│ ├── layouts/
|
||||
│ └── pages/
|
||||
├── astro.config.mjs
|
||||
├── README.md
|
||||
├── package.json
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name.
|
||||
|
||||
There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components.
|
||||
|
||||
The `src/content/` directory contains "collections" of related Markdown and MDX documents. Use `getCollection()` to retrieve posts from `src/content/blog/`, and type-check your frontmatter using an optional schema. See [Astro's Content Collections docs](https://docs.astro.build/en/guides/content-collections/) to learn more.
|
||||
|
||||
Any static assets, like images, can be placed in the `public/` directory.
|
||||
|
||||
## 🧞 Commands
|
||||
|
||||
All commands are run from the root of the project, from a terminal:
|
||||
|
||||
| Command | Action |
|
||||
| :------------------------ | :----------------------------------------------- |
|
||||
| `npm install` | Installs dependencies |
|
||||
| `npm run dev` | Starts local dev server at `localhost:4321` |
|
||||
| `npm run build` | Build your production site to `./dist/` |
|
||||
| `npm run preview` | Preview your build locally, before deploying |
|
||||
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
|
||||
| `npm run astro -- --help` | Get help using the Astro CLI |
|
||||
|
||||
## 👀 Want to learn more?
|
||||
|
||||
Check out [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).
|
||||
|
||||
## Credit
|
||||
|
||||
This theme is based off of the lovely [Bear Blog](https://github.com/HermanMartinus/bearblog/).
|
||||
138
deploy/README.md
138
deploy/README.md
@@ -1,26 +1,126 @@
|
||||
# Server deploy (static)
|
||||
# 部署文档
|
||||
|
||||
This repo builds an Astro static site into `dist/` and deploys it to a Linux server via rsync over SSH.
|
||||
本项目使用 Astro 构建静态站点，通过 Gitea Actions 自动部署到 Linux 服务器。
|
||||
|
||||
## One-time server setup
|
||||
## 架构概览
|
||||
|
||||
1. Create a deploy directory, e.g. `/var/www/publish`.
|
||||
2. Configure your web server (Caddy or Nginx) to serve that directory.
|
||||
3. Create an SSH key for CI and add its public key to the server.
|
||||
```
|
||||
本地开发 → Git Push → Gitea Actions → 构建 → SSH 部署 → 服务器
|
||||
↓
|
||||
飞书通知
|
||||
```
|
||||
|
||||
## Gitea Actions secrets (repo settings)
|
||||
## 服务器信息
|
||||
|
||||
- `SITE_URL`
|
||||
- `PUBLIC_NEWSLETTER_ACTION`
|
||||
- `PUBLIC_NEWSLETTER_EMAIL_FIELD`
|
||||
- `PUBLIC_NEWSLETTER_TITLE` (optional)
|
||||
- `PUBLIC_NEWSLETTER_DESCRIPTION` (optional)
|
||||
- `DEPLOY_SSH_HOST`
|
||||
- `DEPLOY_SSH_PORT`
|
||||
- `DEPLOY_SSH_USER`
|
||||
- `DEPLOY_PATH`
|
||||
- `DEPLOY_SSH_KEY` (private key)
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| IP | `45.32.105.53` |
|
||||
| 用户名 | `root` |
|
||||
| 部署路径 | `/var/www/publish` |
|
||||
| Web 服务器 | Caddy |
|
||||
| 站点域名 | `https://wuyouwulv.me` |
|
||||
|
||||
## Example Caddyfile
|
||||
## 一次性服务器配置
|
||||
|
||||
See `deploy/Caddyfile.example`.
|
||||
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 .
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user