密钥格式
apm_<48 base62> (SHA-256)
RBAC 作用域
full, read + 12 个细粒度权限
控制面覆盖
7 大 API 域 + /enterprise
遥测与事件
HMAC Webhooks + Prometheus

1. 认证机制、密钥生成与安全控制

每个 Apium Cloud OS 节点都在隔离的控制台路径下暴露控制面(/<console>/api/v1/...)。请求支持通过 X-API-Key: apm_... 或 Authorization: Bearer apm_... 传递凭据。

  • 混合熵密钥生成:在界面中签发密钥时,浏览器会采集鼠标移动坐标与时序(client_entropy)并与 crypto.getRandomValues 混合。服务端将该载荷与两组 32 字符 CSPRNG 字符串及纳秒级时间戳通过 SHA-256 融合,最终生成 apm_<48 base62> 令牌。
  • 明文仅显示一次与哈希存储:原始 apm_... 令牌在创建时仅展示一次,api_keys 存储中仅持久化其 SHA-256 摘要。
  • 网络与生命周期护栏:每个密钥均支持 IP 白名单(allowed_ips)与自动过期时间戳(expires_at)。
  • 审计追踪与 OpenAPI:所有 API 调用均记录在审计日志中(GET /api/v1/api-audit),且节点可导出机器可读的 OpenAPI 规范(apium-cloud-os-openapi.json)用于自动生成 SDK。

2. RBAC 权限作用域矩阵与许可证等级

Apium Cloud OS 摒弃了“全有或全无”的超级令牌,而是通过逗号分隔的作用域强制执行最小权限原则。在免费的 Lite 版本上仅允许 read 只读访问;full 与所有写入权限均需 Pro、Ultra 或 Extra 版本。

API 密钥作用域与最小权限配置方案

访问控制

组合全局或资源级作用域,隔离计费机器人、SRE 监控与 HR 自动化系统。

作用域 / 模式访问级别典型业务密钥配置
full跨所有域的无限制读写权限 (Pro/Ultra/Extra)主编排器或专用 IaC 控制器
read跨资源的全局只读权限(不含 /system/config)集中式节点巡检器或外部 BI 仪表盘
users:read / users:write读取账号与会话 / 创建、续期、吊销、踢出与批量操作Telegram 与 SaaS 计费机器人、HR/IAM 入职开通
groups:read / groups:write查看用户组 / 分配与修改分组策略按部门划分的企业访问自动化
plans:read / plans:write列出套餐计划 / 增删套餐并应用流量整形器商业套餐同步与带宽策略引擎
webhooks:read / webhooks:write列出 Webhook 目标 / 注册或移除 HMAC 端点按租户自动配置事件总线
monitoring:read访问 /overview、/health、/metrics、/sessions、/logs、/api-auditPrometheus 抓取器、Grafana、SIEM 与 SOC 采集器
system:read / system:write系统状态 / 级联模式、上游节点、服务与安全模式控制SRE 故障转移自动化与服务生命周期脚本

3. 覆盖 7 大控制域的完整端点地图

所有管理路由均位于 /<console>/api/v1 下,覆盖节点的完整运维表面:

按功能域划分的端点清单

API 表面

Web 界面中管理的每一个子系统均已开放用于确定性 API 自动化。

功能域核心端点核心能力
用户与批量生命周期GET/POST /users, GET /users/generate, POST /users/bulk-create, POST /users/bulk-extend创建账号、批量开通车队账号,以及批量延长配额或有效期
单用户精细控制GET /users/:id/config, POST /users/:id/extend|revoke|restore|reset-traffic|rotate-token|kick, PUT /users/:id/group|expiration|restrictions, GET /users/:id/sessions获取客户端配置、轮换令牌、踢出在线会话及调整单用户限制
套餐与整形器GET/POST /plans, DELETE /plans/:id, POST /shaper/apply管理资费模板并实时下发带宽/整形规则
级联与上游节点PUT /cascade/mode, POST /upstreams/check, POST /upstreams/:id/toggle, POST /upstreams/:id/reset-traffic切换级联路由模式、探测出口节点、启停上游节点与重置计数器
监控与审计GET /overview, GET /health, GET /metrics, GET /sessions, POST /sessions/:id/kick, GET/DELETE /logs, POST /logs/simulate, GET /api-audit健康检查、Prometheus 遥测、实时会话中断与 API 审计日志
Webhooks 与密钥GET/POST /webhooks, DELETE /webhooks/:id, GET/POST /api-keys, DELETE /api-keys/:id以编程方式管理 HMAC Webhook 订阅者与作用域 API 密钥
服务、安全与许可证POST /services/toggle|restart|update-adblock|unban-ip|clear-auth-logs, PUT /settings/security-mode, GET /license/status, POST /license/activate守护进程控制、Fail2ban IP 解封、AdBlock 更新与许可证激活
Corporate GatewayGET /enterprise/overview, POST /enterprise/users/:id/toggle, .../enterprise/users/:id, .../enterprise/gateways/:id面向 Corporate Gateway 用户与网关节点的专用控制面

4. 实用请求与事件示例

A. 批量用户开通与续期

创建绑定至指定套餐(plan_id)的账号、执行批量开通,或在无需重启传输内核的情况下自动恢复并延长订阅(auto_restore: true):

curl -X POST -H "X-API-Key: apm_..." \
  -H "Content-Type: application/json" \
  -d '{"username":"client_9042","plan_id":1}' \
  https://node.apium.cloud/<console>/api/v1/users

curl -X POST -H "Authorization: Bearer apm_..." \
  -H "Content-Type: application/json" \
  -d '{"add_days":30,"add_quota_gb":100,"auto_restore":true}' \
  https://node.apium.cloud/<console>/api/v1/users/42/extend

B. 公共订阅端点(标准客户端响应头)

诸如 v2rayNG、Nekobox、Streisand 和 Hiddify 等客户端应用只需拉取单个带令牌的 URL,即可获得 Base64 配置文件以及标准的配额与到期响应头:

GET /<console>/api/v1/subscriptions/<sub_token>

< HTTP/1.1 200 OK
< Profile-Title: Apium Cloud OS
< Profile-Update-Interval: 12
< Subscription-Userinfo: upload=104857600; download=2147483648; total=107374182400; expire=1798761600

C. HMAC-SHA256 签名 Webhooks

无需每隔几秒轮询节点,直接配置您的计费后端或 CRM 接收经 X-Apium-Signature 验签的实时推送事件:

POST https://billing.example.com/webhooks/apium
X-Apium-Event: user.created
X-Apium-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

{
  "event": "user.created",
  "timestamp": "2026-11-14T12:30:00Z",
  "data": { "user": { "id": 42, "username": "client_9042", "protocol": "hysteria2" } }
}

D. Prometheus 指标 (GET /api/v1/metrics)

使用具备 monitoring:read 权限的密钥将整个节点车队直接接入 Prometheus 与 Grafana,实时追踪活跃会话、用户总数以及上游级联 RTT:

# TYPE apium_active_sessions gauge
apium_active_sessions 1248
# TYPE apium_users_total gauge
apium_users_total{status="active"} 3410
# TYPE apium_upstream_latency_ms gauge
apium_upstream_latency_ms{id="1",name="NL-AMS-01"} 18

5. 真实集成应用场景

Apium Cloud OS API 的最佳发力点

集成模式

基于 Apium REST API、RBAC 密钥、Webhooks 与 Prometheus 构建的常见生产级架构。

应用场景使用的 API 原语运维收益
Telegram 机器人与 SaaS 计费users:write 密钥 + POST /users, /users/bulk-create, /extend, Subscriptions + Webhooks支付后秒级下发密钥、自动续期、零人工干预
企业 HR / IAM 入离职对接users:write + groups:write + POST /users/:id/kick & /enterprise/...入职自动开通 VPN,离职瞬间吊销在线会话
车队 SRE 与监控告警monitoring:read 密钥 + GET /metrics, /health, /api-audit + IP 白名单搭建 Grafana 仪表盘与告警,且绝不暴露写入权限
级联与整形自动化system:write + plans:write + PUT /cascade/mode, POST /upstreams/check, POST /shaper/apply跨出口国家动态故障转移与自动化带宽管控