#Rin（羊角快车二创版）部署指南

本文档将指导您从零开始把 羊角快车二创版 Rin 部署到 Cloudflare。

#前置要求

• 一个 GitHub 账号
• 一个 Cloudflare 账号（免费版即可）
• 大约 10-15 分钟时间

#部署步骤

#第一步：Fork 仓库

本仓库是 羊角快车二创版 Rin，在官方原版基础上增加了邮箱自助友链、TOTP 双因素认证、API Key 等能力，推荐直接 Fork 本仓库：

1. 访问 羊角快车二创版 Rin（本仓库，推荐）：https://github.com/wool-hmq/Rin
2. 点击右上角的 "Fork" 按钮
3. 选择您的个人账户，保持默认设置，点击 "Create fork"

官方原版（上游）：openRin/Rin。它不包含本版新增功能；只有在你明确需要跟随上游时再使用它。本文后续步骤默认基于二创版。

#获取用户 ID 与 API 令牌

参照 https://developers.cloudflare.com/workers/wrangler/ci-cd/ 来配置 GitHub Actions 所需的 Cloudflare 登录环境变量

ID 随意点击一个自己绑定的域名，进入后在右侧（需要向下滑动一段距离）可以找到账户ID

创建 API 令牌：点击右上角头像 > 我的个人资料 > API 令牌 > 创建令牌，模板选择编辑 Cloudflare Workers：

创建完成后保存令牌

#第二步：配置 GitHub Secrets

1. 在您 fork 的仓库页面，点击 "Settings" 标签
2. 在左侧菜单中，展开 "Secrets and variables"，选择 "Actions"
3. 点击 "New repository secret" 按钮，添加以下 Secrets：

#必需 Secrets

提示: JWT_SECRET 可以是任意长度的随机字符串，例如：MySecretKey123!@#

#登录配置 Secrets

Rin 目前支持账号密码登录与 Github OAuth 登录，可二选一或同时配置

账号密码登录（推荐）

GitHub OAuth 登录（可选）

如果您想使用 GitHub 账号登录，请参考高级配置部分添加 OAuth 配置。

提示: 账号密码登录和 GitHub OAuth 登录可以同时启用，用户可以在登录页面自由选择登录方式。

#第三步：触发部署

1. 进入仓库的 "Actions" 标签
2. 在左侧选择 "Build" 工作流
3. 点击 "Run workflow" 按钮
4. 保持默认分支（main），点击 "Run workflow"

部署过程大约需要 3-5 分钟。Build 成功后会通过 workflow_run 自动触发 Deploy 工作流，手动触发 Deploy 时需要提供构建产物 URL。

提示: 部署脚本会自动配置前端环境变量，无需手动配置。站点名称、描述、Worker 名称等可以在 GitHub Variables 中自定义（见下方「站点基础变量」）。

#第四步：访问您的博客

部署完成后，Deploy 工作流的日志会打印 App URL，前端页面与后端 API 都通过该地址访问。默认 Worker 名称为 rin-server，可通过 Variables 中的 WORKER_NAME 覆盖。

#第五步：首次登录

1. 访问前端页面
2. 点击右上角的登录图标
3. 使用您在 Secrets 中设置的 ADMIN_USERNAME 和 ADMIN_PASSWORD 登录
4. 登录后，点击头像进入 个人资料 页面，可以修改昵称和上传头像

#站点基础变量（可选）

以下 GitHub Variables 用于覆盖部署默认值：

邮箱登录、邮箱验证码与邮件自助友链还需要配置 EMAIL_SEND_URLS / EMAIL_SEND_KEYS，详见 环境变量说明。

#发布第一篇文章

1. 登录后，点击右上角的 "写作" 按钮
2. 填写文章标题和内容
3. 点击 "发布" 按钮

🎉 恭喜！您的 Rin 博客已经成功部署并发布了第一篇文章！

#高级配置

#自定义域名

1. 登录 Cloudflare Dashboard
2. 进入 Pages > 您的项目 > 自定义域
3. 按照提示添加您的域名

#图片存储配置

Rin 支持两种存储方式：Cloudflare R2（推荐）或 S3 兼容存储。

#使用 Cloudflare R2（推荐）

如果未配置任何 S3 环境变量，部署脚本会自动尝试使用 Cloudflare R2。您只需在 GitHub Variables 中设置：

部署脚本会自动构建 R2 的 endpoint 和 access host。如果您希望使用自定义域名访问图片，可以额外设置：

#使用 S3 兼容存储

如果您需要使用其他 S3 兼容存储（如 AWS S3、MinIO 等），需要完整配置以下 Secrets：

以及以下 Variable（可选）：

#GitHub OAuth 配置

如果您想使用 GitHub 账号登录：

1. 访问 GitHub Settings > Developer settings > OAuth Apps
2. 点击 "New OAuth App"
3. 填写应用信息：
   • Application name: Rin Blog
   • Homepage URL: 您的前端页面地址
   • Authorization callback URL: https://your-worker-name.your-account-id.workers.dev/api/user/github/callback
4. 创建后，获取 Client ID 和 Client Secret
5. 在 GitHub Secrets 中添加：
   • RIN_GITHUB_CLIENT_ID
   • RIN_GITHUB_CLIENT_SECRET

#Webhook 通知

如果您希望 Rin 将评论通知和友链申请通知发送到机器人、聊天工具或自动化平台，请继续阅读 Webhook 指南。

#故障排除

#部署失败

1. 检查 GitHub Secrets 是否正确配置
2. 查看 Actions 日志获取详细错误信息
3. 确保 Cloudflare 账户有 Workers、Pages、D1 的权限

#无法登录

1. 确认 ADMIN_USERNAME 和 ADMIN_PASSWORD 已正确设置
2. 检查 Worker 日志查看认证错误
3. 清除浏览器缓存后重试

#数据库迁移失败

部署脚本会自动运行数据库迁移。如果失败：

1. 手动进入 Cloudflare Dashboard > D1
2. 找到您的数据库，点击 "Console"
3. 手动执行迁移 SQL（参考 server/sql/ 目录下的文件，按编号顺序执行）

#GitHub Actions 工作流

仓库包含多个 GitHub Actions 工作流，用于自动化测试、构建和部署：

#CI 工作流 (ci.yml)

在推送到 main / trunk 或提交 PR 时运行：

• TypeScript 类型检查
• 代码格式化验证

#测试工作流 (test.yml)

在推送到 main / trunk 或提交 PR 时运行：

• 服务端测试：使用 Bun 的单元测试和集成测试
• 客户端测试：使用 Vitest 的组件测试
• 类型检查：客户端与服务端分别执行 tsc --noEmit
• 构建验证：客户端生产构建

#构建工作流 (build.yml)

在推送到 main / master / trunk、提交 PR 或手动触发时运行：

• 类型检查
• 构建前端
• 通过 Wrangler dry-run 构建后端
• 上传构建产物；成功后自动触发 Deploy

#部署工作流 (deploy.yml)

由 Build 成功后自动触发，或手动提供构建产物 URL 触发：

• 部署前端到 Cloudflare Pages
• 部署后端到 Cloudflare Workers
• 执行 D1 数据库迁移
• 在 Actions 日志中输出部署后的 App URL

#文档工作流 (docs.yml)

推送到 main 且改动涉及 docs/** 时运行：

• 使用 Rspress 构建文档站
• 发布到 GitHub Pages

#发布工作流 (release.yml)

推送 vX.Y.Z 形式的 tag 时运行：

• 校验各 workspace 版本一致性
• 执行类型检查与构建
• 打包并发布构建产物

#PR 预览

创建 Pull Request 时会自动生成预览部署；PR 关闭后由 clean.yml 清理预览 Worker。

#更新博客

当有新版本发布时：

1. 在您的 fork 仓库页面点击 "Sync fork"
2. 点击 "Update branch"
3. 部署会自动触发

#更新羊角快车二创版（推荐）

# 添加二创版仓库为上游
git remote add upstream https://github.com/wool-hmq/Rin.git
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

#同步官方原版（上游，可选）

只在需要合并官方原版改动时使用。官方原版不包含本版新增功能：

git remote add upstream https://github.com/openRin/Rin.git
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

#需要帮助？

• 📖 羊角快车二创版在线文档
• 🐛 羊角快车二创版 Issues
• 💬 羊角快车二创版 Discussions
• 📖 官方原版文档（上游）
• 🐛 官方原版 Issues（上游）
• 💬 官方原版 Discussions（上游）