Miuda.ai

基础配置

本章节帮助你从零搭建一套可用的 RustPBX 实例，包括环境要求、安装、初始化配置与基础验证。所有步骤均以中文说明，方便交付与培训。

1. 前置条件

  • 运行环境：推荐 4C/8G 以上的 x86_64 Linux（Debian/Ubuntu/CentOS 均可）。
  • 依赖：Docker 或 Podman（容器部署），或已安装 Rust toolchain（裸机编译），以及 SQLite/PostgreSQL（按照 Cargo.toml 中的 feature 选择）。
  • 网络：服务器需要固定公网 IP，开放 SIP/HTTPS/诊断端口，并将运营商或 SBC 的 IP 加入安全组。
  • 证书：若启用 WebRTC/HTTPS，需要准备 TLS 证书，可由 addons acme 自动签发。
Topology

2. 安装方式

2.1 商用镜像部署（推荐）

  1. 准备 config.toml 与 config/ 目录（详见下一节）。
  2. 拉取官方镜像：
    • docker pull ghcr.io/restsend/rustpbx:latest
    • 或从商用仓库拉取：docker pull docker.cnb.cool/miuda.ai/rustpbx:latest
  3. 启动示例：
docker run -d --name rustpbx \
	-v $(pwd)/config.toml:/app/config.toml \
	-v $(pwd)/config:/app/config \
	-v $(pwd)/rustpbx.sqlite3:/app/rustpbx.sqlite3 \
	-p 8080:8080 -p 5060:5060/udp -p 12000-42000:12000-42000/udp \
	ghcr.io/restsend/rustpbx:latest
  1. 在 Compose/Kubernetes 中同样引用该镜像，并将配置与数据库挂载为持久卷；日志默认写到 stdout/stderr，便于集中收集。

2.2 裸机部署

  1. 安装 Rust（rustup default stable）。
  2. 在项目根执行 cargo build --release，可得到 target/release/rustpbx。
  3. 将二进制放入 /usr/local/bin，配合 systemd/supervisor 启动。

2.3 命令行选项

参数说明
--conf <PATH>配置文件路径（TOML 格式）
--super-username <NAME>创建或更新控制台超级用户（需配合 --super-password）
--super-password <PASS>超级用户密码
--super-email <EMAIL>超级用户邮箱（默认为 username@localhost）
--skip-migrate跳过数据库迁移（适用于只读副本）
--tokio-console <ADDR>启动 tokio-console 服务器进行异步任务调试

子命令

命令说明
check-config验证配置文件并退出，不启动服务器
# 部署前验证配置
rustpbx --conf config.toml check-config

# 创建管理员用户后退出
rustpbx --conf config.toml --super-username admin --super-password changeme

# 跳过数据库迁移（如只读副本）
rustpbx --conf config.toml --skip-migrate

3. 初始化配置

RustPBX 的运行参数主要来自 config.toml 与 config/ 子目录：

  1. config.toml：全局服务段（[proxy]、[ua]、[console]、[recording]、[callrecord]、[sipflow]、[rwi]、[rwi_webhook]、[cluster]、[storage] 等）以及插件启停；建议先填写监听地址（http_addr、proxy.addr）、鉴权方式（proxy.user_backends、console.allow_registration）与日志级别（log_level、log_file、log_rotation）。
  2. Trunk 文件：在 config/trunks/ 下按模板新增 *.toml，包含 uri、auth、codec 等字段。
  3. Routing 文件：在 config/routes/ 中定义入站/出站匹配规则，并指向分机、队列或 Trunk。
  4. Queue/ACL：如需排队和安全策略，分别在 config/queue/、config/acl/ 中准备对应文件。
  5. 数据库迁移：启动时自动初始化 models/ 中定义的表结构。使用 --skip-migrate 可跳过此步骤。

3.1 端口范围

# RTP 媒体代理端口范围（默认：12000–42000）
rtp_start_port = 12000
rtp_end_port = 42000

# WebRTC 媒体端口范围（默认：30000–40000）
webrtc_start_port = 30000
webrtc_end_port = 40000

请在防火墙上放通这些端口范围，媒体代理会在范围内自动选择可用端口。

3.2 日志与轮转

log_level = "info"
log_file = "/var/log/rustpbx/app.log"
log_rotation = "daily"   # "never"（默认）、"hourly" 或 "daily"

启用日志轮转后，日志文件会在每个轮转周期结束时归档为带时间戳的文件。

3.3 SIP JWT 认证

RustPBX 支持通过 JWT 令牌实现快速的 SIP 注册——分机无需提供 SIP 密码，通过在 SIP 头中携带签名 JWT 即可完成注册：

[proxy.jwt_auth]
enabled = true
secret = "your-jwt-secret-key"
user_id_claim = "userId"          # 包含分机号的 JWT claim
issuer = "auth.example.com"       # 可选：要求特定签发者
audience = "rustpbx"              # 可选：要求特定接收方
sip_header_name = "X-Auth-Token"  # 携带 JWT 的 SIP 头名称
check_local_user = false          # 是否同时校验本地数据库
ws_token_param = "token"          # WebSocket 的 URL 查询参数名
dev_mint_enabled = false          # 开发环境令牌签发端点（生产环境请关闭）

启用后，携带 X-Auth-Token: <jwt> 的 INVITE/REGISTER 请求将直接通过 JWT claims 完成认证，不会发送 Digest 质询。

3.4 紧急号码路由

[proxy.emergency]
enabled = true
numbers = ["110", "119", "120", "122", "911", "999"]
emergency_trunk = "emergency-carrier"

拨打列表中的紧急号码时，呼叫将直接路由到指定的 emergency_trunk，跳过常规路由规则。

3.5 对象存储（录音、CDR、SipFlow）

[storage]
type = "s3"               # "local"（默认）、"s3"、"azure"、"gcp"
[storage.s3]
vendor = "minio"          # "aws"、"minio"、"aliyun"、"cos"
bucket = "rustpbx-recordings"
region = "us-east-1"
access_key = "AKIA..."
secret_key = "..."
endpoint = "https://s3.example.com"
root = "recordings/"

[storage] 段配置录音上传、CDR 归档和 SipFlow 卸载所需的对象存储，配置一次即可被 [recording]、[callrecord] 和 [sipflow] 共享。

0.5 版本的两点增强：

  • 匿名 S3：公有桶或内网共享桶可省略 access_key/secret_key。
  • Presigned 下载：使用 S3 兼容存储时,录音与 SipFlow 下载改为通过 presigned GET URL 提供(有效期有上限),不再经由控制台代理转发。

3.6 队列与语音信箱的全局默认音频

[proxy]
queue_hold_music = "sounds/hold-music.wav"     # 队列默认等待音
voicemail_greeting = "sounds/greeting.wav"     # 语音信箱默认问候音

两者均可选:队列自身的 [proxy.queues.<name>.hold].audio_file 或应用层传入的 greeting_path 仍然优先生效。有了全局默认,就不必在每个队列上重复配置同一段提示音。

rustpbx/
├── 📁 config/
│   ├── 📁 trunks/      → SIP Trunk 配置
│   ├── 📁 routes/      → 入站/出站路由规则
│   ├── 📁 queue/       → 队列定义
│   ├── 📁 ivr/         → IVR 流程定义
│   ├── 📁 acl/         → 访问控制/IP 策略
│   ├── 📁 recorders/   → 录音配置
│   ├── 📁 sounds/      → 音频提示和音效
│   ├── 📁 cdr/         → 通话详单
│   ├── 📁 voicemail/   → 语音信箱配置
│   ├── 📁 models/      → 语音模型（VAD、ASR、降噪）
│   ├── 📁 cc/          → 呼叫中心技能组配置
│   └── 📁 sipflow/     → SipFlow 捕获存储
└── 📄 config.toml      → 主配置文件
ConfigStructure

4. 启动与首个登录

  1. 启动服务：
    • 容器模式：docker run ... 如上所示。
    • 裸机模式：/static/docs-zh/rustpbx/rustpbx --conf config.toml
    • 首次创建管理员：/static/docs-zh/rustpbx/rustpbx --conf config.toml --super-username admin --super-password changeme
  2. 访问控制台（默认 http://<host>:8082/console/）。
  3. 使用管理员账号登录，建议立即修改密码。
  4. 检查控制台状态页面确保所有组件显示正常。

5. 快速验证清单

  1. 创建测试 Trunk：录入运营商或软交换的测试线路。
  2. 添加路由：为测试号段配置 inbound/outbound 路由，动作指向一个临时分机。
  3. 注册软终端：在「分机管理」中创建分机，并在软电话/SIP 设备上完成注册。
  4. 发起测试呼叫：验证主叫与被叫均能建立通话，录音与 CDR 正常生成。
  5. 执行 Reload：通过控制台 Settings → Reload，使配置立即生效，并在 Diagnostics → Routing 运行一次 Evaluate，确认命中的规则与输出的 Trunk。

完成以上步骤后，系统即可承载初始业务流量。更深入的线路策略、计费和诊断方法请参见后续章节。