Quartz—Gitee流水线全流程操作指南

🚀 全流程操作指南：Obsidian + Quartz + Gitee Go + Docker Nginx

1. 本地环境准备与项目初始化（关键步骤）

目标：在本地电脑完成所有繁琐的配置和调试，确保网站在本地能完美运行。

创建项目目录 在本地电脑创建一个空文件夹（例如 my-quartz-site），并初始化 Git：
```
mkdir my-quartz-site
cd my-quartz-site
git init
```
安装 Quartz 框架 推荐使用官方模板初始化（或者克隆 Quartz 仓库）：
```
# 使用官方模板初始化（推荐）
npx create-quartz@latest
# 按照提示操作，通常选择 "No" (不覆盖现有内容) 或直接安装到当前目录
```
如果提示权限问题，可能需要使用 sudo 或检查 Node 版本（建议 Node 20+）。
迁移笔记内容
- 将你的 Obsidian 笔记库中的 .md 文件复制到项目下的 content 文件夹中。
- 注意：不要复制 .obsidian 文件夹（这是 Obsidian 的本地配置，不需要发布）。
安装依赖与本地调试 在终端执行以下命令：
```
# 1. 安装依赖
npm install
 
# 2. 启动本地预览服务
npx quartz build --serve
```
打开浏览器访问 http://localhost:8080。此时你应该能看到你的网站。
- 调试：修改 quartz/config.ts（站点配置）、quartz/styles/custom.scss（样式）等文件，直到你在本地看到的效果满意为止。
配置 .gitignore 确保项目根目录下的 .gitignore 文件包含以下内容，防止将缓存和构建产物上传到 Git：
```
node_modules/
public/
.DS_Store
.env
```

2. Git 仓库结构确认

在上传之前，你的本地项目结构应该如下所示：

my-quartz-site/
├── .gitee/                # (稍后创建) 存放流水线配置
├── content/               # [重要] 你的 Obsidian 笔记
├── quartz/                # Quartz 框架源码 (包含配置和布局)
├── .gitignore             # 忽略文件配置
├── package.json           # 依赖描述文件
└── ...

3. 配置 Gitee 流水线

目标：让 Gitee 服务器自动拉取代码、构建网页并推送到你的云主机。

创建流水线配置文件 在项目根目录下创建文件夹 .gitee，并在其中新建文件 pipelines.yml，内容如下：

version: '1.0'
name: quartz-deploy
displayName: Quartz自动化部署
 
triggers:
  trigger: auto
  push:
    branches:
      prefix:
        - main  # 当推送到 main 分支时触发
 
variables:
  global:
    - SERVER_IP       # 云主机IP
    - SERVER_PATH     # 网站目录
    - SERVER_PORT     # SSH端口
    - SSH_PRIVATE_KEY # SSH私钥
 
stages:
  - name: build_and_deploy
    displayName: 构建与部署
    steps:
      - step: build@nodejs
        name: build_step
        displayName: Node构建与同步
        nodeVersion: 20.10.0
        commands:
          - echo "🚀 开始构建流程"
          - apt-get update && apt-get install -y rsync # 安装同步工具
          - npm config set registry https://registry.npmmirror.com # 设置淘宝源
          - npm install # 安装依赖
          - npx quartz build # 执行构建，生成 public 目录
          
          - echo "🔐 配置SSH连接"
          - mkdir -p ~/.ssh
          - echo "${SSH_PRIVATE_KEY}" > ~/.ssh/id_rsa
          - chmod 600 ~/.ssh/id_rsa
          - ssh-keyscan -H -p ${SERVER_PORT:-22} ${SERVER_IP} >> ~/.ssh/known_hosts
          
          - echo "📤 同步文件到云主机"
          # 注意：确保 deploy 用户有权限写入 SERVER_PATH
          - rsync -avz --delete -e "ssh -p ${SERVER_PORT:-22} -i ~/.ssh/id_rsa" ./public/ deploy@${SERVER_IP}:${SERVER_PATH}
          
          - echo "✅ 部署完成"
        caches:
          - ~/.npm
          - node_modules

提交并推送到 Gitee

git add .
git commit -m "feat: 初始化 Quartz 项目与流水线配置"
git branch -M main
git remote add origin <你的Gitee仓库地址>
git push -u origin main

4. Gitee 仓库变量设置

在 Gitee 项目主页，进入 设置 → 流水线 → 变量管理，添加以下变量（对应上面配置文件中的变量）：

变量名	值示例	说明
`SERVER_IP`	`xxx.152.xxx.xxx`	你的云主机公网 IP
`SERVER_PATH`	`/data/website/site`	Nginx 容器挂载的静态文件目录
`SERVER_PORT`	`22`	SSH 端口 (如果是默认22可留空或填22)
`SSH_PRIVATE_KEY`	`-----BEGIN...`	完整的云主机私钥内容 (用于免密登录)

5. 云主机 (Server) 最终检查

确保你的云主机已准备好接收文件。

检查用户权限 流水线脚本中使用的是 deploy 用户。请登录服务器检查是否存在该用户，或者将脚本中的 deploy 改为 root。
```
# 检查用户是否存在
id deploy 
```

设置目录权限 确保目标目录存在且可写：

sudo mkdir -p /data/website/site
# 赋予 deploy 用户写权限 (假设你使用 deploy 用户)
sudo chown -R deploy:deploy /data/website/site
# 赋予读取权限 (确保 Nginx 容器能读取)
sudo chmod -R 755 /data/website/site

检查 Nginx 配置 确保 /data/website/nginx.conf 正确指向了挂载目录：

server {
    listen 80;
    server_name mydomain.com;
    # 容器内路径，对应宿主机的 /data/website/site
    root /usr/share/nginx/html; 
    
    location / {
        index index.html;
        try_files $uri $uri/ =404;
    }
}

重启 Nginx 容器：docker-compose restart

🎯 最终工作流

写作：在本地 Obsidian 写笔记。
同步：将笔记复制到 my-quartz-site/content。
提交：git add ., git commit, git push。
自动化：Gitee Go 自动构建并推送到服务器。
访问：浏览器访问 ushow.org 查看更新。

我的知识库

Explorer