publish/deploy

部署文档

本项目使用 Astro 构建静态站点，通过 Gitea Actions 自动部署到 Linux 服务器。

架构概览

本地开发 → Git Push → Gitea Actions → 构建 → SSH 部署 → 服务器
                                              ↓
                                         飞书通知

服务器信息

项目	值
IP	45.32.105.53
用户名	root
部署路径	/var/www/publish
Web 服务器	Caddy
站点域名	https://wuyouwulv.me

一次性服务器配置

1. 创建部署目录：

   mkdir -p /var/www/publish
   

2. 配置 Caddy（参考 Caddyfile.example）：

   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 配置变量

# 设置变量
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. 通知 - 发送飞书通知（成功/失败）

手动部署

如需手动部署，可以在本地执行：

# 构建
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 验证变量是否存在：

curl -s -H "Authorization: token YOUR_TOKEN" \
  "https://gitea.refining.dev/api/v1/repos/OWNER/REPO/actions/variables" | jq .