127 lines
3.4 KiB
Markdown
127 lines
3.4 KiB
Markdown
# 部署文档
|
||
|
||
本项目使用 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 .
|
||
```
|