# LisgloSIPS 部署实施指南

本文是 LisgloSIPS V2 的独立部署交接文档。目标是让新的 Codex 会话在不依赖聊天记忆的情况下，按阶段完成本地开发部署、后端实现、联调和阿里云迁移。

设计依据：`SOFTSWITCH_PLATFORM_DESIGN_V2.md`。进度依据：`IMPLEMENTATION_STATUS.md`。任何会话开始时先读取这两个文件，并且一次只执行当前 Sxx 任务。

## 1. 环境与边界

当前阶段使用三台本地 KVM 开发服务器，通过 Tailscale 通信：

| 服务器 | Tailscale 地址 | 职责 |
| --- | --- | --- |
| A | `100.90.90.90` | OpenSIPS、RTPEngine、录音内存盘、HEP、Exporter |
| B | `100.90.90.91` | API/Worker、MySQL、Redis、Web、HOMER、监控和录音持久化 |
| T | `100.93.185.30` | 模拟客户 SIP 注册、IP 对接和测试呼叫 |

开发完成后再迁移阿里云。当前 IP、开发证书和防火墙源地址不能原样作为生产配置。

## 2. 凭据规则

- SSH 与 sudo 凭据只存放在 `.codex-private/`，禁止写入文档、脚本、Git、日志或命令回显。
- 服务账号凭据保存在 `.codex-private/SERVICE_CREDENTIALS.clixml` 和服务器 `/etc/lisglosips/secrets/`。
- 生产使用云 Secret 服务或权限为 `0600/0640` 的受控文件。
- 部署文档只记录凭据位置、权限和轮换流程，不记录明文。

## 3. 总体部署顺序

```text
S00-S02  安全接入、资产与网络
S03-S06  Server B 基础设施
S07-S17  后端骨架与运营业务 API
S18-S21  Server A/T 通信与呼叫基线
S22-S26  CDR、计费、录音、质检与 Dashboard
S27      React 接入真实 API
S28-S29  端到端、性能、故障与安全测试
S30      阿里云迁移、灰度、回滚和验收
```

禁止提前跨阶段实施依赖尚未完成的任务。例如 S08 Schema 完成前，不部署真实业务 API；S22 CDR 事件契约完成前，不让 OpenSIPS 写入正式扣费链路。

## 4. 已完成部署基线

截至 S06：

| 阶段 | 结果 | 文档 |
| --- | --- | --- |
| S00 | SSH Key、host key 修复、SSH 管理端口调整、凭据轮换；保留密钥登录 | `docs/SSH_ACCESS_RUNBOOK.md` |
| S01 | 三机资产盘点 | `docs/inventory-summary.md` |
| S02 | Tailscale 网络和最小端口矩阵 | `docs/infra-check.md` |
| S03 | B 内核、chrony、nftables、fail2ban、目录和 NFS automount | `docs/SERVER_B_BASELINE_RUNBOOK.md` |
| S04 | B MySQL、Redis、ACL、持久化、备份与恢复演练 | `docs/SERVER_B_DATA_SERVICES_RUNBOOK.md` |
| S05 | B Node.js、pnpm、Nginx、systemd、TLS 与发布目录 | `docs/SERVER_B_WEB_RUNTIME_RUNBOOK.md` |
| S06 | B HOMER、HEP 接收、Prometheus、Grafana、Exporters；A Node Exporter | `docs/SERVER_B_HOMER_MONITORING_RUNBOOK.md` |

所有可提交的 Server B 配置副本位于 `infra/server-b/s03/`、`s04/`、`s05/`、`s06/`，Server A 的 S06 采集配置位于 `infra/server-a/s06/`。服务器私钥、密码和数据库数据不进入这些目录。

## 5. Server B 从基线到 Web 入口

在新 Server B 重建时按以下顺序执行：

1. 完成 Ubuntu 24.04 LTS 补丁、chrony、nftables、fail2ban 和系统用户。
2. 建立 `/data`、`/opt/lisglosips/releases`、`/etc/lisglosips` 和备份目录。
3. 安装固定 MySQL/Redis，配置 bind mount、最小权限账号、AOF/RDB、binlog 和备份 timer。
4. 安装固定 Node.js LTS、Corepack/pnpm 和 Nginx。
5. 安装 `lisglosips@.service`，创建实例 env 文件。
6. 发布到新 release，校验后切换 `/opt/lisglosips/current`。
7. 配置 Nginx 静态站点、API 代理、限流、安全头和内部录音 location。
8. 开发阶段签发私有 CA 证书；生产阶段安装正式域名证书。
9. 验证 443、应用本地端口、服务自启、重启恢复和非授权来源拒绝。

具体文件、命令和回滚方式见三个 Server B Runbook，不在本指南重复保存可能过时的命令副本。

## 6. 后端部署模型

S07 起后端使用 TypeScript、NestJS/Fastify、Prisma、ioredis 和 pnpm monorepo。建议发布产物：

```text
/opt/lisglosips/releases/<release-id>/
├── apps/api/dist/
├── apps/cdr-worker/dist/
├── apps/recording-worker/dist/
├── apps/config-publisher/dist/
├── public/
├── package.json
├── pnpm-lock.yaml
└── node_modules/
```

每个进程使用单独的 systemd 实例和环境文件：

```text
lisglosips@api.service
lisglosips@cdr-worker.service
lisglosips@recording-worker.service
lisglosips@config-publisher.service
```

构建应在 CI 或独立构建目录完成，不在生产 `current` 中执行。锁文件必须冻结，安装使用 `pnpm install --frozen-lockfile`。各实例只获得所需数据库、Redis、目录和网络权限。

## 7. 标准发布流程

1. 记录当前 release、数据库版本、Redis 配置版本和服务状态。
2. 备份 MySQL、Redis 与待修改配置，并校验备份哈希。
3. 将构建产物传到新的唯一 release 目录。
4. 核对产物哈希、Node/pnpm 版本和依赖锁文件。
5. 执行向前兼容数据库迁移；禁止在同一窗口直接删除旧列。
6. 切换 `current`，按依赖顺序重启 API/Worker。
7. 执行内部健康、HTTPS 健康、鉴权、数据库、Redis 与队列探针。
8. 发布 Redis 配置快照，确认 Server A 读取的新版本。
9. 使用 T 发起真实测试呼叫，检查 SIP、RTP、CDR、费用、录音和 HOMER。
10. 观察日志、队列积压、错误率和资源指标后再完成发布。

每次发布都要生成一条交接记录，包含 release ID、迁移版本、验证结果和回滚目标。

## 8. 标准回滚流程

- Web/API：将 `current` 指回上一 release 并重启服务。
- 数据库：优先发布修复迁移；不依赖不可逆 down migration。
- Redis 配置：切回上一 `cfg:active_version`，不删除 Stream。
- CDR Worker：停止消费但保留 Pending/Stream，修复后重放。
- OpenSIPS：恢复已校验配置，先语法检查再 reload。
- RTPEngine：恢复上一 systemd 参数并验证现有通话影响。
- 录音：停止源文件删除，保留 A/B 两端待人工核验。

如果变更涉及防火墙、SSH、数据库数据目录或证书，必须先确认独立控制台/恢复路径可用。

## 9. 后续实施清单

### S07-S08

- 创建后端 monorepo、健康检查、结构化日志、配置校验和测试框架。
- 建立 Prisma Schema、迁移、种子和隔离恢复测试。

### S09-S17

- 实现认证、RBAC、审计、客户/供应商、充值、网关、策略、费率和线路组。
- 金额统一 Decimal；充值和扣费必须事务、幂等且有不可变流水。
- Redis 配置发布使用 Outbox、版本号和回滚，不允许数据库与 Redis 双写漂移。

### S18-S26

- 在 A 部署 OpenSIPS、RTPEngine、录音 tmpfs、HEP 和 exporter。
- 在 T 建立 IP 认证和 SIP 注册两套测试场景。
- 完成 CDR Stream、计费、录音搬运、质检和 Dashboard 聚合。

### S27-S30

- React 从 Mock 切到生成的 API Client。
- 完成端到端、并发、故障、安全与恢复测试。
- 创建阿里云 VPC、安全组、数据盘、正式 DNS/TLS 和监控告警。
- 灰度低风险客户或线路，验证后再全量切换。

## 10. 每阶段完成条件

每个 Sxx 任务只有同时满足以下条件才可标记完成：

- 配置或代码已落地，并有仓库副本。
- 语法、单元/集成或服务健康检查通过。
- 网络暴露和最小权限得到验证。
- 发生重启的服务完成重启恢复验证。
- 备份可校验；涉及数据时完成恢复样例。
- 无明文凭据进入仓库或日志。
- `IMPLEMENTATION_STATUS.md` 已更新产物、验证、回滚、遗留问题和下一任务。

## 11. 阿里云迁移前确认

- 确认预计 CPS、并发、日话单、录音量和保留期。
- 为 A/B 配置同 VPC 低时延私网和独立数据盘。
- 安全组只开放 A 的 SIP/RTP、B 的 443 和受控 SSH 管理端口；SSH 密钥登录必须保留。
- 使用正式域名和可信 TLS 证书，配置续期与告警。
- 替换全部开发凭据和证书，不复制本地 CA 私钥。
- 重新执行防火墙、备份恢复、故障注入和端到端呼叫验收。