开发者指南 · 01

架构概览

text

┌──────────────────────────────────────────────────────────────────┐
│                        客户端 / 用户                              │
│  ┌──────────────┐ ┌────────────┐ ┌─────────┐ ┌────────────────┐ │
│  │  Admin SPA   │ │  Service   │ │ WeChat  │ │ Tauri 桌面 App │ │
│  │  React 19    │ │ /s/{sid}   │ │ /wc/.. │ │ (Rust + WV)    │ │
│  └──────┬───────┘ └─────┬──────┘ └────┬────┘ └────────┬───────┘ │
└─────────┼───────────────┼─────────────┼───────────────┼─────────┘
          │ /api/*        │ /api/v1/*   │ iLink         │ launcher.py
          ▼               ▼             ▼               ▼
┌──────────────────────────────────────────────────────────────────┐
│  Nginx (:80) — SSL 终止 + 反向代理                                │
│  → Express (:3000) — 静态资源 (dist/) + /api 代理                 │
│  → FastAPI (:8000) — 核心后端                                      │
├──────────────────────────────────────────────────────────────────┤
│  FastAPI Application (app/)                                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│  │ routes/  │ │ services/│ │ channels/│ │ storage/ │ │ voice/ │ │
│  │ 路由层   │ │ 业务层   │ │ 渠道层   │ │ 存储抽象 │ │ S2S WS │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │
│       └─────┬──────┴───────┬────┘            │           │      │
│             ▼              ▼                  ▼           ▼      │
│  ┌─────────────────────────────┐  ┌──────────────────┐ ┌──────┐ │
│  │  deepagents + LangGraph     │  │  Local FS / S3   │ │ S2S  │ │
│  │  Agent 运行引擎 + AsyncSqlite│  │  + AES key 加密   │ │ Proxy│ │
│  └─────────────────────────────┘  └──────────────────┘ └──────┘ │
└──────────────────────────────────────────────────────────────────┘

外部协议：
  • WeChat iLink Bot：app/channels/wechat/ ⇄ ilinkai.weixin.qq.com
  • OpenAI Realtime：app/voice/router.py ⇄ wss://api.openai.com/.../realtime
  • CloudsWay / Tavily：app/services/web_tools.py（联网搜索）

分层设计

层	职责	目录
路由层	HTTP 请求处理、参数校验、SSE 流	`app/routes/`
业务层	Agent 创建/缓存、工具、对话、调度、收件箱、订阅	`app/services/`
渠道层	WeChat iLink 协议（Service 与 Admin 双栈）	`app/channels/wechat/`
存储层	Local / S3 文件存储抽象	`app/storage/`
核心层	认证、配置、路径安全、加密、Langfuse	`app/core/`
语音层	S2S WebSocket 代理（OpenAI Realtime）	`app/voice/`

三大运行环境

环境	入口	用途
本机开发	`python launcher.py --dev` 或 `uvicorn` + `vite dev`	开发，热重载
Docker 部署	`docker compose up -d --build`	服务器/团队部署
桌面 App	`tauri-launcher/` 编译为 `.dmg` / `.exe`	终端用户一键启动

下一篇技术栈→