安装教程

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

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

安装完成后，你可以：

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

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

二、环境要求

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

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

三、获取安装包

从官方或交付渠道获取 Cloud Blox 安装包（如 cloud-pool-install.tar.gz 或带架构后缀的 cloud-pool-install-amd64.tar.gz、cloud-pool-install-arm64.tar.gz）。

安装包内通常包含：

文件或目录	说明
`install.sh`	一键安装脚本（交互式配置或非交互执行）
`cloud-pool-server`	Go 主程序二进制（或 `cloud-pool-server-amd64` / `cloud-pool-server-arm64`）
`public/`	前端静态资源
`Dockerfile.runtime`	运行时镜像定义（无预构建镜像时用于本地构建）
`cloud-pool-runtime.tar`	预构建运行时镜像（可选；无则需在目标机从 Dockerfile.runtime 构建）
`README.md`	安装包内简要说明

解压后进入目录，例如：

bash

tar -xzf cloud-pool-install.tar.gz
cd cloud-pool-install

四、运行安装脚本

4.1 命令用法

bash

bash install.sh [选项]

选项	说明
（无）	交互式安装：逐步提示配置项，带默认值
`--yes` / `-y`	非交互模式：全部使用默认值，适合自动化部署
`--install-dir DIR`	指定安装目录（默认：当前目录下的 `cloud-pool`）
`--help` / `-h`	显示帮助

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

环境变量	说明	默认值
`ADMIN_PORT`	管理后台端口	28008
`S3_PORT`	S3 API 端口	28080
`ACCESS_PORT`	资源访问端口	28082
`DAV_PORT`	WebDAV 端口	28083
`MYSQL_PASSWORD`	MySQL root 密码（Docker 模式）	root123456
`REDIS_PASSWORD`	Redis 密码（Docker 模式）	redis123456

示例：

bash

# 交互式安装（推荐首次安装）
bash install.sh

# 全默认值自动安装
bash install.sh --yes

# 指定安装目录
bash install.sh --yes --install-dir /opt/cloud-pool

# 自定义端口后自动安装
ADMIN_PORT=28080 S3_PORT=28081 bash install.sh --yes

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

Docker：未安装时可选择自动安装；已安装但未运行时会尝试启动；当前用户无权限访问 Docker 时会提示加入 docker 组或使用 sudo
Docker Compose：未检测到时会提示安装 Compose 插件
安装目录：未指定时默认为当前目录下的 cloud-pool；实例名由安装目录名自动推导（用作 Docker 项目名与容器前缀）
磁盘空间：安装目录所在分区至少约 2GB，不足时会警告并询问是否继续
端口占用：管理后台、S3、资源访问、WebDAV 及 MySQL/Redis 映射端口（若启用）会做冲突检测，有冲突时提示是否继续

4.3 已有安装时的选择（升级 / 全新安装）

若安装目录下已存在 docker-compose.yaml，脚本会识别为已有安装，并提示：

升级：更新 Go 二进制、前端资源、运行时镜像、编排文件与管理脚本，保留 configs/config.yaml 与 data/、storage/、logs/ 等数据
全新安装：重新走一遍配置流程，覆盖 config.yaml、docker-compose.yaml、manage.sh（不会删除数据目录）
取消

升级时无需再次输入 MySQL/Redis 等配置，脚本会从现有 config.yaml 与 docker-compose.yaml 解析并沿用。

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

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

5.1 MySQL

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

5.2 Redis

选项 1：使用 Docker 部署（推荐）
自动创建 Redis 容器，需输入：密码（默认 redis123456）、DB 编号（默认 0）、映射端口（默认 26379，0 表示不映射）。
选项 2：使用已有 Redis
需输入：地址、端口、密码（可留空）、DB 编号。

5.3 ClickHouse（日志与统计）

固定为 Docker 部署，库名 cloud_pool_logs。
可选：将 HTTP 端口（8123）或 Native 端口（9000）映射到宿主机（默认不映射，填 0）。

5.4 应用端口

端口变量	默认值	说明
管理后台	28008	Web 控制台与 API
S3 API	28080	S3 兼容接口
资源访问	28082	绑定域名访问文件与媒体处理
WebDAV	28083	WebDAV 协议

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

5.5 高级配置

JWT 密钥、AES 密钥、Presign 密钥：由脚本自动随机生成，无需输入。
异步上传、媒体处理、缓存 TTL 等可在安装完成后于「系统管理 → 配置」中修改。

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

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

创建目录结构
在安装目录下创建：configs、data/mysql、data/redis、data/clickhouse、storage、storage_temp、logs、cache、backups、public。
复制 Go 二进制
将安装包内的 cloud-pool-server（或与当前架构对应的 cloud-pool-server-amd64 / cloud-pool-server-arm64）复制到安装目录并赋予执行权限。
复制前端资源
将安装包内 public/ 复制到安装目录；用于管理后台静态资源。
运行时镜像
- 若安装包内有 cloud-pool-runtime.tar（或 cloud-pool-runtime-amd64.tar / cloud-pool-runtime-arm64.tar），脚本会执行 docker load 并标记为 cloud-pool-runtime:latest。
- 若无镜像但有 Dockerfile.runtime，则在安装目录从该 Dockerfile 构建镜像。
- 若既无镜像又无 Dockerfile，安装会报错退出。
生成配置文件
- configs/config.yaml：数据库、Redis、ClickHouse、JWT、日志、端口等，由脚本根据前面交互结果写入。
- docker-compose.yaml：MySQL（可选）、Redis（可选）、ClickHouse、应用容器及卷挂载、端口映射；应用容器依赖数据库健康检查后再启动。
- manage.sh：日常管理命令（启动、停止、重启、日志、状态、更新、备份）。
是否立即启动
脚本会询问「是否立即启动服务」。选「是」则执行 docker compose up -d 并等待应用容器就绪（约 90 秒内）；选「否」则仅完成文件准备，需手动进入安装目录执行启动命令。

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

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

管理后台：http://localhost:28008（端口以实际配置为准）
S3 API：http://localhost:28080
资源访问：http://localhost:28082

默认管理员账号：

用户名：admin
密码：admin123

建议首次登录后尽快在「用户管理」或个人设置中修改密码。

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

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

8.1 目录结构

安装完成后，安装目录（默认 cloud-pool）大致为：

cloud-pool/
├── docker-compose.yaml    # 编排文件（MySQL/Redis/ClickHouse/应用）
├── manage.sh              # 管理脚本
├── cloud-pool-server      # Go 主程序（通过卷映射进容器运行）
├── public/                # 前端静态资源（映射进容器）
├── configs/
│   └── config.yaml        # 应用配置（数据库、端口、JWT 等）
├── storage/               # 本地存储数据（映射进容器）
├── storage_temp/          # 异步上传临时文件
├── data/                  # 基础设施数据
│   ├── mysql/
│   ├── redis/
│   └── clickhouse/
├── logs/                  # 应用日志（自动轮转）
├── cache/                 # 媒体处理缓存
└── backups/               # 备份目录（manage.sh backup 等）

数据与配置均落在安装目录内，整机备份时可打包该目录。

8.2 管理脚本 manage.sh

进入安装目录后执行：

bash

cd cloud-pool   # 或你指定的安装目录

./manage.sh <命令>

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

示例：

bash

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

九、升级已有安装

从官方或交付渠道获取新版本安装包（与当前架构一致，如 amd64/arm64）。
解压到当前安装目录（即已存在 docker-compose.yaml 的目录），或解压到任意目录后使用 --install-dir 指向该安装目录。
运行 bash install.sh（或 bash install.sh --install-dir /path/to/cloud-pool）。
脚本检测到已有安装后，选择 1) 升级。
脚本将自动：
- 停止现有服务
- 替换 cloud-pool-server、public/
- 加载新版本运行时镜像（或从 Dockerfile.runtime 构建）
- 从现有 config.yaml 解析配置，重新生成 docker-compose.yaml 与 manage.sh（不覆盖 config.yaml）
- 再次启动服务

数据目录（data/、storage/、logs/ 等）与 configs/config.yaml 均保留，仅程序与编排更新。

十、部署与运维建议

10.1 生产部署

HTTPS：对外提供管理后台或资源访问时，建议在 Nginx、Caddy 等反向代理上配置 HTTPS，将请求转发到对应端口（如 28008、28082）。
端口与防火墙：确认防火墙或安全组放行管理后台、S3、资源访问、WebDAV 所需端口；仅本机访问时可只绑定 localhost。
数据与备份：定期对安装目录或至少 data/、configs/、storage/ 做备份；可使用 manage.sh backup 做逻辑备份，再配合快照或归档策略。

10.2 Nginx 反向代理示例

将域名或路径反向代理到 Cloud Blox 时，可使用如下 location / 配置（$backend_port 替换为实际端口，如管理后台 28008、资源访问 28082；HTTPS 时 $custom_x_forwarded_proto 设为 https）：

nginx

location / {
    proxy_pass http://127.0.0.1:$backend_port;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $custom_x_forwarded_proto;
    proxy_http_version 1.1;
    proxy_redirect off;
}

使用宝塔面板时：请删除站点 Nginx 配置中由宝塔自动添加的以下两个 location 块，否则对图片、JS、CSS 的请求会被 Nginx 直接按静态文件处理或缓存，不会转发到后端，导致管理后台或资源访问异常。

删除 图片等静态缓存 块（location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$，内含 expires 30d、access_log /dev/null 等）。
删除 JS/CSS 缓存 块（location ~ .*\.(js|css)?$，内含 expires 12h、access_log /dev/null 等）。

保留上述 location / 代理即可，让所有请求统一走后端。

10.3 常见问题

Docker 权限：若提示无权限访问 Docker，可将当前用户加入 docker 组（sudo usermod -aG docker $USER）并重新登录，或用 sudo bash install.sh 执行安装。
端口冲突：安装前脚本会检测端口占用；若仍冲突，可更换 ADMIN_PORT、S3_PORT 等或停止占用端口的服务后再安装。
升级后无法启动：查看 docker compose logs app 等日志；确认新二进制与当前架构匹配、配置文件未被人为破坏；必要时从备份恢复 config.yaml 后再试。

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

安装教程 ​

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

二、环境要求 ​

三、获取安装包 ​

四、运行安装脚本 ​

4.1 命令用法 ​

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

4.3 已有安装时的选择（升级 / 全新安装） ​

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

5.1 MySQL ​

5.2 Redis ​

5.3 ClickHouse（日志与统计） ​

5.4 应用端口 ​

5.5 高级配置 ​

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

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

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

8.1 目录结构 ​

8.2 管理脚本 manage.sh ​

九、升级已有安装 ​

十、部署与运维建议 ​

10.1 生产部署 ​

10.2 Nginx 反向代理示例 ​

10.3 常见问题 ​

安装教程

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

二、环境要求

三、获取安装包

四、运行安装脚本

4.1 命令用法

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

4.3 已有安装时的选择（升级 / 全新安装）

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

5.1 MySQL

5.2 Redis

5.3 ClickHouse（日志与统计）

5.4 应用端口

5.5 高级配置

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

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

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

8.1 目录结构

8.2 管理脚本 manage.sh

九、升级已有安装

十、部署与运维建议

10.1 生产部署

10.2 Nginx 反向代理示例

10.3 常见问题