qiyuan-blog-template

🚀 带 AI 问答的 Astro 全功能博客模板 — 内置 RAG 站内问答、文章朗读、评论、网盘、短链与资源站，EdgeOne Makers 部署，开箱即用。

基于 Astro 深度定制的个人博客与技术资源站模板（衍生自 Koharu 主题），在线示例：https://www.qiyuan.icu。

功能页面截图

上图为**示例站（qiyuan.icu，已开启全部可选功能）**首页：顶部 Hero 视频区、作者卡片、文章列表、站内 AI 助手浮窗、导航栏的资源/网盘/短链入口等。模板默认关闭这些可选功能，克隆后按需开启。

歌单	临时邮箱

网盘	资源站

本仓库 qiyuan-blog-template 是一个博客模板：在 GitHub 仓库页面点击 Use this template 即可一键创建你自己的博客仓库，再按需修改 config/site.yaml、填充文章、配置环境变量后部署。部署优先推荐国内友好的 EdgeOne Makers，详见下方「作为模板使用」（资源站为独立子项目，需单独部署，见「资源站搭建教程」）。

永久免费说明

本模板的全部功能（含评论、站内 AI 助手、资源站、临时邮箱、文章朗读、短链、网盘）在对应服务商的免费额度内均可永久免费使用，不强制任何付费。 下表列出每个功能所依赖的外部服务及其当前免费额度（数据核实于 2026-07，以各厂商官网为准）：

说明：

• 永久免费档（长期有效）：Neon、Supabase、Cloudflare（Workers/KV/R2/D1/Email Routing/Turnstile）、硅基流动嵌入/重排、智谱 GLM-4.7-Flash。
• 当前限时免费 / 公测：EdgeOne Makers 加速流量处于限免阶段；商汤 sensenova（deepseek-v4-flash）为免费公测，额度与政策可能随公测结束调整——但模板已内置多生成平台兜底（智谱 GLM-4.7-Flash 永久免费、ModelScope 每日 2000 次免费），任一平台变动都不会让 AI 助手失效。
• 文章朗读音频在本地预生成（Edge TTS，走微软免费语音端点，无需密钥、无费用），生成后仅占用 Cloudflare R2 的存储额度。
• 只要使用量不超出上表各档额度，整套博客（含全部可选功能）即可零成本永久运行；仅在超出免费额度后才需按量付费（如 Supabase 扩容、Cloudflare 超出请求数、Neon 升级计算等）。

🚀 作为模板使用

1. 进入本仓库 qiyuan-blog-template 页面，点击 Use this template → Create a new repository，填写你的新仓库名（可任意命名）。
2. git clone 到本地，npm install。
3. 复制 .env.example 为 .env，按需填写各功能的环境变量（不填则对应功能自动关闭）。
4. 编辑 config/site.yaml：改 site.title / url / avatar / social 为你自己的信息。
5. 删除 src/content/blog/welcome.md，放入你自己的 .md 文章。
6. 部署到 EdgeOne Makers（或其它 Astro 兼容平台），在平台的环境变量中配置与 .env 相同的键值。

可选功能默认关闭

为保持模板开箱即用的纯净度，以下可选功能默认全部关闭，克隆后按需开启：

说明：评论 / 临时邮箱 / 文章朗读属「零依赖或轻依赖」，配好即用；站内 AI 助手 / 资源站 / 网盘 / 短链 依赖边缘函数与外部服务（Neon / Supabase / R2 / Cloudflare），需在部署平台配置对应环境变量。各功能的完整配置见下方「功能特性」与各 docs/*.md。

🛠 开发工具：右键样式编辑器（仅本地 astro dev）

本地 astro dev 运行时直接定死右键可用，无需开关：在页面任意位置右键即弹出样式编辑器，边看边调。面板内不使用任何表情符号，图标一律为内联 SVG；所有可调属性均标注中文 / 日文 / 英文三语。

• 元素：编辑右键所点元素的内联样式（文字/背景颜色、字号、字重、内边距、外边距、圆角、边框、对齐、行高、不透明度）。
• 上传媒体替换：元素面板顶部「上传图片 / 画像 / Image」按钮（SVG 图标），支持 图片 / GIF / 视频：
  • 右键 <img>（如头图、精选分类图）→ 直接替换其 src；若右键的是包裹图片的容器，会自动定位其中的 <img> 一并替换。
  • 右键带背景图的元素（如背景图区域）→ 替换其 background-image；上传视频则注入一个绝对定位的 <video> 覆盖层作为动态背景。
  • 内容以 base64 / blob 注入，刷新后还原（开发期调试用，不写盘）。
• 主题变量：按当前「亮色 / 暗色」分别编辑全局 CSS 变量（SVG 太阳 / 月亮 图标切换）。变量以自然语言说明呈现（如「页面背景色 / ページ背景 / Page background」），技术变量名仅作小号代码注记。改动注入 <style> 并持久化到 localStorage，刷新后保留；「复制 CSS」可导出，「重置」恢复默认。
• 面板不显示滚动条（已隐藏，主题变量区改双列网格压缩高度）；点击面板外空白处自动关闭；面板配色使用博客主题变量，自动跟随亮/暗主题。

⚠️ 该功能仅在 import.meta.env.DEV 下挂载（src/layouts/Layout.astro 中以 {import.meta.env.DEV && <StyleEditor />} 包裹，src/components/dev/StyleEditor.tsx 组件内亦有兜底守卫）。astro build 时被自动 tree-shake，不进入生产产物，对线上访客零影响。

安全响应头

两个边缘函数（edge-functions/api/[[default]].js 与 resource-site/edge-functions/api/[[default]].js）已为所有 API 响应统一注入安全头（经 getCorsHeaders() spread，一处覆盖全部 JSON / 流式 / 代理响应）：

静态资源（HTML / JS / CSS / 字体 / 图片）的安全头需在 EdgeOne 控制台 → 站点加速 → 配置 → HTTP 响应头（修改响应头） 中按文件后缀统一添加上述同样的头（CDN 缓存层注入，被缓存的资源也带安全头）。CSP 暂未启用（站内有 AdSense 与内联脚本，需单独审计）。

可选加固：在 EdgeOne 控制台 → 安全防护 → 速率限制 给写入类接口配「客户端 IP 60s 内 ≥1 次 → 拦截 429」，覆盖 POST /api/comment-image、POST /api/drive/upload-init、POST /api/temp-mail/address，防滥发。EdgeOne 边缘直接判真实客户端 IP（EO-Connecting-IP），不会因 CDN 聚合误伤全体用户。

技术栈

• Astro 5（SSG）+ 定制主题，支持中文 / English / 日本語 三语（[lang]/ 镜像路由）。
• 部署平台：EdgeOne Makers（腾讯云边缘函数 / 云函数）。站点 qiyuan.icu 跑在边缘，全文搜索用 Pagefind。
• 边缘运行时：
  • edge-functions/api/[[default]].js —— EdgeOne 边缘函数单体，承载 RAG 聊天、临时邮箱、评论、上传、MCP、统计等全部 API。
  • cloud-functions/ —— Makers 云函数（如博客图床上传 api/images/upload）。
• 外部依赖：Neon（Postgres + pgvector，博客文章向量库）、Supabase（资源站向量库）、硅基流动（bge-m3 / bge-reranker 嵌入重排）、商汤 sensenova + ModelScope + 智谱（生成模型）、Cloudflare（KV 评论存储 + R2 评论图 + 临时邮箱 Worker/D1）。

功能特性

• 博客文章：Markdown/MDX，封面图，目录，Pagefind 站内搜索；支持按语言切换。
• 站内 AI 助手（RAG）「就这篇文章问 AI」：
  • 检索：博客文章（Neon + pgvector rag_posts 余弦检索）+ 资源站（Supabase products 混合检索：向量 + 词法 ilike，RRF 融合），各取候选经重排后送入上下文。
  • 嵌入 BAAI/bge-m3、重排 BAAI/bge-reranker-v2-m3（均经硅基流动，免费）。
  • 生成：首选商汤 sensenova deepseek-v4-flash（多密钥轮询、关闭思考模式），兜底 ModelScope / 智谱 GLM / 硅基流动 DeepSeek。
  • 使用的大模型平台：
    • 硅基流动（SiliconFlow）：嵌入 BAAI/bge-m3 + 重排 BAAI/bge-reranker-v2-m3（免费），并作生成最终兜底（DeepSeek）。
    • 商汤 sensenova：生成首选，模型 deepseek-v4-flash（多密钥轮询、关闭思考模式）。
    • ModelScope 魔搭：生成兜底，Llama-3.3-70B（国内直连免费）。
    • 智谱 GLM：生成兜底，GLM-4.7-Flash（永久免费、国内直连）。
  • 性能优化：Neon 预热（请求内 SELECT 1 与嵌入并发，消除 scale-to-zero 冷启动）、问题向量缓存（LRU 5 条，相同问题跳过重复嵌入调用）。
• 临时邮箱 qiyuanmail.cc.cd：Cloudflare Email Routing → Worker → D1（temp_addresses / temp_messages）；Turnstile 人机验证；前端支持收件箱、自动刷新、HTML 邮件渲染（链接新标签打开）。
  • ⚠️ 收信 Worker + D1 + Email Routing 需在 Cloudflare 控制台自行部署（代码见 cloudflare/）；本仓库的边缘函数只负责 UI 与读信/生成地址。
• 评论系统：评论存 Cloudflare KV，图片存 Cloudflare R2（经上传 Worker 直写，无需 S3 密钥）；config/site.yaml 中 comment.provider 默认 none（可选 custom / giscus / waline / twikoo）。
• R2 独立图床：评论图走 r2.qiyuan.icu（国内经 EdgeOne 边缘回源 Cloudflare，浏览器全程只碰腾讯网络）。
• 文章朗读（Edge TTS 预生成音频）：文章 frontmatter 加 audio: true 即生成中文朗读 mp3。流程为发布前本地用 Edge TTS 合成 → 上传 Cloudflare R2（audio/<slug>.mp3，经 r2.qiyuan.icu CDN）→ 前端播放器点击播放（非运行时实时合成，体验更稳）。清单 src/assets/audio-manifest.json 记录每篇 slug → { url, voice, chars, bytes, generatedAt }，文章页据此显示播放器。
  • 音频 URL 自动带缓存破坏参数 ?v=<mp3 内容 sha256 前 12 位>：R2/EdgeOne 对未知 query 参数按同一对象返回，但浏览器/CDN 以完整 URL 作缓存键，故音频内容更新后 URL 必变、强制重新拉取，避免旧 mp3 被长期缓存（R2 默认 Cache-Control: max-age=604800）。
  • 生成：npm run generate:audio（增量，内容+音色哈希命中则跳过）；-- --force 全量重生成；-- --local 强制落本地 public/audio/。增量缓存存 .cache/audio-cache.json。
• 短链（Short URL）：把长链接缩短成 {origin}/api/s/<slug>。存储于 Cloudflare KV（与评论同命名空间，前缀 short:）；支持自定义短码（3–32 位字母数字 _-）或自动生成 6 位随机码；仅接受 http/https 目标；访问 /api/s/<slug> 即 302 跳转到原链接，不存在返回 404。需配置 CF_KV_*。
• 公开网盘（Netdisk） /drive：浏览器经 S3 presigned PUT 直传 Cloudflare R2，文件元数据存 Cloudflare KV；单文件默认上限 500MB（DRIVE_MAX_BYTES 可覆盖）。提供上传初始化 /api/drive/upload-init、完成回调 /api/drive/upload-complete、列表 /api/drive/list、分享页元数据 /api/drive/meta/:token。文件 24 小时后自动删除（KV expirationTtl，DRIVE_TTL_HOURS 可改时长），需配合 Cloudflare 控制台 R2 桶 Lifecycle 规则（前缀 drive/）才能真正清理对象。需配置 R2_* 与 CF_KV_*。

本地开发

npm install
npm run dev      # http://localhost:4321
npm run build    # 构建到 dist/
npm run preview  # 预览构建结果

需要 Node.js 18.17.1+（推荐 20+）与 npm 9+。

RAG 相关脚本（可选，CI/部署时通常自动跑）：npm run index:neon（文章向量）、npm run index:resources（资源向量回填）、npm run generate:summaries 等。

文章朗读音频需本地预生成：npm run generate:audio 合成并上传 R2 后，须提交 src/assets/audio-manifest.json（部署只读取清单、不生成音频）。新增或编辑 audio: true 文章后务必重跑本命令。

环境变量（EdgeOne 控制台）

边缘函数通过环境变量注入密钥，本仓库代码不包含任何密钥。

RAG 必需

生成模型（首选 + 兜底）

评论 / R2 图床

网盘 / 短链

短链复用上方 CF_KV_*；网盘复用上方 R2_* 与 CF_KV_*。

临时邮箱

资源站（可选）

资源站是独立部署的项目，博客只是引用它的数据。完整步骤见下方「资源站搭建教程」。

资源站搭建教程

⚠️ 资源站与博客是两个相互独立的部署，不要混为一谈：

• 资源站（网盘资源分享站）：一个单独的 EdgeOne 项目，源码在本仓库的 resource-site/ 子目录，拥有自己的边缘函数、Supabase 数据库与（可选）前端页面，需单独部署、绑定自己的域名（如 resources.qiyuan.icu）。
• 博客：通过共用同一套 Supabase 数据库 + RESOURCES_API_PROXY 指向资源站域名来引用资源数据，在内置「资源」页（/resources）中展示、搜索、获取网盘链接。

也就是说：先把 resource-site/ 当作独立项目部署好，博客再指过去。 二者可共用同一个 Supabase 项目，也可各自独立。

架构

                    ┌──────────────────── 资源站（独立部署，resource-site/）
浏览器               │   EdgeOne 项目 A（域名如 resources.qiyuan.icu）
 ├─ 资源站站点 ──────┤     ├─ edge-functions/api/[[default]].js（认证/商品/评论/图片/MCP）
 │                  │     └─ Supabase（users / products / reviews / orders；product-images 桶）
 │                  └────────────────────
 │
 └─ 博客「资源」页 ──→ EdgeOne 项目 B（博客，本仓库根目录）
        /resources        └─ /api 经 RESOURCES_API_PROXY 引用资源站，或直连同一套 Supabase 读取 products

一、部署资源站（独立项目）

源码见 resource-site/，详细文档见 resource-site/README.md。

1. 建库与 RLS：在 Supabase SQL Editor 依次执行：
   • resource-site/database/schema.sql（建表：users / products / reviews / orders / quark_orders）
   • resource-site/database/rls_policies.sql（RLS：users 对 anon 完全不可见，商品匿名只读上架）
2. 建 Storage 桶：创建 product-images 桶并设为公开（或经 /api/images/* 代理）。
3. 单独部署 resource-site/：将该目录作为独立 EdgeOne 项目部署（边缘函数 + 可选静态前端），并在其控制台配置环境变量：

   SUPABASE_URL=https://your-project.supabase.co
   SUPABASE_SERVICE_KEY=eyJ...      # 服务端密钥
   JWT_SECRET=***                    # 资源站登录 JWT 签名密钥（必填）
   

   前端页面（public/*.html）未随模板附带，可自行编写或从原站取用；仅需 API 时可只部署边缘函数。

二、让博客引用资源站

1. 数据层：博客与资源站共用同一套 Supabase。如需 RAG 语义搜索，在 Supabase 执行 database/products_embedding.sql 为 products 加向量列；分类多语言可选执行 database/resource_category_i18n.sql。
2. 配置指向：博客侧设置 RESOURCES_API_PROXY 指向资源站域名（如 https://resources.qiyuan.icu），本地开发时 npm run dev 会据此代理 /api。
3. 开启资源页：config/site.yaml 中 resources.enabled: true（默认已开），按需改 label / icon / ownerUserId。
4. 部署博客：推送到 Git，EdgeOne Makers 自动构建并发布。

验证

# 对资源站域名验证
curl https://resources.your-domain.com/api/categories
curl "https://resources.your-domain.com/api/products?limit=2"

返回 JSON 即说明资源站已正常工作。管理后台可注册账号、发布商品（密码需同时包含大写 + 小写 + 数字 + 符号）。

更多文档

• 资源站独立部署说明 与 部署指南
• 资源站 API 接口
• 资源站数据库结构
• 博客侧资源引用配置（详细）
• AI 资源发布提示词

站点配置

主配置在 config/site.yaml，常用项：

替换头像：将图片放到 public/img/avatar.svg（或同名 .jpg/.webp），并同步更新 public/favicon.ico（favicon 由头像生成）。

如何添加文章

1. 在 src/content/blog/ 新建 Markdown/MDX 文件，如 my-post.md。
2. 在文件顶部写 frontmatter：

---
title: 我的文章标题
description: 一句话摘要
pubDate: 2026-06-05
heroImage: ./cover.png   # 可选，封面放同级或子目录
categories:
  - 笔记
tags:
  - 标签一
audio: true        # 可选：设为 true 即生成该篇文章的 Edge TTS 中文朗读音频（详见上方「文章朗读」）
---

正文内容写在这里…

1. 封面图规则：
   • 与文章同目录：heroImage: ./cover.png
   • 在子目录：heroImage: ./my-post/cover.png
2. 保存后本地 npm run dev 预览，或 npm run build 构建。

pubDate / heroImage 会自动映射为 date / cover，与 src/content.config.ts 中的 schema 对齐。

修改图片后建议运行 npm run generate:lqips 更新占位渐变。

目录结构

部署

推送到 Git 后由 EdgeOne Makers 自动构建（npm run build）并发布，边缘函数随仓库部署。部署前需在 EdgeOne 控制台填好上面对应的环境变量（尤其 SILICONFLOW_API_KEY / NEON_SERVERLESS_URL / SUPABASE_* / SENSENOVA_API_KEYS / CF_KV_*）。

临时邮箱功能另需在 Cloudflare 控制台完成：部署 cloudflare/ 下的收信 Worker、建 D1 表、配置 Email Routing catch-all → Worker、配置 Turnstile。详见各文件内注释。

许可证

本项目以 MIT 许可证 开源（详见 LICENSE）。你可以自由 fork、修改、部署为自己的博客，只需保留版权与许可证声明；商业用途亦可，风险自负。