1164 lines
42 KiB
Markdown
1164 lines
42 KiB
Markdown
# LisgloSIPS V2 项目设计与实施文档
|
||
|
||
> 中文名：聆界SIP管理平台
|
||
> 文档版本：V2.0
|
||
> 编制日期：2026-06-20
|
||
> 文档状态：实施基线草案
|
||
> 依据：服务器架构图、`SOFTSWITCH_PLATFORM_DESIGN_V1.md`、当前 React Web Demo、`OPENSIPS_INSTALL_NOTES.md`
|
||
|
||
## 1. 文档目的
|
||
|
||
V2 的目标是把当前纯前端原型转化为可部署、可联调、可上线的软交换运营平台。本文不仅描述产品功能，还给出服务器部署、软件安装、后端代码、OpenSIPS/RTPEngine 对接、数据库、Redis、录音迁移、测试和上线方案。
|
||
|
||
本文作为下一阶段执行基线，后续数据库 DDL、OpenAPI、OpenSIPS 脚本和部署脚本应从本文拆分并版本化管理。
|
||
|
||
## 2. V2 范围
|
||
|
||
### 2.1 本期实施页面
|
||
|
||
以下菜单已在 Web Demo 中完成交互设计，纳入 V2 后端和联调范围：
|
||
|
||
| 菜单 | V2 实施内容 |
|
||
| --- | --- |
|
||
| 概览 Dashboard | 通话、接通率、消费、成本、毛利、注册、节点、异常网关、质检指标 |
|
||
| 客户管理 | 客户新增、编辑、启停、余额、授信、充值、网关数量 |
|
||
| 客户网关管理 | IP/SIP 注册认证、启停、多个策略、优先级、主被叫匹配、线路组绑定 |
|
||
| 充值记录 | 客户充值、供应商充值、余额前后值、操作人、备注 |
|
||
| 供应商管理 | 供应商账户、余额、授信、充值 |
|
||
| 落地网关管理 | 认证、并发、CPS、禁呼时段、编码、号码转换、计费周期、费率、启停 |
|
||
| 落地线路组 | 线路组、组内网关、优先级、并发汇总 |
|
||
| 话单中心 | 话单查询、挂断原因、费用、录音、信令入口、详情 |
|
||
| 质检中心 | 抽检规则、录音列表、连续播放、自动播放、问题标注、评分 |
|
||
| 用户管理 | 用户新增、编辑、启停、重置密码、角色绑定 |
|
||
| 角色与权限 | 角色、权限矩阵、角色用户数、内置角色保护 |
|
||
| 操作日志 | 条件查询、结果、详情、导出 |
|
||
|
||
### 2.2 延期页面
|
||
|
||
以下菜单在 Web Demo 中标记为“待设计”，本期不开发其业务页面：
|
||
|
||
- 费率与计费
|
||
- SIP 运维
|
||
- 监控告警
|
||
- 系统设置
|
||
|
||
说明：页面延期不代表底层能力完全取消。V2 仍需实现：
|
||
|
||
- 最小计费引擎，用于生成话单客户费用、成本费用并更新余额。
|
||
- Prometheus/Grafana 基础设施监控，但不接入自研“监控告警”页面。
|
||
- OpenSIPS/RTPEngine 配置文件和环境变量管理，但不开放自研“系统设置”页面。
|
||
- HOMER 信令查询入口，但不开发自研“SIP 运维”页面。
|
||
|
||
### 2.3 明确不做
|
||
|
||
- 客户自助门户。
|
||
- 多 OpenSIPS 节点和通话级高可用。
|
||
- 完整账单、发票、对账和复杂费率管理页面。
|
||
- 自研可视化 SIP Trace、监控告警和系统配置页面。
|
||
- Kubernetes。双机阶段使用 systemd、Nginx 和 Docker Compose 的有限组合。
|
||
|
||
## 3. 总体架构
|
||
|
||
### 3.1 服务器规划
|
||
|
||
环境分为两个阶段：
|
||
|
||
- 当前开发阶段：A、B、T 均为本地 KVM 虚拟机，通过 Tailscale 专网联调。
|
||
- 开发完成后：将 A、B 部署到阿里云，按下表建立 VPC、公网入口和安全组；T 保留为外部 SIP 测试端。
|
||
|
||
下表为最终阿里云生产目标，不代表当前本地开发机已经位于阿里云：
|
||
|
||
| 服务器 | 规格 | 定位 | 公网暴露 |
|
||
| --- | --- | --- | --- |
|
||
| Server A | 阿里云计算型 4C8G | 核心通信网关 | SIP `15060/UDP`、RTP UDP 端口段 |
|
||
| Server B | 阿里云通用型 4C16G | 业务、缓存、数据库、录音、监控中心 | `443/TCP`，可选 `80/TCP` 跳转 HTTPS |
|
||
|
||
两台服务器必须位于同一 VPC、同一可用区或低时延可用区，使用私网 IP 通信。目标私网 RTT 小于 1 ms。
|
||
|
||
本地开发阶段的实测网络、端口矩阵和未来阿里云安全组清单见 `docs/infra-check.md`。
|
||
|
||
### 3.2 逻辑拓扑
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
UA["客户 SIP / 上游线路"] -->|"SIP 15060/UDP"| OS["Server A: OpenSIPS"]
|
||
UA <-->|"RTP UDP 端口段"| RTP["Server A: RTPEngine"]
|
||
OS <-->|"call-time Redis 查询"| REDIS["Server B: Redis"]
|
||
OS -->|"Redis Stream: CDR"| REDIS
|
||
OS -->|"HEP/9060 私网"| HEP["Server B: Heplify-server + HOMER"]
|
||
RTP --> TMP["Server A: /dev/shm/voip_rec"]
|
||
WORKER["Server B: Recording Worker"] -->|"私网拉取 ready 文件"| TMP
|
||
WORKER --> SSD["Server B: 录音数据盘"]
|
||
API["Server B: LisgloSIPS API"] --> MYSQL["Server B: MySQL"]
|
||
API --> REDIS
|
||
CDRW["Server B: CDR/Billing Worker"] --> REDIS
|
||
CDRW --> MYSQL
|
||
WEB["React Web + Nginx"] --> API
|
||
EXPORTER["Server A: Exporters"] --> PROM["Server B: Prometheus + Grafana"]
|
||
```
|
||
|
||
### 3.3 Server A 职责
|
||
|
||
- OpenSIPS：SIP 鉴权、客户识别、策略匹配、路由、Dialog/CDR 事件。
|
||
- RTPEngine：媒体锚定、NAT 穿透、双向录音、内核态转发。
|
||
- `/dev/shm/voip_rec`：3 GiB tmpfs 录音缓冲区。
|
||
- HEP 发送端：向 Server B 发送信令镜像。
|
||
- Node Exporter 和自定义 textfile 指标。
|
||
- Fail2ban、nftables、OpenSIPS `pike`/`ratelimit` 防护。
|
||
|
||
“无状态”定义为不在 Server A 持久化业务主数据。OpenSIPS 运行时仍会维护事务和 Dialog 内存状态，服务重启会影响现有通话，V2 单节点接受此限制。
|
||
|
||
### 3.4 Server B 职责
|
||
|
||
- Nginx、React 静态资源、HTTPS 和 API 反向代理。
|
||
- LisgloSIPS API、CDR Worker、Recording Worker、Config Publisher。
|
||
- Redis：呼叫热数据、配置版本、锁、Redis Streams。
|
||
- MySQL：业务主数据、充值流水、话单、质检、权限、审计。
|
||
- 录音数据盘：保存迁移后的录音文件。
|
||
- Heplify-server、HOMER UI 及其独立存储。
|
||
- Prometheus、Grafana 及必要 exporters。
|
||
|
||
## 4. 架构图必须修正的两点
|
||
|
||
### 4.1 RTP 端口不能只开放 SIP 端口
|
||
|
||
架构图写明 Server A 公网仅暴露 `15060/UDP`，这不足以完成 RTP 媒体通信。若 RTPEngine 负责公网媒体锚定，安全组和主机防火墙还必须开放 RTPEngine 配置的 UDP 端口范围，例如：
|
||
|
||
```text
|
||
SIP: 15060/UDP
|
||
RTP: 30000-40000/UDP
|
||
```
|
||
|
||
端口范围应根据并发测算缩小，并尽量限制来源运营商或客户 IP 段。若上游 RTP 来源不可预知，需要保留公网 UDP 范围并强化速率限制和监控。
|
||
|
||
### 4.2 CDR 使用 Redis Stream
|
||
|
||
架构图中的 `queue:cdr_payload` 不应实现为无法确认消费的普通 Redis List。V2 使用 Redis Stream：
|
||
|
||
```text
|
||
stream:cdr_payload
|
||
consumer group: billing-workers
|
||
```
|
||
|
||
要求支持：
|
||
|
||
- 消息 ID 和业务幂等键。
|
||
- `XREADGROUP` 消费。
|
||
- MySQL 提交成功后 `XACK`。
|
||
- Pending 消息重领。
|
||
- 死信 Stream。
|
||
- Redis 暂时不可用时 Server A 本地受限缓冲或告警降级。
|
||
|
||
## 5. 技术栈与下载清单
|
||
|
||
### 5.1 版本原则
|
||
|
||
- 服务器统一 Ubuntu 24.04 LTS。
|
||
- OpenSIPS 使用项目已验证的 3.6.x 分支。
|
||
- 其他软件选择受支持稳定版，禁止部署时无条件升级“最新版”。
|
||
- 所有版本写入 `versions.env`、部署脚本或容器镜像标签。
|
||
- 先在预生产执行安装、通话和性能验证，再用于生产。
|
||
|
||
### 5.2 Server A 软件
|
||
|
||
| 软件 | 用途 | 安装来源 |
|
||
| --- | --- | --- |
|
||
| OpenSIPS 3.6.x | SIP 核心 | https://apt.opensips.org/ |
|
||
| opensips-cli | 管理与检查 | OpenSIPS APT |
|
||
| OpenSIPS Redis/HTTP/JSON 模块 | Redis 热路径、MI、事件 | OpenSIPS APT |
|
||
| RTPEngine daemon + kernel module | RTP 转发与录音 | https://github.com/sipwise/rtpengine |
|
||
| Heplify client 或 OpenSIPS tracer/HEP | 信令镜像 | https://github.com/sipcapture/heplify |
|
||
| Node Exporter | 主机指标 | https://prometheus.io/docs/guides/node-exporter/ |
|
||
| Fail2ban、nftables | 主机防护 | Ubuntu APT |
|
||
| chrony | 时间同步 | Ubuntu APT |
|
||
|
||
建议 OpenSIPS 包：
|
||
|
||
```text
|
||
opensips
|
||
opensips-cli
|
||
opensips-redis-module
|
||
opensips-http-modules
|
||
opensips-json-module
|
||
opensips-tls-module
|
||
opensips-auth-modules
|
||
opensips-mysql-dbschema
|
||
```
|
||
|
||
实际包名以 OpenSIPS 3.6 Ubuntu 24.04 仓库为准，安装脚本执行前用 `apt-cache search opensips` 校验。
|
||
|
||
### 5.3 Server B 软件
|
||
|
||
| 软件 | 用途 | 安装来源 |
|
||
| --- | --- | --- |
|
||
| Node.js LTS | API 和 Worker | https://nodejs.org/en/about/previous-releases |
|
||
| pnpm | Node.js 包管理 | Corepack |
|
||
| Nginx | Web、HTTPS、反向代理 | https://nginx.org/en/linux_packages.html |
|
||
| Redis | 热数据与 Streams | https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/ |
|
||
| MySQL | 业务持久化 | https://dev.mysql.com/downloads/repo/apt/ |
|
||
| Heplify-server + HOMER UI | 信令接收和排障 | https://github.com/sipcapture/heplify-server |
|
||
| Prometheus | 指标存储 | https://prometheus.io/docs/prometheus/latest/installation/ |
|
||
| Grafana | 监控大盘 | https://grafana.com/docs/grafana/latest/setup-grafana/installation/debian/ |
|
||
| mysqld_exporter、redis_exporter | 数据库与缓存指标 | Prometheus Community |
|
||
| Docker Engine/Compose | 仅用于 HOMER 组合服务 | https://docs.docker.com/engine/install/ubuntu/ |
|
||
| ffmpeg | 录音格式校验与转换 | Ubuntu APT |
|
||
|
||
HOMER 数据与业务 MySQL 必须逻辑隔离。优先使用 HOMER 官方 Compose 所要求的数据库，不把 HEP 海量信令写入业务库。
|
||
|
||
## 6. 网络、安全组和端口
|
||
|
||
### 6.1 Server A 入站
|
||
|
||
| 端口 | 来源 | 说明 |
|
||
| --- | --- | --- |
|
||
| `15060/UDP` | 客户/供应商允许列表 | SIP |
|
||
| `30000-40000/UDP` | RTP 对端或允许网段 | RTPEngine 媒体，最终按容量调整 |
|
||
| `<SSH_ADMIN_PORT>/TCP` | 堡垒机或管理 VPN | SSH 管理端口，不对全网开放；保留密钥登录 |
|
||
|
||
### 6.2 Server B 入站
|
||
|
||
| 端口 | 来源 | 说明 |
|
||
| --- | --- | --- |
|
||
| `443/TCP` | 管理端用户 | LisgloSIPS HTTPS |
|
||
| `80/TCP` | 可选 | 跳转 HTTPS，不承载登录 |
|
||
| `9060/UDP` | Server A 私网 IP | HEP |
|
||
| `<SSH_ADMIN_PORT>/TCP` | 堡垒机或管理 VPN | SSH 管理端口；保留密钥登录 |
|
||
|
||
Redis `6379`、MySQL `3306`、Prometheus `9090`、Grafana `3000`、应用端口、HOMER 内部端口不得直接暴露公网。Redis 和 MySQL至少绑定私网 IP，并通过安全组仅允许明确来源；同机服务优先使用 `127.0.0.1`。
|
||
|
||
### 6.3 安全要求
|
||
|
||
- 全部服务器启用 chrony，CDR、HOMER 和审计日志时间必须一致。
|
||
- Web 强制 HTTPS、HSTS、SameSite Cookie 和 CSRF 防护。
|
||
- 管理员密码使用 Argon2id；不记录明文密码。
|
||
- SIP 注册密码按 OpenSIPS Digest 需要保存 HA1 或受控密文，不直接返回前端。
|
||
- MI HTTP 只绑定 Server A `127.0.0.1`。
|
||
- 所有生产 Secret 放入权限为 `0600` 的环境文件或云 Secret 服务。
|
||
- 操作日志不得记录密码、完整 Authorization、Cookie、录音签名 URL。
|
||
|
||
## 7. 基础环境部署
|
||
|
||
### 7.1 阿里云资源
|
||
|
||
1. 创建 VPC 和私有子网。
|
||
2. 创建 Server A 4C8G 计算型实例和 Server B 4C16G 通用型实例。
|
||
3. Server B 挂载独立 ESSD 数据盘，业务数据库、录音和监控数据使用独立目录或分区。
|
||
4. 配置安全组、EIP、DNS 和快照策略。
|
||
5. 建议先创建同规格预生产环境，至少在上线前保留 3 天完整演练时间。
|
||
|
||
### 7.2 两台服务器通用初始化
|
||
|
||
```bash
|
||
sudo apt update && sudo apt full-upgrade -y
|
||
sudo apt install -y curl wget ca-certificates gnupg jq git unzip chrony \
|
||
nftables fail2ban vim htop iotop sysstat lsof net-tools tcpdump
|
||
sudo timedatectl set-timezone Asia/Shanghai
|
||
sudo systemctl enable --now chrony nftables fail2ban
|
||
```
|
||
|
||
生产环境推荐系统内部统一存 UTC，前端按 `Asia/Shanghai` 展示；若操作系统使用上海时区，数据库字段仍需明确 UTC 语义。
|
||
|
||
### 7.3 Server A tmpfs
|
||
|
||
```bash
|
||
sudo mkdir -p /dev/shm/voip_rec
|
||
sudo chown rtpengine:rtpengine /dev/shm/voip_rec
|
||
sudo chmod 0750 /dev/shm/voip_rec
|
||
```
|
||
|
||
`/etc/fstab`：
|
||
|
||
```fstab
|
||
tmpfs /dev/shm/voip_rec tmpfs rw,nosuid,nodev,noexec,size=3G,mode=0750 0 0
|
||
```
|
||
|
||
3 GiB 缓冲不是长期存储。按双向 G.711 原始音频约 16 KiB/s 粗略估算，只能容纳约 53 个“并发小时”，未计算容器和文件头开销。100 路持续录音时缓冲可能不到 35 分钟。Recording Worker 建议 5-15 秒扫描一次，使用量超过 70% 告警，超过 85% 时停止接受新的非强制录音或触发紧急迁移。
|
||
|
||
### 7.4 Server B 数据盘目录
|
||
|
||
```text
|
||
/data/mysql
|
||
/data/redis
|
||
/data/recordings/YYYY/MM/DD
|
||
/data/prometheus
|
||
/data/grafana
|
||
/data/homer
|
||
/data/backups
|
||
```
|
||
|
||
数据盘挂载参数、文件系统和 IOPS 规格需根据压测结果确认。录音目录和 MySQL 不建议共享同一个容易打满的根分区。
|
||
|
||
## 8. OpenSIPS 与 RTPEngine 实施
|
||
|
||
### 8.1 OpenSIPS 呼叫路径
|
||
|
||
```text
|
||
INVITE
|
||
-> 基础合法性与防扫描检查
|
||
-> IP 或 SIP Digest 认证
|
||
-> Redis 查询客户、客户网关、状态、余额门槛
|
||
-> Redis 查询客户网关策略（主叫条件 AND 被叫条件，按优先级）
|
||
-> 获得落地线路组
|
||
-> 按组内优先级、启用状态、并发/CPS 选择落地网关
|
||
-> 执行主被叫前缀转换、时段和编码限制
|
||
-> RTPEngine offer/answer
|
||
-> 转发到供应商
|
||
-> BYE/失败时生成标准化 CDR 事件
|
||
```
|
||
|
||
### 8.2 呼叫前原子检查
|
||
|
||
Redis Lua 脚本一次完成：
|
||
|
||
- 客户是否启用。
|
||
- 客户网关是否启用。
|
||
- IP/账号是否匹配。
|
||
- 余额加授信是否大于最小通话门槛。
|
||
- 网关 CPS 和并发是否超限。
|
||
- 黑名单是否命中。
|
||
- 返回配置版本、线路组和路由策略。
|
||
|
||
金额禁止使用 Redis 浮点数，统一使用整数“微元”或其他固定精度最小单位。
|
||
|
||
### 8.3 RTPEngine
|
||
|
||
- 使用内核转发模块并在启动时校验。
|
||
- 控制接口只在本机或私网监听。
|
||
- RTP 端口段与安全组保持一致。
|
||
- 录音先写 `.part`，完成后原子重命名为 `.ready`。
|
||
- 文件名包含日期、Call-ID 哈希和方向，禁止直接拼接未清洗 SIP Header。
|
||
|
||
### 8.4 CDR 标准事件
|
||
|
||
```json
|
||
{
|
||
"event_id": "uuid",
|
||
"idempotency_key": "call_id + ended_at 或 event_id",
|
||
"call_id": "sip-call-id",
|
||
"node_id": "a1",
|
||
"opensips_instance": "opensips-a1",
|
||
"ingress_a_ip": "100.90.90.90",
|
||
"rtpengine_node": "a1",
|
||
"customer_id": "C1001",
|
||
"customer_gateway_id": "CGW-001",
|
||
"source_ip": "10.10.1.11",
|
||
"caller": "02160010001",
|
||
"callee": "13800138000",
|
||
"vendor_id": "V1001",
|
||
"vendor_gateway_id": "VGW-001",
|
||
"line_group_id": "LG-001",
|
||
"started_at": "2026-06-20T02:14:22.123Z",
|
||
"answered_at": "2026-06-20T02:14:27.010Z",
|
||
"ended_at": "2026-06-20T02:17:30.445Z",
|
||
"duration_sec": 183,
|
||
"sip_code": 200,
|
||
"hangup_reason": "NORMAL_CLEARING",
|
||
"recording_key": "2026/06/20/xxx.ready",
|
||
"config_version": 1042
|
||
}
|
||
```
|
||
|
||
`event_id` 和 `call_id + ended_at` 作为幂等依据。任何重试不得重复扣费或重复写充值/余额流水。
|
||
|
||
## 9. Redis 设计
|
||
|
||
### 9.1 Key 规范
|
||
|
||
```text
|
||
cfg:active_version
|
||
cfg:customer:{customer_id}
|
||
cfg:customer_gateway:{gateway_id}
|
||
cfg:customer_gateway:{gateway_id}:policies
|
||
cfg:vendor_gateway:{gateway_id}
|
||
cfg:line_group:{group_id}:items
|
||
auth:ip:{ip}
|
||
auth:sip:{username}
|
||
balance:customer:{customer_id}
|
||
blacklist:caller
|
||
blacklist:callee
|
||
stream:cdr_payload
|
||
stream:cdr_deadletter
|
||
stream:recording_jobs
|
||
lock:cdr:{event_id}
|
||
```
|
||
|
||
### 9.2 配置发布
|
||
|
||
1. API 在 MySQL 事务中写业务表和 `outbox_events`。
|
||
2. Config Publisher 读取 outbox，生成完整配置快照。
|
||
3. 使用临时版本 Key 写入 Redis。
|
||
4. 校验数量和哈希后原子切换 `cfg:active_version`。
|
||
5. 发布成功后更新 outbox 状态。
|
||
6. 保留上一个版本，故障时一键回滚。
|
||
|
||
禁止 API 先改 Redis、后改 MySQL。MySQL 是唯一业务事实源，Redis 是呼叫热路径副本。
|
||
|
||
### 9.3 Redis 持久化
|
||
|
||
- 启用 AOF `appendfsync everysec`。
|
||
- 配置 RDB 快照。
|
||
- 限制 `maxmemory`，配置前评估淘汰策略；核心配置和队列不得被随机淘汰。
|
||
- 监控 Stream 长度、Pending 数、消费延迟、内存和连接数。
|
||
|
||
## 10. MySQL 数据模型
|
||
|
||
### 10.1 业务核心表
|
||
|
||
```text
|
||
customers
|
||
customer_gateways
|
||
customer_gateway_policies
|
||
customer_recharges
|
||
vendors
|
||
vendor_recharges
|
||
vendor_gateways
|
||
vendor_gateway_forbidden_periods
|
||
vendor_gateway_codecs
|
||
vendor_gateway_prefix_rules
|
||
landing_line_groups
|
||
landing_line_group_items
|
||
raw_cdrs
|
||
rated_cdrs
|
||
recordings
|
||
quality_sampling_rules
|
||
quality_reviews
|
||
users
|
||
roles
|
||
permissions
|
||
user_roles
|
||
role_permissions
|
||
audit_logs
|
||
outbox_events
|
||
idempotency_keys
|
||
```
|
||
|
||
### 10.2 关键约束
|
||
|
||
- ID 使用业务前缀 + 雪花 ID/UUID，禁止依赖前端生成。
|
||
- 金额使用 `DECIMAL(20,6)`，应用层不得使用 JavaScript 浮点直接计算金额。
|
||
- 充值使用不可变流水，余额变化必须与流水在同一事务提交。
|
||
- 网关策略唯一索引至少包含 `gateway_id + priority`。
|
||
- 线路组成员唯一索引包含 `line_group_id + vendor_gateway_id`。
|
||
- CDR 使用 `event_id` 唯一索引。
|
||
- 所有管理表包含 `created_at`、`updated_at`、`created_by`、`updated_by` 和乐观锁版本号。
|
||
- 时间存 UTC；API 返回 ISO 8601。
|
||
- 删除优先软删除；充值、CDR、审计日志不允许物理删除。
|
||
|
||
### 10.3 余额事务
|
||
|
||
充值事务：
|
||
|
||
```text
|
||
锁定客户/供应商账户行
|
||
-> 读取充值前余额
|
||
-> 插入充值流水
|
||
-> 更新余额
|
||
-> 插入审计日志/Outbox
|
||
-> 提交
|
||
```
|
||
|
||
CDR 扣费事务：
|
||
|
||
```text
|
||
检查 event_id 幂等
|
||
-> 写 raw_cdr
|
||
-> 计算最小计费结果
|
||
-> 写 rated_cdr
|
||
-> 锁定客户余额
|
||
-> 扣费并写余额流水
|
||
-> ACK Redis Stream
|
||
```
|
||
|
||
## 11. 后端工程设计
|
||
|
||
### 11.1 技术选型
|
||
|
||
- TypeScript + Node.js LTS。
|
||
- NestJS + Fastify Adapter。
|
||
- Prisma 管理 MySQL Schema 和迁移。
|
||
- ioredis 访问 Redis 和 Streams。
|
||
- OpenAPI/Swagger 生成 API 契约。
|
||
- Pino 输出结构化 JSON 日志。
|
||
- Vitest/Jest 做单元测试，Supertest 做 API 集成测试。
|
||
- systemd 管理 API 和 Worker；HOMER 可使用 Docker Compose。
|
||
|
||
### 11.2 推荐目录
|
||
|
||
```text
|
||
lisglosips/
|
||
├── apps/
|
||
│ ├── web/
|
||
│ ├── api/
|
||
│ ├── worker-cdr/
|
||
│ ├── worker-recording/
|
||
│ └── worker-config-publisher/
|
||
├── packages/
|
||
│ ├── contracts/
|
||
│ ├── domain/
|
||
│ ├── database/
|
||
│ ├── redis/
|
||
│ ├── auth/
|
||
│ └── observability/
|
||
├── prisma/
|
||
│ ├── schema.prisma
|
||
│ └── migrations/
|
||
├── deploy/
|
||
│ ├── server-a/
|
||
│ ├── server-b/
|
||
│ ├── nginx/
|
||
│ ├── systemd/
|
||
│ └── homer/
|
||
├── opensips/
|
||
│ ├── opensips.cfg
|
||
│ ├── routes/
|
||
│ └── scripts/
|
||
├── docs/
|
||
│ ├── openapi.yaml
|
||
│ ├── redis-keys.md
|
||
│ └── runbooks/
|
||
└── tests/
|
||
```
|
||
|
||
### 11.3 后端模块
|
||
|
||
```text
|
||
AuthModule
|
||
DashboardModule
|
||
CustomersModule
|
||
CustomerGatewaysModule
|
||
CustomerGatewayPoliciesModule
|
||
RechargesModule
|
||
VendorsModule
|
||
VendorGatewaysModule
|
||
LandingLineGroupsModule
|
||
CdrModule
|
||
RecordingsModule
|
||
QualityModule
|
||
UsersModule
|
||
RolesModule
|
||
AuditModule
|
||
ConfigPublisherModule
|
||
HealthModule
|
||
```
|
||
|
||
### 11.4 API 清单
|
||
|
||
```text
|
||
POST /api/v2/auth/login
|
||
POST /api/v2/auth/refresh
|
||
POST /api/v2/auth/logout
|
||
GET /api/v2/dashboard/summary
|
||
GET /api/v2/dashboard/trends
|
||
|
||
GET /api/v2/customers
|
||
POST /api/v2/customers
|
||
PATCH /api/v2/customers/:id
|
||
POST /api/v2/customers/:id/recharges
|
||
|
||
GET /api/v2/customer-gateways
|
||
POST /api/v2/customer-gateways
|
||
PATCH /api/v2/customer-gateways/:id
|
||
POST /api/v2/customer-gateways/:id/enable
|
||
POST /api/v2/customer-gateways/:id/disable
|
||
GET /api/v2/customer-gateways/:id/policies
|
||
POST /api/v2/customer-gateways/:id/policies
|
||
PATCH /api/v2/customer-gateway-policies/:id
|
||
DELETE /api/v2/customer-gateway-policies/:id
|
||
POST /api/v2/customer-gateways/:id/policies/reorder
|
||
|
||
GET /api/v2/vendors
|
||
POST /api/v2/vendors
|
||
PATCH /api/v2/vendors/:id
|
||
POST /api/v2/vendors/:id/recharges
|
||
GET /api/v2/recharges
|
||
|
||
GET /api/v2/vendor-gateways
|
||
POST /api/v2/vendor-gateways
|
||
PATCH /api/v2/vendor-gateways/:id
|
||
POST /api/v2/vendor-gateways/:id/enable
|
||
POST /api/v2/vendor-gateways/:id/disable
|
||
|
||
GET /api/v2/landing-line-groups
|
||
POST /api/v2/landing-line-groups
|
||
PATCH /api/v2/landing-line-groups/:id
|
||
POST /api/v2/landing-line-groups/:id/items
|
||
DELETE /api/v2/landing-line-groups/:id/items/:gatewayId
|
||
POST /api/v2/landing-line-groups/:id/items/reorder
|
||
|
||
GET /api/v2/cdrs
|
||
GET /api/v2/cdrs/:id
|
||
GET /api/v2/cdrs/:id/recording
|
||
GET /api/v2/cdrs/:id/signaling-link
|
||
|
||
GET /api/v2/quality/rules
|
||
POST /api/v2/quality/rules
|
||
PATCH /api/v2/quality/rules/:id
|
||
DELETE /api/v2/quality/rules/:id
|
||
POST /api/v2/quality/rules/:id/enable
|
||
POST /api/v2/quality/rules/:id/disable
|
||
GET /api/v2/recordings
|
||
GET /api/v2/recordings/:id
|
||
PUT /api/v2/recordings/:id/review
|
||
|
||
GET /api/v2/users
|
||
POST /api/v2/users
|
||
PATCH /api/v2/users/:id
|
||
POST /api/v2/users/:id/reset-password
|
||
GET /api/v2/roles
|
||
POST /api/v2/roles
|
||
PATCH /api/v2/roles/:id
|
||
PUT /api/v2/roles/:id/permissions
|
||
GET /api/v2/audit-logs
|
||
GET /api/v2/audit-logs/:id
|
||
```
|
||
|
||
### 11.5 API 规范
|
||
|
||
- 列表统一 `page`、`page_size`、`sort`、筛选参数。
|
||
- 返回 `{ data, meta, request_id }`。
|
||
- 错误返回稳定业务码，不把数据库错误直接返回前端。
|
||
- 新增、充值、重置密码、策略重排支持 `Idempotency-Key`。
|
||
- 写请求校验 `If-Match` 或版本字段，防止覆盖其他管理员修改。
|
||
- 导出采用异步任务和短期下载地址，避免长请求占用 5 Mbps 公网带宽。
|
||
|
||
## 12. 录音迁移和质检
|
||
|
||
### 12.1 文件生命周期
|
||
|
||
```text
|
||
RTPEngine 写入 .part
|
||
-> 录音完成原子改名 .ready
|
||
-> Recording Worker 私网扫描
|
||
-> 拉取到 Server B 临时目录
|
||
-> 校验大小、SHA-256、音频时长
|
||
-> 原子移动到 /data/recordings/YYYY/MM/DD
|
||
-> 写 recordings 表
|
||
-> 删除 Server A 源文件
|
||
```
|
||
|
||
任何一步失败都不得先删除 Server A 文件。Worker 使用文件锁或 Redis 锁防止重复搬运，并对 `.part`、过期 `.ready`、孤儿文件分别处理。
|
||
|
||
### 12.2 播放
|
||
|
||
- API 先校验 `recording.play` 权限。
|
||
- Nginx `X-Accel-Redirect` 发送文件，Node.js 不直接读取整段音频到内存。
|
||
- 支持 HTTP Range，便于拖动播放。
|
||
- 操作日志记录播放人、录音 ID、时间和 IP。
|
||
- Server B 公网只有 5 Mbps 时需限制并发播放；后续可迁移至阿里云 OSS，使用短期签名 URL。
|
||
|
||
### 12.3 抽检规则
|
||
|
||
V2 字段与 Web Demo 保持一致：
|
||
|
||
- 规则名称。
|
||
- 客户。
|
||
- 抽检比例。
|
||
- 指定线路。
|
||
- 生效时间。
|
||
- 状态。
|
||
|
||
Worker 在录音入库后根据客户、线路和稳定哈希进行抽样，避免重启导致随机结果变化。
|
||
|
||
## 13. 权限与审计
|
||
|
||
### 13.1 权限模型
|
||
|
||
权限粒度采用 `resource.action`：
|
||
|
||
```text
|
||
customers.view
|
||
customers.manage
|
||
vendors.view
|
||
vendors.manage
|
||
gateways.view
|
||
gateways.manage
|
||
routes.view
|
||
routes.manage
|
||
recharge.manage
|
||
cdr.view
|
||
cdr.export
|
||
recording.play
|
||
quality.manage
|
||
users.manage
|
||
roles.manage
|
||
logs.view
|
||
```
|
||
|
||
超级管理员、运营管理员、财务、质检和技术运维为内置角色。内置角色名称和关键权限禁止普通管理员修改。
|
||
|
||
### 13.2 审计要求
|
||
|
||
审计日志至少记录：
|
||
|
||
- `request_id`、操作人、用户账号、角色。
|
||
- 时间、IP、User-Agent。
|
||
- 模块、动作、对象类型、对象 ID。
|
||
- 修改前/后摘要，敏感字段脱敏。
|
||
- 成功/失败和业务错误码。
|
||
|
||
审计日志由服务端生成，前端传入的“操作人”不可信。
|
||
|
||
## 14. Dashboard 数据策略
|
||
|
||
- 实时在线通话和注册：Redis 热数据或 OpenSIPS 指标。
|
||
- 今日通话、费用、成本、毛利：MySQL 聚合表。
|
||
- 24 小时趋势：按 5 分钟或 1 小时预聚合，禁止首页扫描全量 CDR。
|
||
- 失败响应码：CDR 聚合。
|
||
- 异常网关：健康状态缓存。
|
||
- 质检待处理：recordings/quality_reviews 聚合。
|
||
|
||
创建定时聚合任务 `worker-metrics` 或复用 CDR Worker 增量写统计表。
|
||
|
||
## 15. 最小计费实现
|
||
|
||
虽然“费率与计费”页面延期，V2 仍需最小计费能力支持话单费用和余额。
|
||
|
||
V2 首期仅支持落地网关上的：
|
||
|
||
- 计费周期，单位秒，最大 60。
|
||
- 周期费率。
|
||
- 分钟费率展示值：`周期费率 * 60 / 计费周期`。
|
||
|
||
计算使用 Decimal：
|
||
|
||
```text
|
||
计费周期数 = ceil(通话秒数 / 计费周期)
|
||
费用 = 计费周期数 * 周期费率
|
||
```
|
||
|
||
客户侧费率在完整页面设计前可由受控配置表或迁移脚本维护，不对普通运营角色开放。所有费率变更必须留审计记录和生效时间。
|
||
|
||
## 16. 监控、日志和备份
|
||
|
||
### 16.1 基础监控
|
||
|
||
即使自研“监控告警”页面延期，也必须部署：
|
||
|
||
- Server A/B CPU、内存、磁盘、网络、负载。
|
||
- OpenSIPS 进程、SIP 请求量、响应码、活动 Dialog。
|
||
- RTPEngine 会话、丢包、端口使用率。
|
||
- tmpfs 使用率和最老录音文件年龄。
|
||
- Redis 内存、连接、Stream 长度、Pending。
|
||
- MySQL 连接、慢查询、锁等待、磁盘。
|
||
- API P95/P99、5xx、Worker 延迟。
|
||
|
||
### 16.2 日志
|
||
|
||
- 应用日志输出 JSON，包含 `request_id`、`call_id`、`event_id`。
|
||
- journald 保留短期日志；可选 Loki/Promtail 后续集中化。
|
||
- 禁止在普通日志输出 SIP 密码、Web Token 和录音内容。
|
||
|
||
### 16.3 备份
|
||
|
||
- MySQL：每日全量备份 + binlog，定期恢复演练。
|
||
- Redis：AOF + RDB；Redis 不是业务主数据唯一副本。
|
||
- 录音：数据盘快照，后续转 OSS 生命周期管理。
|
||
- OpenSIPS、Nginx、systemd、Prometheus 配置进入 Git。
|
||
- 备份密钥与业务数据分开保存。
|
||
|
||
## 17. 开发与部署阶段
|
||
|
||
### 阶段 0：确认技术决策（2-3 天）
|
||
|
||
- 确认 SIP 公网端口、RTP 端口段和运营商 IP 范围。
|
||
- 确认预估并发、CPS、日通话量、日录音小时数。
|
||
- 确认客户余额实时控制规则和最低余额门槛。
|
||
- 确认录音保存周期和是否接 OSS。
|
||
- 确认 MySQL 还是 MariaDB。本文默认 MySQL；若沿用现有 MariaDB，需先验证 Prisma 和 SQL 兼容性。
|
||
|
||
### 阶段 1：服务器和网络（3-4 天）
|
||
|
||
- 创建 VPC、Server A/B、EIP、数据盘和安全组。
|
||
- 安装基础工具、时间同步、防火墙。
|
||
- 验证私网 RTT、带宽、磁盘吞吐和 DNS。
|
||
- 输出 `infra-check.md` 和端口验收结果。
|
||
|
||
### 阶段 2：Server A 通信栈（5-7 天）
|
||
|
||
- 安装 OpenSIPS 3.6.x、RTPEngine 和内核模块。
|
||
- 配置 SIP 15060、RTP 端口范围和 MI 本地端口。
|
||
- 配置 Redis 连接、HEP、录音 tmpfs、指标和安全限制。
|
||
- 完成 IP 认证、SIP 注册认证和基础呼叫。
|
||
- 完成单通、双通、挂断、失败响应和录音测试。
|
||
|
||
### 阶段 3：Server B 基础服务（4-5 天）
|
||
|
||
- 安装 Nginx、Node.js、Redis、MySQL。
|
||
- 部署 HOMER、Prometheus、Grafana 和 exporters。
|
||
- 初始化数据盘、备份目录和 TLS。
|
||
- 创建应用系统用户、systemd 服务账户和最小权限目录。
|
||
|
||
### 阶段 4：后端骨架（5 天）
|
||
|
||
- 初始化 monorepo、NestJS、Prisma、OpenAPI、日志和健康检查。
|
||
- 完成认证、JWT 刷新、RBAC、审计拦截器。
|
||
- 建立数据库迁移、种子数据和 CI。
|
||
- 完成 Redis 客户端、Stream 基础库和 outbox publisher。
|
||
|
||
### 阶段 5：运营业务 API（10-12 天）
|
||
|
||
- 客户、客户网关、策略、充值。
|
||
- 供应商、落地网关、落地线路组。
|
||
- 用户、角色、权限、操作日志。
|
||
- 接入当前 React Demo，移除 Mock 数据。
|
||
|
||
### 阶段 6：通话、CDR 和录音闭环（8-10 天）
|
||
|
||
- Redis 配置发布和回滚。
|
||
- OpenSIPS 呼叫时查询和路由。
|
||
- CDR Stream、幂等消费、最小计费、余额扣减。
|
||
- Recording Worker、文件校验、Range 播放。
|
||
- HOMER Call-ID 跳转。
|
||
|
||
### 阶段 7：Dashboard 和质检（5-7 天）
|
||
|
||
- Dashboard 聚合指标。
|
||
- 抽检规则、录音列表、连续播放、质检结果。
|
||
- 权限校验和播放审计。
|
||
|
||
### 阶段 8：测试和上线（7-10 天）
|
||
|
||
- 功能、集成、故障、性能、安全测试。
|
||
- 全量上线演练和回滚演练。
|
||
- 小流量客户灰度。
|
||
- 观察 24-72 小时后扩大流量。
|
||
|
||
预计总周期 8-10 周，建议至少配置：后端 1 人、SIP/媒体 1 人、前端 1 人、运维 0.5 人、测试 0.5 人。单人实施需要相应延长周期并优先保证呼叫、CDR、余额和录音闭环。
|
||
|
||
## 18. 后端代码完成标准
|
||
|
||
- 所有本期页面均使用真实 API，不再依赖硬编码 Mock。
|
||
- OpenAPI 可生成前端类型或 API Client。
|
||
- 数据库迁移可在空库一键执行，也能回滚最近一次变更。
|
||
- 关键服务有 `/health/live` 和 `/health/ready`。
|
||
- CDR 重复投递不会重复扣费。
|
||
- 充值重复请求不会重复加余额。
|
||
- 配置发布失败不会留下半套 Redis 配置。
|
||
- 录音搬运失败不会删除源文件。
|
||
- RBAC 在服务端生效，隐藏按钮不能替代权限校验。
|
||
- 敏感操作全部进入审计日志。
|
||
- 单元测试覆盖金额、优先级、主被叫条件、幂等和权限。
|
||
|
||
## 19. 测试与验收
|
||
|
||
### 19.1 功能验收
|
||
|
||
- IP 和 SIP 注册两种客户网关认证成功/失败路径。
|
||
- 主叫等于、主叫前缀、被叫等于、被叫前缀及组合条件。
|
||
- 多策略优先级和多落地网关优先级。
|
||
- 网关启停、禁呼时段、编码、号码前缀转换。
|
||
- 充值、余额前后值、授信和审计。
|
||
- CDR 字段、挂断原因、客户费用、成本费用。
|
||
- 抽检规则、录音播放、上下条、自动播放、保存质检结果。
|
||
- 用户、角色、权限和重置密码。
|
||
|
||
### 19.2 性能验收
|
||
|
||
压测目标必须在阶段 0 根据业务量确认。最低应覆盖：
|
||
|
||
- 目标 CPS 的 1.5 倍持续 30 分钟。
|
||
- 目标并发的 1.2 倍持续 2 小时。
|
||
- Redis 呼叫时查询 P99。
|
||
- CDR Worker 堆积恢复速度。
|
||
- 100% 录音下 tmpfs 增长和迁移速度。
|
||
- 多用户同时查询 CDR 和播放录音时 Server B 带宽。
|
||
|
||
### 19.3 故障验收
|
||
|
||
- Redis 短暂不可用。
|
||
- MySQL 重启和事务回滚。
|
||
- CDR Worker 异常退出后重领 Pending。
|
||
- Recording Worker 重复执行。
|
||
- Server B 数据盘接近满。
|
||
- Server A tmpfs 达 70%/85%。
|
||
- RTPEngine 重启。
|
||
- 配置版本回滚。
|
||
|
||
### 19.4 安全验收
|
||
|
||
- SIP 扫描、暴力注册、非法来源 IP、超 CPS。
|
||
- 越权访问其他模块 API。
|
||
- 重放充值请求。
|
||
- SQL 注入、XSS、CSRF、弱密码和 Session 失效。
|
||
- 录音 URL 过期、Range 越权和路径穿越。
|
||
|
||
## 20. 上线和回滚
|
||
|
||
### 20.1 上线顺序
|
||
|
||
1. 备份 MySQL、Redis、OpenSIPS 和 Nginx 配置。
|
||
2. 部署 Server B 数据库迁移和后端，但暂不切流。
|
||
3. 发布 Redis 配置快照并校验。
|
||
4. 部署 Server A OpenSIPS/RTPEngine 配置。
|
||
5. 使用测试账号完成真实呼叫、CDR、扣费和录音。
|
||
6. 灰度一个低风险客户或一条线路。
|
||
7. 观察指标、CDR 差异、余额和录音完整性。
|
||
8. 逐步扩大流量。
|
||
|
||
### 20.2 回滚
|
||
|
||
- Web/API：切回上一个发布目录或镜像。
|
||
- 数据库：使用向前兼容迁移；上线窗口不执行不可逆删列。
|
||
- Redis 配置：切回上一个 `cfg:active_version`。
|
||
- OpenSIPS：恢复上一版配置并执行语法检查后重载。
|
||
- RTPEngine：恢复上一版 systemd 参数。
|
||
- CDR：停止 Consumer，不删除 Stream；修复后重放。
|
||
- 录音：停止删除 Server A 源文件，保留 B 端临时文件等待人工处理。
|
||
|
||
## 21. 主要风险
|
||
|
||
| 风险 | 影响 | 控制措施 |
|
||
| --- | --- | --- |
|
||
| Server A 单点 | 重启影响通话 | V2 接受；配置快速恢复；后续增加双节点 |
|
||
| 仅开放 15060 | 无 RTP 或单通 | 必须开放并验证 RTP UDP 端口段 |
|
||
| 3 GiB tmpfs 打满 | 录音丢失、进程异常 | 高频搬运、阈值告警、降级策略 |
|
||
| Server B 5 Mbps | 多录音播放卡顿 | Range、限并发、后续 OSS/CDN |
|
||
| Redis 成为呼叫热路径单点 | 新呼叫失败 | AOF/RDB、监控、后续主从/Sentinel |
|
||
| CDR 重复消费 | 重复扣费 | Stream ACK、唯一索引、幂等事务 |
|
||
| 配置半发布 | 路由不一致 | MySQL Outbox + Redis 版本原子切换 |
|
||
| HOMER 数据膨胀 | 数据盘占满 | 独立存储、保留周期、容量告警 |
|
||
| 金额浮点误差 | 对账差异 | Decimal/整数最小单位，禁止 JS Number 计费 |
|
||
|
||
## 22. 下一步执行清单
|
||
|
||
### 立即执行
|
||
|
||
- [ ] 确认预计 CPS、并发、日话单、录音小时数。
|
||
- [ ] 确认 Server A RTP 端口段和安全组来源范围。
|
||
- [ ] 确认 Server B 数据盘容量、IOPS 和录音保留期。
|
||
- [ ] 确认 MySQL/MariaDB 最终选择。
|
||
- [ ] 申请域名和 TLS 证书。
|
||
- [ ] 创建预生产 VPC 和两台服务器。
|
||
|
||
### 服务器部署完成条件
|
||
|
||
- [ ] Server A OpenSIPS、RTPEngine、Redis 私网连接、HEP、tmpfs、exporter 正常。
|
||
- [ ] Server B Nginx、Node.js、Redis、MySQL、HOMER、Prometheus、Grafana 正常。
|
||
- [ ] 安全组端口和主机防火墙验收。
|
||
- [ ] 备份、日志轮转、时间同步和系统用户验收。
|
||
- [ ] 完成端到端测试呼叫并在 HOMER 查询到信令。
|
||
- [ ] 完成录音从 A 内存盘到 B 数据盘的搬运测试。
|
||
|
||
### 后端开发启动条件
|
||
|
||
- [ ] 创建 V2 monorepo 和 CI。
|
||
- [ ] 提交 Prisma Schema V1 和初始化迁移。
|
||
- [ ] 提交 OpenAPI V2 基线。
|
||
- [ ] 提交 Redis Key 和 Stream 契约。
|
||
- [ ] 完成 Auth/RBAC/Audit 骨架。
|
||
- [ ] 先实现客户、网关、线路组和配置发布，再实现 CDR/录音。
|
||
|
||
## 23. V2 交付物
|
||
|
||
```text
|
||
1. 阿里云双机部署记录和安全组清单
|
||
2. Server A/Server B 幂等安装脚本
|
||
3. OpenSIPS 和 RTPEngine 配置仓库
|
||
4. MySQL DDL/Prisma migrations
|
||
5. Redis Key/Stream 契约
|
||
6. OpenAPI 文档
|
||
7. LisgloSIPS API 和 Workers 源码
|
||
8. React Web 与真实 API 集成版本
|
||
9. Prometheus/Grafana/HOMER 部署配置
|
||
10. 自动化测试、压测报告和安全检查报告
|
||
11. 上线、回滚、备份恢复和故障处置 Runbook
|
||
```
|
||
|
||
## 24. 最终实施原则
|
||
|
||
- 先打通“配置发布 -> 呼叫 -> CDR -> 计费 -> 余额 -> 录音 -> 质检”闭环，再扩展页面。
|
||
- MySQL 是业务事实源，Redis 是呼叫热路径和队列，不反向替代主库。
|
||
- 金额、CDR、充值和录音全部按可重试、可审计、幂等设计。
|
||
- Server A 保持精简，Server B 承担业务复杂度。
|
||
- 待设计菜单不阻塞底层必需能力，但不得在 V2 临时扩张为未确认的产品页面。
|
||
- 所有部署和配置必须脚本化、版本化、可回滚。
|
||
|
||
## 25. Codex 全流程分步实施规范
|
||
|
||
### 25.1 目的
|
||
|
||
本项目计划主要由 Codex 持续实施。为避免单次任务过大、上下文丢失、误操作和新会话重复工作，整个 V2 被拆分为 31 个原子任务 `S00-S30`。每个会话默认只完成一个任务，除非用户明确授权合并。
|
||
|
||
详细实时状态记录在 `IMPLEMENTATION_STATUS.md`，服务器密码只保存在被 `.gitignore` 排除的 `.codex-private/SERVER_ACCESS.md`。
|
||
|
||
### 25.2 服务器固定代号
|
||
|
||
| 代号 | IP | SSH 用户 | 职责 |
|
||
| --- | --- | --- | --- |
|
||
| Server A | `100.90.90.90` | `hector` | 核心通信网关 |
|
||
| Server B | `100.90.90.91` | `hector` | 业务、缓存与监控中心 |
|
||
| Server T | `100.93.185.30` | `hector` | 已安装 OpenSIPS，模拟 SIP 客户 |
|
||
|
||
主文档不保存明文密码。新会话只有在用户授权当前任务连接服务器后，才读取私密访问文件，并禁止在回复或日志中回显密码。
|
||
|
||
### 25.3 单会话执行纪律
|
||
|
||
1. 先读取 `SOFTSWITCH_PLATFORM_DESIGN_V2.md` 和 `IMPLEMENTATION_STATUS.md`。
|
||
2. 只执行状态文件中的“当前任务”。
|
||
3. 服务器任务先做只读检查，再做写操作。
|
||
4. 修改配置前备份，记录绝对路径、时间戳和回滚命令。
|
||
5. 服务重启、防火墙、SSH、数据库迁移、数据删除前说明影响。
|
||
6. 不能因安装困难随意更换技术栈或扩大公网端口。
|
||
7. 安装软件必须记录来源、版本和校验结果。
|
||
8. 完成后执行该任务的验收，不以“命令无报错”代替功能验证。
|
||
9. 更新状态文件后再结束会话。
|
||
10. 出现阻塞时停止在安全状态，不绕过安全控制继续后续任务。
|
||
|
||
### 25.4 原子任务顺序
|
||
|
||
#### S00-S02：安全接入和资产盘点
|
||
|
||
**S00 SSH 安全接入与凭据迁移**
|
||
|
||
- 用户明确授权后连接 A/B/T。
|
||
- 在本机生成项目专用 Ed25519 Key，不覆盖现有 Key。
|
||
- 安装公钥并验证三个独立新会话。
|
||
- 备份 `sshd_config`，确认不会锁死后只调整 SSH 管理端口，不禁止 SSH 密钥登录。
|
||
- 轮换当前密码，私密文件同步更新或改为只记录 Key。
|
||
- 验收：新端口 Key 登录成功；sudo 可用；现有会话保留到新会话验证完成。
|
||
|
||
**S01 三机只读资产盘点**
|
||
|
||
- 只读取 OS、内核、CPU、内存、磁盘、网卡、路由、时间、端口、服务、包版本。
|
||
- 盘点 T 上现有 OpenSIPS 配置和测试能力，不修改。
|
||
- 输出 `docs/inventory-A.md`、`inventory-B.md`、`inventory-T.md`。
|
||
- 验收：报告包含差异、风险和安装前备份清单。
|
||
|
||
**S02 网络与安全组验收**
|
||
|
||
- 验证 A/B/T 双向可达性和实际私网 RTT。
|
||
- 确认 A 的 SIP 15060/UDP、RTP 端口段；B 的 443/TCP、私网 HEP 9060/UDP。
|
||
- 不通过 SSH 直接修改云安全组；生成阿里云控制台操作清单供用户确认。
|
||
- 验收：形成端口矩阵和最小暴露方案。
|
||
|
||
#### S03-S06：Server B 基础设施
|
||
|
||
**S03 Server B 基础系统初始化**
|
||
|
||
- 更新系统、安装基础包、chrony、nftables、fail2ban。
|
||
- 检查并初始化数据盘目录，不格式化未知数据盘。
|
||
- 创建应用、录音和监控系统用户与目录权限。
|
||
- 验收：重启后时间、挂载、权限和防火墙正常。
|
||
|
||
**S04 MySQL 与 Redis**
|
||
|
||
- 固定版本安装并限制监听地址。
|
||
- 创建业务库/用户，启用 MySQL binlog、Redis AOF/RDB。
|
||
- 配置备份脚本和健康检查。
|
||
- 验收：重启恢复、权限隔离、备份和恢复样例通过。
|
||
|
||
**S05 Node.js、Nginx 与 TLS 基线**
|
||
|
||
- 安装固定 Node.js LTS 和 pnpm。
|
||
- 建立 `/opt/lisglosips/releases`、`current` 和 systemd 模板。
|
||
- 配置 Nginx 静态站点、API 代理、Range、限流和 HTTPS 预案。
|
||
- 验收：占位健康页通过 Nginx 访问，应用端口不暴露公网。
|
||
|
||
**S06 HOMER 与基础监控**
|
||
|
||
- 部署 Heplify-server/HOMER、Prometheus、Grafana、exporters。
|
||
- HOMER 数据和业务 MySQL 分离。
|
||
- 验收：B 私网 9060 接收测试 HEP；A/B 主机指标可见。
|
||
|
||
#### S07-S10：后端基础
|
||
|
||
**S07 后端 Monorepo 骨架**
|
||
|
||
- 创建 NestJS/Fastify、Prisma、结构化日志、配置校验、健康检查和测试框架。
|
||
- 建立 CI 命令：lint、typecheck、test、build。
|
||
- 验收：本地和 B 均可构建；健康检查可用。
|
||
|
||
**S08 数据库 Schema 与迁移**
|
||
|
||
- 实现本文第 10 章表结构、索引、Decimal、审计列和 Outbox。
|
||
- 提供空库迁移、种子和回滚/恢复说明。
|
||
- 验收：空库一键初始化；重复执行安全；Schema 测试通过。
|
||
|
||
**S09 登录认证基础**
|
||
|
||
- 登录、刷新、退出、Argon2id、失败锁定、Token/Cookie 安全。
|
||
- 验收：成功、失败、过期、刷新、注销和暴力尝试路径通过。
|
||
|
||
**S10 用户、角色、权限与审计**
|
||
|
||
- 实现用户、角色、权限矩阵、内置角色保护和重置密码。
|
||
- 服务端 RBAC 和审计拦截器必须先于业务 API 完成。
|
||
- 验收：越权被拒绝；敏感字段脱敏；审计详情可查询。
|
||
|
||
#### S11-S17：运营业务 API
|
||
|
||
**S11 客户管理**：客户 CRUD、启停、余额/授信读取。
|
||
**S12 充值流水**：客户/供应商充值、事务、幂等、并发。
|
||
**S13 客户网关**：IP/SIP 注册认证、启停、密码安全。
|
||
**S14 网关策略与配置发布**：主被叫条件、优先级、Outbox、Redis 版本。
|
||
**S15 供应商管理**：供应商 CRUD、余额、授信。
|
||
**S16 落地网关**：认证、CPS、并发、禁呼、编码、号码转换、周期费率。
|
||
**S17 落地线路组**：成员增删、优先级、并发汇总、引用校验。
|
||
|
||
每个任务必须同时完成：数据库迁移、领域校验、API、权限、审计、单元测试、集成测试和 OpenAPI，不允许先堆积未测试接口后统一补测。
|
||
|
||
#### S18-S21：通信栈和测试客户
|
||
|
||
**S18 Server A OpenSIPS 基线**
|
||
|
||
- 先备份现状，再安装/固定 OpenSIPS 3.6.x。
|
||
- 配置 15060、认证、防扫描、MI 本地绑定和模块基线。
|
||
- 每次改动先执行语法检查，验证失败立即回滚。
|
||
|
||
**S19 RTPEngine 与录音 tmpfs**
|
||
|
||
- 配置内核转发、RTP 端口段、3 GiB tmpfs 和 `.part -> .ready` 生命周期。
|
||
- 验收：双向音频、NAT、录音、重启和 tmpfs 阈值。
|
||
|
||
**S20 Redis 热路径、HEP 与指标**
|
||
|
||
- 实现 Lua 原子检查、版本化配置读取、CDR XADD、HEP 发送和指标采集。
|
||
- 验收：Redis 超时、配置缺失、HEP 中断均有明确降级和日志。
|
||
|
||
**S21 Server T 客户模拟**
|
||
|
||
- 在不破坏 T 现有 OpenSIPS 的前提下配置测试域、IP 认证和 SIP 注册账号。
|
||
- 编写成功呼叫、忙、拒绝、超时、错误密码、超 CPS 测试脚本。
|
||
- 验收：所有脚本可重复执行并输出 Call-ID。
|
||
|
||
#### S22-S26：异步闭环
|
||
|
||
**S22 CDR Redis Stream**：事件契约、Consumer Group、ACK、Pending、死信、幂等。
|
||
**S23 最小计费**：Decimal 周期计费、客户费用、成本、余额扣减。
|
||
**S24 录音搬运与播放**：私网拉取、哈希、原子移动、Range、权限和源文件删除保护。
|
||
**S25 质检后端**：规则、稳定抽样、连续录音查询、质检保存和审计。
|
||
**S26 Dashboard 聚合**：实时指标和预聚合趋势，避免扫描全量 CDR。
|
||
|
||
#### S27-S30：联调和上线
|
||
|
||
**S27 React 接入真实 API**
|
||
|
||
- 按菜单逐页替换 Mock；每次只接入一个领域。
|
||
- 增加加载、空状态、错误、权限隐藏和并发更新提示。
|
||
- 待设计菜单继续保留标识，不接临时 API。
|
||
|
||
**S28 三机端到端联调**
|
||
|
||
- T 发起 SIP -> A 鉴权/路由/媒体/录音 -> B CDR/费用/信令/质检。
|
||
- 按 Call-ID 核对 OpenSIPS、Redis Stream、MySQL、HOMER 和录音文件。
|
||
|
||
**S29 性能、故障与安全测试**
|
||
|
||
- 执行 CPS、并发、录音、Redis/MySQL/Worker 故障和 Web/SIP 安全测试。
|
||
- 所有失败必须形成缺陷、修复和复测记录。
|
||
|
||
**S30 备份、Runbook、灰度与上线**
|
||
|
||
- 完成恢复演练、上线/回滚脚本和灰度。
|
||
- 上线前冻结版本和数据库迁移，输出最终验收报告。
|
||
|
||
### 25.5 Codex 新会话启动模板
|
||
|
||
```text
|
||
请先读取 SOFTSWITCH_PLATFORM_DESIGN_V2.md 和 IMPLEMENTATION_STATUS.md，
|
||
只执行当前任务 Sxx，不提前执行下一任务。
|
||
如任务需要服务器访问，读取 .codex-private/SERVER_ACCESS.md，但不要在回复、日志或文档中回显密码。
|
||
所有服务器写操作先备份并给出回滚点；涉及重启、SSH、防火墙、数据库迁移或删除时先说明影响。
|
||
完成后执行验收并更新 IMPLEMENTATION_STATUS.md，包括状态、产物、验证、回滚、遗留问题和下一任务。
|
||
```
|