博客部署测试

本文记录了本博客的部署方案和自动化构建流程。

整体部署方案：

前端：使用 Cloudflare Pages 部署。
后端：部署在个人的 VPS 服务器上。

1. 前端部署 (Cloudflare Pages)

在 Cloudflare 的 Workers & Pages 页面中点击“创建应用程序”。请注意，默认创建的是 Workers 类型的程序，需要点击底部的 “想要部署 Pages？开始使用” 按钮来创建 Pages 应用。

选择对应的 GitHub 仓库后，填写具体的构建信息：

框架预设 (Framework preset)：Vue
根目录 (Root directory)：blog_by_vue
构建命令 (Build command)：npm run build
构建输出目录 (Build output directory)：dist
环境变量：别忘了添加后端接口地址，例如 VITE_API_BASE_URL = https://api.yourdomain.com

配置完成后，点击“保存并部署”，等待构建完成即可。

2. 后端部署 (Flask + Nginx)

后端部署在个人服务器上。首先将代码克隆到本地并配置服务器的 Python 运行环境：

git clone git@github.com:你的用户名/MarkVault.git
cd ~/MarkVault
uv venv .venv
source .venv/bin/activate
cd server_flask
pip install -r requirements.txt
pip install gunicorn  # 安装生产环境的 WSGI 服务器

接着安装 Nginx：

sudo dnf install nginx

2.1 配置用户级 systemd 服务

为了让当前的非 root 用户（例如 aa）能够安全地在自动化部署时管理进程，并且在重启服务时不需要输入 sudo 密码，我们采用用户级的 systemd。

首先，开启该用户的驻留（Linger）权限，确保即使退出 SSH 后进程也能一直在后台运行（这一步需要用到 root 权限的 sudo）：

sudo loginctl enable-linger $USER

接着，创建用户级别的 systemd 目录和服务配置文件：

mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/markvault-backend.service

将以下内容粘贴到文件中：

[Unit]
Description=Gunicorn instance to serve MarkVault Backend
After=network.target

[Service]
# 注意：用户级 systemd 默认就是以当前用户运行，所以无需配置 User 和 Group
WorkingDirectory=%h/MarkVault/server_flask
Environment="PATH=%h/MarkVault/.venv/bin"
# 为了方便 Nginx 代理，绑定到本地的 8000 端口
ExecStart=%h/MarkVault/.venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 run:app

[Install]
WantedBy=default.target

加载配置、启动并激活服务（注意这些命令不要加 sudo）：

systemctl --user daemon-reload
systemctl --user start markvault-backend
systemctl --user enable markvault-backend

2.2 配置 Nginx 反向代理

接下来配置 Nginx，拦截 api.yourdomain.com 的请求并转发给本地的 Flask 服务。 Fedora/CentOS 的 Nginx 配置文件默认存放在 /etc/nginx/conf.d/ 目录下。

sudo nano /etc/nginx/conf.d/markvault-api.conf

填入以下内容：

server {
    listen 80;
    server_name api.yourdomain.com; # 替换为你的真实 API 域名

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

测试配置并启动 Nginx：

sudo nginx -t
sudo systemctl start nginx
sudo systemctl enable nginx

2.3 配置 SSL 证书

接下来为 API 域名申请免费的 SSL 证书。

安装 Certbot 及其 Nginx 插件：

sudo dnf install -y certbot python3-certbot-nginx

申请证书（Certbot 会自动修改 Nginx 配置文件以开启 HTTPS）：

sudo certbot --nginx -d api.yourdomain.com

验证自动续期是否配置正确：

sudo certbot renew --dry-run

3. 自动化部署 (GitHub Actions)

为了实现持续集成：当 GitHub 仓库发生变动时，对于前端，Cloudflare Pages 会自动拉取最新代码并重新构建；而后端部署在自己的 VPS 上，需要借助 GitHub Actions 实现自动化部署（通过 SSH 连接到服务器，拉取最新代码并重启服务）。

3.1 编写 Workflow 配置文件

在代码仓库的 .github/workflows/ 文件夹下创建部署配置文件：

name: Deploy Backend to VPS

on:
  push:
    branches:
      - main
    paths:
      - 'server_flask/**'
      - 'manage.py'
      - '.github/workflows/deploy-backend.yml'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to DMIT VPS via SSH
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USERNAME }}
          key: ${{ secrets.VPS_SSH_KEY }}
          port: ${{ secrets.VPS_PORT }}
          script: |
            echo "Deploying MarkVault Backend..."
            cd ~/MarkVault
            git pull origin main
            
            # 激活虚拟环境并安装可能的依赖更新 (虚拟环境在根目录)
            source .venv/bin/activate
            cd server_flask
            pip install -r requirements.txt
            
            # 重启 systemd 后端服务 (使用用户级 systemd，无需 sudo)
            systemctl --user restart markvault-backend
            echo "Backend restarted successfully."

3.2 配置 GitHub Secrets

以上 Action 依赖于相关的环境变量。请按照以下步骤在 GitHub 仓库中配置：

在浏览器里打开你的 GitHub 仓库主页。
点击仓库右上角的 ⚙️ Settings（设置）选项卡。
在左侧边栏找到 Secrets and variables 菜单并展开，点击里面的 Actions。
在打开的页面中，点击绿色的 New repository secret（新建仓库机密）按钮。
然后依次添加以下 4 个变量：

Name (变量名)	Secret (变量值)	说明
`VPS_HOST`	`123.45.67.89`	填你的 VPS 的公网 IP 地址
`VPS_PORT`	`22`	你的 SSH 端口号（默认一般为 22）
`VPS_USERNAME`	`aa`	你用来执行部署的非 root 用户名（示例为 aa）
`VPS_SSH_KEY`	`-----BEGIN OPENSSH PRIVATE KEY-----` (一大串)	重点：你需要填入用于免密登录的 SSH 私钥。

3.3 关于生成 VPS_SSH_KEY 的补充说明

为了安全起见，推荐为 GitHub Actions 单独生成一对 SSH 密钥，而不是使用默认的密钥：

1. 在 VPS 上生成一对全新的密钥：

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_github_actions -C "github-actions-deploy"

（一路回车，不要设置密码保护）

2. 将公钥加入到部署用户的白名单中：

查看刚才生成的公钥内容：

cat ~/.ssh/id_ed25519_github_actions.pub

将输出的那段以 ssh-ed25519 开头的文本，追加到负责部署的用户（例如 aa）的 authorized_keys 中：

echo "刚才那串公钥内容" >> ~/.ssh/authorized_keys

3. 将私钥保存到 GitHub Secrets：

查看新生成的私钥内容：

cat ~/.ssh/id_ed25519_github_actions

将输出的一长串内容（包含 BEGIN OPENSSH PRIVATE KEY 及 END OPENSSH PRIVATE KEY 的完整部分）复制下来，填写到 GitHub 的 VPS_SSH_KEY 变量值中。

4. 博客内容同步方案

为了实现博客内容的无缝更新，我选择使用 Syncthing 在个人服务器（VPS）和本地 PC 之间进行双向同步。

4.1 本地 (Mac) 安装与配置

社区为 macOS 专门开发了带有图形界面的 Cask 版本，它的底层依然是官方的 Syncthing 核心，但增加了一个常驻顶部菜单栏的小图标，方便直观管理。

# 安装带 GUI 图标的客户端
brew install --cask syncthing

安装完成后，按下 Command + 空格 呼出聚焦搜索（Spotlight），输入 Syncthing 并回车打开。启动后，它会在屏幕右上角显示一个状态图标，并自动在浏览器中打开本地控制台地址 http://127.0.0.1:8384。

4.2 服务器 (VPS) 安装与配置

1. 安装与运行：在 Fedora/CentOS 环境下，只需一行命令安装 Syncthing。随后，如同配置后端服务一样，将其设置为当前用户（例如 aa）的后台驻留服务：

sudo dnf install syncthing
systemctl --user enable --now syncthing

2. 安全配置（最巧妙的地方）： Syncthing 在服务器上运行后，同样会在本地的 127.0.0.1:8384 开启控制台网页。由于安全机制，该面板默认不向外网暴露。强烈建议不要修改配置将其暴露到公网。最安全的做法是在本地 Mac 上利用 SSH 建立一条端口转发隧道：

ssh -L 8384:127.0.0.1:8384 aa@你的VPS_IP

只要保持这条 SSH 连接不断开，就可以直接在本地 Mac 的浏览器里访问 http://127.0.0.1:8384，此时你看到的正是那台远端 VPS 上的 Syncthing 控制面板。

4.3 开始同步

加好友配对：打开刚才通过 SSH 映射出来的 VPS 控制面板，在右上角点击“操作 -> 显示 ID”，复制出那一长串的设备 ID。接着回到 Mac 本地的控制面板（建议给两个控制台分配不同颜色的浏览器标签以防混淆），点击右下角的“添加远程设备”，填入复制的 ID 并保存。随后 VPS 面板会弹出“是否允许连接”的提示，点击同意后，两台设备就成功配对了。
共享文件夹：在 Mac 的控制面板中，添加你需要同步的博客内容文件夹（例如位于 Google Drive 中的 content 目录），并在“共享”选项卡中勾选你的 VPS 节点。切换到 VPS 控制面板，收到来自 Mac 的共享请求后点击接受，并将文件夹的保存路径设置为 /home/aa/blog-content。至此，双端的无缝内容同步便配置完成了。