85d495dd16
- add batch-scoped reconcile_runs persistence and queries - route batch detail and reconcile writes through batch_id/host_id - refresh production boards with host-scope acceptance artifacts - include latest real-host acceptance evidence for self_service and subscription
76 lines
2.6 KiB
Markdown
76 lines
2.6 KiB
Markdown
# Sub2API CN Relay Manager 部署指南
|
|
|
|
## 概览
|
|
|
|
Sub2API CN Relay Manager 是一个 Go 控制面服务，用于：
|
|
- 注册并探测 sub2api 宿主
|
|
- 安装 pack / 导入 provider
|
|
- 记录 import batch / managed resources / access closure / reconcile 结果
|
|
- 执行基于已记录资源集的回滚
|
|
|
|
当前内置运行面能力以最小生产闭环为主：
|
|
- 已内置：`/healthz`、SQLite 状态库、宿主注册与探测、导入/回滚/对账 API
|
|
- 未内置：`/metrics`、限流、配额治理、Prometheus/Grafana 集成
|
|
|
|
## 前置条件
|
|
|
|
| 组件 | 版本 | 说明 |
|
|
|---|---|---|
|
|
| Go | 1.22+ | 构建与本地运行 |
|
|
| SQLite | 3.40+ | 内嵌状态库，需持久化挂载 |
|
|
| Docker / Podman | 4.x+ | 本地容器验收可选 |
|
|
| 控制面 Admin Token | - | 调用控制面 API |
|
|
| 宿主 Admin 凭据 | - | 注册 host 时写入控制面，用于后续 import / reconcile / rollback |
|
|
|
|
## 快速启动
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# 至少设置 SUB2API_CRM_ADMIN_TOKEN
|
|
|
|
docker compose up --build -d
|
|
curl -fsS http://127.0.0.1:18081/healthz
|
|
```
|
|
|
|
或本地直接运行：
|
|
|
|
```bash
|
|
SUB2API_CRM_ADMIN_TOKEN=change-me-before-production SUB2API_CRM_LISTEN_ADDR=127.0.0.1:18081 SUB2API_CRM_SQLITE_DSN='file:/tmp/sub2api-cn-relay-manager.db?_foreign_keys=on&_busy_timeout=5000' go run ./cmd/server
|
|
```
|
|
|
|
## 关键配置
|
|
|
|
| 变量 | 说明 | 示例 |
|
|
|---|---|---|
|
|
| `SUB2API_CRM_ADMIN_TOKEN` | 控制面 Bearer token | `crm-admin-token` |
|
|
| `SUB2API_CRM_LISTEN_ADDR` | 监听地址 | `:18081` |
|
|
| `SUB2API_CRM_SQLITE_DSN` | SQLite DSN | `file:/tmp/sub2api-cn-relay-manager.db?_foreign_keys=on&_busy_timeout=5000` |
|
|
|
|
## 上线前验证
|
|
|
|
```bash
|
|
gofmt -l .
|
|
go vet ./...
|
|
go test ./...
|
|
go test -race ./...
|
|
go test ./tests/integration/... -count=1
|
|
go test -cover ./internal/...
|
|
```
|
|
|
|
## 生产注意事项
|
|
|
|
- host 注册后，后续 `preview-import / import / reconcile / access / rollback-provider / status / resources / import-batches` 应统一使用 `host_id` 或 `host_id` 查询参数，不再依赖临时 `host_base_url` 作为运行时主键。
|
|
- 状态库会持久化宿主认证信息；部署时必须把 SQLite 文件放到受限目录并纳入备份/权限管理。
|
|
- `rollback-provider` 现在只按已记录的 managed resources 回滚；若缺少批次资源记录，会拒绝危险删除。
|
|
- capability probe 已改为无副作用探测，但仍建议先在预生产宿主验证后再接入生产宿主。
|
|
|
|
## 真实能力边界
|
|
|
|
当前文档不应宣称以下能力已经内置：
|
|
- `/metrics`
|
|
- Prometheus / Grafana 接入
|
|
- 限流 / quota enforcement
|
|
- 完整审计日志面板
|
|
|
|
这些能力若为上线要求，需要单独实现后再升级部署结论。
|