boos
5d29f03d50
- Moved boosapi-rs/* to repo root - Deleted all Node.js source (src/server/, src/web/, scripts/) - Deleted node_modules, package.json, tsconfig, vite.config - Updated .gitignore and AGENTS.md for Rust-only stack - Fixed static file path for frontend dist/web/ - Dockerfile stays the same (already Rust-only) - Kept dist/web/ for Rust static serving
165 lines
5.5 KiB
Markdown
165 lines
5.5 KiB
Markdown
# 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 镜像拉取超时，需排查网络 |
|