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-audit | Prometheus 抓取器、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 Gateway | GET /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 | 跨出口国家动态故障转移与自动化带宽管控 |