105 lines
4.0 KiB
Markdown
105 lines
4.0 KiB
Markdown
# Netts Energy Orchestrator
|
||
|
||
Netts Energy Orchestrator 是一个使用 Go 实现的独立服务，用于为自动到账系统中的 TRON 地址自动租赁能量。它集成了 [Netts API v2](https://doc.netts.io/api/v2/)，支持地址自动加入 Host Mode、轮询剩余能量周期并按需购买能量租赁周期，从而显著降低 TRC20 归集的手续费。
|
||
|
||
## 功能亮点
|
||
|
||
- ✅ **Netts API 集成**：封装 `usdt/analyze`、`time/add`、`time/status`、`time/order` 等核心接口。
|
||
- 🔁 **自动周期管理**：当剩余周期低于阈值时自动补充，可选自动 Host Mode 注册。
|
||
- 🧩 **独立微服务**：提供 REST API (`POST /api/v1/energy/rent`)，便于与现有到账平台对接。
|
||
- ⚙️ **可配置化**：通过 `config.yaml` 或环境变量管理 API Key、阈值、重试策略等。
|
||
- 📈 **可观察性**：结构化日志、健康检查接口，易于纳入现有监控体系。
|
||
|
||
## 快速开始
|
||
|
||
1. 复制配置模板：
|
||
|
||
```bash
|
||
cp config.example.yaml config.yaml
|
||
```
|
||
|
||
2. 编辑 `config.yaml`，填入 Netts API Key、白名单 IP、Host Mode 回调地址等；或通过环境变量覆盖：
|
||
|
||
```bash
|
||
export NETTS_API_KEY=your-key
|
||
export NETTS_REAL_IP=1.2.3.4
|
||
```
|
||
|
||
3. 运行服务：
|
||
|
||
```bash
|
||
go run ./cmd/server -config config.yaml
|
||
```
|
||
|
||
4. 调用接口租赁能量：
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/energy/rent \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"from_address": "Txxx",
|
||
"to_address": "Tyyy",
|
||
"amount": "200.0"
|
||
}'
|
||
```
|
||
|
||
返回值包含分析结果、是否新增 Host Mode、下单详情以及最新剩余周期。
|
||
|
||
## 配置说明
|
||
|
||
参见 `config.example.yaml`，主要段落如下：
|
||
|
||
- `server`：HTTP 服务监听地址、超时等。
|
||
- `netts`：Netts API 参数（`apiKey` 可通过 `NETTS_API_KEY` 覆盖）。
|
||
- `energy`：
|
||
- `autoAddHost`：是否自动调用 `time/add` 把地址加入 Host Mode。
|
||
- `minCycles` / `targetCycles`：低于最小阈值时补足到目标阈值。
|
||
- `postOrderWait`：下单后等待能量生效的时间。
|
||
- `logging`：日志级别与输出格式（text/json）。
|
||
|
||
更多环境变量详见 `internal/config/config.go` 中的 `envPrefix` 定义。
|
||
|
||
## REST API
|
||
|
||
`POST /api/v1/energy/rent`
|
||
|
||
```json
|
||
{
|
||
"from_address": "源地址（监控地址）",
|
||
"to_address": "归集地址",
|
||
"amount": "USDT 数量，可选，默认 100",
|
||
"callback_url": "可选，覆盖 config 默认回调"
|
||
}
|
||
```
|
||
|
||
响应字段包括推荐能量、下单情况、当前 Host Mode 状态等，详细 schema 请见 `docs/api.md`。
|
||
|
||
## 测试与质量
|
||
|
||
```bash
|
||
go test ./...
|
||
golangci-lint run # 若本地已安装，可执行静态检查
|
||
```
|
||
|
||
CI 流程（`.github/workflows/ci.yaml`）会执行 `go fmt`, `go vet`, `go test`。
|
||
|
||
## 与自动到账系统的集成
|
||
|
||
- 对接点：在归集服务中，当检测到能量不足（或计划归集）时调用本服务接口即可。
|
||
- 配置建议：将主系统的数据库中保存的地址同步到 Netts Host Mode，或在首次归集前调用 `rent` 接口，由服务自动注册/购买能量。
|
||
- 监控：可通过 `/healthz` 结合现有 Prometheus/Consul 健康检查；同时建议订阅 Netts 提供的 webhook 以获知能量下发事件。
|
||
|
||
更多架构细节、部署流程以及 CI/CD 建议请参阅 `docs/architecture.md` 与 `docs/deployment.md`。
|
||
|
||
## Netts 平台接入流程
|
||
|
||
在部署本服务之前，请确保完成 Netts Workspace 的账号准备（详见 `docs/deployment.md` 中的“Netts 账号准备流程”）：
|
||
|
||
1. 注册并登录 [https://netts.io/workspace](https://netts.io/workspace)，生成 API Key；
|
||
2. 在 Wallet 页面充值 TRX，保证账户余额可覆盖租赁费用；
|
||
3. 在 API 设置中配置服务器出口 IP 白名单；
|
||
4. 将 API Key、Real IP、回调地址写入 `config.yaml` 或环境变量；
|
||
5. 通过 `curl https://netts.io/apiv2/userinfo`（携带 `X-API-KEY` 与 `X-Real-IP`）验证连通性。
|
||
|
||
完成上述步骤后，才可由本服务调用 Netts 接口完成能量租赁。
|