📦 Tel-Agent 项目部署教程

Tel-Agent 是一个开源的 AI 电话助理网关，它能够将电话线路（通过 SIP 协议）与任何 AI 模型连接起来。你可以用它来接听电话，根据规则转接给人工、拦截或交由 AI 代理处理，AI 还能调用工具（如转接、查日历、调用 HTTP 接口）。所有通话都会被录音、转录并支持搜索。该项目由维也纳的 Dpro GmbH 维护。

⚠️ 部署前的重要提醒

项目状态：Pre-alpha（前期开发阶段），目前尚不可用。

根据项目官方 README 的明确说明，Tel-Agent 目前 没有可安装的正式版本，正处在 Milestone 0 的开发中（目标是先让一个简单的网页对话能够端到端工作）。电话功能是最后才实现的部分（Milestone 11）。

因此，本教程旨在帮助你在当前状态下搭建开发环境以预览或参与贡献，而不是部署一个生产可用的 AI 电话助理。

💻 开发环境快速启动 (Docker)

这是项目官方提供的唯一“快速启动”方式，用于在当前阶段运行开发中的代码。

1. 前提条件

已安装 Docker 和 Docker Compose。
API 密钥：你需要准备好至少一个 STT（语音转文本）、一个 LLM（大语言模型） 和一个 TTS（文本转语音） 云服务商的 API 密钥（例如 Deepgram, OpenAI, ElevenLabs）。本地模型支持将在 v1.1 版本后提供。

2. 克隆并配置

1
2
3

git clone https://github.com/Dpro-at/Tel-Agent.git
cd Tel-Agent
cp .env.example .env

重要：打开 .env 文件，设置一个 ENCRYPTION_KEY（用于加密 API 密钥）：

1 2	# 使用命令生成一个安全的密钥 openssl rand -hex 32

将生成的密钥填入 ENCRYPTION_KEY 字段。

3. 构建并启动服务

1	docker compose up -d --build

此命令会构建并启动后端 API、前端界面和数据库等容器。

4. 访问与首次设置

前端界面：打开浏览器访问 http://localhost:38471。
后端 API 文档：访问 http://localhost:38472/docs 查看自动生成的 API 交互文档。
首次运行：访问前端页面后，系统会引导你完成安装向导，包括：
1. 设置管理员账户（没有默认凭证）。
2. 配置你选择的 AI 模型提供商及对应的 API 密钥。
数据默认存储在名为 tel-agent-data 的 Docker 卷中（使用 SQLite）。

注意：这两个端口默认只绑定在 127.0.0.1（loopback），即只能从本机访问。如需外部访问，请通过 .env 文件中的 TEL_AGENT_* 相关变量进行配置，并强烈建议在前面放置一个终止 TLS 的反向代理。

🛠️ 无 Docker 手动运行（供开发者）

如果你想直接运行 Python 代码进行开发或调试（无需每次重建镜像），项目也支持手动运行。

前提条件：
- Python 3.11+ 和 pip
- Node.js 18+ 和 npm（用于前端）
- 安装并配置好 PostgreSQL 和 Redis（或使用 SQLite 进行轻量测试）

克隆并设置后端：

git clone https://github.com/Dpro-at/Tel-Agent.git
cd Tel-Agent
cp .env.example .env
# 编辑 .env，设置 ENCRYPTION_KEY 和数据库连接等

# 创建虚拟环境并安装依赖
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .           # 以可编辑模式安装项目

运行后端 API：
1
python -m api
后端服务将启动。
设置并运行前端（在另一个终端中）：
1
2
3
cd web
npm install
npm run dev
前端开发服务器将启动，通常监听 http://localhost:3000。

🏗️ 架构与设计要点

了解其架构有助于更好地部署和使用：

核心组件：后端 API (Python + FastAPI)、前端 (Next.js + React)、数据库 (PostgreSQL/SQLite)、缓存/队列 (Redis)、反向代理 (Caddy)。
语音流水线：Deepgram (STT) → 云端 LLM → ElevenLabs (TTS)。所有流都采用流式传输，目标延迟低于 800 毫秒。
电话集成：通过 SIP 协议与现有的 PBX（如 3CX、Asterisk）对接。不支持直接模拟线路，需通过 ATA（如 Grandstream HT801）转换。
安全设计：
- API 密钥在数据库中加密存储（使用 ENCRYPTION_KEY）。
- 默认端口监听在 loopback，不直接暴露。
- 首次启动强制设置管理员密码（无默认凭据）。
- 默认开启通话录音声明，以符合相关法律（如奥地利法律）。

❗ 重要事项总结与未来展望

不要用于生产：当前版本仅为开发预览，功能不完整且不稳定。
功能路线图：项目规划了从 Milestone 0 到 11 共 12 个阶段，电话功能在最后。当前目标仅是让一个网页对话能工作。完整路线图请查阅项目内的 docs/ROADMAP.md。
参与贡献：如果你有兴趣贡献，请阅读 CONTRIBUTING.md（贡献者需签署 CLA）和 docs/ONBOARDING.md（新手上手指南）。对于使用 AI 编程助手的开发者，请阅读 AGENTS.md。
许可协议：项目采用 AGPL-3.0 许可证。如果你将修改后的版本作为网络服务运行，必须公开你的修改。如需闭源集成，可联系 Dpro GmbH 获取商业许可。