TEN Framework Voice Assistant SIP Plivo Server：独立 HTTP 服务架构与实战部署指南-育师

人工智能
AI Agent
多模态
语音
AI 应用

【免费下载链接】ten-framework

Open-source framework for conversational voice AI agents

项目地址：https://gitcode.com/TEN-framework/ten-framework

导读

本文围绕 TEN-framework 仓库中ai_agents/agents/examples/voice-assistant-sip-plivo/server/下的独立 Plivo 服务器展开，讲解一个从main_python扩展迁移而来的、无框架依赖的 FastAPI 服务：它负责 Plivo 电话的配置加载、健康检查与 tenapp 子进程生命周期管理，而 WebSocket 音频流与 STT→LLM→TTS 语音对话管线仍由 tenapp 内的main_python扩展承载。读完本文，你将掌握该服务器的环境变量配置、启动方式、HTTP 接口语义、进程管理原理，以及它与完整 voice-assistant-sip-plivo 示例（前端、ngrok、TMAN Designer）的协作关系。

一、服务器定位：职责分离的“配置与进程管家”

server/目录是 voice-assistant-sip-plivo 示例中一个独立可运行的 FastAPI 应用。值得注意：其 README.md 标题写作 "Voice Assistant SIP Twilio Server"，属模板复制遗留，实际集成对象是Plivo（Twilio 的竞品服务商），源码与依赖均以 Plivo 为准。

该服务器的核心设计是职责分离：

HTTP 管理面：由本服务器（FastAPI + uvicorn）提供 REST API，负责配置下发、健康检查、tenapp 进程拉起与监控；
媒体面：WebSocket 音频流、呼叫应答 XML（/webhook/answer）、状态回调（/webhook/status）等实时语音逻辑，全部由 tenapp 应用（main_python扩展）处理，对应实现位于 tenapp/ten_packages/extension/main_python/server.py。

从源码看，PlivoServer类在start_server()中先启动 tenapp 子进程（执行./scripts/start.sh），随后才监听自身端口；一旦 tenapp 进程退出，监控线程会主动向自身发送SIGTERM关闭整个服务器（见 plivo_server.py）。因此，本服务器实际上承担了"轻量级进程管理器 + 配置服务"的双重角色。

二、安装与依赖

服务器为纯 Python 实现，依赖集中在 requirements.txt：

依赖	用途
`fastapi`	REST API 框架
`uvicorn[standard]`	ASGI 服务器
`plivo`	Plivo REST 客户端（本服务器仅用于配置透传）
`pydantic`	配置模型校验（`PlivoServerConfig`继承`BaseModel`）

说明：requirements.txt 特意注明 WebSocket 与音频处理（audioop）不属于本服务器职责，前者由main_python扩展处理，后者是 Python 标准库，无需额外安装。

在完整示例中，安装通过 Taskfile 编排（Taskfile.yml）：

cd ai_agents/agents/examples/voice-assistant-sip-plivo task install

该命令依次执行tman install（安装 tenapp 依赖）、./scripts/install_python_deps.sh（安装 Python 依赖）、bun install（安装前端依赖）。若仅需本服务器，可直接在server/目录下用 pip 安装上述依赖。

三、配置：环境变量与命令行参数

3.1 环境变量

服务器通过环境变量加载配置，全部定义在PlivoServerConfig（plivo_server.py）中：

环境变量	默认值	说明
`PLIVO_AUTH_ID`	空字符串	Plivo Auth ID（必填）
`PLIVO_AUTH_TOKEN`	空字符串	Plivo Auth Token（必填）
`PLIVO_FROM_NUMBER`	空字符串	发起外呼的 Plivo 号码（必填）
`PLIVO_HTTP_PORT`	`8080`	本服务器监听端口（进程管理面）
`PLIVO_PUBLIC_SERVER_URL`	空字符串	无协议公网地址（如`your-domain.com:9000`），同时用于媒体流与 webhook；本地调试用 ngrok 暴露
`PLIVO_USE_HTTPS`	`false`	webhook 使用 HTTPS 或 HTTP
`PLIVO_USE_WSS`	`false`	媒体流使用 WSS 或 WS

设置示例：

export PLIVO_AUTH_ID="your_plivo_auth_id" export PLIVO_AUTH_TOKEN="your_plivo_auth_token" export PLIVO_FROM_NUMBER="+1234567890" export PLIVO_HTTP_PORT="8080" export PLIVO_PUBLIC_SERVER_URL="your-domain.com:9000" export PLIVO_USE_HTTPS="true" export PLIVO_USE_WSS="true"

注意：PLIVO_USE_HTTPS/PLIVO_USE_WSS的解析逻辑为os.getenv(..., "false").lower() == "true"，即只有显式设置为字符串"true"才启用，其余值一律视为false。

3.2 命令行参数

通过 main.py 提供的 argparse 入口，可以覆盖两个关键配置：

参数	默认值	说明
`--tenapp-dir`	空（回退为`server/../tenapp`）	tenapp 应用目录，用于定位启动脚本
`--port`	`8080`	覆盖`PLIVO_HTTP_PORT`，指定服务器监听端口

命令行参数优先级高于环境变量：load_config()中以args.port覆盖PLIVO_HTTP_PORT，以args.tenapp_dir覆盖默认路径（main.py）。

四、启动服务器

4.1 启动方式

# 方式一：通过 Taskfile（推荐，位于示例根目录） cd ai_agents/agents/examples/voice-assistant-sip-plivo task run-api-server # 等价于：python3 main.py --tenapp-dir ../tenapp # 方式二：直接运行 cd ai_agents/agents/examples/voice-assistant-sip-plivo/server python3 main.py # 方式三：指定 tenapp 目录与端口 python3 main.py --tenapp-dir /path/to/tenapp --port 9000

4.2 启动时序与生命周期

从PlivoServer.start_server()（plivo_server.py）可还原完整启动流程：

解析配置（环境变量 + CLI 参数）；
_start_tenapp_process()在 tenapp 目录下执行./scripts/start.sh（该脚本设置PYTHONPATH、LD_LIBRARY_PATH、NODE_PATH后 execbin/main，见 tenapp/scripts/start.sh），并以os.setsid创建独立进程组；
启动守护线程_monitor_tenapp_process()，每秒轮询 tenapp 进程状态；
等待 2 秒后，以 uvicorn 启动 FastAPI 应用；
若 tenapp 进程意外退出，守护线程记录退出码并向自身发送SIGTERM触发整体关闭；
关闭时_stop_tenapp_process()向进程组发送SIGTERM，10 秒内未退出则升级为SIGKILL强制结束。

main()中还注册了SIGINT/SIGTERM信号处理器（plivo_server.py），保证 Ctrl+C 或系统终止信号下能优雅清理子进程。

4.3 日志

入口main.py使用logging.basicConfig，同时输出到标准输出与/tmp/plivo_server.log；
PlivoServer内部使用logging.getLogger("plivo_process_manager")，格式为%(asctime)s - %(name)s - %(levelname)s - %(message)s；
tenapp 子进程的 stdout/stderr 直接透传到父进程控制台，便于统一观察。

五、HTTP API 端点

PlivoServer仅注册两个端点（plivo_server.py），与 README 描述的"调用管理"语义略有差异，这里以源码为准：

方法	路径	说明
`GET`	`/health`	健康检查，返回`{"status": "healthy", "server_time": "<ISO时间>"}`
`GET`	`/api/config`	返回服务器与 tenapp 配置，供前端展示

/api/config的返回结构包含：plivo_from_number、server_port、tenapp_port（默认 9000，可从PLIVO_PUBLIC_SERVER_URL中冒号后的端口解析出来）、tenapp_url、public_server_url、use_https/use_wss，以及按协议拼接好的media_ws_url（wss://<url>/media）和webhook_url（https://<url>/webhook/status）。

注意：真正的外呼、查询、挂断、应答与状态回调接口并不在本服务器上，而是在 tenapp 内main_python扩展的 server.py 中，其端口为 tenapp 的 9000：

# 发起外呼（tenapp 9000 端口） curl -X POST http://localhost:9000/api/call \ -H "Content-Type: application/json" \ -d '{"phone_number": "+1234567890", "message": "Hello from AI assistant!"}' # 查询单个呼叫 curl http://localhost:9000/api/call/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # 列出所有呼叫 curl http://localhost:9000/api/calls # 停止呼叫 curl -X DELETE http://localhost:9000/api/call/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

tenapp 侧完整的 REST 端点还包括POST /webhook/answer（返回 Plivo XML 应答）与POST /webhook/status（状态回调）。

六、与完整示例的协作关系

本服务器是 voice-assistant-sip-plivo 示例的一个组件，完整运行task run会同时拉起四个进程（Taskfile.yml）：

组件	端口	职责
tenapp（`main_python`扩展）	9000	呼叫控制、WebSocket 媒体流、STT/LLM/TTS 对话管线
本服务器（Plivo Configuration Server）	8080	tenapp 进程管理、配置下发、健康检查
前端（frontend）	3000	Web 控制界面
TMAN Designer	49483	可视化修改 tenapp 图配置
ngrok	动态公网地址	将本地服务暴露为`PLIVO_PUBLIC_SERVER_URL`

Plivo 侧的 webhook 与媒体流 URL 通过环境变量PLIVO_PUBLIC_SERVER_URL统一注入：tenapp 内的PlivoCallServer会根据plivo_use_https/plivo_use_wss组装answer_url、status_url与 WebSocket 地址（见 server.py）。tenapp 的完整图配置（STT=deepgram、LLM=openai、TTS=elevenlabs、main_control=main_python 等节点）位于 tenapp/property.json，其中main_control节点的plivo_server_port: 9000正是上面提到的 tenapp 端口。

七、与原代码的差异与设计要点

README 总结了该服务器从main_python扩展迁移后的五点改进：

独立运行：完全独立，无外部框架依赖，可脱离 TEN runtime 单独启动；
配置管理：以环境变量驱动配置，便于容器化与多环境部署；
日志系统：采用 Python 标准logging，同时落盘/tmp/plivo_server.log；
模块化设计：PlivoServerConfig（配置模型）、PlivoServer（服务器与进程管理）、main.py（CLI 入口）职责清晰；
关注点分离：WebSocket 与音频处理留在main_python扩展，本服务器只做 HTTP 管理面。

这种"管理面独立、媒体面留在扩展"的拆分，使开发者可以复用 TEN 框架的实时语音管线，同时用轻量 FastAPI 服务处理 Plivo 账号配置、健康探测与进程守护，是 SIP 类语音助手落地时常见的部署形态。

八、注意事项

确保 Plivo 账号的PLIVO_AUTH_ID、PLIVO_AUTH_TOKEN、PLIVO_FROM_NUMBER配置正确，否则外呼创建会失败；
PLIVO_PUBLIC_SERVER_URL必须为 Plivo 可达的公网地址，本地调试请配合 start-with-ngrok.sh 暴露服务，并将 ngrok 域名填入该环境变量；
防火墙需放行本服务器端口（默认 8080）、tenapp 端口（9000）以及前端端口（3000）；
本服务器只提供 HTTP 管理面端点，呼叫的应答、状态回调与媒体流全部由main_python扩展处理，排查问题时请同时查看 tenapp 子进程的控制台输出。