feat: Phase 5-6 - Proxy Conductor, Token Router, Services, Dockerfile

- Proxy Conductor: retry/fallback/auth-refresh orchestration loop - Token Router: exact/wildcard/regex model routing with channel selection - Services: Cron scheduler, OAuth token refresh, Update center, Announcements - User routes: profile + API key management - DB queries module - Dockerfile: multi-stage build - Proxy routes integrated with Conductor + TokenRouter
2026-05-18 03:00:09 +08:00
parent 78d46eeddb
commit 56391f2193
75 changed files with 7428 additions and 464 deletions
@@ -0,0 +1,164 @@
+# 2026-05-15 技术报告 / Technical Report
+
+## Executive Summary
+
+本日完成 BoosAPI 品牌迁移、ComfyUI Agent 对话助手开发、Gitea CI/CD Runner 部署、Notification Service 能力梳理及部署文档重写。核心变更包括：将项目内 `Metapi` 全局替换为 `BoosAPI`，新增 `/comfyui-agent` 对话式 AI 视频生成入口，完成 SSE streaming 前后端链路，并完善生产部署文档与通知服务说明。
+
+---
+
+## 1. Metapi → BoosAPI 全局改名 / Global Rename
+
+### 1.1 变更范围 / Change Scope
+
+| 区域 / Area | 变更内容 / Changes |
+|---|---|
+| UI 界面 / UI | About 页面、侧边栏、登录页品牌名更新为 `BoosAPI` |
+| i18n 翻译 / Internationalization | 所有语言文件中的 `Metapi` 替换为 `BoosAPI` |
+| 后端通知 / Backend Notification | `notifyService.ts` 通知前缀由 `[metapi]` 改为 `[BoosAPI]` |
+| 桌面元数据 / Desktop Metadata | Electron / Docker 描述信息更新 |
+
+### 1.2 已完成的技术标识替换 / Completed Technical Identifier Changes
+
+| 项目 / Item | 变更说明 / Description |
+|---|---|
+| HTTP Header | `x-metapi-*` → `x-boosapi-*` |
+| 推理签名前缀 / Inference Signature Prefix | `metapi:` → `boosapi:` |
+| 运行时属性 / Runtime Properties | `__metapiTruncated` 等 → `__boosapi*` |
+| 环境变量 / Environment Variables | `METAPI_*` → `BOOSAPI_*` |
+| Package Name | `package.json` 中 `name` 更新为 `boosapi` |
+
+### 1.3 验证方式 / Verification
+
+```bash
+grep -rn '[mM]etapi' src/ --include='*.ts' --include='*.tsx' --include='*.html' \
+  | grep -v '.test.' | grep -v node_modules | grep -iv 'boosapi'
+```
+
+预期结果：无输出。
+
+---
+
+## 2. ComfyUI Agent 对话助手 / Conversational Assistant
+
+### 2.1 功能概述 / Feature Overview
+
+侧边栏新增「对话助手」入口，路由为 `/comfyui-agent`，提供与 AI 视频生成助手的对话式交互，支持文本、角色提示词、图像、场景、语音和 ComfyUI workflow 等多类型内容的流式渲染。
+
+### 2.2 技术架构 / Architecture
+
+```
+用户 / User → POST /api/comfyui-agent/chat → BoosAPI → LLM 本地 API (streaming)
+                                                         → SSE 事件流 → BoosAPI 转发 → 浏览器
+```
+
+### 2.3 后端实现 / Backend
+
+| 文件 / File | 作用 / Responsibility |
+|---|---|
+| `src/server/routes/api/comfyuiAgent.ts` | SSE 流式聊天接口，调用本地 LLM API |
+| `src/server/services/boosapi_comfy_nodes.py` | ComfyUI 自定义节点，默认连接 `http://127.0.0.1:4000/v1` |
+
+### 2.4 前端实现 / Frontend
+
+| 文件 / File | 作用 / Responsibility |
+|---|---|
+| `src/web/pages/ComfyUIAgent.tsx` | 对话界面组件，SSE 流式渲染 |
+| `src/web/App.tsx` | 注册 `/comfyui-agent` 路由及侧边栏入口 |
+
+### 2.5 SSE 事件类型 / SSE Event Types
+
+| `type` | 含义 / Meaning | 前端渲染 / Rendering |
+|---|---|---|
+| `text` | 流式文本 | 追加到对话内容 |
+| `character_prompts` | 四角度角色提示词 | 角色卡片 |
+| `image` | 生成的角色图像 | 内联图片 |
+| `scene` | 场景提示词 | 场景块 |
+| `tts` | 语音音频 | 音频播放器 |
+| `comfyui_workflow` | 完整 ComfyUI 工作流 JSON | 下载按钮 |
+| `done` | 流结束 | 停止等待 |
+
+### 2.6 验证结果 / Verification
+
+| 命令 | 结果 |
+|---|---|
+| `npm install` | ✅ |
+| `npm run typecheck:web` | ✅ 0 error |
+
+---
+
+## 3. Gitea CI/CD Runner 部署 / Runner Deployment
+
+### 3.1 部署信息 / Deployment Info
+
+| 项目 | 详情 |
+|---|---|
+| 系统 | Alpine Linux, OpenRC |
+| 部署方式 | 裸机直跑，无 DinD |
+| Runner 版本 | v0.1.3 |
+| 注册模式 | `:host` 标签 |
+| OpenRC 服务 | `/etc/init.d/gitea-runner` |
+| 代理 | `HTTP_PROXY=http://127.0.0.1:7890` |
+| `NO_PROXY` | 包含 `git.boos.lat` |
+| 持久化 | `ephemeral: false` |
+
+### 3.2 已知限制 / Known Limitations
+
+- 不支持 Docker in Docker；CI 使用 `runs-on: host`
+- 无原生 artifact 存储；构建产物需手动备份
+- `actions/checkout` 偶发 timeout；可重试或使用本地 git 镜像
+
+---
+
+## 4. Notification Service
+
+### 4.1 支持通道 / Supported Channels
+
+| 通道 | 配置前缀 | 协议 |
+|---|---|---|
+| Telegram | `telegram*` | Bot API |
+| 企业微信 | `wecom*` | Webhook |
+| 飞书 | `feishu*` | Webhook |
+| 通用 Webhook | `webhook*` | JSON POST |
+| Bark | `bark*` | HTTP, iOS |
+| Server酱 | `serverchan*` | HTTP |
+| SMTP | `smtp*` | Email |
+
+### 4.2 Telegram 消息格式
+
+- 纯文本，不启用 HTML/Markdown 解析
+- 单条最大 3900 字符，超长截断 + `...(truncated)`
+- 支持 Telegram Topics（`message_thread_id`）
+
+### 4.3 节流机制 / Throttling
+
+- 基于通知签名的全局冷静期：`notifyCooldownSec`
+- 同一签名在冷静期内重复触发时合并为一次
+- 冷静期为全局共享，不按通道独立
+
+---
+
+## 5. 部署文档完善 / Deployment Documentation
+
+Commit: `5bd847d`
+
+对 `docs/deployment.md` 全量重写，修复所有 `metapi` 残留：
+
+- 完整 `docker-compose.yml` 示例（含 healthcheck）
+- `.env` 变量插值模式
+- 全部环境变量参考表（20+ 变量）
+- 扩展配置：外部 MySQL/PostgreSQL、Redis、资源限制
+- 生产部署检查清单
+- Nginx 反向代理（WebSocket + SSE）
+- 管理后台 IP 白名单限制示例
+- Docker run 常用选项表
+- 升级/回滚操作流程
+
+---
+
+## 6. 待办事项 / TODO
+
+| 优先级 | 事项 | 说明 |
+|---|---|---|
+| High | 服务未运行 | CI 崩溃后容器未恢复，需确定 Docker vs `npm run dev` |
+| Medium | Telegram 格式优化 | 待确认 HTML/Markdown/简化 |
+| Medium | CI pipeline 稳定性 | Docker 镜像拉取超时，需排查网络 |