diff --git a/README.md b/README.md index dcc20ab..f455886 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,17 @@ Message Nest 是一个灵活而强大的消息推送整合平台，旨在简化 关于运行日志，考虑到目前多数服务以收集控制台输出为主，暂时不支持写出日志文件。 ## 更新日志 ☕ -[点我转跳](https://engigu.github.io/Message-Push-Nest/guide/changelog.html) + +### 最近更新 + +**2025.12.06** - 新增消息模板功能、V2 API +**2025.10.12** - 增加 cookies 过期天数设置 +**2025.09.30** - 支持明暗主题切换、登录日志 +**2025.08.10** - 重构 web 页面，UI 升级（shadcn-vue + tailwindcss） +**2025.04.28** - 支持 TiDB、数据库 SSL 配置 +**2025.01.01** - 支持托管消息功能 + +[查看完整更新日志](https://engigu.github.io/Message-Push-Nest/guide/changelog.html) ## 项目来由 💡 @@ -43,10 +53,6 @@ Message Nest 是一个灵活而强大的消息推送整合平台，旨在简化 欢迎通过提交问题和提出改进建议。 -## 致谢 🙏 - -该项目汲取了[go-gin-example](https://github.com/eddycjy/go-gin-example)项目的灵感，展示了 Go 和 Gin 在实际应用中的强大和多才多艺。 - ## Star History ⭐ [![Star History Chart](https://api.star-history.com/svg?repos=engigu/Message-Push-Nest&type=Date)](https://star-history.com/#engigu/Message-Push-Nest&Date) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 412d495..fbad0f4 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -32,7 +32,17 @@ export default defineConfig({ '/guide/': [ { text: '介绍', link: '/guide/introduction' }, { text: '特色功能', link: '/guide/features' }, - { text: '消息模板', link: '/guide/template' }, + { + text: '功能使用', + items: [ + { text: '渠道配置', link: '/guide/channels' }, + { text: '发送任务', link: '/guide/tasks' }, + { text: '消息模板', link: '/guide/template' }, + { text: '定时消息', link: '/guide/scheduled-messages' }, + { text: '托管消息', link: '/guide/self-hosted-messages' }, + { text: '系统设置', link: '/guide/settings' } + ] + }, { text: '更新日志', link: '/guide/changelog' } ], '/deployment/': [ diff --git a/docs/guide/changelog.md b/docs/guide/changelog.md index 4ec1d49..419a19c 100644 --- a/docs/guide/changelog.md +++ b/docs/guide/changelog.md @@ -14,10 +14,6 @@ - 使用加密 Token 提升安全性 - 支持占位符参数传递 - 自动遍历模板的所有启用实例 -- **优化代码结构** - - 重构模板相关 Model 命名（`MessageTemplate` → `Template`） - - 添加 TypeScript 类型声明文件 - - 完善文档体系 ### 2025.10.12 - 增加cookies过期天数设置 diff --git a/docs/guide/channels.md b/docs/guide/channels.md new file mode 100644 index 0000000..9abb9de --- /dev/null +++ b/docs/guide/channels.md @@ -0,0 +1,364 @@ +# 推送渠道配置 + +Message Nest 支持多种消息推送渠道，您可以根据需求配置不同的渠道，实现多渠道消息推送。 + +## 邮件（SMTP） + +通过标准 SMTP 协议发送邮件通知。 + +### 配置参数 + +| 参数 | 说明 | 示例 | +|------|------|------| +| 渠道名称 | 自定义渠道名称 | `公司邮箱` | +| SMTP 服务器 | 邮件服务器地址 | `smtp.gmail.com` | +| SMTP 端口 | 服务器端口 | `587` (TLS) 或 `465` (SSL) | +| 发件人邮箱 | 发送邮件的邮箱地址 | `noreply@example.com` | +| 发件人名称 | 显示的发件人名称 | `系统通知` | +| 邮箱密码 | 邮箱密码或授权码 | `your_password` | +| 加密方式 | TLS/SSL/无 | `TLS` | + +### 常见邮箱配置 + +#### Gmail + +- **SMTP 服务器**: `smtp.gmail.com` +- **端口**: `587` (TLS) +- **注意**: 需要开启"允许不够安全的应用"或使用应用专用密码 + +#### QQ 邮箱 + +- **SMTP 服务器**: `smtp.qq.com` +- **端口**: `587` (TLS) 或 `465` (SSL) +- **注意**: 需要在邮箱设置中开启 SMTP 服务并获取授权码 + +#### 163 邮箱 + +- **SMTP 服务器**: `smtp.163.com` +- **端口**: `465` (SSL) +- **注意**: 需要开启 SMTP 服务并使用授权码 + +#### 企业邮箱 + +根据企业邮箱服务商提供的 SMTP 配置填写。 + +### 使用场景 + +- ✅ 用户注册/登录通知 +- ✅ 订单确认和物流通知 +- ✅ 账单和发票发送 +- ✅ 密码重置和安全提醒 +- ✅ 营销邮件和活动通知 + +### 注意事项 + +::: warning 注意 +- 邮件发送可能会被识别为垃圾邮件，建议配置 SPF、DKIM 等记录 +- 使用授权码而非邮箱密码，提高安全性 +- 注意邮件发送频率限制，避免被封禁 +- 建议使用企业邮箱，稳定性更好 +::: + +## 钉钉机器人 + +通过钉钉群机器人发送消息到钉钉群。 + +### 配置步骤 + +1. **创建钉钉群** + - 在钉钉中创建一个群聊 + +2. **添加自定义机器人** + - 进入群设置 → 智能群助手 → 添加机器人 → 自定义 + - 设置机器人名称和头像 + +3. **配置安全设置** + - 选择"自定义关键词"或"加签"方式 + - 记录 Webhook 地址 + +4. **在 Message Nest 中配置** + - 渠道名称：自定义名称 + - Webhook URL：复制的 Webhook 地址 + - 安全设置：根据选择填写关键词或密钥 + +### 配置参数 + +| 参数 | 说明 | 必填 | +|------|------|------| +| 渠道名称 | 自定义渠道名称 | 是 | +| Webhook URL | 机器人 Webhook 地址 | 是 | +| 安全关键词 | 自定义关键词（如选择此方式） | 否 | +| 加签密钥 | 加签密钥（如选择此方式） | 否 | + +### 消息格式 + +钉钉支持以下格式： +- **Text** - 纯文本 +- **Markdown** - 支持 Markdown 格式 + +### @提醒功能 + +支持@群成员： +- **@手机号** - 通过手机号@指定成员 +- **@所有人** - @群内所有成员（需要机器人权限） + +### 使用场景 + +- ✅ 系统告警和监控通知 +- ✅ 任务完成提醒 +- ✅ 审批流程通知 +- ✅ 团队协作消息 +- ✅ 日报/周报推送 + +### 注意事项 + +::: warning 注意 +- 每个机器人每分钟最多发送 20 条消息 +- @所有人功能需要群主授权 +- 建议在消息中包含安全关键词，避免发送失败 +- 机器人被移除后 Webhook 将失效 +::: + +## 企业微信机器人 + +通过企业微信群机器人发送消息到企业微信群。 + +### 配置步骤 + +1. **创建企业微信群** + - 在企业微信中创建群聊 + +2. **添加群机器人** + - 进入群设置 → 群机器人 → 添加机器人 + - 设置机器人名称 + +3. **获取 Webhook** + - 复制 Webhook 地址 + +4. **在 Message Nest 中配置** + - 渠道名称：自定义名称 + - Webhook URL：复制的 Webhook 地址 + +### 配置参数 + +| 参数 | 说明 | 必填 | +|------|------|------| +| 渠道名称 | 自定义渠道名称 | 是 | +| Webhook URL | 机器人 Webhook 地址 | 是 | + +### 消息格式 + +企业微信支持以下格式： +- **Text** - 纯文本 +- **Markdown** - 支持 Markdown 格式 + +### @提醒功能 + +支持@群成员： +- **@用户ID** - 通过用户ID@指定成员 +- **@手机号** - 通过手机号@指定成员 +- **@所有人** - @群内所有成员 + +### 使用场景 + +- ✅ 企业内部通知 +- ✅ 项目进度更新 +- ✅ 系统运维告警 +- ✅ 工作流审批提醒 +- ✅ 会议和日程通知 + +### 注意事项 + +::: warning 注意 +- 每个机器人每分钟最多发送 20 条消息 +- 消息内容不能包含敏感词 +- 机器人被移除后 Webhook 将失效 +- 建议使用 Markdown 格式，展示效果更好 +::: + +## 微信测试公众号 + +通过微信测试公众号发送模板消息。 + +### 配置步骤 + +1. **申请测试公众号** + - 访问 [微信公众平台测试号](https://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=sandbox/login) + - 使用微信扫码登录 + +2. **获取配置信息** + - appID：测试号信息中的 appID + - appsecret：测试号信息中的 appsecret + +3. **添加模板消息** + - 在"模板消息接口"中添加模板 + - 记录模板 ID + +4. **关注测试公众号** + - 使用微信扫描测试号二维码关注 + - 记录用户的 OpenID + +5. **在 Message Nest 中配置** + - 填写 appID、appsecret、模板ID、OpenID + +### 配置参数 + +| 参数 | 说明 | 必填 | +|------|------|------| +| 渠道名称 | 自定义渠道名称 | 是 | +| appID | 测试公众号 appID | 是 | +| appsecret | 测试公众号 appsecret | 是 | +| 模板ID | 模板消息 ID | 是 | +| OpenID | 接收用户的 OpenID | 是 | + +### 使用场景 + +- ✅ 个人项目测试 +- ✅ 小范围通知 +- ✅ 开发环境调试 + +### 注意事项 + +::: warning 注意 +- 测试公众号仅供开发测试使用，不能用于生产环境 +- 测试公众号有关注人数限制（100人） +- 模板消息格式需要符合微信规范 +- 正式使用需要申请正式公众号 +::: + +## 自定义 Webhook + +向自定义的 HTTP 接口发送消息。 + +### 配置参数 + +| 参数 | 说明 | 必填 | +|------|------|------| +| 渠道名称 | 自定义渠道名称 | 是 | +| Webhook URL | 目标 HTTP 接口地址 | 是 | +| 请求方法 | GET/POST/PUT 等 | 是 | +| 请求头 | 自定义 HTTP 请求头 | 否 | +| 请求体模板 | 自定义请求体格式 | 否 | + +### 请求体模板 + +支持使用变量： +- `{{title}}` - 消息标题 +- `{{text}}` - 纯文本内容 +- `{{html}}` - HTML 内容 +- `{{markdown}}` - Markdown 内容 + +**示例：** + +```json +{ + "message": "{{title}}", + "content": "{{text}}", + "timestamp": "{{timestamp}}" +} +``` + +### 使用场景 + +- ✅ 集成第三方系统 +- ✅ 自建消息服务 +- ✅ 对接其他通知平台 +- ✅ 自定义消息处理逻辑 + +### 注意事项 + +::: tip 提示 +- 确保目标接口可访问 +- 注意接口的请求频率限制 +- 建议添加认证信息保证安全 +- 可以通过请求头传递 Token 等认证信息 +::: + +## 自托管消息 + +将 Message Nest 站点作为消息接收平台，用户登录站点查看消息。 + +### 核心定位 + +**与其他渠道的区别：** +- **邮件/钉钉/企业微信** - 推送到外部平台 +- **自托管消息** - 存储在 Message Nest 站点，用户登录站点查看 + +### 配置参数 + +| 参数 | 说明 | 必填 | +|------|------|------| +| 渠道名称 | 自定义渠道名称 | 是 | +| 渠道描述 | 渠道用途说明 | 否 | + +### 功能特点 + +- ✅ 站点作为消息接收平台 +- ✅ 无需外部依赖 +- ✅ 消息集中存储和管理 +- ✅ 支持多种格式展示（Text/HTML/Markdown） +- ✅ 支持消息搜索和筛选 +- ✅ 支持消息已读/未读状态 + +### 使用场景 + +- ✅ 站内消息中心 +- ✅ 系统公告发布 +- ✅ 内部工作流通知 +- ✅ 系统告警记录 +- ✅ 消息归档平台 + +### 查看消息 + +1. 登录 Message Nest 站点 +2. 进入"自托管消息"或"消息中心"页面 +3. 查看接收到的消息列表 +4. 点击消息查看详情 + +### 注意事项 + +::: tip 提示 +- 消息不会自动清理，需要手动清理 +- 建议定期清理不需要的消息，避免占用过多存储空间 +- 可以根据需要导出消息记录 +- 适合作为消息的集中查看和管理平台 +::: + +## 渠道管理 + +### 创建渠道 + +1. 登录管理后台 +2. 进入"推送渠道"页面 +3. 点击"新建渠道" +4. 选择渠道类型 +5. 填写配置信息 +6. 保存并测试 + +### 测试渠道 + +创建渠道后，建议先进行测试： + +1. 在渠道列表中找到新建的渠道 +2. 点击"测试"按钮 +3. 发送测试消息 +4. 确认消息正常接收 + +### 编辑和删除 + +- **编辑**：点击渠道的"编辑"按钮，修改配置信息 +- **删除**：点击"删除"按钮，确认后删除（注意：删除后关联的任务和模板将无法使用该渠道） + +### 最佳实践 + +1. **命名规范** - 使用清晰的渠道名称，便于识别 +2. **分类管理** - 按用途或环境分类（如：生产环境邮件、测试环境钉钉） +3. **定期检查** - 定期检查渠道配置是否有效 +4. **安全管理** - 妥善保管密钥和密码信息 +5. **备用渠道** - 配置多个渠道作为备用，提高可靠性 + +## 下一步 + +- 查看 [发送任务](/guide/tasks) 了解如何使用渠道发送消息 +- 查看 [消息模板](/guide/template) 了解如何创建模板 +- 查看 [API 文档](/api/v1) 了解如何通过 API 发送消息 diff --git a/docs/guide/features.md b/docs/guide/features.md index 5d13d4b..f80122f 100644 --- a/docs/guide/features.md +++ b/docs/guide/features.md @@ -1,19 +1,112 @@ +# 特色功能 -## 支持的推送方式 +Message Nest 提供了丰富的功能，帮助您轻松实现多渠道消息推送。 -- **邮件发送** - 支持标准SMTP邮件发送 -- **钉钉** - 支持钉钉机器人消息推送 -- **企业微信** - 支持企业微信应用消息推送 -- **微信测试公众号** - 支持微信测试公众号模板消息发送 -- **自定义 Webhook** - 支持自定义的Webhook消息发送 +## 核心功能 + +### 多渠道推送 + +支持多种主流消息推送渠道，一次配置，多处使用。 + +- **邮件发送** - 支持标准SMTP邮件发送，适用于正式通知和账单发送 +- **钉钉** - 支持钉钉机器人消息推送，适用于团队协作和系统告警 +- **企业微信** - 支持企业微信应用消息推送，适用于企业内部通知 +- **微信测试公众号** - 支持微信测试公众号模板消息发送，适用于开发测试 +- **自定义 Webhook** - 支持自定义的Webhook消息发送，灵活对接第三方系统 - **自托管消息** - 可以将站点作为消息的接收方，登录站点查看消息 +👉 [查看推送渠道配置详细说明](/guide/channels) + +### 消息模板（⭐推荐） + +通过模板管理消息内容，支持占位符动态替换，大幅提高开发效率和维护便利性。 + +**核心特性：** +- ✅ 支持 Text、HTML、Markdown 三种格式 +- ✅ 占位符动态替换（`{{key}}` 语法） +- ✅ 多实例配置，一次发送多渠道 +- ✅ @提醒功能（钉钉、企业微信） +- ✅ 模板启用/禁用控制 +- ✅ 版本管理和灰度发布 + +**适用场景：** +- 用户通知（注册、登录、密码重置） +- 订单消息（下单、支付、发货、退款） +- 系统告警（服务异常、资源不足） +- 营销推广（活动通知、优惠券） + +👉 [查看消息模板详细说明](/guide/template) + +### 发送任务 + +基于任务的消息发送方式，适用于完全动态的消息内容。 + +**核心特性：** +- ✅ 配置多个推送渠道 +- ✅ 支持多种消息格式 +- ✅ 获取 API Token +- ✅ 查看发送日志 + +**说明：** 发送任务主要用于兼容历史数据，新项目推荐使用消息模板。 + +👉 [查看发送任务详细说明](/guide/tasks) + +### 定时消息 + +自动化的定时消息发送功能，使用 Cron 表达式设置执行时间。 + +**核心特性：** +- ✅ 使用 Cron 表达式设置执行时间 +- ✅ 关联发信任务进行发送 +- ✅ 启用/禁用定时任务 +- ✅ 立即执行测试 +- ✅ 查看执行日志 + +**适用场景：** +- 每日报表推送 +- 周会/月会提醒 +- 定期系统巡检 +- 月度账单推送 + +👉 [查看定时消息详细说明](/guide/scheduled-messages) + +### 自托管消息 + +将 Message Nest 站点作为消息接收平台，用户登录站点查看消息。 + +**核心定位：** +- 💡 站点作为消息接收和展示平台 +- 💡 用户登录站点查看消息 +- 💡 不推送到外部渠道 + +**核心特性：** +- ✅ 站点作为消息中心 +- ✅ 搜索消息 +- ✅ 查看消息详情 + +**适用场景：** +- 站内消息中心 +- 内部工作流通知平台 +- 系统告警记录平台 +- 消息归档平台 + +👉 [查看自托管消息详细说明](/guide/self-hosted-messages) + +### 系统设置 + +灵活的系统配置和管理功能。 + +**配置项：** +- ✅ 站点设置（标题、标语、Logo、分页、Cookie 过期天数） +- ✅ 重置密码（修改当前用户密码） +- ✅ 日志清理（定时清理、保留条数） +- ✅ 登录日志（查看登录历史记录） +- ✅ 站点关于（版本信息、系统状态） + +👉 [查看系统设置详细说明](/guide/settings) + ## 其他功能 -### 定时任务 - -支持自定义的定时消息发送，可以设置定时推送任务。 - ### 数据统计 支持数据统计展示，可以查看消息发送情况和历史记录。 @@ -28,19 +121,6 @@ - 支持查看定时清理日志 - 支持登录日志记录 -### 用户管理 - -- 支持用户密码设置 -- 支持用户定时任务清理 -- 支持更新定时时间 - -### 系统信息 - -- 支持系统信息展示 -- 支持站点信息自定义 -- 支持明暗主题切换设置 -- 支持Cookies过期天数设置 - ### 数据库支持 - **SQLite** - 轻量级部署，无需额外数据库服务 diff --git a/docs/guide/scheduled-messages.md b/docs/guide/scheduled-messages.md new file mode 100644 index 0000000..ebb6aef --- /dev/null +++ b/docs/guide/scheduled-messages.md @@ -0,0 +1,297 @@ +# 定时消息 + +定时消息功能允许您设置定时发送的消息任务，系统会按照设定的 Cron 表达式自动执行发送。 + +## 功能概述 + +定时消息允许您： +- ✅ 创建定时发送任务 +- ✅ 使用 Cron 表达式设置执行时间 +- ✅ 关联发信任务进行发送 +- ✅ 启用/禁用定时任务 +- ✅ 立即执行定时任务 +- ✅ 查看执行日志 + +## 创建定时消息 + +### 步骤 + +1. 进入"定时消息"页面 +2. 点击"新增定时消息"按钮 +3. 填写定时消息信息 +4. 点击"创建定时消息"保存 + +### 配置项 + +| 字段 | 说明 | 必填 | +|------|------|------| +| 定时消息名称 | 定时任务的名称 | 是 | +| 关联发信任务 | 选择要使用的发信任务 | 是 | +| Cron 表达式 | 定时执行的时间规则 | 是 | +| 标题 | 消息标题 | 是 | +| 内容 | 消息内容 | 是 | +| url | 可选的 URL 链接 | 否 | + +::: warning 重要提示 +请确保所选的发信任务已配置至少一个发送实例，否则无法发送消息。 +::: + +### Cron 表达式 + +Cron 表达式用于设置定时任务的执行时间，格式为：`分 时 日 月 周` + +#### 常用模板 + +系统提供了常用的 Cron 表达式模板，点击即可应用： + +| 模板 | Cron 表达式 | 说明 | +|------|------------|------| +| 每分钟 | `* * * * *` | 每分钟执行一次 | +| 每5分钟 | `*/5 * * * *` | 每5分钟执行一次 | +| 每小时 | `0 * * * *` | 每小时整点执行 | +| 每天凌晨2点 | `0 2 * * *` | 每天凌晨2点执行 | +| 每周一凌晨2点 | `0 2 * * 1` | 每周一凌晨2点执行 | +| 每月1号凌晨2点 | `0 2 1 * *` | 每月1号凌晨2点执行 | + +#### Cron 表达式格式 + +``` +* * * * * +│ │ │ │ │ +│ │ │ │ └─ 星期 (0-7, 0和7都表示周日) +│ │ │ └─── 月份 (1-12) +│ │ └───── 日期 (1-31) +│ └─────── 小时 (0-23) +└───────── 分钟 (0-59) +``` + +#### 特殊字符 + +- `*` - 匹配任意值 +- `,` - 列举多个值，如 `1,3,5` +- `-` - 范围，如 `1-5` +- `/` - 步长，如 `*/5` 表示每5个单位 + +#### 示例 + +``` +0 9 * * * # 每天上午9点 +0 9-17 * * * # 每天9点到17点的整点 +0 9,12,18 * * * # 每天9点、12点、18点 +*/30 9-17 * * * # 每天9点到17点，每30分钟 +0 9 * * 1-5 # 周一到周五的上午9点 +0 0 1,15 * * # 每月1号和15号的凌晨 +``` + +## 管理定时消息 + +### 查看定时消息列表 + +在"定时消息"页面可以看到所有定时消息： + +| 列 | 说明 | +|----|------| +| ID | 定时消息的唯一标识 | +| 名称 | 定时消息名称（可点击查看完整内容） | +| 内容 | 消息内容（可点击查看完整内容） | +| Cron表达式 | 定时执行的时间规则 | +| 关联任务 | 关联的发信任务 ID | +| 下次执行时间 | 下一次计划执行的时间 | +| 创建时间 | 定时消息创建时间 | +| 操作 | 操作按钮和启用/禁用开关 | + +### 定时消息操作 + +#### 查看日志 + +1. 点击定时消息的"日志"按钮 +2. 查看该定时消息的执行记录 +3. 可以查看发送成功/失败的详细信息 + +#### 编辑定时消息 + +1. 点击定时消息的"编辑"按钮 +2. 在弹出的对话框中修改信息 +3. 可以点击"立即发送"测试发送 +4. 点击"更新定时消息"保存修改 + +#### 删除定时消息 + +1. 点击定时消息的"删除"按钮 +2. 确认删除操作 +3. 定时消息将被删除，不再执行 + +#### 启用/禁用定时消息 + +- 点击定时消息行的开关按钮 +- 禁用的定时消息不会自动执行 +- 可以随时重新启用 + +#### 立即发送 + +在编辑定时消息时，可以点击"立即发送"按钮立即执行一次发送，用于测试定时消息配置是否正确。 + +### 搜索定时消息 + +在定时消息列表页面的搜索框中输入任务名称，可以快速筛选定时消息。 + +## 使用场景 + +### 场景 1：每日报表推送 + +**需求：** 每天早上9点自动发送前一天的业务报表 + +**配置：** +- 定时消息名称：每日业务报表 +- 关联发信任务：报表推送任务 +- Cron 表达式：`0 9 * * *` +- 标题：每日业务报表 +- 内容：前一天的业务数据统计 + +### 场景 2：周会提醒 + +**需求：** 每周一上午9点提醒团队周会 + +**配置：** +- 定时消息名称：周会提醒 +- 关联发信任务：团队通知任务 +- Cron 表达式：`0 9 * * 1` +- 标题：周会提醒 +- 内容：今天上午10点周会，请准时参加 + +### 场景 3：系统巡检 + +**需求：** 每小时检查系统状态并发送报告 + +**配置：** +- 定时消息名称：系统巡检 +- 关联发信任务：系统告警任务 +- Cron 表达式：`0 * * * *` +- 标题：系统巡检报告 +- 内容：系统运行正常 + +### 场景 4：月度账单 + +**需求：** 每月1号凌晨发送上月账单 + +**配置：** +- 定时消息名称：月度账单 +- 关联发信任务：账单推送任务 +- Cron 表达式：`0 2 1 * *` +- 标题：月度账单 +- 内容：上月账单详情 + +## 工作流程 + +```mermaid +graph LR + A[创建定时消息] --> B[设置 Cron 表达式] + B --> C[关联发信任务] + C --> D[启用定时消息] + D --> E[系统定时检查] + E --> F{到达执行时间?} + F -->|是| G[调用发信任务] + F -->|否| E + G --> H[发送消息] + H --> I[记录日志] + I --> E +``` + +## 最佳实践 + +### 1. Cron 表达式设置 + +- ✅ 使用系统提供的常用模板 +- ✅ 避免设置过于频繁的执行（如每分钟） +- ✅ 选择系统低峰期执行（如凌晨） +- ✅ 测试 Cron 表达式是否正确 + +### 2. 发信任务配置 + +- ✅ 确保关联的发信任务已配置实例 +- ✅ 测试发信任务是否能正常发送 +- ✅ 为重要消息配置多个渠道 +- ✅ 使用有意义的任务名称 + +### 3. 消息内容 + +- ✅ 标题简洁明了 +- ✅ 内容清晰完整 +- ✅ 提供必要的链接（url 字段） +- ✅ 使用立即发送测试内容 + +### 4. 监控和维护 + +- ✅ 定期查看执行日志 +- ✅ 及时处理发送失败的情况 +- ✅ 禁用不再需要的定时消息 +- ✅ 定期检查下次执行时间是否正确 + +### 5. 性能优化 + +- ✅ 避免在同一时间执行大量定时任务 +- ✅ 合理设置执行频率 +- ✅ 对于大量消息，考虑分批发送 +- ✅ 监控系统资源使用情况 + +## 常见问题 + +### Q: 定时消息没有执行怎么办？ + +**A:** +1. 检查定时消息是否已启用（开关是否打开） +2. 检查 Cron 表达式是否正确 +3. 查看下次执行时间是否符合预期 +4. 检查关联的发信任务是否配置了实例 +5. 查看日志是否有错误信息 + +### Q: 如何测试定时消息配置是否正确？ + +**A:** +1. 编辑定时消息 +2. 点击"立即发送"按钮 +3. 查看是否成功发送 +4. 检查日志中的发送记录 + +### Q: Cron 表达式如何设置？ + +**A:** +1. 使用系统提供的常用模板 +2. 参考 Cron 表达式格式说明 +3. 使用在线 Cron 表达式生成器 +4. 通过立即发送测试是否正确 + +### Q: 定时消息发送失败怎么办？ + +**A:** +1. 查看日志中的错误信息 +2. 检查关联的发信任务配置 +3. 确认发信任务的渠道是否正常 +4. 检查消息内容是否符合要求 +5. 尝试立即发送测试 + +### Q: 可以暂停定时消息吗？ + +**A:** +可以。点击定时消息行的开关按钮禁用，定时消息将不再自动执行。需要时可以重新启用。 + +### Q: 定时消息和发信任务有什么关系？ + +**A:** +定时消息需要关联一个发信任务，定时消息只负责定时触发，实际的消息发送由关联的发信任务完成。发信任务决定了消息发送到哪些渠道。 + +## 注意事项 + +::: warning 重要提示 +1. **关联任务配置** - 确保关联的发信任务已配置至少一个发送实例 +2. **Cron 表达式** - 设置前请仔细检查，避免执行时间错误 +3. **执行频率** - 避免设置过于频繁的执行，影响系统性能 +4. **消息内容** - 定时消息的内容是固定的，不支持动态内容 +5. **启用状态** - 创建后记得启用定时消息，否则不会执行 +::: + +## 下一步 + +- 查看 [发送任务](/guide/tasks) 了解如何配置发信任务 +- 查看 [V1 API 文档](/api/v1) 了解消息发送机制 +- 查看 [渠道配置](/guide/channels) 了解如何配置推送渠道 diff --git a/docs/guide/self-hosted-messages-old.md b/docs/guide/self-hosted-messages-old.md new file mode 100644 index 0000000..e0eaf23 --- /dev/null +++ b/docs/guide/self-hosted-messages-old.md @@ -0,0 +1,480 @@ +# 自托管消息 + +自托管消息功能将 Message Nest 作为消息接收平台，用户登录站点查看消息。 + +## 功能概述 + +**核心定位：** 将 Message Nest 站点作为消息接收和展示平台，而不是推送到外部渠道。 + +**主要功能：** +- ✅ 站点作为消息接收平台 +- ✅ 用户登录后台查看消息 +- ✅ 搜索消息 +- ✅ 查看消息详情 + +**与其他渠道的区别：** +- **邮件/钉钉/企业微信** - 推送到外部平台，用户在对应平台查看 +- **自托管消息** - 存储在 Message Nest 站点，用户登录站点查看 + +## 配置自托管消息渠道 + +### 创建渠道 + +1. 登录管理后台 +2. 进入"推送渠道"页面 +3. 点击"新建渠道" +4. 选择渠道类型："自托管消息" +5. 填写配置信息 + +### 配置参数 + +| 参数 | 说明 | 必填 | 默认值 | +|------|------|------|--------| +| 渠道名称 | 自定义渠道名称 | 是 | - | +| 渠道描述 | 渠道用途说明 | 否 | - | + +### 配置示例 + +``` +渠道名称：站内通知 +渠道描述：用户站内消息通知 +``` + +## 使用自托管消息 + +### 方式一：通过任务发送 + +1. 创建发送任务 +2. 添加自托管消息渠道实例 +3. 通过 V1 API 发送消息 + +**API 示例：** + +```bash +curl -X POST http://your-domain/api/v1/message/send \ + -H "Content-Type: application/json" \ + -d '{ + "token": "your_task_token", + "title": "系统通知", + "text": "您有一条新消息", + "html": "

系统通知

您有一条新消息

", + "markdown": "## 系统通知\n\n您有一条新消息" + }' +``` + +### 方式二：通过模板发送（推荐） + +1. 创建消息模板 +2. 为模板添加自托管消息实例 +3. 通过 V2 API 发送消息 + +**API 示例：** + +```bash +curl -X POST http://your-domain/api/v2/message/send \ + -H "Content-Type: application/json" \ + -d '{ + "token": "your_template_token", + "title": "订单通知", + "placeholders": { + "order_id": "20241206001", + "status": "已发货" + } + }' +``` + +## 查看消息 + +### 消息列表 + +1. 登录管理后台 +2. 进入"自托管消息"或"消息中心"页面 +3. 查看消息列表 + +**列表信息：** + +| 列 | 说明 | +|----|------| +| 状态 | 已读/未读标识 | +| 标题 | 消息标题 | +| 来源 | 发送任务或模板名称 | +| 接收时间 | 消息接收时间 | +| 操作 | 查看详情、标记已读、删除 | + +### 消息筛选 + +支持多种筛选条件： + +- **状态筛选** - 全部/未读/已读 +- **时间筛选** - 今天/最近7天/最近30天/自定义 +- **来源筛选** - 按任务或模板筛选 +- **关键词搜索** - 搜索标题或内容 + +**筛选示例：** + +``` +状态：未读 +时间：最近7天 +来源：订单通知模板 +关键词：发货 +``` + +### 查看详情 + +点击消息标题或"查看"按钮查看消息详情： + +**详情页面包含：** +- 消息标题 +- 发送时间 +- 来源信息 +- 消息内容（根据格式展示） +- 操作按钮（标记已读、删除） + +**内容展示：** +- **Text** - 纯文本展示 +- **HTML** - 富文本渲染 +- **Markdown** - Markdown 渲染 + +### 消息操作 + +#### 标记已读/未读 + +- **单个标记** - 点击消息的"标记已读"按钮 +- **批量标记** - 选择多条消息，点击"批量标记已读" +- **全部已读** - 点击"全部标记为已读" + +#### 删除消息 + +- **单个删除** - 点击消息的"删除"按钮 +- **批量删除** - 选择多条消息，点击"批量删除" +- **清空消息** - 点击"清空全部消息"（谨慎操作） + +::: warning 注意 +删除操作不可恢复，请谨慎操作！ +::: + +## 消息格式 + +### Text 格式 + +纯文本格式，适用于简单通知。 + +**示例：** + +```text +您的订单 20241206001 已发货。 + +快递公司：顺丰速运 +快递单号：SF1234567890 +预计送达：2024-12-08 + +如有问题请联系客服。 +``` + +**展示效果：** 保持原始换行和格式 + +### HTML 格式 + +HTML 格式，支持富文本样式。 + +**示例：** + +```html +
+

订单发货通知

+

您的订单 20241206001 已发货。

+ + + + + + + + + +
快递公司：顺丰速运
快递单号：SF1234567890
+

如有问题请联系客服。

+
+``` + +**展示效果：** 完整的 HTML 渲染，支持样式和布局 + +### Markdown 格式 + +Markdown 格式，支持格式化文本。 + +**示例：** + +```markdown +## 订单发货通知 + +您的订单 **20241206001** 已发货。 + +| 项目 | 信息 | +|------|------| +| 快递公司 | 顺丰速运 | +| 快递单号 | SF1234567890 | +| 预计送达 | 2024-12-08 | + +> 如有问题请联系客服。 +``` + +**展示效果：** Markdown 渲染，支持标题、表格、引用等 + +## 使用场景 + +### 场景 1：站内消息中心 + +**需求：** 将 Message Nest 作为网站/应用的消息中心 + +**实现方案：** + +1. 创建"用户通知"模板 +2. 添加自托管消息渠道实例 +3. 在用户操作时调用 API 发送消息到自托管渠道 +4. 用户登录 Message Nest 站点查看消息 + +**典型应用：** +- 系统公告发布 +- 账号安全提醒 +- 订单状态更新 +- 活动通知推送 + +**优势：** +- 无需开发消息中心功能 +- 直接使用 Message Nest 作为消息平台 +- 用户登录即可查看所有消息 + +### 场景 2：内部工作流通知 + +**需求：** 团队内部的工作流通知和待办事项集中管理 + +**实现方案：** + +1. 创建不同类型的通知模板（审批、任务、提醒） +2. 配置自托管消息渠道 +3. 工作流触发时发送消息到自托管渠道 +4. 团队成员登录 Message Nest 站点查看待办 + +**典型应用：** +- 审批请求通知 +- 任务分配提醒 +- 会议提醒 +- 进度更新通知 + +**优势：** +- 所有工作通知集中在一个平台 +- 团队成员统一登录查看 +- 避免消息分散在多个渠道 + +### 场景 3：系统告警记录平台 + +**需求：** 将 Message Nest 作为系统告警的集中查看平台 + +**实现方案：** + +1. 创建"系统告警"模板 +2. 配置自托管消息渠道（同时可配置钉钉/邮件用于即时通知） +3. 系统监控触发告警时发送到自托管渠道 +4. 管理员登录 Message Nest 站点查看和管理告警 + +**典型应用：** +- 服务异常告警 +- 资源使用告警 +- 安全事件告警 +- 性能告警 + +**优势：** +- 所有告警集中存储在平台 +- 便于历史告警查询和分析 +- 支持搜索和筛选功能 +- 可导出告警数据 + +### 场景 4：消息归档平台 + +**需求：** 将 Message Nest 作为所有消息的归档和查询平台 + +**实现方案：** + +1. 为所有任务/模板添加自托管消息渠道实例 +2. 所有消息都会存储在 Message Nest 站点 +3. 用户登录站点查看历史消息 +4. 定期导出归档数据 + +**典型应用：** +- 所有发送消息的完整记录 +- 消息审计和追溯 +- 历史消息查询 +- 数据分析和统计 + +**优势：** +- Message Nest 成为消息归档中心 +- 所有消息集中存储和管理 +- 支持强大的搜索和筛选 +- 便于导出和分析 + +## 消息管理 + +### 手动清理 + +可以手动清理消息以释放存储空间。 + +**清理选项：** + +- **清理已读消息** - 删除所有已读消息 +- **清理过期消息** - 删除指定天数前的消息 +- **清空全部消息** - 删除所有消息（谨慎操作） + +**步骤：** + +1. 进入"自托管消息"页面 +2. 点击"清理"按钮 +3. 选择清理选项 +4. 确认操作 +5. 等待清理完成 + +### 消息导出 + +导出消息数据用于备份或分析。 + +**导出格式：** +- CSV - 适合 Excel 分析 +- JSON - 适合程序处理 +- PDF - 适合打印存档 + +**导出步骤：** + +1. 进入"自托管消息"页面 +2. 设置筛选条件（可选） +3. 点击"导出"按钮 +4. 选择导出格式 +5. 下载导出文件 + +## 消息统计 + +查看消息的统计数据和趋势。 + +### 统计指标 + +| 指标 | 说明 | +|------|------| +| 总消息数 | 累计接收的消息总数 | +| 未读消息 | 当前未读消息数量 | +| 今日新增 | 今天接收的消息数 | +| 平均响应时间 | 从接收到已读的平均时间 | +| 消息来源分布 | 各任务/模板的消息占比 | + +### 趋势图表 + +- **消息趋势** - 最近 30 天的消息接收趋势 +- **来源分布** - 各来源的消息数量饼图 +- **已读率** - 消息已读率变化趋势 + +### 查看统计 + +1. 进入"自托管消息"页面 +2. 点击"统计"按钮 +3. 查看各项统计数据 +4. 可导出统计报表 + +## 最佳实践 + +### 1. 消息分类 + +- **按重要性分类** - 重要/一般/提示 +- **按类型分类** - 通知/告警/提醒 +- **使用不同模板** - 便于筛选和管理 + +### 2. 内容设计 + +- **标题简洁明了** - 让用户快速了解消息内容 +- **内容结构清晰** - 使用标题、列表、表格等 +- **提供操作入口** - 添加相关链接或按钮 +- **适配多种格式** - 提供 Text/HTML/Markdown + +### 3. 存储管理 + +- **定期手动清理** - 定期清理已读或过期消息，释放存储空间 +- **重要消息导出备份** - 避免数据丢失 +- **监控存储使用情况** - 及时清理不需要的消息 + +### 4. 用户体验 + +- **及时标记已读** - 保持消息列表整洁 +- **使用筛选功能** - 快速找到需要的消息 +- **定期查看消息** - 避免遗漏重要通知 +- **合理设置通知** - 避免消息过载 + +### 5. 安全性 + +- **权限控制** - 确保只有授权用户可以查看 +- **敏感信息加密** - 对敏感内容进行加密 +- **定期审计** - 检查消息访问日志 +- **数据备份** - 定期备份重要消息 + +## 与其他渠道对比 + +| 特性 | 自托管消息 | 邮件 | 钉钉/企业微信 | +|------|-----------|------|--------------| +| 实时性 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | +| 到达率 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | +| 格式支持 | Text/HTML/Markdown | Text/HTML | Text/Markdown | +| 历史查询 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | +| 成本 | 免费 | 免费/付费 | 免费 | +| 依赖 | 无 | SMTP 服务器 | 钉钉/企业微信 | +| 适用场景 | 站内通知、归档 | 正式通知、账单 | 即时通知、协作 | + +## 常见问题 + +### Q: 自托管消息和其他渠道有什么区别？ + +**A:** +- **自托管消息** - 存储在系统内，需要登录后台查看 +- **其他渠道** - 推送到外部平台（邮件、钉钉等），用户在对应平台查看 + +### Q: 可以同时使用自托管消息和其他渠道吗？ + +**A:** 可以。为任务或模板同时配置多个渠道实例，消息会发送到所有渠道。 + +### Q: 消息会永久保存吗？ + +**A:** 消息会一直保存，不会自动清理。建议定期手动清理不需要的消息，并导出重要消息备份。 + +### Q: 如何提高消息的查看率？ + +**A:** +1. 配合其他渠道（如邮件、钉钉）提醒用户 +2. 在应用中显示未读消息数量 +3. 提供消息通知功能 +4. 定期提醒用户查看 + +### Q: 消息被误删了怎么办？ + +**A:** +- 如果有备份，可以从备份恢复 +- 如果配置了其他渠道，可以从其他渠道查看 +- 建议定期导出重要消息 + +### Q: 如何在应用中集成消息中心？ + +**A:** +1. 调用 API 发送消息到自托管渠道 +2. 提供登录入口到 Message Nest 后台 +3. 或者通过 API 查询消息列表（需要开发） +4. 在应用中展示消息 + +## 注意事项 + +::: warning 重要提示 +1. **存储空间** - 消息不会自动清理，注意定期手动清理，避免占用过多存储空间 +2. **性能影响** - 大量消息可能影响查询性能，建议定期清理已读或过期消息 +3. **权限控制** - 确保消息只能被授权用户查看 +4. **数据备份** - 重要消息建议定期导出备份 +5. **手动清理** - 删除操作不可恢复，请谨慎操作 +::: + +## 下一步 + +- 查看 [渠道配置](/guide/channels) 了解如何配置自托管消息渠道 +- 查看 [消息模板](/guide/template) 了解如何创建模板 +- 查看 [V2 API 文档](/api/v2) 了解如何发送消息 diff --git a/docs/guide/self-hosted-messages.md b/docs/guide/self-hosted-messages.md new file mode 100644 index 0000000..953ac88 --- /dev/null +++ b/docs/guide/self-hosted-messages.md @@ -0,0 +1,151 @@ +# 自托管消息 + +自托管消息功能将 Message Nest 作为消息接收平台，用户登录站点查看消息。 + +## 功能概述 + +**核心定位：** 将 Message Nest 站点作为消息接收和展示平台，而不是推送到外部渠道。 + +**主要功能：** +- ✅ 站点作为消息接收平台 +- ✅ 用户登录后台查看消息 +- ✅ 搜索消息 +- ✅ 查看消息详情 + +**与其他渠道的区别：** +- **邮件/钉钉/企业微信** - 推送到外部平台，用户在对应平台查看 +- **自托管消息** - 存储在 Message Nest 站点，用户登录站点查看 + +## 配置自托管消息渠道 + +### 创建渠道 + +1. 登录管理后台 +2. 进入"推送渠道"页面 +3. 点击"新建渠道" +4. 选择渠道类型："自托管消息" +5. 填写渠道名称和描述 +6. 保存渠道 + +### 配置参数 + +| 参数 | 说明 | 必填 | +|------|------|------| +| 渠道名称 | 自定义渠道名称 | 是 | +| 渠道描述 | 渠道用途说明 | 否 | + +## 使用自托管消息 + +### 方式一：通过任务发送 + +1. 创建发送任务 +2. 添加自托管消息渠道实例 +3. 通过 V1 API 发送消息 + +**API 示例：** + +```bash +curl -X POST http://your-domain/api/v1/message/send \ + -H "Content-Type: application/json" \ + -d '{ + "token": "your_task_token", + "title": "系统通知", + "text": "您有一条新消息" + }' +``` + +### 方式二：通过模板发送（推荐） + +1. 创建消息模板 +2. 为模板添加自托管消息实例 +3. 通过 V2 API 发送消息 + +**API 示例：** + +```bash +curl -X POST http://your-domain/api/v2/message/send \ + -H "Content-Type: application/json" \ + -d '{ + "token": "your_template_token", + "title": "订单通知", + "placeholders": { + "order_id": "20241206001" + } + }' +``` + +## 查看消息 + +### 消息列表 + +1. 登录管理后台 +2. 进入"托管消息"页面 +3. 查看消息列表 + +**列表信息：** + +| 列 | 说明 | +|----|------| +| ID | 消息 ID | +| 消息标题 | 消息标题（可点击查看完整内容） | +| 消息内容 | 消息内容（可点击查看完整内容） | +| 创建时间 | 消息接收时间 | +| 详情 | 查看按钮 | + +### 搜索消息 + +在消息列表页面的搜索框中输入关键词，可以搜索消息标题和内容。 + +### 查看详情 + +点击消息行的"查看"按钮，在侧边栏中查看消息完整信息： + +- 标题 +- 内容 +- URL（如果有） +- 创建时间 +- 修改时间 + +## 使用场景 + +### 场景 1：站内消息中心 + +将 Message Nest 作为网站/应用的消息中心，用户登录站点查看消息。 + +**适用于：** +- 系统公告 +- 用户通知 +- 订单状态更新 + +### 场景 2：内部通知平台 + +团队内部的工作通知集中管理，成员登录站点查看。 + +**适用于：** +- 审批通知 +- 任务分配 +- 会议提醒 + +### 场景 3：消息归档 + +所有发送的消息都存储在站点，便于查询和追溯。 + +**适用于：** +- 消息记录 +- 审计追溯 +- 历史查询 + +## 注意事项 + +::: warning 重要提示 +1. **存储空间** - 消息不会自动清理，注意定期手动清理 +2. **查看方式** - 用户需要登录 Message Nest 站点才能查看消息 +3. **消息格式** - 支持 Text、HTML、Markdown 格式 +4. **权限控制** - 确保只有授权用户可以登录查看 +::: + +## 下一步 + +- 查看 [渠道配置](/guide/channels) 了解如何配置自托管消息渠道 +- 查看 [消息模板](/guide/template) 了解如何创建模板 +- 查看 [V2 API 文档](/api/v2) 了解如何发送消息 diff --git a/docs/guide/settings.md b/docs/guide/settings.md new file mode 100644 index 0000000..df4629c --- /dev/null +++ b/docs/guide/settings.md @@ -0,0 +1,217 @@ +# 系统设置 + +系统设置页面允许您配置 Message Nest 的各项参数，包括站点信息、日志清理、密码管理等。 + +## 站点设置 + +自定义站点的基本信息和显示参数。 + +### 配置项 + +| 设置项 | 说明 | 默认值 | +|--------|------|--------| +| 站点标题 | 显示在浏览器标题和页面顶部 | `Message Nest` | +| 站点标语 | 显示在登录页面的标语 | `消息推送整合平台` | +| 站点图标 | 网站 Logo（仅支持 SVG 文本） | 默认 Logo | +| 分页大小 | 列表页面每页显示的数据条数 | `10` | +| Cookie 过期天数 | 用户登录状态保持时间（天） | `1` | + +### 使用场景 + +- ✅ 企业内部部署，使用企业品牌 +- ✅ 个性化定制，提升用户体验 +- ✅ 统一品牌形象 + +### 配置步骤 + +1. 登录管理后台 +2. 进入"系统设置" → "站点设置" +3. 填写或修改相关信息 +4. 保存设置 +5. 下次登录时生效（如不生效，在登录页面 Ctrl+F5 强制刷新） + +::: tip 提示 +- **站点图标**：仅支持 SVG 文本格式，将替换网页 ico、登录页面 logo、导航栏 logo +- **站点标语**：将在登录页面展示 +- **Cookie 过期天数**：设置用户登录后的有效期，修改后下次登录时生效 +- **分页大小**：影响所有列表页面的显示数量 +::: + +## 重置密码 + +修改当前用户的登录密码。 + +### 配置步骤 + +1. 进入"系统设置" → "重置密码" +2. 输入当前密码 +3. 输入新密码 +4. 确认新密码 +5. 点击"确定"保存 + +::: warning 安全建议 +- 使用强密码（包含大小写字母、数字、特殊字符） +- 定期更换密码（建议 3 个月） +- 不要使用常见密码 +- 不要与其他系统使用相同密码 +::: + +## 日志清理 + +配置定时日志清除和保留策略。 + +### 配置项 + +| 设置项 | 说明 | 默认值 | +|--------|------|--------| +| 定时清除 Cron 表达式 | 定时清理日志的时间规则 | `0 1 * * *`（每天凌晨 1 点） | +| 保留日志条数 | 保留最近的日志数量 | `1000` | + +### 配置步骤 + +1. 进入"系统设置" → "日志清理" +2. 设置 Cron 表达式（可选） +3. 设置保留日志条数（可选） +4. 点击"确定"保存 +5. 点击"查看日志"可以查看清理日志 + +::: tip 提示 +- **Cron 表达式**：如果不设置，默认是在每天的 0 点 1 分进行清理 +- **保留数目**：如果不设置，默认保留最近 1000 条 +- 清理任务会自动执行，删除超出保留数量的旧日志 +::: + +### Cron 表达式示例 + +``` +0 1 * * * # 每天凌晨 1 点 +0 */6 * * * # 每 6 小时 +0 0 * * 0 # 每周日凌晨 +0 2 1 * * # 每月 1 号凌晨 2 点 +``` + +## 登录日志 + +查看系统的登录历史记录。 + +### 查看方式 + +1. 进入"系统设置" → "登录日志" +2. 查看登录记录列表 + +### 记录内容 + +- 登录时间 +- 登录 IP 地址 +- 登录状态（成功/失败） + +### 使用场景 + +- ✅ 安全审计 +- ✅ 异常登录检测 +- ✅ 用户行为分析 + +## 站点关于 + +查看系统的版本信息和运行状态。 + +### 系统信息 + +| 信息项 | 说明 | +|--------|------| +| 系统版本 | Message Nest 版本号 | +| 构建时间 | 系统构建时间 | +| 内存使用 | 当前内存使用情况 | +| 运行时间 | 系统已运行时长 | + +### 技术栈 + +- Golang +- Vue 3 +- TypeScript +- Vite +- Tailwind CSS +- Shadcn/ui + +### 功能特性 + +- 多渠道消息推送 +- 定时消息管理 +- 托管消息服务 +- 发信日志追踪 +- 渠道配置管理 +- 站点信息配置 + +### 版本日志 + +点击"查看更新日志"按钮可以查看系统的版本更新历史。 + +### 查看方式 + +1. 进入"系统设置" → "站点关于" +2. 查看系统信息和技术栈 +3. 点击"查看更新日志"查看版本历史 +4. 点击"GitHub 仓库"访问项目主页 + +## 最佳实践 + +### 1. 安全配置 + +- ✅ 使用强密码 +- ✅ 定期更换密码（建议 3 个月） +- ✅ 定期查看登录日志，检查异常登录 +- ✅ 合理设置 Cookie 过期天数 + +### 2. 日志管理 + +- ✅ 合理设置日志保留条数，避免占用过多存储空间 +- ✅ 根据业务需求调整清理时间（避开高峰期） +- ✅ 定期查看清理日志，确认清理正常执行 + +### 3. 站点配置 + +- ✅ 自定义站点标题和标语，提升品牌形象 +- ✅ 使用 SVG 格式的 Logo，保证清晰度 +- ✅ 合理设置分页大小，平衡性能和用户体验 +- ✅ 修改配置后记得刷新页面查看效果 + +## 常见问题 + +### Q: 修改站点信息后没有生效？ + +**A:** 尝试以下方法： +1. 在登录页面强制刷新（Ctrl+F5） +2. 清除浏览器缓存 +3. 检查是否保存成功 +4. 下次登录时生效 + +### Q: 忘记密码怎么办？ + +**A:** +1. 如果是 Docker 部署，可以通过环境变量重置 +2. 如果是直接运行，可以通过数据库直接修改 +3. 联系系统管理员重置 + +### Q: 日志清理任务没有执行？ + +**A:** +1. 检查 Cron 表达式是否正确 +2. 查看清理日志确认执行情况 +3. 确认系统时间是否准确 +4. 检查系统日志是否有错误信息 + +### Q: Cookie 过期天数修改后没生效？ + +**A:** +Cookie 过期天数的修改会在下次登录时生效，当前已登录的会话不受影响。 + +### Q: 如何查看系统版本？ + +**A:** +进入"系统设置" → "站点关于"，可以查看系统版本、构建时间等信息。 + +## 下一步 + +- 查看 [部署文档](/deployment/overview) 了解部署配置 +- 查看 [渠道配置](/guide/channels) 开始使用系统 +- 查看 [消息模板](/guide/template) 创建第一个模板 diff --git a/docs/guide/tasks.md b/docs/guide/tasks.md new file mode 100644 index 0000000..cc176a0 --- /dev/null +++ b/docs/guide/tasks.md @@ -0,0 +1,341 @@ +# 发送任务 + +发送任务是 Message Nest 的基础功能，用于配置消息发送的渠道和参数，通过 V1 API 发送消息。 + +::: tip 💡 推荐使用模板 +对于新项目，我们推荐使用 [消息模板](/guide/template) 功能，它提供更好的内容管理和维护体验。发送任务主要用于兼容历史数据。 +::: + +## 功能概述 + +发送任务允许您： +- ✅ 创建发送任务 +- ✅ 为任务添加推送渠道实例 +- ✅ 配置每个实例的参数 +- ✅ 获取 API Token 用于发送消息 +- ✅ 查看任务的发送日志 + +## 创建任务 + +### 步骤 + +1. 进入"发送任务"页面 +2. 点击"新增任务"按钮 +3. 输入任务名称 +4. 点击"保存" + +### 配置项 + +| 字段 | 说明 | 必填 | +|------|------|------| +| 任务名称 | 任务的唯一标识名称 | 是 | + +::: tip 提示 +任务创建后，需要添加推送实例才能发送消息。 +::: + +## 添加推送实例 + +为任务添加一个或多个推送渠道实例。 + +### 步骤 + +1. 在任务列表中点击"编辑"按钮 +2. 在搜索框中输入渠道名称 +3. 从下拉列表中选择已创建的推送渠道 +4. 配置实例参数（根据渠道类型不同） +5. 选择消息格式（Text/HTML/Markdown） +6. 点击"添加"保存实例 + +### 实例配置说明 + +不同渠道需要配置不同的参数： + +#### 邮件渠道 + +- **收件人邮箱** - 接收邮件的邮箱地址 +- **消息格式** - Text 或 HTML + +#### 钉钉/企业微信 + +- **消息格式** - Text 或 Markdown +- **@提醒** - 可选配置@手机号或@所有人 + +#### 自定义 Webhook + +- 根据 Webhook 要求配置相应参数 + +#### 自托管消息 + +- 无需额外配置 +- **消息格式** - Text、HTML 或 Markdown + +## 管理任务 + +### 查看任务列表 + +在"发送任务"页面可以看到所有任务： + +| 列 | 说明 | +|----|------| +| ID | 任务的唯一标识 | +| 发信任务名称 | 任务名称 | +| 创建时间 | 任务创建时间 | +| 更新时间 | 任务最后修改时间 | +| 操作/状态 | 操作按钮 | + +### 任务操作 + +#### 查看接口 + +1. 点击任务的"接口"按钮 +2. 查看 API Token 和调用示例 +3. 复制 Token 用于 V1 API 调用 + +#### 查看日志 + +1. 点击任务的"日志"按钮 +2. 查看该任务的发送记录 +3. 可以筛选和搜索日志 + +#### 编辑任务 + +1. 点击任务的"编辑"按钮 +2. 在弹出的对话框中管理推送实例 +3. 可以添加、删除、启用/禁用实例 + +#### 删除任务 + +1. 点击任务的"删除"按钮 +2. 确认删除操作 +3. 任务及其所有实例将被删除 + +::: warning 注意 +删除任务后，该任务的 Token 将失效，无法再使用 V1 API 发送消息。 +::: + +### 管理推送实例 + +在编辑任务对话框中可以管理推送实例： + +#### 查看实例列表 + +| 列 | 说明 | +|----|------| +| 渠道名称 | 推送渠道的名称 | +| 渠道类型 | 渠道类型（邮件、钉钉等） | +| 消息格式 | Text/HTML/Markdown | +| 状态 | 启用/禁用开关 | +| 操作 | 删除按钮 | + +#### 启用/禁用实例 + +- 点击实例行的开关按钮 +- 禁用的实例不会参与消息发送 +- 可以随时重新启用 + +#### 删除实例 + +- 点击实例行的"删除"按钮 +- 确认删除操作 +- 实例将从任务中移除 + +### 搜索任务 + +在任务列表页面的搜索框中输入任务名称，可以快速筛选任务。 + +## 使用任务发送消息 + +### 通过 API 调用 + +使用 V1 API 发送消息，详见 [V1 API 文档](/api/v1)。 + +**基本示例：** + +```bash +curl -X POST http://your-domain/api/v1/message/send \ + -H "Content-Type: application/json" \ + -d '{ + "token": "your_task_token", + "title": "消息标题", + "text": "消息内容" + }' +``` + +### 多格式发送 + +可以同时提供多种格式，系统会根据实例配置自动选择： + +```json +{ + "token": "your_task_token", + "title": "订单通知", + "text": "您的订单已发货", + "html": "

订单通知

您的订单已发货

", + "markdown": "## 订单通知\n\n您的订单已发货" +} +``` + +### @提醒功能 + +对于支持的渠道（钉钉、企业微信），可以使用@提醒： + +```json +{ + "token": "your_task_token", + "title": "系统告警", + "text": "服务器CPU使用率过高", + "at_mobiles": ["13800138000"], + "at_all": false +} +``` + +## 工作流程 + +```mermaid +graph LR + A[创建任务] --> B[添加推送实例] + B --> C[配置实例参数] + C --> D[获取 Token] + D --> E[调用 API] + E --> F[系统遍历实例] + F --> G[发送到各渠道] + G --> H[记录日志] +``` + +## 使用场景 + +### 场景 1：多渠道通知 + +创建一个任务，配置多个推送实例（邮件 + 钉钉 + 企业微信），一次 API 调用同时推送到所有渠道。 + +**适用于：** +- 重要系统告警 +- 关键业务通知 +- 需要多渠道触达的消息 + +### 场景 2：不同环境隔离 + +为开发、测试、生产环境创建不同的任务，使用不同的渠道配置。 + +**适用于：** +- 环境隔离 +- 测试验证 +- 灰度发布 + +### 场景 3：按用途分类 + +为不同用途创建不同的任务（如：用户通知、系统告警、营销推广），便于管理和统计。 + +**适用于：** +- 消息分类管理 +- 统计分析 +- 权限控制 + +## 最佳实践 + +### 1. 任务命名 + +使用清晰的命名规范： +- ✅ `生产-用户通知-邮件钉钉` +- ✅ `测试-系统告警-企业微信` +- ❌ `任务1`、`test` + +### 2. 实例配置 + +- **合理选择渠道** - 根据消息重要性和紧急程度选择合适的渠道 +- **配置备用渠道** - 为重要消息配置多个渠道，提高送达率 +- **格式适配** - 为不同渠道提供合适的消息格式 + +### 3. Token 管理 + +- **安全存储** - 不要在代码中硬编码 Token，使用环境变量或配置文件 +- **定期轮换** - 定期更新 Token，提高安全性 +- **权限控制** - 不同环境使用不同的 Token + +### 4. 日志监控 + +- **定期查看** - 定期检查发送日志，及时发现问题 +- **失败处理** - 对发送失败的消息进行重试或告警 +- **统计分析** - 分析发送数据，优化渠道配置 + +### 5. 性能优化 + +- **异步调用** - 使用异步方式调用 API，避免阻塞主流程 +- **批量发送** - 对于大量消息，考虑批量发送或限流 +- **错误重试** - 实现合理的重试机制 + +## 常见问题 + +### Q: 任务和模板有什么区别？ + +**A:** +- **任务（V1 API）**：内容在 API 调用时传递，适合完全动态的内容 +- **模板（V2 API）**：内容预定义在模板中，通过占位符替换，推荐使用 + +详见 [V1 API 文档](/api/v1) 中的对比说明。 + +### Q: 可以为一个任务配置多个实例吗？ + +**A:** 可以。一个任务可以配置多个推送实例，API 调用时会自动遍历所有启用的实例进行发送。 + +### Q: 如何知道消息是否发送成功？ + +**A:** +1. API 响应会返回发送状态 +2. 在任务的日志页面查看详细的发送记录 +3. 可以配置自托管消息渠道，在后台查看消息 + +### Q: Token 泄露了怎么办？ + +**A:** +1. 立即删除该任务（Token 将失效） +2. 创建新的任务获取新的 Token +3. 更新使用该 Token 的所有代码 + +### Q: 发送失败如何处理？ + +**A:** +1. 查看日志中的错误信息 +2. 检查渠道配置是否正确 +3. 确认渠道服务是否正常 +4. 检查消息内容是否符合渠道要求 +5. 实现重试机制 + +## 迁移到模板 + +如果您正在使用发送任务，我们建议迁移到消息模板： + +### 迁移步骤 + +1. **创建模板** + - 根据现有任务的消息内容创建模板 + - 定义占位符替换动态内容 + +2. **配置实例** + - 将任务的推送实例配置复制到模板 + +3. **更新代码** + - 将 V1 API 调用改为 V2 API + - 使用模板 Token 和占位符参数 + +4. **测试验证** + - 测试新的模板发送是否正常 + - 对比新旧方式的效果 + +5. **切换上线** + - 逐步切换到模板方式 + - 保留旧任务一段时间作为备用 + +### 迁移优势 + +- ✅ 内容统一管理，便于维护 +- ✅ 修改内容无需改代码 +- ✅ 支持版本控制和灰度发布 +- ✅ 更好的团队协作体验 + +## 下一步 + +- 查看 [推送渠道配置](/guide/channels) 了解如何配置渠道 +- 查看 [消息模板](/guide/template) 了解推荐的使用方式 +- 查看 [V1 API 文档](/api/v1) 了解 API 调用方法 diff --git a/docs/index.md b/docs/index.md index 6018457..97333a4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -48,39 +48,3 @@ features: title: 数据统计 details: 支持数据统计展示，查看消息发送情况。 --- - - diff --git a/web/src/components/pages/messageTemplate/MessageTemplate.vue b/web/src/components/pages/messageTemplate/MessageTemplate.vue index 16e4cfa..d5718a5 100644 --- a/web/src/components/pages/messageTemplate/MessageTemplate.vue +++ b/web/src/components/pages/messageTemplate/MessageTemplate.vue @@ -184,7 +184,7 @@ onMounted(async () => {