feat: 实现公告板功能

- 后端：从 GitHub Issues API 获取公告数据 - 支持筛选指定 assignees 的评论 - 支持排除指定 issue 的评论 - 从评论第一行提取标题（移除 Markdown 格式） - 支持获取 reactions 数据（+1、heart、laugh 等） - 实现 10 分钟缓存机制 - 强制刷新时，如果被限流则保留缓存数据 - 添加 GitHub API 健康检查 - 前端：公告列表和详情页面 - 响应式设计（移动端和桌面端） - 移动端使用侧边抽屉显示列表 - 支持 Markdown 渲染 - 支持内容折叠（超过 30 行） - 显示 reactions（使用 emoji） - 添加刷新按钮（支持强制刷新） - 公告菜单项放在第一位 - 默认页面改为公告页 - 其他： - 更新 favicon 为 SVG 格式 - 添加 GitHub API 限流方案文档 - 添加 GitHub Token 配置文档
2025-12-07 16:15:59 +08:00
parent 89e3c726b2
commit 07d1b50b9b
20 changed files with 3535 additions and 14 deletions
@@ -0,0 +1,298 @@
+# GitHub Token 获取和配置指南
+
+## 📋 概述
+
+GitHub Personal Access Token (PAT) 用于提高 API 限流容量：
+- **未认证**：60 次/小时
+- **使用 Token**：5,000 次/小时（REST API）或 5,000 点/小时（GraphQL API）
+
+---
+
+## 🔑 获取 GitHub Token
+
+### 方法 1：通过 GitHub 网站创建（推荐）
+
+#### 步骤 1：登录 GitHub
+1. 访问 [GitHub](https://github.com)
+2. 登录您的账户
+
+#### 步骤 2：进入开发者设置
+1. 点击右上角头像
+2. 选择 **Settings**（设置）
+3. 在左侧菜单中，滚动到底部
+4. 点击 **Developer settings**（开发者设置）
+
+#### 步骤 3：创建 Personal Access Token
+1. 在左侧菜单中，点击 **Personal access tokens**
+2. 选择 **Tokens (classic)** 或 **Fine-grained tokens**
+
+**推荐使用 Fine-grained tokens（更安全）：**
+- 点击 **Generate new token** → **Generate new token (fine-grained)**
+- 填写 Token 名称（如：`PolyHermes Announcements API`）
+- 设置过期时间（建议：90 天或自定义）
+- 选择资源所有者（Repository access）：
+  - 如果公告在您的仓库：选择 **Only select repositories**，然后选择 `WrBug/PolyHermes`
+  - 如果公告在公共仓库：选择 **Public repositories (read-only)**
+- 设置权限（Repository permissions）：
+  - **Metadata**: Read（必需）
+  - **Contents**: Read（如果需要读取 Issue 内容）
+  - **Issues**: Read（必需，用于读取 Issue 和评论）
+- 点击 **Generate token**
+
+**或使用 Classic tokens（更简单）：**
+- 点击 **Generate new token (classic)**
+- 填写 Token 名称（如：`PolyHermes Announcements API`）
+- 设置过期时间
+- 选择权限（Scopes）：
+  - ✅ **public_repo**（读取公共仓库的 Issue 和评论）
+  - 如果仓库是私有的，需要选择 **repo**
+- 点击 **Generate token**
+
+#### 步骤 4：复制并保存 Token
+⚠️ **重要**：Token 只会显示一次，请立即复制并保存到安全的地方！
+
+```
+ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+---
+
+### 方法 2：通过 GitHub CLI 创建
+
+如果您安装了 GitHub CLI (`gh`)，可以使用命令行创建：
+
+```bash
+# 登录 GitHub CLI
+gh auth login
+
+# 创建 Token
+gh auth token
+```
+
+---
+
+## 🔐 所需权限说明
+
+### Fine-grained Token 权限
+- **Metadata**: Read（必需，读取仓库基本信息）
+- **Contents**: Read（可选，读取仓库内容）
+- **Issues**: Read（必需，读取 Issue 和评论）
+
+### Classic Token 权限
+- **public_repo**（公共仓库）
+- **repo**（私有仓库，如果需要）
+
+---
+
+## ⚙️ 在项目中使用 Token
+
+### 方式 1：环境变量（推荐）
+
+#### 1. 在配置文件中添加 Token 配置
+
+编辑 `backend/src/main/resources/application.properties`：
+
+```properties
+# GitHub 配置（用于公告功能）
+github.repo.owner=WrBug
+github.repo.name=PolyHermes
+github.announcement.issue.number=1
+github.token=${GITHUB_TOKEN:}  # 从环境变量读取，如果未设置则为空
+```
+
+#### 2. 设置环境变量
+
+**Linux/macOS：**
+```bash
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+**Windows (PowerShell)：**
+```powershell
+$env:GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+**Windows (CMD)：**
+```cmd
+set GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+#### 3. 在 Docker 中使用
+
+在 `docker-compose.yml` 或启动命令中添加：
+```yaml
+environment:
+  - GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+或在启动命令中：
+```bash
+docker run -e GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ...
+```
+
+---
+
+### 方式 2：直接配置（不推荐，仅用于测试）
+
+⚠️ **不推荐**：Token 会暴露在配置文件中，存在安全风险。
+
+编辑 `backend/src/main/resources/application.properties`：
+
+```properties
+github.token=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+---
+
+## 💻 代码实现
+
+### 更新 RetrofitFactory
+
+在 `RetrofitFactory.kt` 中添加 Token 支持：
+
+```kotlin
+fun createGitHubApi(): GitHubApi {
+    val baseUrl = "https://api.github.com"
+    
+    // 从配置读取 Token
+    val githubToken = githubToken  // 从 @Value 注入
+    
+    // 添加拦截器
+    val githubInterceptor = object : Interceptor {
+        override fun intercept(chain: Interceptor.Chain): Response {
+            val requestBuilder = chain.request().newBuilder()
+                .header("Accept", "application/vnd.github+json")
+            
+            // 如果配置了 Token，添加认证头
+            if (githubToken.isNotBlank()) {
+                requestBuilder.header("Authorization", "Bearer $githubToken")
+            }
+            
+            return chain.proceed(requestBuilder.build())
+        }
+    }
+    
+    val okHttpClient = createClient()
+        .addInterceptor(githubInterceptor)
+        .build()
+    
+    // ... 其余代码
+}
+```
+
+---
+
+## 🔒 安全注意事项
+
+### 1. Token 存储
+- ✅ **推荐**：使用环境变量存储 Token
+- ✅ **推荐**：使用密钥管理服务（如 AWS Secrets Manager、HashiCorp Vault）
+- ❌ **禁止**：将 Token 提交到 Git 仓库
+- ❌ **禁止**：在日志中输出 Token
+
+### 2. Token 权限
+- ✅ **最小权限原则**：只授予必要的权限
+- ✅ **定期轮换**：建议每 90 天更新一次 Token
+- ✅ **监控使用**：定期检查 Token 的使用情况
+
+### 3. 配置文件
+- ✅ 将 `application.properties` 添加到 `.gitignore`（如果包含 Token）
+- ✅ 使用 `application-local.properties` 存储本地配置
+- ✅ 使用环境变量覆盖配置
+
+---
+
+## 🧪 测试 Token
+
+### 使用 curl 测试
+
+```bash
+# 测试 REST API
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+     -H "Accept: application/vnd.github+json" \
+     https://api.github.com/repos/WrBug/PolyHermes/issues/1
+
+# 测试 GraphQL API
+curl -X POST \
+     -H "Authorization: Bearer YOUR_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"query": "query { viewer { login } }"}' \
+     https://api.github.com/graphql
+```
+
+### 检查限流
+
+响应头中包含限流信息：
+```
+X-RateLimit-Limit: 5000
+X-RateLimit-Remaining: 4999
+X-RateLimit-Used: 1
+X-RateLimit-Reset: 1701964800
+```
+
+---
+
+## 📝 完整配置示例
+
+### application.properties
+```properties
+# GitHub 配置（用于公告功能）
+github.repo.owner=WrBug
+github.repo.name=PolyHermes
+github.announcement.issue.number=1
+github.token=${GITHUB_TOKEN:}  # 从环境变量读取
+```
+
+### .env 文件（用于本地开发）
+```env
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### docker-compose.yml
+```yaml
+services:
+  backend:
+    environment:
+      - GITHUB_TOKEN=${GITHUB_TOKEN}
+```
+
+---
+
+## 🚨 常见问题
+
+### Q1: Token 过期了怎么办？
+**A:** 重新生成新的 Token，更新环境变量或配置文件。
+
+### Q2: Token 泄露了怎么办？
+**A:** 立即在 GitHub 设置中删除该 Token，然后生成新 Token。
+
+### Q3: 如何查看 Token 的使用情况？
+**A:** 在 GitHub Settings → Developer settings → Personal access tokens 中查看 Token 的最后使用时间。
+
+### Q4: 可以使用 GitHub App 吗？
+**A:** 可以，GitHub App 的限流更高（组织应用 10,000 点/小时），但实现更复杂。
+
+### Q5: Token 需要哪些权限？
+**A:** 对于公共仓库，只需要 `public_repo` 权限；对于私有仓库，需要 `repo` 权限。
+
+---
+
+## 📚 参考链接
+
+- [GitHub Personal Access Tokens 文档](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
+- [GitHub API 认证文档](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api)
+- [GitHub API 限流文档](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting)
+
+---
+
+## ✅ 检查清单
+
+- [ ] 已创建 GitHub Personal Access Token
+- [ ] Token 已保存到安全的地方
+- [ ] 已在环境变量中配置 Token
+- [ ] 已更新 `application.properties` 配置
+- [ ] 已更新代码支持 Token 认证
+- [ ] 已测试 Token 是否生效
+- [ ] 已检查限流是否提升（从 60 → 5,000）
+- [ ] 已将 Token 相关配置添加到 `.gitignore`
+