XMAIL - 网站消息通知平台

XMAIL 是一个开源的消息代理平台. 它允许你从任何网站接收消息, 并将它们实时转发到你选择的通知服务 (如 Slack, Telegram).

管理员可以通过后台面板管理站点配置, 查看所有接收到的消息.

✨ 功能

• 网站集成: 提供轻量级 JavaScript SDK, 可轻松集成到任何现有网站.
• 多渠道通知: 支持将消息转发到 Slack 和 Telegram.
• 管理后台: 提供一个 React 管理界面, 用于管理站点, 配置通知参数和查看消息历史.
• Docker 化: 整个项目使用 Docker Compose 进行容器化, 实现一键启动和隔离环境.
• 数据库迁移: 使用 Prisma 管理数据库结构和迁移.

---

🚀 技术栈

• 后端: Node.js, Express.js, Prisma (ORM)
• 前端 (管理后台): React
• 数据库: PostgreSQL
• 包管理器: Yarn Workspaces
• 容器化: Docker, Docker Compose

---

🏗️ 项目架构

本项目是一个 Monorepo, 包含三个核心部分:

1. backend/: Node.js API 服务器.
   • 处理来自 SDK 的消息请求.
   • 管理用户, 站点和消息数据.
   • 根据站点配置发送通知.
2. admin-frontend/: React 单页应用.
   • 提供给管理员登录和管理站点的界面.
   • 可以查看所有通过平台接收到的消息.
3. frontend/: 客户端 JS-SDK.
   • sdk.js 文件可以被嵌入到任何网站中, 用于捕获表单数据并发送到 backend.

---

🔧 本地开发

你可以通过 Docker Compose 在本地轻松启动整个项目.

1. 克隆项目

git clone <your-repository-url>
cd xmail

2. 配置环境变量

backend 服务需要一些环境变量. 你可以从示例文件开始.

cp backend/.env.example backend/.env

然后, 编辑 backend/.env 文件并填入必要的值:

# 数据库连接字符串 (Docker Compose 会使用这个)
DATABASE_URL="postgresql://user:password@db:5432/xmaildb?schema=public"

# 用于签发 JWT 的密钥: openssl rand -hex 32
JWT_SECRET="YOUR_SUPER_SECRET_KEY"

# 初始化管理员账户
ADMIN_EMAIL="admin@example.com"
ADMIN_PASSWORD="your_admin_password"

3. 安装依赖并启动

项目使用 Yarn Workspaces. 根目录下的 package.json 包含启动整个项目的脚本.

# 安装所有工作区的依赖
yarn install

# 使用 Docker Compose 构建并启动所有服务 (db, backend, admin-frontend)
# --build 标志确保在代码更改后重新构建镜像
docker-compose up --build

4. 访问服务

• 管理后台: http://localhost:3001
• 后端 API: http://localhost:3000
• 模拟界面: http://localhost:8000

---

📖 使用方法

1. 登录后台: 使用你在 .env 文件中配置的 ADMIN_EMAIL 和 ADMIN_PASSWORD 登录管理后台.
2. 创建站点: 在后台中, 创建一个新的站点并获取其唯一的 siteId.
3. 配置通知: 为你的站点配置 Slack Webhook URL 或 Telegram Bot Token/Chat ID.
4. 集成 SDK: 将生成的 HTML 代码片段嵌入到你的网站中. sdk.js 将自动为指定的表单添加事件监听.

---

部署

关于如何将此项目部署到生产环境, 请参考 DEPLOYMENT.md 文件中的详细说明.