88 lines
3.6 KiB
Markdown
88 lines
3.6 KiB
Markdown
# SIP 管理后台
|
|
|
|
独立于仓库其它业务的管理项目：Go 负责最终鉴权、版本/CAS、发布屏障、Cell 状态和统计；TanStack Start 只负责管理页面。运行时不导入 `agent_call`、不读取其它项目数据库、不代理 Python API，也不会因启动而拨打真实电话。
|
|
|
|
## 技术栈与固定基座
|
|
|
|
- 后端：Go 1.26、Fiber v3、Viper、Cobra、Logrus、SQLite、sqlc。
|
|
- 前端：上游 `Kiranism/tanstack-start-dashboard`，锁定提交 `f3375fcce5d2b2fbc35caef776e5a1c61b030439`；许可证保留在 `frontend/LICENSE`，依赖和 `bun.lock` 随项目发布。
|
|
- 契约：`docs/contracts/` 是唯一来源；`contracts/` 是打包后的生成快照，使用 `scripts/sync-contracts.sh --check` 校验。
|
|
|
|
## 本地运行
|
|
|
|
```bash
|
|
cd management/backend
|
|
go test -race ./...
|
|
go vet ./...
|
|
go run ./cmd/management serve
|
|
```
|
|
|
|
默认监听 `127.0.0.1:8080`，默认 SQLite 为 `backend/data/management.db`。首次演示数据：
|
|
|
|
```bash
|
|
MANAGEMENT_DB_PATH=/tmp/agent-call-management.db go run ./cmd/management seed-demo
|
|
curl -H 'Authorization: Bearer dev-admin-token' http://127.0.0.1:8080/admin/v1/sip-status
|
|
```
|
|
|
|
演示数据仅使用合成的 TEST-NET SIP 地址；`dev-*` 令牌仅适用于 `mock` 本地开发，生产必须通过受控环境注入专用令牌和 mTLS 文件。可用令牌域隔离：`dev-admin-token`、`dev-config-token`、`dev-publisher-token`、`dev-observer-token`、`dev-audit-token`、`dev-saas-token`。调度器令牌不会被管理 API 接受。
|
|
|
|
前端另开终端：
|
|
|
|
```bash
|
|
cd management/frontend
|
|
bun install --frozen-lockfile
|
|
VITE_MANAGEMENT_API_URL=http://127.0.0.1:8080 bun run dev
|
|
```
|
|
|
|
页面首次打开后在当前浏览器会话输入管理令牌；令牌不写入源码、URL、localStorage 或日志。
|
|
|
|
## 独立验证
|
|
|
|
```bash
|
|
# contract source/snapshot
|
|
management/scripts/sync-contracts.sh --check
|
|
|
|
# backend
|
|
cd management/backend
|
|
gofmt -w .
|
|
go test -race ./...
|
|
go vet ./...
|
|
|
|
# frontend
|
|
cd ../frontend
|
|
bun run lint
|
|
bun run format:check
|
|
bun run build
|
|
```
|
|
|
|
后端测试覆盖鉴权域隔离、资源范围、幂等重放、CAS 冲突、全 Cell 发布屏障、Mock 意图恢复、观察 boot/sequence、新鲜度和统计事实语义。默认 `mock` 发布不声称 Cell 已应用；需要协议 Mock 完整验收时显式设置 `MANAGEMENT_MOCK_CELL_APPLY=true`。
|
|
|
|
## 模式与安全边界
|
|
|
|
`MANAGEMENT_MODE=mock` 只处理合成/协议 Mock 数据；`MANAGEMENT_MODE=real` 发布前要求 HTTPS Cell Agent、mTLS 客户端证书、CA 和主机白名单，失败时保留原活动版本并保持 admission barrier，绝不静默回退 Mock。SIP 凭据只能是 secret-store reference，管理读取、审计和统计均不返回密钥或完整被叫号码。
|
|
|
|
`real` 模式不会把 `123.56.71.98` 当 SIP 服务端；该地址只作为固定出口白名单事实。真实供应商、MQ/OSS、云资源和真实呼叫验收需要另行安排，不是本项目启动前置。
|
|
|
|
## 一键 Compose 部署
|
|
|
|
从仓库根目录执行：
|
|
|
|
```bash
|
|
docker compose -f management/deploy/compose.yaml up -d --build
|
|
```
|
|
|
|
打开 <http://localhost:3000/dashboard/overview>，输入 `dev-admin-token`。健康检查和日志：
|
|
|
|
```bash
|
|
curl http://localhost:8080/healthz/live
|
|
docker compose -f management/deploy/compose.yaml logs -f management-api
|
|
```
|
|
|
|
停止服务：
|
|
|
|
```bash
|
|
docker compose -f management/deploy/compose.yaml down
|
|
```
|
|
|
|
默认仍是隔离 Mock。使用 Gitea Registry 镜像时，将 `MANAGEMENT_API_IMAGE`、`MANAGEMENT_UI_IMAGE` 传给 `deploy/compose.images.yaml`；镜像由根目录 `.gitea/workflows/management-images.yml` 在 PR 构建、在 `main`/版本标签推送。不要将示例令牌和 Mock 配置用于生产。
|