Cloud Blox文档
开始部署

安全与可观测性

安全边界

Cloud Blox 同时暴露管理、S3、资源访问、WebDAV 和客户端协议。不同入口使用不同认证方式，但最终都必须落到用户、存储桶、对象和路径权限。

flowchart LR
    Admin[管理控制台] -->|Bearer Token| AdminAPI[管理 API]
    S3Client[S3 客户端] -->|SigV4 / 预签名| S3[S3 API]
    Browser[资源访问] -->|ACL / 预签名 / 防盗链| Access[Access]
    Dav[WebDAV 客户端] -->|Basic Auth + TLS| WebDAV[WebDAV]
    Desktop[桌面客户端] -->|设备会话| ClientAPI[客户端 API]
    Node[区域节点] -->|内部签名 + 防重放| Internal[节点间请求]

身份认证

管理控制台

管理控制台使用 JWT Bearer Token。用户登录后，Token 与角色、权限和可访问菜单共同决定控制面访问范围。登出、密码修改和权限收缩应能够使旧 Token 失效。

浏览器 Token 使用持久存储，优点是刷新后仍保持登录，风险是页面脚本一旦被注入即可读取。因此 HTTPS、内容安全策略和第三方脚本治理是控制台安全的一部分。

桌面客户端

桌面客户端使用独立设备会话：

  • Access Token 只存在于客户端原生进程内存；
  • Refresh Token 轮换，旧 Token 使用后失效；
  • 服务端只保存 Refresh Token 的哈希；
  • 设备可单独撤销，也可全部撤销；
  • 设备同步前缀限制其可访问路径；
  • 后台传输票据绑定方向、存储桶和对象或上传会话，短时有效且可撤销。

桌面系统上的 Refresh Token 依赖应用数据目录权限保护，终端还应启用系统磁盘加密、屏幕锁和设备管理。

S3

S3 入口支持标准签名和预签名 URL。密钥应按用户和用途拆分，定期轮换，并只授权必要存储桶和操作。

WebDAV

WebDAV 使用存储桶级账号和 Basic Auth，必须通过 HTTPS 使用。账号应限制读写权限和路径范围，避免共用管理员密码。

节点内部认证

跨区域代理和内部健康检查使用共享秘密、请求签名和防重放状态。未完整配置内部秘密时，相关信任能力应关闭，而不是自动进入弱认证模式。

授权与访问控制

平台提供多层授权：

  • 管理端 RBAC 和按钮权限；
  • 发行版功能门控；
  • 存储桶所有权；
  • 公开读、公开写和私有访问策略；
  • S3 密钥的桶级授权；
  • WebDAV 账号的读写和路径范围；
  • 桌面设备同步前缀；
  • IP、Referer 和 User-Agent 防盗链；
  • 存储桶级 CORS；
  • 欠费停服策略；
  • 内容审核结果拦截。

前端隐藏按钮只是体验优化，真正的权限判断必须由服务端执行。

秘密与凭据

生产环境需要保护：

  • MySQL、Redis 和 ClickHouse 密码；
  • JWT 密钥；
  • 全局预签名与内部节点密钥；
  • S3 密钥；
  • 存储通道凭据和 Cookie；
  • 支付、通知、审核和 CDN 凭据；
  • 桌面客户端 Refresh Token；
  • TLS 私钥和客户端发布签名材料。

建议：

  • 不把真实秘密写入镜像或文档；
  • 使用安装脚本生成随机秘密；
  • .env 和配置目录只授予运行账户访问；
  • 关键环境接入外部秘密管理；
  • 建立轮换和吊销流程；
  • 日志、错误和外部推送统一清洗敏感字段。

当前需要优先加固的安全项

初始管理员

默认管理员使用固定初始密码。生产安装应改为一次性随机密码、首次登录强制修改，且禁止在普通日志中输出明文密码。

HTTPS 与安全响应头

应用本身不终止 TLS。生产部署必须由反向代理提供 HTTPS，并统一启用：

  • HSTS；
  • Content Security Policy；
  • 防点击劫持策略；
  • MIME 嗅探保护；
  • 合理的 Referrer Policy；
  • 管理端与资源域名分离。

外部连接证书校验

不同存储和外部服务连接的 TLS 策略需要统一。证书校验应默认开启，不安全模式必须显式配置、醒目标记并限制到受控内网。

容器运行权限

标准应用容器仍需要加强最小权限：

  • 使用非 root 用户；
  • 只挂载必要目录；
  • 只开放必要端口；
  • 尽可能使用只读根文件系统；
  • 删除不需要的 Linux capabilities；
  • 限制管理和数据库网络。

桌面服务地址

桌面客户端可连接用户输入的服务地址。生产账号应只允许 HTTPS，本机开发地址可以保留受控例外。

日志体系

应用按职责区分日志：

  • 应用启动与通用日志；
  • 管理 API；
  • S3；
  • 资源访问；
  • WebDAV；
  • 计划任务；
  • 队列消费者；
  • 存储插件；
  • 跨区域转发；
  • 支付。

文件日志支持轮转；访问、通道、副本、计费事件和节点历史指标进入 ClickHouse。请求使用统一请求标识，便于关联入口日志和业务日志。

敏感查询参数、签名、Token、密码和未知请求头应在日志出口统一清洗。外部日志推送还需要限制并发、超时和重试，避免接收端故障拖垮应用。

健康探针

  • 存活探针只确认进程存在；
  • 就绪探针决定节点是否可以接收流量；
  • 综合健康检查用于运维诊断，包括数据库、Redis、ClickHouse、队列、计划任务、日志、媒体工具、节点信息和磁盘。

就绪状态必须与部署声明一致。如果 Redis、ClickHouse 或异步上传被配置为当前发行版的必需能力，初始化失败时不能仍然报告完全就绪。

指标与仪表盘

当前可选 Prometheus 指标主要覆盖 HTTP 请求量和延迟，并使用低基数的路由模板。ClickHouse 与 Grafana 可用于访问日志和历史节点指标。

生产环境仍需要补充：

  • 队列深度、最老任务年龄和失败率；
  • Worker 并发、执行耗时和租约回收；
  • 计费事件积压、死信和小时快照完整率；
  • 各通道成功率、吞吐和延迟；
  • 缓存命中率、索引失败和淘汰数量；
  • 临时目录、缓存和数据盘水位；
  • MySQL、Redis、ClickHouse 连接池；
  • 外部审核、通知、支付和 CDN 的错误率；
  • 桌面客户端版本、会话和同步错误概览。

追踪

当前请求标识可用于日志关联，但不等同于跨服务分布式追踪。多区域代理、异步任务、存储插件和外部服务调用需要传播统一追踪上下文，才能还原完整链路。

建议的服务级目标

生产环境应先定义少量可操作的 SLO：

  • 管理 API 和对象读取可用性；
  • 上传接收成功率；
  • 上传从接收到最终可用的延迟；
  • 下载首字节时间；
  • 异步任务成功率和最大积压年龄；
  • 计费事件投递延迟；
  • 小时快照完整率；
  • 备份成功率和恢复时间；
  • 桌面同步成功率和冲突率。

每个 SLO 都应绑定告警、值班响应和故障复盘，而不仅是展示图表。

部署拓扑、备份与升级步骤见部署与运维架构。