本教程将指导您完成从零开始，使用 Jekyll 和 GitHub Pages 搭建一个完全免费、功能强大且易于维护的个人静态博客的完整过程。

为什么选择 Jekyll + GitHub Pages？

• 完全免费: 托管在 GitHub Pages 上，无需任何服务器费用。
• 简单高效: 您只需要用 Markdown 格式写作，Jekyll 会自动生成整个网站。
• 无缝集成: GitHub Pages 原生支持 Jekyll，您只需将代码推送到仓库，网站就会自动更新，无需复杂的部署流程。
• 高度可定制: 您可以轻松更换主题、修改样式，完全掌控您的博客外观。

第一步：准备本地开发环境

为了能在发布前在自己电脑上预览效果，我们需要安装必要的工具。对于 macOS 用户，强烈建议使用版本管理器 rbenv 来安装一个现代化的 Ruby，以避免与系统自带的旧版 Ruby 产生冲突。

1. 安装 rbenv (Ruby 版本管理器)

brew install rbenv

2. 配置 rbenv

将 rbenv 的初始化脚本添加到您的终端配置中，这样每次打开终端它都能正常工作。

echo 'eval "$(rbenv init -)"' >> ~/.zshrc

然后，关闭并重新打开一个新的终端窗口以让配置生效。

3. 安装新版 Ruby

我们将安装一个现代、稳定的 Ruby 版本（例如 3.3.0）。

# 安装 Ruby 3.3.0 (此过程会从源码编译，可能需要几分钟)
rbenv install 3.3.0

# 将 3.3.0 设置为全局默认版本
rbenv global 3.3.0

验证一下是否成功，运行 ruby -v，应该会显示 ruby 3.3.0。

4. 安装 Jekyll 和 Bundler

在全新的 Ruby 环境中，安装 Jekyll 和它的依赖管理器 Bundler。

gem install bundler jekyll

至此，您的本地环境已准备就绪。

第二步：创建并预览您的博客

1. 创建一个新的 Jekyll 站点

进入您想存放博客代码的目录，运行以下命令。它会创建一个名为 my-blog 的文件夹，并包含博客所需的所有模板文件。

jekyll new my-blog

2. 进入项目目录

cd my-blog

3. 本地预览

在发布到网上前，先在本地启动一个服务器来实时预览效果。

bundle exec jekyll serve

命令运行后，打开您的浏览器，访问 http://localhost:4000。您应该能看到一个默认主题的博客网站。

第三步：撰写第一篇文章

1. 找到文章目录: 您的所有博文都存放在 _posts 文件夹中。
2. 创建文章文件: 在 _posts 目录下创建一个新的 Markdown 文件。文件名必须遵循 年-月-日-文章标题.md 的格式。
   • 例如: 2025-09-05-how-to-build-a-blog.md

3. 添加头信息 (Front Matter): 每篇文章的开头，都必须有一个 YAML 格式的“头信息”，用来告诉 Jekyll 这篇文章的标题、布局、日期等元数据。请务必将其放在文件的最顶端。

   ---
   layout: post
   title:  "这是我的第一篇文章"
   date:   2025-09-05 20:30:00 +0800
   categories: tech life
   ---
   
   (从这里开始，用 Markdown 格式写您的正文...)
   
   # 这是一个一级标题
   
   这是段落内容。
   

第四步：部署到 GitHub Pages

这是最后一步，将您的博客发布到全世界。

1. 创建 GitHub 仓库

• 登录您的 GitHub 账户。
• 创建一个 新的、公开的 (Public) 仓库。
• 仓库的名称必须使用一个特殊的格式：<your-github-username>.github.io
  • 例如，如果您的 GitHub 用户名是 octocat，那么仓库名就必须是 octocat.github.io。

2. 关联并推送代码

回到您本地的 my-blog 文件夹，在终端里依次执行以下 git 命令，将您的博客代码推送到刚刚创建的 GitHub 仓库。

# 初始化 Git
git init -b main

# 添加所有文件到暂存区
git add .

# 创建第一次提交
git commit -m "Initial blog setup"

# 关联到您的远程 GitHub 仓库 (请将地址替换为您自己的)
git remote add origin https://github.com/your-github-username/your-github-username.github.io.git

# 推送到 GitHub
git push -u origin main

3. 访问您的线上博客

代码推送成功后，请耐心等待一两分钟。GitHub Pages 会在后台自动构建您的网站。

之后，您就可以通过 https://<your-github-username>.github.io 这个网址，看到您线上部署好的博客了。

第五步：如何更新博客

您的博客已经上线了！之后更新网站的流程非常简单：

1. 在本地的 _posts 文件夹里，创建一个新的 Markdown 文件来写新文章。
2. 写完后，在 my-blog 目录下，依次运行三条命令：

   git add .
   git commit -m "Post a new article"
   git push
   

3. 等待几分钟，您的线上博客就会自动出现新文章。

本文记录了一个从零开始，通过 Web 界面下载在线视频内容的工具的完整构建过程。项目从一个简单的想法出发，经历了一系列真实世界中常见的技术挑战，并通过不断的迭代和优化，最终演变成一个稳定、高效、安全且可部署在云端的私有应用。

一、最终成品

一个部署在云端的、受密码保护的 Web 应用。用户只需在前端页面粘贴目标内容的链接和访问密码，即可触发后端下载，并通过流式接口将文件下载到本地。文件在用户下载完成后会自动从服务器删除，不占用云端磁盘空间。

二、技术栈

• 前端 (Frontend):
  • HTML5
  • CSS3 (无特定框架)
  • JavaScript (ES6+) (无特定框架)
• 后端 (Backend):
  • Node.js: JavaScript 服务器端运行环境。
  • Express.js: 轻量级 Node.js Web 框架，用于搭建 API 服务器。
• 核心工具 (Core Tool):
  • yt-dlp: 业界领先的命令行视频下载工具，负责解析、下载和合并。
  • FFmpeg: yt-dlp 的底层依赖，用于处理音视频的合并与转换。
• 部署 (Deployment):
  • Docker: 将应用及所有依赖（Node.js, Python, yt-dlp, FFmpeg）打包成一个可移植的容器。
  • ClawCloud Run (或任何支持 Docker 的 PaaS 平台): 运行和托管我们的 Docker 容器。

三、核心设计思路

项目的核心是 “专业工具原则”。我们不重新发明轮子，而是将复杂、专业的任务（如解析和下载）交给领域内最强大的工具 yt-dlp。我们的 Node.js 后端只扮演一个“胶水层”和“安全外壳”的角色：

1. 接收请求: 通过 Express.js 提供一个简单的 API 接口。
2. 安全验证: 对前端传来的访问密码进行验证。
3. 任务调度: 在验证通过后，安全地构建并执行 yt-dlp 命令行指令。
4. 结果反馈: 将 yt-dlp 的执行结果（成功或失败）返回给前端。
5. 流式下载与清理: 创建一个专用的下载接口，将文件以“流”的形式传给用户，并在传输完成后自动删除源文件，实现“阅后即焚”，节约磁盘空间。

四、部署指南

1. Dockerfile

这是我们最终优化后的 Dockerfile，它通过使用轻量的 Alpine 系统和静态 ffmpeg，将镜像体积控制在了理想的大小。

# Stage 1: Use a lightweight Alpine-based Node.js image
FROM node:18-alpine

# Set the working directory
WORKDIR /usr/src/app

# Install dependencies. We need wget and xz to download and extract ffmpeg.
# We still need python and pip for yt-dlp.
RUN apk add --no-cache \
    wget \
    xz \
    python3

# Download and install a static build of ffmpeg, which is much smaller
RUN wget https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz && \
    tar -xf ffmpeg-release-amd64-static.tar.xz && \
    mv ffmpeg-*-static/ffmpeg /usr/local/bin/ && \
    rm -rf ffmpeg-release-amd64-static.tar.xz ffmpeg-*-static

# Install pip, build dependencies for yt-dlp, then install yt-dlp and remove build deps.
RUN apk add --no-cache --virtual .build-deps gcc musl-dev python3-dev && \
    apk add --no-cache py3-pip && \
    pip3 install --upgrade pip --break-system-packages && \
    pip3 install yt-dlp --break-system-packages && \
    apk del .build-deps

# Copy package.json and package-lock.json
COPY package*.json ./ 

# Install Node.js application dependencies
RUN npm install --production

# Copy the rest of the application files
COPY . .

# Make the downloads directory
RUN mkdir -p downloads

# Expose port 3000
EXPOSE 3000

# Define the command to run your app
CMD [ "node", "server.js" ]

2. 环境变量

在项目根目录创建 .env 文件，并根据 .env.example 的格式填入你的配置。在云端部署时，这些变量需要配置在平台的“环境变量”或“密钥”设置中。

AUTH_TOKEN=your_auth_token
CT0=your_ct0_token
APP_PASSWORD=your_secret_password

3. 构建与部署

构建一个支持云端服务器 (AMD64) 和本地 Mac (ARM64) 的跨平台镜像是最佳实践。

# 1. (仅首次需要) 创建并使用一个新的 builder
docker buildx create --name mybuilder --use

# 2. 构建并直接推送到 Docker Hub
docker buildx build --platform linux/amd64,linux/arm64 -t your-docker-username/x-downloader --push .

在 ClawCloud Run 等平台上部署时，指向这个镜像地址，配置好端口 (3000) 和环境变量，并挂载一个持久化存储卷到容器的 /usr/src/app/downloads 目录。

五、实战踩坑记录

这个项目的真正价值在于解决了一系列从开发到部署的真实问题。

• 问题一：Puppeteer 导航超时
  • 现象: 最初尝试用 Puppeteer 模拟浏览器抓取，但因反爬虫机制而超时。
  • 解决: 尝试增加超时、伪装 User-Agent 等，但效果不佳，且方案过于脆弱。
• 问题二：长视频下载失败
  • 现象: Node.js 下载方案在处理长视频时，因一次性发起过多并发请求而导致早期请求超时。
  • 解决: 在 Node.js 中实现了一个并发下载队列来控制请求数量。
• 问题三：下载速度被服务器限流
  • 现象: 即便并发下载，速度依然被限制在和视频播放速度几乎一致。
  • 解决: 第一次重大技术转向。放弃在 Node.js 中造轮子，承认 ffmpeg 也被限流的事实，转而采用更专业的命令行工具 yt-dlp，它内置了更成熟的反限速策略。
• 问题四：Docker 镜像体积过大 (1GB - 3.4GB)
  • 现象: 简单的 Dockerfile 构建出的镜像异常庞大。
  • 原因: 经过层层排查，先后发现了两个原因：1. COPY . . 指令错误地将本地下载的视频文件打包了进去；2. 系统包管理器 apk 安装 ffmpeg 时，附带了极其庞大的依赖库。
  • 解决: 1. 将 downloads/ 目录添加到 .dockerignore 文件中；2. 第二次重大技术转向，放弃从系统源安装 ffmpeg，改为直接下载和使用体积小巧的静态编译版本。
• 问题五：跨平台部署失败
  • 现象: 在 Mac (ARM 架构) 上构建的镜像，无法在云端服务器 (AMD64 架构) 上运行，报错 no match for platform in manifest。
  • 解决: 使用 docker buildx 构建支持多CPU架构的跨平台镜像。
• 问题六：云端文件丢失
  • 现象: 下载成功后，去取文件时却提示“文件不存在”。
  • 原因: 云平台使用的是“临时文件系统”，两次请求之间，容器的文件系统可能已被重置。
  • 解决: 在云平台为应用配置并挂载持久化存储卷，确保文件能够永久保存。
• 问题七：云端资源不足
  • 现象: 在最低配置的实例上，长视频下载任务会莫名失败。
  • 原因: 256MB 内存过低，长视频处理时内容超出上限，导致进程被系统强制杀死 (OOMKill)。
  • 解决: 将实例内存提升到更稳定的 512MB。

六、总结

这个项目完美地诠释了现代软件开发的常见模式：用一个轻量级的后端（Node.js）作为“外壳”，去驱动一个或多个强大的、专业的底层工具（yt-dlp），并将它们通过 Docker 容器化，最终部署到一个现代化的云平台。整个过程中的排错经历，尤其是在 Docker 镜像优化和云原生环境适应（如临时文件系统、跨平台构建）方面，是非常宝贵的实战经验。