bc-netts-energy/docs/deployment.md

部署与运维指南

环境要求

• Go 1.24+
• Netts API v2 账号，并完成：
  • 获取 API Key；
  • 配置 IP 白名单（若使用代理，可在 config.yaml 中设置 netts.realIp）；
  • 充值余额，以便购买能量周期。

Netts 账号准备流程

1. 注册 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 与白名单均已生效。

构建

go build -o bin/netts-energy ./cmd/server

可选 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，简例：

   - 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 代理或反向代理，限制访问来源。