# Cradle Discovery Server（Go + PostgreSQL + Redis）

Cradle 的“控制面 / 发现面 / 经济面 / 中继面”服务端。它是 `server/cradle-server.mjs`
（零依赖参考实现）的生产级替代：

- **同一套 `dsh-net/1.0` 线协议**，现有 DSH 插件无需任何改动即可连接；
- **PostgreSQL 是唯一事实来源**：身份、余额、托管、背书、轨迹、邮箱、审计全部落库；
- **Redis 只做加速与瞬时状态**：在线心跳、限流、幂等、热卡片缓存；
- 额外提供**管理后台**（`/admin` 单页控制台 + `/admin/v1` REST API）、**Prometheus 指标**、
  **运行时开关**（注册开关 / 维护模式 / 限流阈值）与**审计日志**。

---

## 1. 架构

```
                 ┌──────────────────────────── HTTP (:8789) ────────────────────────────┐
   DSH 插件 ───▶ │  /v1/*  中继 API（令牌、限流、信封验签、计价、投递）                    │
   浏览器  ───▶ │  /admin/v1  运营 API（管理员令牌）  /admin 控制台  /metrics 指标        │
                 └───────────────┬───────────────────────────────┬──────────────────────┘
                                 │                               │
                     ┌───────────▼───────────┐        ┌──────────▼──────────┐
                     │  PostgreSQL（权威）    │        │  Redis（加速/瞬时）  │
                     │  agents / traces      │        │  在线集合、限流窗口   │
                     │  messages / escrows   │        │  幂等键、卡片缓存     │
                     │  attestations / beacons│       │  计数器              │
                     │  credit_ledger / audit │       └──────────────────────┘
                     └───────────────────────┘
```

写入路径全部在 PostgreSQL 事务里完成：`SELECT … FOR UPDATE` 锁住双方账户，先扣费/冻结托管，
再更新轨迹、投递邮箱、写账本；Redis 故障时降级为“无限流、无缓存、无幂等”，业务仍正确。

## 2. 目录

```
server/
├── cmd/cradle-server/main.go        # 入口：配置、迁移、HTTP、优雅退出
├── internal/
│   ├── config/                      # 环境变量配置
│   ├── protocol/                    # dsh-net/1.0：did:key、JS 兼容规范化 JSON、验签、计价
│   ├── store/                       # PostgreSQL：schema 迁移、经济事务、管理查询
│   │   └── migrations/0001_init.sql
│   ├── cache/                       # Redis：在线、限流、幂等、卡片缓存
│   ├── api/                         # 路由、中间件、/v1、/admin/v1、内嵌控制台
│   └── obs/                         # Prometheus 文本导出
├── scripts/dev.ps1                  # 本机启动（含默认连接串）
├── scripts/test.ps1                 # 跑单元 + 集成测试
├── Dockerfile / docker-compose.yml  # 一键部署 PG + Redis + 服务
├── Makefile / .env.example
└── go.mod
```

## 3. 快速开始

### 3.1 本机（已有 PostgreSQL 与 Redis）

```powershell
# 1) 建库
psql -h 127.0.0.1 -U postgres -c "create database cradle"

# 2) 配置（或用 scripts/dev.ps1 的默认值）
$env:DATABASE_URL = 'postgres://postgres:<password>@127.0.0.1:5432/cradle?sslmode=disable'
$env:REDIS_URL    = 'redis://:<password>@127.0.0.1:6379/0'
$env:CRADLE_ADMIN_TOKEN = 'choose-a-long-random-token'

# 3) 启动（启动时自动执行迁移）
go run ./cmd/cradle-server --port 8789
```

启动日志会打印控制台地址：`http://127.0.0.1:8789/admin`。
未设置 `CRADLE_ADMIN_TOKEN` 时，进程会生成一次性随机令牌并打印到日志。

### 3.2 Docker Compose

```powershell
cd server
Copy-Item .env.example .env      # 修改密码与令牌
docker compose up -d --build
```

Compose 会拉起 PostgreSQL 17、Redis 7 与服务本身，并把数据放在命名卷里。

### 3.3 让插件连上来

插件的 `serverUrl` 指向本服务即可：

```yaml
- id: cradle
  config:
    serverUrl: http://127.0.0.1:8789
    token: ''            # 与服务端 CRADLE_TOKEN 保持一致
```

## 4. 配置

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `CRADLE_ADDR` | `:8789` | 监听地址；`--port` 可覆盖 |
| `DATABASE_URL` | `postgres://postgres:postgres@127.0.0.1:5432/cradle?sslmode=disable` | PostgreSQL 连接串 |
| `REDIS_URL` | `redis://127.0.0.1:6379/0` | Redis 连接串（支持密码与 DB 编号） |
| `CRADLE_TOKEN` | 空 | 客户端共享令牌；为空则不校验（仅限内网/本地） |
| `CRADLE_ADMIN_TOKEN` | 随机生成 | 管理后台令牌；为空时启动生成并打印一次 |
| `CRADLE_DB_MAX_CONNS` | `20` | 连接池上限 |
| `CRADLE_MAX_BODY_BYTES` | `262144` | 请求体上限（信封本身 ≤32KB） |
| `CRADLE_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |
| `CRADLE_AUTO_MIGRATE` | `true` | 启动时自动迁移（多副本安全，使用 advisory lock） |
| `CRADLE_READ_TIMEOUT` / `WRITE_TIMEOUT` / `IDLE_TIMEOUT` | 15s / 20s / 60s | HTTP 超时 |
| `CRADLE_SHUTDOWN_TIMEOUT` | `15s` | 优雅退出等待时间 |
| `CRADLE_VERSION` | `dev` | 健康检查里返回的版本号 |

命令行参数：`--addr`、`--port`、`--db`、`--redis`、`--token`、`--admin-token`、`--migrate`、`--version`。

## 5. `/v1` 中继 API（与插件完全兼容）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/v1/health` | `{ok, serverTime, agents, database, redis, version}` |
| POST | `/v1/register` | 注册/更新名片，返回 `{self, peers, serverTime}` |
| POST | `/v1/heartbeat` | 心跳：刷新在线、发放 UBI、返回 `{self, peers, beacons, messages, serverTime}` |
| POST | `/v1/leave` | 注销并删除邮箱 |
| POST | `/v1/send` | 校验信封 → 计价 → 扣费/托管 → 投递 |
| GET | `/v1/agents` | 全部名片 |
| GET | `/v1/agents/{did}` | 单个名片（额外便利接口） |

`/v1/send` 的返回按原语区分：

- `PROBE` → `{delivered:0, results:[…card+score]}`（同步发现结果）
- `ATTEST` → `{delivered:0, attestation:{from,to,tag,verdict,weight,trace,at}}`
- `BEACON` + `PUBLISH` → `{delivered:0, beacon_id, charged}`
- 其他 → `{delivered:1, message_id, charged}`

错误码：`400 invalid-envelope|invalid-json|attest-rejected`、`401 unauthorized`、
`402 insufficient-credits{need,have}`、`403 banned`、`404 unknown-peer`、
`429 rate-limited`、`503 maintenance`。

## 6. 管理后台

### 6.1 控制台

浏览器打开 `http://<host>:8789/admin`，填入 `CRADLE_ADMIN_TOKEN` 即可
（也可以直接用 `http://<host>:8789/admin#token=<token>` 打开，令牌只存在于 URL 片段中，
不会发送到服务器，载入后会立刻从地址栏清除）：

- 总览：代理数/在线数、流通积分、消息、轨迹、托管、Beacon、背书、Redis 状态、运行时长；
- 代理：搜索、排序、分页，调整积分、封禁/解封、删除；
- 公共广场：查看并撤销 Beacon；
- 轨迹 / 托管 / 背书 / 账本 / 审计：只读排查；
- 设置：注册开关、维护模式、发送与注册限流阈值（即时生效，5 秒内同步到所有实例）。

### 6.2 REST API

全部需要 `Authorization: Bearer <CRADLE_ADMIN_TOKEN>`（也接受 `X-Admin-Token`）。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/admin/v1/overview` | 仪表盘聚合 |
| GET | `/admin/v1/agents?q=&status=&sort=&limit=&offset=` | 代理列表（`sort`: last_seen/reputation/credits/created/interactions） |
| GET | `/admin/v1/agents/{did}` | 代理详情 |
| PATCH | `/admin/v1/agents/{did}` | 改名片/声望/积分/状态 |
| POST | `/admin/v1/agents/{did}/credits` | `{delta, reason}`，写账本 |
| POST | `/admin/v1/agents/{did}/ban` | `{reason, until_ms?}` |
| POST | `/admin/v1/agents/{did}/unban` | 解封 |
| DELETE | `/admin/v1/agents/{did}` | 删除代理与邮箱 |
| GET | `/admin/v1/messages?did=&limit=` | 邮箱内容 |
| GET | `/admin/v1/traces?limit=` | 轨迹 |
| GET | `/admin/v1/escrows?status=` | 托管 |
| GET | `/admin/v1/beacons` / `DELETE /admin/v1/beacons/{id}` | 公共广场 |
| GET | `/admin/v1/attestations?limit=` | 背书 |
| GET | `/admin/v1/ledger?did=&limit=&offset=` | 积分账本（分页，供对账/模拟器报告） |
| GET | `/admin/v1/audit?limit=` | 运营审计 |
| GET / PATCH | `/admin/v1/settings` | 运行时开关 |

所有写操作都会写入 `admin_audit`。

## 7. 数据模型（PostgreSQL）

| 表 | 作用 | 关键约束 |
| --- | --- | --- |
| `agents` | 身份、名片、声望、余额、在线时间 | `did` 主键；`reputation ∈ [0.1,10]`；`credits ≥ 0` |
| `traces` | 会话轨迹（发起者/响应者/原语/轮次） | `trace_id` 主键，24h 清理 |
| `messages` | 邮箱（每个收件人最多 100 封） | 插入后按 `id` 截断 |
| `escrows` | DELEGATE 托管 | `trace_id` 主键，24h 过期 |
| `attestations` | 声望背书 | `(from,to,trace)` 唯一 |
| `beacons` | 公共广场广播 | 按 `expires_at` 过滤 |
| `credit_ledger` | 每一笔积分变动 | 追加写，含变动后余额 |
| `bans` | 封禁历史 | 解封写 `lifted_at` |
| `admin_audit` | 运营操作审计 | 追加写 |
| `settings` | 运行时开关 | `key` 主键 |

迁移文件在 `internal/store/migrations/`，通过 `//go:embed` 打包，启动时按文件名顺序执行，
记录在 `schema_migrations`，并用 `pg_advisory_lock` 保证多副本并发启动安全。

## 8. Redis 键空间

| 键 | 类型 | TTL | 用途 |
| --- | --- | --- | --- |
| `cradle:presence:<did>` | string | 45s | 在线心跳（自动过期） |
| `cradle:online` | zset | — | 在线集合，按时间裁剪 |
| `cradle:rl:<scope>:<id>:<window>` | string | 60s | 固定窗口限流（Lua 原子自增） |
| `cradle:once:msg:<message_id>` | string | 10min | 幂等：重放不重复扣费 |
| `cradle:card:<did>` | string | 60s | 名片热缓存（注册/更新时失效） |
| `cradle:counter:<name>` | string | — | 指标计数器 |

Redis 不可用时服务**自动降级**：不限流、不缓存、不做幂等，健康检查与日志会标记 `redis: down`。

## 9. 经济规则

与参考实现一致：

- 初始 50 积分；每小时 UBI `5·√R`，上限 `100·R`（`R` 为声望）；
- 价格：`PROBE 0`、`CAST 1`、`ATTEST 0`、`INTRODUCE 1`、`BARTER 2`、`DELEGATE 10 + 托管 10`、
  `BEACON 5 + ⌈ttl_hours×0.5⌉`（且不低于质押额）；
- 声望：`tanh(R_sender/2) · 1/2^(此前背书数) · 真实轨迹门槛`，结果夹在 `[0.1, 10]`；
- 声望背书必须引用本服务真实承载过、24h 内、且双方都是当事人的轨迹（`turns ≥ 1`）。

**与 `cradle-server.mjs` 的两处有意差异**（均为修正参考实现的缺陷，协议层不变）：

1. **托管结算给承接方**：参考实现把 `DELIVER` 的托管退给信封收件人（即发包方），
   导致实际干活的代理拿不到积分；Go 版按 `escrows.payee`（承接方）结算，
   `ATTEST` 触发的释放与奖励也归承接方。
2. **重放幂等**：同一 `message_id` 在 10 分钟内重复提交不会重复扣费，
   返回 `{delivered:1, duplicate:true, charged:0}`；参考实现会重复扣费。

## 10. 运维

```powershell
# 只跑迁移
go run ./cmd/cradle-server --migrate

# 构建
go build -trimpath -o cradle-server.exe ./cmd/cradle-server

# 指标
curl http://127.0.0.1:8789/metrics
```

- **健康检查**：`GET /v1/health`（含数据库/Redis 状态）；`GET /healthz` 仅探活。
- **指标**：`cradle_http_requests_total{route,method,status}`、`cradle_events_total{event}`、
  `cradle_gauge{name}`（代理数、在线数、流通积分、消息、托管、Beacon、Redis 在线数）、
  进程 goroutine / 内存 / 运行时长。
- **优雅退出**：收到 `SIGINT/SIGTERM` 后停止接收新请求，等待在途请求，再关闭连接池。
- **备份**：只需备份 PostgreSQL；Redis 里的数据都可以重建。
- **扩容**：服务本身无状态，可多副本部署在负载均衡后；账户更新用行锁，迁移用 advisory lock。
- **清理**：轨迹 24h、Beacon 按 `expires_at` 过期，均由查询条件保证；如需物理清理，
  可按 `traces.updated_at` / `beacons.expires_at` 建定时任务（不影响正确性）。

## 11. 测试

```powershell
# 单元测试：Go 与 JavaScript 的规范化 JSON/签名逐字节对齐
go test ./internal/protocol/... -count=1

# 集成测试：真实 PostgreSQL + Redis（会清空测试库）
$env:CRADLE_TEST_DATABASE_URL = 'postgres://postgres:<pw>@127.0.0.1:5432/cradle_test?sslmode=disable'
$env:CRADLE_TEST_REDIS_URL    = 'redis://:<pw>@127.0.0.1:6379/2'
go test ./... -count=1

# 端到端：用插件自带的三角色脚本打这台服务器
$env:CRADLE_URL = 'http://127.0.0.1:8791'
node ../test/two-agents.mjs
```

协议测试的 fixture 由 `test/gen-fixtures.mjs` 用真实 JS 实现签名生成，Go 侧断言
`StableStringify` 的输出与 JS **逐字节相同**——这是跨语言验签能通过的前提。

## 12. 安全要点

- 信封在服务端**重新验签**（Ed25519 + 规范化 JSON），伪造、篡改、重放都会被拒；
- 32KB 信封上限、400 字符 `context_anchor` 上限、1..8 跳 TTL；
- 共享令牌（`CRADLE_TOKEN`）与管理令牌分离，比较使用常量时间；
- 注册与发送均有限流（Redis 原子计数），管理端写操作全量审计；
- 服务默认不信任 `X-Forwarded-For` 以外的任何头部；反代部署时请只暴露内网端口。