🏗️ 系统架构

┌───────────────────────────┐
│ RyuChan-Content(内容仓) │ ┌───────────────────────┐
│ 文章/配置/图片/友链等 │ │ RyuChan-CMS(可选) │
└─────────────┬─────────────┘ │ React/Vite 管理端 │
 │ prebuild clone │ /blog / /config 等 │
 ▼ └───────────┬───────────┘
┌───────────────────────┐ │ trigger-deploy
│ RyuChan │ ▼
│ (Astro 前端展示) │──────────────► ┌──────────────────┐
│ /blog / /about 等 │ 构建同步 │ Cloudflare Pages│
└───────────────────────┘ │ 部署上线 │
 └──────────────────┘

✨ 核心亮点

🚀 在线编辑体验

🎨 优雅的前端展示

⬇️ 快速开始

前置要求

1. 克隆前端仓库

git clone https://github.com/kobaridev/RyuChan.git
cd RyuChan
pnpm i

2. 配置内容仓库

# 在 RyuChan 的上级目录执行
git clone https://github.com/kobaridev/RyuChan-Content.git ryuchan-content

# 在 RyuChan 根目录创建 .env
CONTENT_REPO=/path/to/ryuchan-content

CONTENT_REPO_OWNER=kobaridev
CONTENT_REPO_NAME=RyuChan-Content
CONTENT_REPO_BRANCH=main
CONTENT_TOKEN=ghp_xxxxxxxxxxxx # 内容仓为私有时需要

3. 运行

pnpm run dev

📦 内容仓库结构(RyuChan-Content)

ryuchan-content/
├── src/content/
│ ├── site/config.yaml # 站点通用配置:标题/描述/主题/favicon/banner
│ ├── user/config.yaml # 用户信息:头像/描述/社交链接/收款码
│ ├── footer/config.yaml # 页脚:社交链接与备案信息
│ ├── blog/
│ │ ├── config.yaml # 博客模块标题/副标题 + 每页文章条数
│ │ └── src/ # 文章(.md / .mdx),一条记录一篇文章
│ ├── about/
│ │ ├── config.yaml # 关于页标题/副标题
│ │ └── src/index.md # 关于页正文
│ ├── friends/
│ │ ├── config.yaml # 友链页配置
│ │ └── list/ # 一条友链一个文件(01.yaml, 02.yaml ...)
│ ├── project/
│ │ ├── config.yaml # 项目页配置
│ │ └── src/ # 一个项目一个文件(01.yaml, 02.yaml ...)
│ ├── album/
│ │ ├── config.yaml # 相册页配置
│ │ └── categories/ # 一个相册一个文件(一组照片)
│ ├── navigation/
│ │ ├── config.yaml # 导航页配置
│ │ └── categories/ # 一个分组一个文件(01.yaml, 02.yaml ...)
│ ├── music/
│ │ ├── config.yaml # 音乐页配置 + Meting API 基址
│ │ ├── list/ # 一个播放列表一个文件
│ │ └── custom/ # 自定义歌单完整数据
│ ├── anime/
│ │ ├── config.yaml # 追番页配置 + 数据源列表
│ │ └── provider/ # bilibili.yaml / tmdb.yaml
│ ├── comments/
│ │ ├── config.yaml # 评论开关与选用 provider
│ │ └── provider/ # giscus.yaml / twikoo.yaml / waline.yaml
│ └── analysis/
│ ├── config.yaml # 统计脚本开关
│ └── provider/ # umami / claity 统计脚本
├── assets/
│ ├── media/ # 文章配图,构建时映射到 public/image/
│ └── brand/ # 站点级图片,构建时展开到 public/ 根
│ ├── favicon.ico / logo.png / profile.png / home.webp
│ └── qrcode/
│ ├── Alipay.jpg
│ └── WeChat.jpg
└── ryucms.schema.json # RyuChan-CMS 管理端的 collection 定义

内容 → 前端映射关系

🔧 可选:CMS 管理端(RyuChan-CMS)

功能模块

技术栈

🔐 环境变量

前端仓(RyuChan)

本地开发(.env 文件)

# 内容仓 GitHub 配置(在线编辑写入目标)
PUBLIC_GITHUB_OWNER=kobaridev
PUBLIC_GITHUB_REPO=RyuChan-Content
PUBLIC_GITHUB_BRANCH=main
PUBLIC_GITHUB_APP_ID= # 你的 GitHub App ID
PUBLIC_GITHUB_ENCRYPT_KEY= # 你的 AES-256 加密密钥(可选)
# 前端仓名称(仅 about-edit 需要,默认 RyuChan)
# PUBLIC_FRONTEND_REPO=RyuChan
# 内容仓(推荐:克隆到同级目录自动检测)
# git clone https://github.com/kobaridev/RyuChan-Content.git ../ryuchan-content
# 或手动指定路径
# CONTENT_REPO=/absolute/path/to/ryuchan-content
# CI 构建用(本地可省略)
CONTENT_REPO_OWNER=kobaridev
CONTENT_REPO_NAME=RyuChan-Content
CONTENT_REPO_BRANCH=main
# CONTENT_TOKEN=ghp_xxxxxxxxxxxx # 内容仓为私有时需要

GitHub Actions Secrets(前端仓)

内容仓(RyuChan-Content)

CMS 管理端(RyuChan-CMS,可选)

📝 配置详解(site/config.yaml)

site 配置

site:
 tab: RyuChan # 浏览器标签页标题
 title: RyuChan # 站点主标题
 title_type: text # 导航栏标题展示方式:text(文字)或 image(图片)
 title_image: /logo.png # title_type 为 image 时使用的图片
 description: 站点描述文字 # SEO meta description
 language: zh # 语言代码(zh / en)
 favicon: /favicon.ico # 站点图标
 theme:
 light: garden # 浅色主题(daisyUI 主题名)
 dark: dracula # 深色主题(daisyUI 主题名)
 code: snazzy-light # 代码高亮主题
 date_format: ddd MMM DD YYYY # 日期显示格式
 banner:
 enableRandom: true # 是否启用随机 Banner 图
 randomUrl: https://t.alcy.cc/ycy # 随机图 API 地址
 randomCount: 5 # 每次随机获取图片数量
 height: 70vh # Banner 区域高度
 images: # 固定图片列表(enableRandom 为 false 时使用)
 - https://example.com/bg1.jpg
 menu: # 顶部导航菜单
 - id: write
 text: 写作
 href: /write
 svg: material-symbols:edit-square-outline-rounded
 target: _self

user 配置

user:
 name: 作者名
 description: 个人简介
 site: https://example.com # 个人主页
 avatar: /profile.png # 头像(位于 assets/brand/)
 qr_wechat: /WeChat.jpg # 微信收款码
 qr_alipay: /Alipay.jpg # 支付宝收款码
 sidebar:
 social: # 侧边栏社交图标(Iconify 图标名)
 - href: https://github.com/user
 ariaLabel: Github
 svg: ri:github-line
 footer:
 social: # 页脚社交图标
 - href: https://twitter.com/user
 ariaLabel: Twitter
 svg: ri:twitter-line

其他模块配置

# blog/config.yaml
title: 博客标题
subtitle: 博客副标题
pageSize: 8 # 每页文章条数
typewriterTexts: # 首页打字机效果文本
 - Hello World
 - 欢迎来到我的博客
# comments/config.yaml
enable: true
provider: twikoo # twikoo / waline / giscus
# comments/provider/twikoo.yaml
envId: xxx
# comments/provider/waline.yaml
serverURL: https://waline.example.com
lang: zh
# comments/provider/giscus.yaml
repo: owner/repo
repoId: xxx
category: Announcements
categoryId: xxx
# anime/config.yaml
title: 追番
provider:
 - bilibili
 - tmdb
subtitle: 记录和分享我喜欢的动漫
# anime/provider/bilibili.yaml
uid: 12345678
# anime/provider/tmdb.yaml
apiKey: xxx
listId: 12345
# music/config.yaml
title: Music
api: https://meting.mikus.ink/api # Meting API 基址
subtitle: 沉浸式享受音乐时光
# analysis/config.yaml
enable: true
provider:
 - umami-head # 或 claity
# analysis/provider/umami-head.yaml
baseUrl: https://umami.example.com
shareId: xxx
websiteId: xxx
timezone: Asia/Shanghai

📝 文章写作约定

🌐 页面功能

追番页面

导航页面

相册页面

音乐页面

静态页面

🛠️ 部署流程

最低配置(仅搭建博客)

1. 克隆内容仓到任意位置(或公开仓库)
2. 克隆前端仓,克隆内容仓到同级目录
3. 配置 GitHub Actions Secrets(CLOUDFLARE_*、CONTENT_TOKEN 如有)
4. push 代码触发 deploy-pages workflow
5. 内容更新时,push 内容仓自动触发 trigger-deploy → 前端 redeploy

完整配置(含可选 CMS)

1. 前端仓(RyuChan)→ Cloudflare Pages / Vercel / Workers
 - Secrets: CONTENT_TOKEN(私有仓)、CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID
 - 或 VERCEL_TOKEN、VERCEL_ORG_ID、VERCEL_PROJECT_ID
2. 内容仓(RyuChan-Content)→ GitHub 公共/私有仓库
 - Secrets: FRONTEND_REPO_OWNER、FRONTEND_REPO_NAME、FRONTEND_BRANCH、DISPATCH_TOKEN
 - push 触发 trigger-deploy.yml → repository_dispatch → 前端 redeploy
3. CMS 管理端(RyuChan-CMS)→ 任意静态托管(Vercel / Cloudflare Pages 等)
 - Env: VITE_GITHUB_CLIENT_ID、VITE_OAUTH_PROXY_URL
 - OAuth 代理 Cloudflare Worker Secrets:
 GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、REDIRECT_URI、CMS_ORIGIN

部署流程一图概览

本地开发:
 RyuChan-Content(本地 clone)
 ↓ prebuild 脚本同步
 RyuChan(pnpm dev)→ 浏览器访问
线上部署(无 CMS):
 push 内容仓 → trigger-deploy → repository_dispatch → 前端仓库 build + deploy
 push 前端仓 → deploy-pages workflow → Cloudflare Pages
线上部署(含 CMS):
 push 内容仓 → trigger-deploy → 前端 redeploy
 CMS 部署(Vercel 等)→ GitHub OAuth → 直接读写内容仓

🛠️ 常用命令

pnpm dev # 启动开发服务器
pnpm build # 完整构建(prebuild → astro build → pagefind 索引)
pnpm run search:index # 生成/更新全文搜索索引
pnpm run preview # 本地预览构建产物
pnpm run check # Astro 类型检查
pnpm run deploy # 构建并部署到 Cloudflare Pages
pnpm run prefetch:music # 预取音乐时长数据
pnpm run search:clean # 清理搜索索引

🙏 致谢

📝 许可证

🤝 贡献