阿里云对象存储（OSS）与 CDN 配置说明

本文说明在 Baklib Docker 部署中，如何将静态资源存储到阿里云 OSS，并通过阿里云 CDN 加速访问。应用侧通过 .env 中的存储相关变量与 docker-compose.yml 注入的环境变量生效；变量名需与示例文件完全一致，阿里云对象存储相关前缀为 STORAGE_ALIYUN_（Aliyun）。若现有 .env 仍使用历史错误拼写 STORAGE_ALIIYUN_，请改为 STORAGE_ALIYUN_ 后重启服务。

前置条件

  • 已开通阿里云账号，并完成实名认证。
  • 已创建 RAM 用户（推荐专用子账号），仅授予对象存储与（若使用 CDN 鉴权）相应只读/读写策略，不要使用主账号 AccessKey 生产环境。
  • 已部署或准备部署本仓库中的 Baklib，并完成 .env 基础配置。

目标结果

  • 创建子账号，获取账号的 API Access Key 和 Secret Key
    • STORAGE_ALIYUN_ACCESS_KEY
    • STORAGE_ALIYUN_SECRET_KEY
  • 创建 Bucket ，记录环境变量
    • STORAGE_ALIYUN_BUCKET
    • STORAGE_ALIYUN_ENDPOINT
  • 配置 CDN，记录环境变量
    • STORAGE_ALIYUN_CDN_HOST
    • STORAGE_ALIYUN_CDN_KEY

一、配置 OSS

第一步：创建 Bucket

登录 对象存储 OSS 控制台，在目标地域创建 Bucket。

第二步：授权账号读写权限

💡
进权限控制 - Bucket 授权策略, 点击新增授权
💡
勾选用于读写 Bucket 的子账号，授权操作选择“完全控制”

第三步：配置跨域访问

配置此项是为了解决浏览器上传文件和编辑图片时的跨域问题。
💡
进入“数据安全”-“跨域设置”，点击“创建规则”。来源填写星号“*“，勾选“GET”，“PUT”。允许 Headers 填写如下内容：
authorization
content-md5
content-type
x-oss-date

第四步：填写 OSS 相关变量

💡
进入“概览”，记录如下信息，写入环境变量：
  • 存储空间名称(baklib-dev-oss)
  • 访问端口-外网访问的Endpoint(oss-cn-hangzhou.aliyuncs.com)
STORAGE_ALIYUN_BUCKET = 'baklib-dev-oss'
STORAGE_ALIYUN_ENDPOINT = 'oss-cn-hangzhou.aliyun.cs.com'
3. RAM 访问密钥

二、配置 CDN

在 OSS 前增加 CDN 可缩短静态资源访问延迟、分担回源流量。

第一步：添加加速域名

💡
  1. 打开 CDN 控制台，「域名管理」中新增域名。
  2. 加速区域一般选择“仅中国内地”。
  3. 业务类型一般选择「图片小文件」或「大文件下载」，按实际资源类型选择。
💡
源站信息，点击新增原站信息，源站类型选择「OSS 域名」，选中上一步创建的 Bucket（baklib-dev-oss.xxxxxxx）。
💡
确定添加之后，下面的成功界面，不做任何操作，点击进入“跳过，暂不配置”

第二步：DNS CNAME

👋
在域名 DNS 服务商处，将用于加速的域名CNAME 到 CDN 控制台为该域名分配的 CNAME 地址。
👋
配置成功之后，回到阿里云CDN域名列表，会看到CNAME状态显示为“已配置”，状态“正常运行”

第三步：配置 CDN

💡
进入域名管理-回源配置，打开“阿里云OSS私有Bucket回源”，选择同账号回源，确定。
💡
进入“缓存配置”-“修改出站响应头“, 让用户浏览器缓存数据1个月
Cache-Control: max-age=2592000,private
Access-Control-Allow-Origin: *

第四步：开启URL鉴权

💡
开启URL鉴权之后，可以有效防止流量被盗刷的风险

第五步：填写 CDN 相关变量

STORAGE_ALIYUN_CDN_HOST = 'https://saas-dev.bk-cdn01.com' # 这是上传的图片/视频等文件的公开访问域名
STORAGE_ALIYUN_CDN_KEY  = 'long-secret-key-abcd-1234'     # 这是你自定义的防盗链加密字符串，切勿泄漏出去

三、在 Baklib Docker 中启用阿里云存储

1. 设置默认存储为阿里云

在 .env 中设置：
STORAGE_SAAS_DEFAULT_SERVICE = 'aliyun'

2. 完整变量示例（请替换为真实值）

STORAGE_SAAS_DEFAULT_SERVICE = 'aliyun'

STORAGE_ALIYUN_ACCESS_KEY = 'LTAIxxxxxxxxxxxx'
STORAGE_ALIYUN_SECRET_KEY = 'xxxxxxxxxxxxxxxx'
STORAGE_ALIYUN_BUCKET     = 'baklib-dev-oss'
STORAGE_ALIYUN_ENDPOINT   = 'oss-cn-hangzhou.aliyuncs.com'

# 可选：CDN
STORAGE_ALIYUN_CDN_HOST   = 'https://saas-dev.bk-cdn01.com'
STORAGE_ALIYUN_CDN_KEY    = 'long-secret-key-abcd-1234'

# 是否公开读（true/false，按 Bucket 与应用需求填写）
STORAGE_ALIYUN_PUBLIC     = false

3. 应用配置

  • 可直接编辑 .env，或运行 ./config.sh，在交互流程中选择存储类型 aliyun，按提示填入上述项。
  • 修改存储相关变量后，需重启服务，例如：./restart.sh 或 docker compose up -d（以你当前运维方式为准）。

四、验证与常见问题

  1. 上传与访问：在 Baklib 中上传附件或图片，在 OSS 控制台对应 Bucket 中应能看到对象；浏览器访问资源链接应返回 200（私有 Bucket 需使用带签名的 URL）。
  2. Endpoint 错误：地域与 Endpoint 必须匹配；不要混入内网 Endpoint 到仅公网可达的环境。
更多环境变量名称与占位说明见仓库根目录 .env.example。
提交反馈
上一页
如何安装