mirza-rizvi/ResolveHQ

来源：https://github.com/mirza-rizvi/ResolveHQ

ResolveHQ

ResolveHQ 是一款基于 Cloudflare 生态、可自主部署的帮助台系统，专为小型支持团队设计。

一键部署至 Cloudflare（https://deploy.workers.cloudflare.com/?url=https://github.com/mirza-rizvi/ResolveHQ）

核心功能

• 支持共享收件箱，实现租户隔离管理客户、工单、任务分配、状态流转、优先级设置、标签分类与全文搜索。
• 支持作为所有者注册，邀请团队成员，并通过跨组织切换器管理所有者/管理员/坐席角色。
• 严格遵循 RFC 5322 规范进行邮件线程处理，有效防范跨工单的主题行伪造攻击。
• 通过 Cloudflare Email Routing 接收邮件，借助 Resend 发送邮件，提供投递状态跟踪、重试机制与幂等性 Webhook。出站回复可携带关联附件，死信队列可导出为持久化、可恢复的记录。
• 支持通过经验证的 R2 授权上传方式为工单附加文件。
• 提升响应效率：支持预存回复、内部备注、AI 生成草稿（可选启用），并提供响应式三栏收件箱视图，具备乐观版本冲突处理机制。
• 通过与工单邮件相同的服务通道，支持密码重置与邀请链接接收。
• 可从知识库文章生成公开帮助中心，草稿默认仅团队内部可见。
• 通过报告功能追踪工单量与响应速度，支持任意时间窗口数据导出为 CSV，并可通过基于规则的自动化引擎实现工单自动分类。
• 通过应用内通知向坐席推送任务分配与客户回复，支持亮色/暗色主题模式自由切换。
• 支持将客户存储的全部数据导出为 JSON，或通过可暂停恢复的工作流程彻底删除数据（同时取消相关待处理邮件）。
• 自动恢复机制：每五分钟运行的定时任务会重试停滞的邮件作业，并清理临时数据与孤立数据。
• 按工作区控制 AI 辅助功能：默认关闭，需管理员在设置中启用后，才会将工单对话内容发送至 OpenAI。
• 设置 TICKET_RETENTION_DAYS（例如 365）可使系统定时清理超过设定天数的已解决/已关闭工单（含附件），实现数据永久删除。

界面设计

工作区采用受 Slack 启发的茄子紫侧边栏，搭配自主托管的 Lato 字体、Lucide 图标库与 Radix UI 组件。主题感知控件与状态色系适配亮色/暗色工作区。移动端采用底部导航栏与键盘可达的工作区抽屉设计，确保所有功能入口可用；工单列表自适应布局以保持标题可读性。

使用 Cmd/Ctrl+K 快速跳转页面。侧边栏停靠区包含通知中心、主题切换与账户操作入口。

运行原理

ResolveHQ 作为单个 Cloudflare Worker 运行于您的账户中。通过 Hono 框架同时提供 REST API 服务与内置 React 应用。Cloudflare D1 存储工单与客户数据，R2 存储附件，Cloudflare Queues 处理进出站邮件作业。Cloudflare Email Routing 将入站邮件投递至 Worker，Resend 负责发送出站邮件。工单与附件存储在您的 Cloudflare 账户中，出站邮件内容通过 Resend 传输。

成本说明

在符合 Workers、D1、R2、Queues、Cron Triggers 与 Email Routing 当前免费套餐限额的前提下，ResolveHQ 可在 Cloudflare 免费计划上运行。CPU 密集型身份验证或邮件解析可能需要升级至 Workers 付费套餐，请根据实际部署进行性能测试。Queues 功能在 Workers 免费版中可用。R2 需单独激活账户并设置计费。Resend 的出站邮件在其自身限额内处理。详见免费套餐审计文档。

部署指南

最快捷的入门方式是使用上方 部署至 Cloudflare 按钮。您需要准备：

• Cloudflare 账户（Workers 免费版支持 Queues，需单独激活 R2）
• 已接入 Cloudflare 的域名（用于配置 Email Routing）
• 可选：Resend 账户及已验证的发件域名（用于发送出站邮件）

部署完成后，访问您的 ResolveHQ 网址并以所有者身份注册，可设置可选支持邮箱作为默认收件箱。在 Cloudflare 控制面板中添加 Email Routing 规则，将该地址指向已部署的 Worker，随后发送测试邮件确认可正常接收。

详细部署流程、配置要求、初始化设置与手动部署方式请参阅部署指南。

本地开发

npm install
cp .dev.vars.local.example .dev.vars
npm run db:migrate:local
npm run db:seed:local
npm run dev

Vite 应用运行于 http://localhost:5173，并代理 /api 请求至 http://localhost:8787 的 Wrangler 服务。

文档资料

• 部署与配置
• 系统架构
• 安全须知

可选配置项

• AI 辅助功能：在 Worker 密钥中设置 OPENAI_API_KEY（可选配置 OPENAI_MODEL，默认 gpt-4o-mini）以启用 AI 功能。每个工作区仍需在设置中主动开启；未配置密钥时该功能不会显示且不会发起任何 AI 请求。
• 数据保留策略：在 Worker 变量中设置 TICKET_RETENTION_DAYS，系统将自动删除超过设定天数的已解决/已关闭工单（含附件）。未设置则不执行自动删除。

尚未实现的功能

• 多语言界面
• 应用外通知（如邮件摘要）

许可证

详见 LICENSE 文件。