从单体 Python 到双 Go 微服务的架构演进，构建高并发、低延迟的数字人交互后端

---

一、项目背景

沐光而行 是一款基于 Live2D 的 AI 数字人交互平台，核心能力包括语音识别（ASR）、智能对话（Agent）、语音合成（TTS）三大管线，前身为纯 Python（FastAPI）架构。

随着用户增长和实时交互场景的复杂化，原有架构暴露出三个核心瓶颈：

• 并发瓶颈：Python 异步虽有改善，但面对 WebSocket 长连接场景，CPU 密集的协议解析成为阻力
• 耦合严重：ASR、TTS、Agent 逻辑与 HTTP 服务深度耦合，难以独立扩展
• 协议匮乏：仅有简单的 HTTP REST 接口，无法支撑语音流式的实时双向通信

为此启动了 双 Go 后端重构工程，在保留 Python 核心引擎的同时，用 Go 重建了代理网关层和 WebSocket 实时服务层。

---

二、新架构总览

                        ┌──────────────────────────────────┐
                        │         Web 前端 (Next.js)         │
                        │   Live2D 渲染 / embed.js 组件      │
                        └─────┬──────────────┬──────────────┘
                              │ HTTP/SSE     │ WebSocket
                              ▼              ▼
              ┌───────────────────┐  ┌──────────────────────────┐
              │  Go 网关层 (8880)  │  │  Go WS 服务 (8881)        │
              │  digital-human-   │  │  awesome-digital-human    │
              │  server           │  │                          │
              │                   │  │  • WebSocket 文本/二进制   │
              │  • HTTP路由+中间件  │  │  • 沉浸模式 (逐句TTS)     │
              │  • Agent SSE推理   │  │  • 会话管理+心跳          │
              │  • 安全层(认证限流)  │  │  • 打断机制              │
              │  • 静态资源服务     │  │  • SSE 兼容端点          │
              └────────┬──────────┘  └──────────────────────────┘
                       │ 反向代理
                       ▼
              ┌──────────────────────────┐
              │  Python 核心引擎 (8881)    │
              │  _internal/digitalHuman/ │
              │                          │
              │  • TTS 语音合成引擎        │
              │  • ASR 语音识别引擎        │
              │  • LLM 语言模型引擎        │
              └──────────────────────────┘

职责分离原则：

层级	职责	技术栈
网关层	路由分发、安全中间件、Agent SSE 推理、静态服务	Go + net/http
实时层	WebSocket 连接管理、语音管线、沉浸模式、会话状态	Go + gorilla/websocket
引擎层	TTS 合成、ASR 识别、LLM 推理	Python + 各类 SDK

---

三、数据协议体系设计

3.1 SSE 事件流协议（Agent 推理）

event: CONVERSATION_ID
data: conv_abc123

event: EXPRESSION
data: {"type":"smile","confidence":0.9,"duration":2}

event: MOTION
data: {"type":"nod","repeat":1}

event: TEXT
data: 你好！很高兴见到你。

event: THINK
data: 用户很热情，我应该友好回应

event: DONE
data: 

设计要点：

• 语义事件分离：文本、思考、表情、动作各自独立事件，前端可按需订阅渲染
• 中文情感映射：内建 91 个中文情感关键词 → 6 种表情（微笑/生气/伤心/惊讶/害羞/冷漠）
• 动作关键词检测：支持 20 种 Live2D 动作（点头、摇头、鞠躬、挥手等）

3.2 WebSocket 统一协议

文本模式 — JSON 协议：

{
  "type": "text",
  "data": {
    "content": "你好",
    "conversation_id": "conv_abc123",
    "mode": "immersive"
  }
}

二进制模式 — 语音管线协议：

┌──────────────┬──────────────┬──────────────────┐
│  Action(18B) │ Size(4B/BE)  │  Payload (变长)   │
└──────────────┴──────────────┴──────────────────┘

Action 类型：ENGINE_START → ASR_DATA → ASR_RESULT → TTS_RESULT → ENGINE_END

3.3 沉浸模式（Immersive Mode）

核心创新：逐句 TTS 流式推送，Agent 输出不等待全文结束，而是按句子边界实时切分、即时合成，实现接近真人对话的延迟体验：

Agent 流:  "今天天气真好" [句边界] → 立即 TTS → 推送音频
           "非常适合出去玩" [句边界] → 立即 TTS → 推送音频
           "你打算去哪里呢？" [完结] → 立即 TTS → 推送音频

---

四、多智能体引擎系统

支持 5 种 AI 后端，通过 YAML 配置热切换：

引擎	协议	配置项
Repeater	回声复读	无（测试用）
OpenAI	/v1/chat/completions	model, base_url, api_key
Dify	/chat-messages (streaming)	api_server, api_key
Coze	/v3/chat (SSE)	token, bot_id
FastGPT	/v1/chat/completions	base_url, api_key

Agent 注册中心采用单例模式，启动时自动扫描 _internal/configs/agents/ 目录下的 YAML 文件完成注册，运行时可通过 HTTP API 动态查询引擎列表和参数。

// 注册中心接口
type Registry struct {
    agents   map[string]Agent
    default_ string
}

func (r *Registry) Run(ctx context.Context, input TextMessage) (<-chan SSEEvent, error)
func (r *Registry) List() []AgentInfo
func (r *Registry) GetDefault() AgentInfo

---

五、安全中间件体系

通过 security.yaml 统一配置三层安全防护：

token: ""                    # Bearer Token 认证，留空不启用
allow_origins: ["*"]         # CORS 白名单
rate_limit: 0                # 每 IP 每分钟请求数，0=不限流

中间件链：

请求 → RateLimiter(令牌桶) → CORS(Origin白名单) → Auth(Bearer Token) → 业务处理

• 限流器：令牌桶算法，per-IP 计数，每分钟清理过期桶
• CORS：支持精确 Origin 匹配和通配符 *
• 鉴权：可选的 Bearer Token，空 token 自动跳过

---

六、前端交互体系

6.1 嵌入式组件（embed.js v2.0）

<script src="embed.js"></script>
<script>
window.sentioConfig = {
  baseUrl: 'http://localhost:8880',
  appId: 'my-app',
  draggable: true,
  dragAxis: 'y',
  notification: { initial: '在吗？', interval: 30000 }
};
</script>

一行脚本即可将数字人气泡嵌入任意网站，支持：

• 拖拽浮动气泡按钮（脉冲动画 + 涟漪效果）
• iframe 窗口加载数字人界面
• 通知徽标、ESC 关闭
• 暴露 window.sentioAPI = { open, close, toggle, setBadge, destroy }

6.2 Web UI（Next.js SSR 导出）

基于 Next.js App Router，静态导出为纯 HTML/JS/CSS，由 Go 后端直接托管。通过 overrides.css 注入定制化 UI 美化（353 行 CSS），覆盖滚动条、聚焦环、按钮、输入框、卡片动画等全局样式。

---

七、技术亮点总结

维度	技术选型	收益
并发模型	Go goroutine + channel	单机万级 WebSocket 并发
协议设计	SSE + WS 二元协议	覆盖文本/语音全场景
流式体验	沉浸模式逐句 TTS	延迟从秒级降至毫秒级
引擎扩展	插件式 Agent 注册	新增引擎零代码改动
安全防护	中间件链	认证/限流/CORS 可插拔
前端集成	embed.js 零依赖	一行脚本嵌入任意网站
会话管理	Pipeline 状态机 + 心跳	长时间对话不丢状态

---

八、运行方式

# 一线启动
双击 启动服务器.bat

# 或手动
digital_human.exe    # Python 引擎层 (端口 8881)
server.exe           # Go 网关层 (端口 8880)

---

重构工程的核心理念：用 Go 的高并发能力承载连接和协议，用 Python 的生态优势保留核心引擎，以清晰的协议边界实现分层解耦。这使得沐光而行数字人在保持原有能力的同时，获得了面向生产环境的稳定性、可扩展性和实时交互体验。