lunar-mini/.gitea/docs/DEPLOY_NOTIFICATIONS.md

部署通知配置指南

本文档说明如何配置 Gitea Actions 的部署通知功能，支持 Telegram 和 Discord 双渠道通知。

功能说明

• ✅ 自动触发：部署成功或失败时自动发送通知
• ✅ 双渠道：同时支持 Telegram 和 Discord
• ✅ 详细信息：包含仓库、分支、提交、作者、工作流等信息
• ✅ 失败容错：通知发送失败不会影响部署流程

配置步骤

1. Telegram Bot 配置

1.1 创建 Telegram Bot

1. 在 Telegram 中搜索 @BotFather
2. 发送 /newbot 创建新机器人
3. 按提示设置机器人名称和用户名
4. 获得 Bot Token，格式类似：123456789:ABCdefGHIjklMNOpqrsTUVwxyz

1.2 获取 Chat ID

方法 1：通过 Bot API

1. 将你的 Bot 添加到目标群组或频道
2. 发送任意消息给 Bot
3. 访问：https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
4. 在返回的 JSON 中找到 chat.id

方法 2：使用第三方 Bot

1. 添加 @userinfobot 到你的群组
2. 它会自动显示 Chat ID

2. Discord Webhook 配置

1. 打开 Discord 服务器设置
2. 进入 集成 → Webhook
3. 点击 新建 Webhook
4. 设置名称和头像（可选）
5. 选择目标频道
6. 复制 Webhook URL，格式类似：

   https://discord.com/api/webhooks/123456789/abcdefghijklmnopqrstuvwxyz
   

3. 配置 Gitea Secrets

由于 Gitea Actions API 在该实例不可用，需要直接写入 MySQL 数据库。

3.1 连接到 Gitea 数据库

# SSH 到 Gitea 服务器
ssh doc79

# 连接 MySQL（根据实际情况调整）
mysql -u gitea -p gitea

3.2 插入 Secrets

-- Telegram Bot Token
INSERT INTO action_variable (owner_id, repo_id, name, data, created_unix, updated_unix)
VALUES (0, 0, 'TELEGRAM_BOT_TOKEN', '你的Bot Token', UNIX_TIMESTAMP(), UNIX_TIMESTAMP());

-- Telegram Chat ID
INSERT INTO action_variable (owner_id, repo_id, name, data, created_unix, updated_unix)
VALUES (0, 0, 'TELEGRAM_CHAT_ID', '你的Chat ID', UNIX_TIMESTAMP(), UNIX_TIMESTAMP());

-- Discord Webhook URL
INSERT INTO action_variable (owner_id, repo_id, name, data, created_unix, updated_unix)
VALUES (0, 0, 'DISCORD_WEBHOOK_URL', '你的Webhook URL', UNIX_TIMESTAMP(), UNIX_TIMESTAMP());

注意：

• owner_id=0 表示全局变量，所有仓库可用
• 如果只想对特定仓库生效，需要查询该仓库的 repo_id 并替换

3.3 验证配置

-- 查看所有 Actions 变量
SELECT id, owner_id, repo_id, name, LEFT(data, 20) as data_preview 
FROM action_variable 
WHERE name IN ('TELEGRAM_BOT_TOKEN', 'TELEGRAM_CHAT_ID', 'DISCORD_WEBHOOK_URL');

4. 测试通知

配置完成后，推送代码到 main 分支触发部署：

# 测试后端部署通知
git add server/
git commit -m "test: 测试部署通知"
git push origin main

# 测试小程序部署通知
git add mini/
git commit -m "test: 测试小程序通知"
git push origin main

通知示例

Telegram 通知

✅ 后端服务部署成功

状态: 成功
仓库: gouki/lunar
分支: main
提交: abc1234
作者: gouki
工作流: Build and Deploy Server #42

部署包已保存到: /opt/lunar/ci-artifacts/server-deploy-latest.tar.gz

查看详情

Discord 通知

Discord 会显示一个嵌入消息卡片，包含：

• 标题和状态图标
• 仓库、分支、提交、作者信息
• 部署详情
• 时间戳
• 可点击的链接跳转到 Actions 页面

故障排查

通知未发送

1. 检查 Secrets 配置

   SELECT * FROM action_variable WHERE name LIKE '%TELEGRAM%' OR name LIKE '%DISCORD%';
   

2. 查看 Actions 日志

   • 在 Gitea 网页界面查看 Actions 运行日志
   • 查找 "发送 Telegram 通知" 或 "发送 Discord 通知" 相关输出

3. 检查网络连接

   • 确保运行器可以访问 api.telegram.org 和 discord.com
   • 你的运行器在海外，理论上没有问题

Telegram 通知失败

• Bot Token 错误：检查 Token 是否正确
• Chat ID 错误：确保 Bot 已加入群组/频道，且 Chat ID 正确
• 权限问题：确保 Bot 有发送消息的权限

Discord 通知失败

• Webhook URL 错误：检查 URL 是否完整
• Webhook 被删除：重新创建 Webhook
• 频道权限：确保 Webhook 有权限在目标频道发送消息

高级配置

自定义通知内容

编辑 .gitea/workflows/server-deploy.yml 或 .gitea/workflows/miniapp-preview.yml，修改通知步骤的消息内容：

.gitea/scripts/notify.sh success \
  "自定义标题" \
  "自定义消息内容"

只使用单一渠道

如果只想使用 Telegram 或 Discord 之一，只需配置对应的 Secrets 即可。脚本会自动跳过未配置的渠道。

添加更多通知渠道

可以扩展 .gitea/scripts/notify.sh 脚本，添加其他通知渠道（如 Slack、钉钉、企业微信等）。

安全建议

1. 保护 Secrets：不要将 Bot Token、Chat ID、Webhook URL 提交到代码仓库
2. 定期轮换：定期更换 Bot Token 和 Webhook URL
3. 权限最小化：Telegram Bot 只授予发送消息权限，Discord Webhook 只用于特定频道
4. 监控异常：如果发现异常通知，立即检查 Secrets 是否泄露

相关文件

• 通知脚本：.gitea/scripts/notify.sh
• 后端部署工作流：.gitea/workflows/server-deploy.yml
• 小程序部署工作流：.gitea/workflows/miniapp-preview.yml

更新日志

• 2026-08-07: 初始版本，支持 Telegram 和 Discord 双渠道通知