120 lines
4.4 KiB
Markdown
120 lines
4.4 KiB
Markdown
# 部署与运维指南
|
||
|
||
## 环境要求
|
||
|
||
- Go 1.24+
|
||
- Netts API v2 账号，并完成：
|
||
- 获取 API Key；
|
||
- 配置 IP 白名单（若使用代理，可在 `config.yaml` 中设置 `netts.realIp`）；
|
||
- 充值余额，以便购买能量周期。
|
||
|
||
## Netts 账号准备流程
|
||
|
||
1. **注册 Workspace 账号**
|
||
- 打开 [https://netts.io/workspace](https://netts.io/workspace) 使用邮箱注册并登录；
|
||
- 首次登录后系统会自动给当前账号生成一组 API Key。
|
||
|
||
2. **完成余额充值**
|
||
- 在 Workspace → Wallet 菜单中充值 TRX（建议先充 10–20 TRX 做验证）；
|
||
- Netts 扣费直接来自账户余额，没有余额将无法下单购买能量。
|
||
|
||
3. **配置 IP 白名单**
|
||
- 进入 Workspace → API → IP Whitelist，将本服务所在服务器的出口 IP 填入；
|
||
- 如果经由代理访问，可在配置文件 `netts.realIp` 中设置对应的公网 IP。
|
||
|
||
4. **获取并保管 API Key**
|
||
- 在 Workspace → API 区域复制 Key；
|
||
- 设置到 `config.yaml` 的 `netts.apiKey` 字段，或通过 `NETTS_API_KEY` 环境变量注入；
|
||
- 生产环境请妥善存储在 Secrets 或 Vault 中。
|
||
|
||
5. **可选：配置回调地址**
|
||
- 若希望接收能量下发事件，可在 Workspace → Host Mode Callback处填写统一回调 URL；
|
||
- 亦可在调用本服务的 `/api/v1/energy/rent` 时传入 `callback_url` 覆盖。
|
||
|
||
6. **API 验证**
|
||
- 使用 cURL/ Postman 请求 `https://netts.io/apiv2/userinfo`，在 Header 中携带 `X-API-KEY` 和 `X-Real-IP`；
|
||
- 当返回 `status=success` 时，说明账号、Key 与白名单均已生效。
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
go build -o bin/netts-energy ./cmd/server
|
||
```
|
||
|
||
可选 Dockerfile（伪代码）：
|
||
|
||
```dockerfile
|
||
FROM golang:1.24-alpine AS builder
|
||
WORKDIR /app
|
||
COPY . .
|
||
RUN go build -o /build/netts-energy ./cmd/server
|
||
|
||
FROM alpine:3.20
|
||
WORKDIR /srv/app
|
||
COPY --from=builder /build/netts-energy /usr/local/bin/netts-energy
|
||
COPY config.example.yaml ./config.yaml
|
||
CMD ["netts-energy", "-config", "/srv/app/config.yaml"]
|
||
```
|
||
|
||
## 运行时配置
|
||
|
||
1. 根据 `config.example.yaml` 编辑正式配置，或注入环境变量（`NETTS_API_KEY` 等）。
|
||
2. 建议通过 systemd / Supervisor 运行，示例：
|
||
|
||
```
|
||
[Unit]
|
||
Description=Netts Energy Orchestrator
|
||
After=network-online.target
|
||
|
||
[Service]
|
||
ExecStart=/srv/netts/netts-energy -config /srv/netts/config.yaml
|
||
Restart=on-failure
|
||
Environment=NETTS_API_KEY=***
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
3. 健康检查：
|
||
- HTTP GET `http://host:port/healthz` 返回 200。
|
||
- 可接入 Kubernetes / Nginx upstream 的健康探测。
|
||
|
||
## CI/CD 建议
|
||
|
||
仓库内置 GitHub Actions workflow (`.github/workflows/ci.yaml`)：
|
||
|
||
- 安装依赖；
|
||
- `go fmt` + `go vet`；
|
||
- `go test ./...`。
|
||
|
||
若需要自动部署服务器，可以在 CI 中加入以下步骤：
|
||
|
||
1. 在 GitHub 仓库配置 Secrets：
|
||
- `SSH_HOST` / `SSH_USER` / `SSH_KEY`；
|
||
- `DEPLOY_PATH` 等自定义变量。
|
||
2. 在 workflow 中追加 job，简例：
|
||
|
||
```yaml
|
||
- name: Deploy
|
||
if: github.ref == 'refs/heads/main'
|
||
run: |
|
||
scp bin/netts-energy ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:${{ secrets.DEPLOY_PATH }}
|
||
ssh ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }} 'systemctl restart netts-energy'
|
||
```
|
||
|
||
> 注：部署脚本默认留空，需根据实际服务器环境完善。
|
||
|
||
## 与现有自动到账系统的集成
|
||
|
||
1. **地址维护**：在充值服务创建新用户地址后，触发一次 `rent` 调用，让服务自动加入 Host Mode。
|
||
2. **归集流程**：在执行 TRC20 归集前调用 `rent` 接口，确保能量充足后再发起链上交易。
|
||
3. **降级策略**：若 Netts API 不可用，可回退到旧的 Feee 方案；建议通过 Prometheus 指标或报警系统监控 `rent` 接口的失败率。
|
||
4. **费用对比**：响应中的 `analysis.cost_breakdown` 与订单 `total_cost` 方便和现有成本核算系统对接。
|
||
|
||
## 运维建议
|
||
|
||
- **日志**：标准输出为结构化日志，建议接入 Loki / ELK 做集中采集。
|
||
- **监控**：结合 Netts webhook 与本服务返回数据，设置周期不足、下单失败等告警。
|
||
- **升级**：新增 Netts 接口（例如 `time/infinitystart`）时，可在 `internal/netts` 中扩展方法并追加 service 策略。
|
||
- **安全**：谨慎保管 API Key；生产环境务必使用 HTTPS 代理或反向代理，限制访问来源。
|