个人博客从零到一自动化部署全纪实

本白皮书完整记录了个人博客 xmengai.com 从环境搭建到实现“双路自动化部署”的所有技术细节。这不仅是一次建站记录，更是一场关于 Linux 权限、Docker 容器化及 CI/CD 流水线的实战演练。

一、 技术架构全景 (Tech Stack)

• 域名：xmengai.com (解析至云服务器)
• 服务器：2核 2G 内存 (轻量应用服务器)
• 前端引擎：VitePress (基于 Vue 3 的极速静态站点生成器)
• 容器化：Docker & Docker Compose (环境隔离与快速迁移)
• 自动化：GitHub Actions (实现 CI/CD 自动化流水线)
• 双路部署策略：
  • 主站：云服务器 (通过 Nginx 托管)
  • 备站：GitHub Pages (利用其全球 CDN 优势)

二、 核心部署流程图

整个自动化部署流程如下，实现了“本地写作，一键发布”：

1. 本地开发：在 VS Code 中编写 Markdown 文章。
2. 代码推送：执行 git push 将源码推送至 GitHub 仓库。
3. 云端触发：GitHub Actions 监测到推送，启动两个并行任务：
   • 任务 A：打包根路径版本，通过 SSH 同步至云服务器。
   • 任务 B：打包子路径版本（通过 --base 参数），自动发布至 GitHub Pages。

三、 详细操作步骤回顾

1. 本地配置

初始化项目

在你的电脑上找一个空文件夹，运行以下命令：

mkdir xmeng-blog
cd xmeng-blog

npm init -y
npm add -D vitepress vue
npx vitepress init

[关键步骤] 统一脚本名称：
打开你项目根目录下的 package.json。根据你提供的文件，你的脚本目前带有 docs: 前缀。为了让自动化部署脚本识别，请将 scripts 部分修改或添加为以下内容：

"scripts": {
  "dev": "vitepress dev",
  "build": "vitepress build",
  "preview": "vitepress preview"
}

完善首页内容 (index.md)

编辑根目录下的 index.md，让它看起来更专业：

---
layout: home
hero:
  name: "xmengai.com"
  text: "AI Agent & 全栈开发"
  tagline: 从后端思维出发，探索 AI 时代的无限可能
  actions:
    - theme: brand
      text: 开始阅读
      link: /guide
---

新建 gitignore 文件。

在项目根目录下创建 .gitignore 文件。

node_modules
.vitepress/dist
.vitepress/cache

编写部署脚本 (.github/workflows/deploy.yml)

在本地创建该文件。为了适配最新的 Node.js 24 环境，我们添加了 FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 环境变量：

name: Deploy Blog V2
on:
  push:
    branches: [main]

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

jobs:
  deploy-to-server:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: 'npm'

      - name: Build for Server
        run: |
          npm ci
          npm run build

      - name: Sync to Cloud Server
        uses: easingthemes/ssh-deploy@main
        with:
          SSH_PRIVATE_KEY: ${{ secrets.SERVER_SSH_KEY }}
          SOURCE: ".vitepress/dist/"
          REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
          REMOTE_USER: ${{ secrets.REMOTE_USER }}
          TARGET: "/opt/blog/html"

  deploy-to-pages:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - name: Build for Pages
        run: |
          npm ci
          npx vitepress build --base /xmeng-ai-blog/
          touch .vitepress/dist/.nojekyll

      - name: Upload to GitHub Pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: .vitepress/dist

      - name: Activate GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

提交代码

在 GitHub 上创建一个名为 xmeng-ai-blog 的仓库，然后本地执行：

git init
git add .
git commit -m "feat: 博客初始化"
git branch -M main
git remote add origin [https://github.com/mengkecoding/xmeng-ai-blog.git](https://github.com/mengkecoding/xmeng-ai-blog.git)
git push -u origin main

配置 GitHub Secrets

前往 GitHub 仓库 -> Settings -> Secrets and variables -> Actions，点击 New repository secret。

依次添加：

REMOTE_HOST: 服务器 IP。

REMOTE_USER: deployer。

SERVER_SSH_KEY: 完整的私钥内容。

2. 云服务器配置 (非 Root 部署)

创建专用账户

sudo useradd -m -s /bin/bash deployer

sudo passwd deployer

sudo usermod -aG docker deployer

su - deployer

ssh-keygen -t ed25519 -C "github-actions-deploy"


mkdir -p ~/.ssh
chmod 700 ~/.ssh

cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys

chmod 600 ~/.ssh/authorized_keys

cat ~/.ssh/id_ed25519

chown -R deployer:deployer /opt/blog

安装docker

我们使用 Docker 来运行 Nginx，这样以后如果你想升级博客或更换服务器，只需要搬走配置文件即可。

sudo apt-get update

sudo apt-get install -y docker.io docker-compose

sudo systemctl start docker
sudo systemctl enable docker

创建目录与权限配置

GitHub Actions 会把文件传送到 /opt/blog/html。我们需要预先创建好这些文件夹，并确保 rsync 工具已安装（Actions 同步文件需要它）。

sudo mkdir -p /opt/blog/html
sudo mkdir -p /opt/blog/nginx/conf.d

sudo apt-get install -y rsync

sudo chown -R $USER:$USER /opt/blog

配置 Nginx 反向代理

在 /opt/blog/nginx/conf.d 目录下创建一个名为 blog.conf 的文件，告诉 Nginx 怎么找到你的博客。

server {
    listen 80;
    server_name xmengai.com www.xmengai.com; # 这里替换为你的域名

    location /.well-known/acme-challenge/ {
        root /usr/share/nginx/html;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

编写 Docker Compose

在 /opt/blog 目录下创建 docker-compose.yaml 文件：

version: '3'

services:
  nginx:
    image: nginx:alpine
    container_name: blog-nginx
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./html:/usr/share/nginx/html:ro
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - /etc/letsencrypt:/etc/nginx/cert:ro
    networks:
      - blog-network

networks:
  blog-network:

启动服务

cd /opt/blog
docker compose up -d

四、GitHub 与云服务器连接测试指南（可选）

在本地项目中创建测试文件

在你的博客项目根目录下，确保存在 .github/workflows/test-ssh.yml 文件。

name: Test SSH Connection

on:
  workflow_dispatch: # 允许你在 GitHub 页面上点击按钮手动触发测试

jobs:
  test-connection:
    runs-on: ubuntu-latest
    steps:
      - name: 测试 SSH 连接
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.REMOTE_HOST }}
          username: ${{ secrets.REMOTE_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          port: 22
          script: |
            echo "你好，GitHub！我是你的服务器。"
            echo "当前登录用户是: $(whoami)"
            echo "服务器运行时间: $(uptime)"
            docker --version

提交代码到 GitHub

请按照以下顺序执行命令。

git init

git remote remove xmeng-ai-blog 2>/dev/null
git remote add origin [https://github.com/mengkecoding/xmeng-ai-blog.git](https://github.com/mengkecoding/xmeng-ai-blog.git)

git add .
git commit -m "chore: 准备测试 SSH 连接"

git branch -M main

git push -u origin main

在 GitHub 页面手动运行测试

1. 打开你的 GitHub 仓库页面 mengkecoding/xmeng-ai-blog（此处改为你的GitHub仓库）。

2. 点击顶部的 Actions 标签。

3. 在左侧菜单中点击 Test SSH Connection。

4. 点击右侧的 Run workflow 下拉按钮，然后点击绿色的 Run workflow 按钮。

观察结果

如果圆圈变绿 (Success)：恭喜你！GitHub 已经成功通过 SSH 密钥登录到了你的服务器。

如果圆圈变红 (Failure)：请点击进入查看日志，看看是 Connection timeout（网络/防火墙问题）还是 Permission denied（密钥配置问题）。

四、日常更新流程

以后你只需要做三件事：

写文章：在本地 docs 目录下写 Markdown 文件。

提交：git add . -> git commit -m "更新内容"。

发布：git push。

GitHub Actions 会自动帮你完成打包、传输、部署的全过程。