# 部署通知配置指南

本文档说明如何配置 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 数据库

```bash
# SSH 到 Gitea 服务器
ssh doc79

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

#### 3.2 插入 Secrets

```sql
-- 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 验证配置

```sql
-- 查看所有 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 分支触发部署：

```bash
# 测试后端部署通知
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 配置**
   ```sql
   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`，修改通知步骤的消息内容：

```yaml
.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 双渠道通知