Cloud Blox文档
开始部署

安装教程

本文介绍如何通过 安装脚本 安装、部署与日常管理 Cloud Blox。产品以安装包形式交付，内含一键安装脚本，自动完成数据库选型、端口配置、编排文件生成与服务启动，无需从源码编译。

一、使用介绍（Cloud Blox 能做什么）

安装完成后，你可以：

  • 管理后台：通过浏览器登录 Web 控制台，管理用户与权限、存储桶与文件、存储通道、系统配置、计费与任务等
  • 对象存储：创建存储桶，上传、下载、删除文件，配置绑定域名、回源、备份、访问控制、CORS、S3 密钥、WebDAV 账号等
  • S3 兼容访问：使用 AWS CLI、s3cmd、MinIO Client 或各语言 SDK，通过 S3 接口上传下载、列举、分片上传
  • WebDAV 访问：挂载为网络磁盘，通过 WebDAV 协议直接读写存储桶中的文件
  • 资源访问：为存储桶绑定访问域名后，通过该域名直接访问桶内文件，并可在 URL 上带参数做图片/视频处理（缩放、裁剪、水印、截帧等）
  • 计费：按存储、流量、请求、媒体处理等用量日结算，支持套餐、资源包与用户钱包

详细功能与各模块使用方式见 功能总览 及各专题文档。

二、环境要求

项目说明
Docker20.10 及以上。安装脚本可检测未安装时提示是否自动安装（支持 Ubuntu/Debian、CentOS/RHEL 等）
Docker ComposeV2 插件（docker compose）或 V1（docker-compose）。未检测到时脚本可引导安装
内存最低 2GB，推荐 4GB+
磁盘安装目录所在分区至少约 2GB 可用空间，脚本会做检查

MySQL、Redis、ClickHouse 由安装脚本通过 Docker 自动部署（也可选择使用已有外部实例），因此无需在宿主机单独安装数据库。

三、获取安装包

从官方发布渠道获取与你的发行版、服务器 CPU 架构对应的安装包：

发行版获取渠道
免费版官网下载页或官方发布渠道
商业版 / 源码版购买授权后由官方交付渠道提供，不在公开渠道发布

3.1 产物命名

所有服务端产物统一命名为 cloud-blox-<类型>-<版本>-<系统>-<架构>-<发行版>，其中「架构」为 amd64 或 arm64，「发行版」为 free、commercial 或 source：

产物文件名示例适用场景
一键安装包（本文）cloud-blox-install-1.0.2-linux-amd64-free.tar.gz推荐。自带 install.sh、安装载荷与运行时镜像，可选由 Docker 一并部署 MySQL / Redis / ClickHouse
一键安装包（精简）cloud-blox-install-1.0.2-linux-amd64-free-lite.tar.gz不内置运行时镜像，安装时在目标机器上构建；体积更小
裸二进制包cloud-blox-server-1.0.2-linux-amd64-free.tar.gz已有数据库、不使用 Docker 时直接运行二进制（附 systemd 单元）
Docker Compose 在线包cloud-blox-docker-online-1.0.2-free.tar.gz目标机器可访问镜像仓库，安装时拉取应用镜像
Docker Compose 离线包cloud-blox-docker-offline-1.0.2-linux-amd64-free.tar.gz内网 / 离线环境，内置应用镜像

下载目录中同时提供 checksums.txt，安装前可用 sha256sum -c checksums.txt 校对完整性。下文以一键安装包为准。

3.2 安装包内容

安装包根目录（解压后）仅保留：

文件说明
README.md安装包内简要说明
install.sh一键安装脚本（交互式配置或非交互执行）
release.env安装包元数据：版本号、发行版、目标系统与架构、构建时间。安装脚本据此做架构与版本校验，请勿修改
install-package.tar.gz安装载荷（服务端二进制、Web 管理端资源、运行时构建文件；安装时再解压到目标目录）
cloud-blox-runtime.tar预构建运行时镜像（精简包不含；无则安装时从载荷内的运行时构建文件构建）

二进制、前端资源与运行时构建文件不直接摊在安装包根目录，由 install.sh 在安装过程中解压到你指定的安装目录。

解压后进入目录，例如：

Shell
tar -xzf cloud-blox-install-1.0.2-linux-amd64-free.tar.gzcd cloud-blox-install-1.0.2-linux-amd64-free

四、运行安装脚本

4.1 命令用法

Shell
bash install.sh [选项]
选项说明
（无）交互式安装：逐步提示配置项，带默认值
--yes / -y非交互模式：全部使用默认值，适合自动化部署
--upgrade检测到已有安装时直接升级，不再询问；同版本重复执行安全，配置与数据不变
--install-dir DIR指定安装目录（默认：当前目录下的 cloud-blox）
--no-start安装 / 升级完成后不启动服务，稍后手动执行 ./manage.sh start
--force允许降级、跨架构或切换发行版（默认拒绝，避免误操作）
--output / -o DIR仅 region-pack：指定输出目录
--version / -V显示安装包版本后退出
--help / -h显示帮助

子命令：

子命令说明
region-pack在已安装的主节点上生成区域节点安装包（自动检测是否支持）

示例：

Shell
# 交互式安装（推荐首次安装）bash install.sh# 全默认值自动安装（主节点）bash install.sh --yes# 区域节点自动安装（仅连接已有数据库）NODE_TYPE=region bash install.sh --yes# 指定安装目录bash install.sh --yes --install-dir /opt/cloud-blox# 已有安装直接升级（保留配置和 data/）bash install.sh --upgrade --install-dir /opt/cloud-blox# 自动化升级，只更新文件、稍后手动启动bash install.sh --upgrade --yes --no-start --install-dir /opt/cloud-blox# 查看安装包版本bash install.sh --version# 主节点生成区域安装包bash install.sh region-pack --install-dir /opt/cloud-blox# 自定义端口与密码后自动安装ADMIN_PORT=8080 MYSQL_PASSWORD=my_pwd bash install.sh --yes

非交互模式可配合环境变量（与 --yes 一起使用）：

环境变量说明默认值
NODE_TYPE部署类型：main（主节点）或 region（区域节点，仅连已有库）main
ADMIN_PORT管理后台端口38002
S3_PORTS3 API 端口38003
ACCESS_PORT资源访问端口38004
DAV_PORTWebDAV 端口38005
MYSQL_PASSWORDMySQL 应用用户密码（未设置时随机生成）（随机）
MYSQL_ROOT_PASSWORDMySQL root 密码（Docker 模式，未设置时随机生成）（随机）
REDIS_PASSWORDRedis 密码（未设置时随机生成）（随机）
CLICKHOUSE_PASSWORD / CH_PASSWORDClickHouse 密码（未设置时随机生成）（随机）
REGION_MAIN_HOSTregion-pack：主节点对区域节点可达的地址（探测局域网 IP）

4.2 安装前检查（脚本自动执行）

  • CPU 架构：比较安装包 release.env 中的目标架构与本机架构（amd64 / arm64），不一致时拒绝安装并提示应下载的包名；只有明确知道后果时才用 --force 跳过
  • Docker：未安装时可选择自动安装；已安装但未运行时会尝试启动；当前用户无权限访问 Docker 时会提示加入 docker 组或使用 sudo
  • Docker Compose：未检测到时会提示安装 Compose 插件
  • 安装目录：未指定时默认为当前目录下的 cloud-blox；实例名由安装目录名自动推导（用作 Docker 项目名与容器前缀）
  • 磁盘空间：安装目录所在分区至少约 2GB，不足时会警告并询问是否继续
  • 端口占用：管理后台、S3、资源访问、WebDAV 及 MySQL/Redis 映射端口（若启用）会做冲突检测，有冲突时提示是否继续

4.3 已有安装时的选择（升级 / 全新安装 / 打包区域节点）

若安装目录下已存在 docker-compose.yaml，脚本会识别为已有安装，先比较安装目录中记录的版本与本安装包版本：

版本关系行为
安装包 更新正常升级
版本 相同视为重装：重新展开程序文件与编排，配置与数据不变，可安全重复执行
安装包 更旧拒绝降级并退出；确需回退时加 --force，并自行确认数据库结构兼容
发行版不同（如 free → commercial）默认拒绝，--force 后按升级处理

随后提示：

  1. 升级：更新服务端二进制、前端资源、运行时镜像、编排文件与管理脚本，保留 configs/config.yaml 与 data/ 下的全部运行数据
  2. 全新安装：重新走一遍配置流程，覆盖 config.yaml、docker-compose.yaml、manage.sh（不会删除数据目录）
  3. 打包区域节点：与 bash install.sh region-pack 相同，自动检测当前是否为主节点并生成区域安装包
  4. 取消

升级时无需再次输入 MySQL/Redis 等配置，脚本会从现有 config.yaml 与 docker-compose.yaml 解析并沿用。带 --upgrade 时跳过上述菜单直接升级，适合自动化。

五、配置项说明（交互式安装时）

全新安装时，脚本会按顺序引导以下配置。

5.1 部署类型

类型说明
主节点（默认）可创建本地 MySQL/Redis/ClickHouse 或使用已有实例；负责数据库迁移、默认数据初始化、全部定时任务
区域节点仅连接已有数据库，不创建任何数据库容器；仅运行区域任务（清理、副本备份等）

多节点部署时，只需一个主节点，其他机器选择区域节点。

5.2 MySQL

  • 选项 1：使用 Docker 部署（推荐）
    自动创建 MySQL 容器，需输入：应用用户名（默认 cloud-blox）、数据库名（默认 cloud_pool）、应用用户密码与 root 密码（未填则随机生成）、映射到宿主机的端口（默认 38007，填 0 表示不映射）。
  • 选项 2：使用已有 MySQL
    需输入：地址、端口、用户名、密码、数据库名；脚本会通过 extra_hosts 让容器访问宿主机上的 MySQL。

5.3 Redis / ClickHouse 端口映射

主节点部署时，脚本会询问是否将 Redis、ClickHouse 映射端口到宿主机（默认「否」）。选「是」时，后续会询问具体映射端口（Redis 默认 38006，ClickHouse HTTP 默认 38008、Native 默认 38009）；选「否」则均不映射。

5.4 Redis

  • 选项 1：使用 Docker 部署（推荐）
    自动创建 Redis 容器，需输入：密码（未填则随机生成）、DB 编号（默认 0）。
  • 选项 2：使用已有 Redis
    需输入：地址、端口、密码、DB 编号。

5.5 ClickHouse（日志与统计）

  • 主节点：通过 Docker 部署，库名 cloud_pool_logs；建议设置密码（未填则随机生成），便于区域节点安全访问。
  • 区域节点：仅连接外部实例，需输入地址、端口、数据库名、用户名、密码。

5.6 应用端口

端口默认值说明
管理后台38002Web 控制台与 API
S3 API38003S3 兼容接口
资源访问38004绑定域名访问文件与媒体处理
WebDAV38005WebDAV 协议

端口需在 1–65535 之间；脚本会校验格式并检测占用。

5.7 高级配置

  • JWT 密钥、Presign 密钥、管理员初始密码：由脚本自动随机生成，无需输入；管理员初始密码仅在安装结束时打印一次，首次登录后必须修改。
  • 异步上传、媒体处理、缓存 TTL 等可在安装完成后于「系统管理 → 配置」中修改。
  • 密码经 HTTPS 明文提交，无需再配置 RSA / AES。

配置确认后，脚本会询问「确认以上配置，开始安装」，确认后进入安装步骤。

六、安装步骤（脚本自动执行）

  1. 创建安装目录结构

    在目标安装目录下创建 configs、public、backups，以及 compose 同级的 data/（storage、storage_temp、cache、logs；主节点另含 mysql、redis、clickhouse）。区域节点不创建数据库数据子目录。已有旧安装若数据仍在根目录 storage/ 等位置，升级时会继续使用原路径。

  2. 解压安装载荷

    将 install-package.tar.gz 解压到安装目录，展开 cloud-blox-server、public/ 与运行时构建文件。

  3. 准备服务端二进制与前端资源

    确认安装目录内 cloud-blox-server 可执行、public/ 已就绪（用于管理后台静态资源）。

  4. 准备运行时镜像

    • 若安装包内有 cloud-blox-runtime.tar，脚本会执行 docker load 并标记为 cloud-blox-runtime:latest。
    • 若无镜像但有 Dockerfile.runtime（解压后位于安装目录），则从该 Dockerfile 构建镜像。
    • 若既无镜像又无 Dockerfile，安装会报错退出。

  5. 生成配置文件

    • configs/config.yaml：数据库、Redis、ClickHouse、JWT、域名、区域角色、日志、缓存等，由脚本根据前面交互结果写入。
    • docker-compose.yaml：按选择生成 MySQL / Redis / ClickHouse（可选）与应用容器及卷挂载、端口映射；应用容器依赖数据库健康检查后再启动。
    • manage.sh：日常管理命令（启动、停止、重启、日志、状态、更新、备份）。

  6. 记录安装信息

    将本次安装的版本、发行版与架构写入安装目录 release.env，供下次升级时校验。

  7. 启动服务

    脚本会询问「是否立即启动服务」。选「是」则执行 docker compose up -d 并等待应用 /readyz 就绪；选「否」（或带 --no-start）则仅完成文件准备，需手动进入安装目录执行 ./manage.sh start。

七、安装完成后的访问方式

启动成功后，脚本会输出类似：

  • 管理后台：http://localhost:38002（端口以实际配置为准）
  • S3 API：http://localhost:38003
  • 资源访问：http://localhost:38004
  • WebDAV：http://localhost:38005

默认管理员账号：

  • 用户名：admin
  • 密码：安装结束时脚本打印的随机初始密码（仅显示一次）

首次登录后必须修改密码；未修改前无法使用其他功能。

查看日志、停止服务、管理脚本用法等见下一节。

八、安装目录结构与日常管理

8.1 目录结构

1）安装包解压后的根目录（精简）：

文本
cloud-blox-install-<版本>-linux-<架构>-<发行版>/
├── README.md
├── install.sh
├── release.env              # 安装包元数据（版本 / 发行版 / 架构），勿改
├── install-package.tar.gz   # 载荷：二进制 + public + 运行时构建文件
└── cloud-blox-runtime.tar   # 精简包不含；预构建运行时镜像

2）执行 install.sh 后的安装目录（默认 ./cloud-blox）大致为：

文本
cloud-blox/
├── docker-compose.yaml    # 编排文件（按选择含 MySQL/Redis/ClickHouse/应用）
├── manage.sh              # 管理脚本
├── release.env            # 已安装版本记录（升级时用于比较版本）
├── cloud-blox-server      # 服务端主程序（由载荷解压，卷映射进容器）
├── Dockerfile.runtime     # 无预构建镜像时用于本地构建（来自载荷）
├── public/                # 前端静态资源（来自载荷）
├── configs/
│   └── config.yaml        # 应用配置（数据库、端口、JWT 等）
├── data/                  # 全部运行数据（compose 同目录）
│   ├── mysql/             # 仅 Docker 部署 MySQL 时
│   ├── redis/
│   ├── clickhouse/
│   ├── storage/           # 本地存储
│   ├── storage_temp/      # 异步上传临时文件
│   ├── cache/             # 媒体处理缓存
│   └── logs/              # 应用日志
└── backups/               # 备份目录（manage.sh backup 等）

数据与配置均落在安装目录内，整机备份时可打包该目录。运行数据统一在 data/ 下，与编排文件放在一起。

8.2 管理脚本 manage.sh

进入安装目录后执行：

Shell
cd cloud-blox   # 或你指定的安装目录./manage.sh <命令>
命令说明
start / up启动所有服务
stop / down停止所有服务
restart [服务名]重启（可仅重启 app 等）
logs [服务名]查看日志（默认跟踪所有，可指定 app、mysql 等）
status / ps查看容器状态
update更新应用：检查二进制、前端、运行时镜像后重启（用于替换新版本二进制或镜像后执行）
backup备份：MySQL dump、配置文件等到 backups/ 下带时间戳的目录

示例：

Shell
./manage.sh start    # 启动./manage.sh logs app # 只看应用日志./manage.sh backup   # 备份./manage.sh update   # 更新后重启

九、升级已有安装

  1. 获取新版本安装包

    从官方或交付渠道获取与当前架构一致（amd64 / arm64）、发行版一致的新版本安装包。升级前建议先执行 ./manage.sh backup 备份数据库与配置。

  2. 解压并执行升级

    解压到任意目录，用 --install-dir 指向已有安装目录（即已存在 docker-compose.yaml 的目录）：

    Shell
    tar -xzf cloud-blox-install-1.0.2-linux-amd64-free.tar.gzcd cloud-blox-install-1.0.2-linux-amd64-freebash install.sh --upgrade --install-dir /opt/cloud-blox

    不带 --upgrade 时脚本会在检测到已有安装后弹出菜单，选择 1) 升级 即可。

  3. 脚本自动校验

    架构必须一致；比较已安装版本，拒绝降级（确需回退加 --force），同版本按重装处理，可放心重复执行。

  4. 脚本自动完成更新

    • 停止现有服务（若编排正在运行）
    • 解压新版 install-package.tar.gz，更新 cloud-blox-server、public/ 等
    • 加载新版本运行时镜像（或从 Dockerfile.runtime 构建）
    • 从现有 config.yaml 解析配置，重新生成 docker-compose.yaml 与 manage.sh（不覆盖 config.yaml）
    • 备份旧的 config.yaml 和 docker-compose.yaml（带时间戳后缀）
    • 更新安装目录 release.env 中的版本记录
    • 若升级前服务在运行，则再次启动服务（带 --no-start 时不启动，稍后手动 ./manage.sh start）

数据目录（data/）与 configs/config.yaml 均保留，仅程序与编排更新。数据库结构迁移由主节点在启动时自动执行（安装脚本生成的配置默认开启 database.migrate.auto），区域节点不参与迁移，无需手工操作。

十、区域节点部署（多节点）

Cloud Blox 支持多节点部署：一个主节点 + 多个区域节点，共享同一套数据库。区域节点安装包由主节点生成（前提是已按本文完成主节点安装），也可用普通安装包手动选择区域节点模式安装。

主节点与区域节点的区别、region-pack 生成区域安装包、手动安装与安装后的区域配置，见独立页面 区域节点部署。

十一、部署与运维建议

11.1 生产部署与默认端口

应用只提供 HTTP，公网部署须由 Nginx、Caddy 等反向代理终止 TLS。

服务默认端口说明
管理后台（Admin）38002Web 控制台与管理 API
S3 API38003S3 兼容协议
资源访问（Access）38004绑定域名访问文件、媒体处理；未匹配域名时默认入口
WebDAV38005WebDAV 协议
Redis（可选映射）38006仅宿主机映射时；默认不映射则仅 Docker 内网
MySQL（可选映射）38007同上
ClickHouse HTTP（可选映射）38008同上
ClickHouse Native（可选映射）38009同上
  • HTTPS：对外提供管理后台、S3、资源访问或 WebDAV 时，建议在反向代理上配置 HTTPS，并按下方 map 将请求转发到对应后端端口。
  • 端口与防火墙：公网只放行 80/443（或反向代理端口）；应用端口 38002–38005 建议仅本机或内网可达。区域节点需连主节点数据库时，再按需开放 38006–38009（且不要只绑 127.0.0.1）。
  • 数据与备份：定期对安装目录或至少 data/、configs/ 做备份；可使用 manage.sh backup。

11.2 Nginx 反向代理

公网部署须由 Nginx、Caddy 等反向代理终止 TLS，并按 Host 将请求分发到管理后台 / S3 / 资源访问 / WebDAV 对应端口。

完整的 map 规则示例、宝塔面板注意事项与多节点场景说明，见独立页面 Nginx 反向代理。也可在管理后台「区域管理 → 服务端配置」中按区域直接生成 Nginx / Caddy 配置。

11.3 常见问题

  • Docker 权限：若提示无权限访问 Docker，可将当前用户加入 docker 组（sudo usermod -aG docker $USER）并重新登录，或用 sudo bash install.sh 执行安装。
  • 端口冲突：安装前脚本会检测端口占用；若仍冲突，可更换 ADMIN_PORT、S3_PORT 等或停止占用端口的服务后再安装。
  • 提示「架构不匹配」：安装包是为另一种 CPU 架构构建的。按提示重新下载 -linux-amd64- 或 -linux-arm64- 对应的包；uname -m 输出 x86_64 对应 amd64，aarch64 对应 arm64。
  • 提示「拒绝降级」：安装包版本低于已安装版本。请确认下载的是最新版本；确需回退时加 --force，并先用 ./manage.sh backup 备份数据库。
  • 升级后无法启动：查看 ./manage.sh logs app 等日志；确认配置文件未被人为破坏；必要时从备份恢复 config.yaml 后再试。
  • 区域节点连不上 Redis/ClickHouse：主节点若未映射端口，或映射仅绑 127.0.0.1，其他机器无法访问；需映射为局域网可达地址并放行防火墙。

产品文档随安装包提供或从官方渠道获取；更多功能说明见 功能总览、后台管理入门、存储桶与文件 等。