华为云 obsutil 使用指南

obsutil 实战：前端静态资源自动上传华为云OBS + GitLab CI 完整指南

摘要：obsutil 是华为云对象存储 OBS 官方命令行工具，对标阿里云 ossutil64，同样适合 Vue/React 前端打包产物增量同步、搭配华为 CDN 对外访问。本文对齐上一篇 ossutil 博客结构，重点对比差异、sync 同步、IAM最小权限、GitLab CI流水线落地，方便你在阿里云、华为云两套方案之间切换。

一、obsutil 是什么？

obsutil 是华为云官方提供的 OBS（Object Storage Service）对象存储命令行管理工具，支持文件上传、下载、增量同步、批量删除、自定义HTTP响应头、跨区域同步等操作，Linux / Windows / macOS 全平台支持。

一句话类比：obsutil sync 就是华为云OBS版本的 rsync / ossutil sync

ossutil：阿里云OSS

obsutil：华为云OBS
重点差异提醒：华为云 obsutil 的 sync 命令默认不带删除能力 ，想要清理远端多余文件，需要额外加上 --delete 参数，参数习惯和阿里云ossutil保持一致，但鉴权、endpoint、权限体系是华为云IAM体系。

二、前置概念：AK/SK（华为云访问密钥）

华为云这边叫 AccessKey（AK）、SecretAccessKey（SK），和阿里云AK逻辑一致，是程序调用OBS的密钥对：

AK：访问密钥ID，标识账号
SK：密钥，签名用，严格保密，只在创建时展示一次

✅ 最佳实践：禁止使用主账号AK/SK，新建IAM子用户，只授予指定OBS桶最小权限，遵循最小权限原则。

华为云IAM = 阿里云RAM。

三、Linux 安装 obsutil（GitLab CI Runner 直接执行）

bash 复制代码

# 下载Linux amd64版本
wget [https://obs-community.obs.cn-north-1.myhuaweicloud.com/obsutil/current/obsutil_linux_amd64.tar.gz](https://obs-community.obs.cn-north-1.myhuaweicloud.com/obsutil/current/obsutil_linux_amd64.tar.gz)
# 解压
tar -zxvf obsutil_linux_amd64.tar.gz
cd obsutil_linux_amd64
# 赋予执行权限
chmod +x obsutil
# 放到全局PATH
mv obsutil /usr/local/bin/obsutil
# 验证
obsutil version

华为云obsutil没有 ossutil64 这种版本后缀，统一叫 obsutil；不同架构（arm）需要换对应下载包。

四、两种配置鉴权方式

方式1：交互式配置（本地调试，CI不推荐）

bash 复制代码

obsutil config

依次输入 endpoint、AK、SK，STS token 直接回车跳过。

会生成 ~/.obsutilconfig 配置文件，CI环境不适合，密钥持久化存在风险。

方式2：命令行参数传入（✅ CI流水线首选）

参数说明：

-e：OBS桶对应的Endpoint（地域必须匹配，例如华北四：obs.cn-north-4.myhuaweicloud.com）
-i：AccessKey ID（AK）
-k：SecretAccessKey（SK）

bash 复制代码

obsutil ls obs://my-bucket \
-e obs.cn-north-4.myhuaweicloud.com \
-i $OBS_AK \
-k $OBS_SK

五、核心命令详解（前端部署重点）

1. sync（增量同步，对标 rsync -avz --delete / ossutil sync）【最核心】

语法：

bash 复制代码

obsutil sync 本地目录 obs://bucket/路径/ [参数]

⚠️ 和ossutil、rsync一样：末尾 / 是大坑

./dist/：同步dist里面所有文件到目标路径（业务常用）
./dist：把dist整个文件夹作为子目录上传

常用参数：

--delete：删除OBS上本地不存在的文件（清理旧静态资源，高危！）
-f：force，不交互确认，CI流水线必须加
-dryRun：试运行，只打印操作，不上传、不删除，上线前必测
--exclude="*.map"：排除sourcemap源码映射文件
--acl public-read：设置文件公共读，搭配CDN访问静态页面
--meta "Cache-Control:max-age=31536000"：设置HTTP缓存头

示例：

bash 复制代码

# 试运行，先校验变更逻辑，不会真实改动OBS
obsutil sync ./my-project-production/ obs://my-bucket/my-project-production/ \
-e obs.cn-north-4.myhuaweicloud.com \
-i $OBS_AK \
-k $OBS_SK \
--delete -f \
--dryRun \
--exclude="*.map"

# 确认无误后，去掉 --dryRun 正式执行
obsutil sync ./my-project-production/ obs://my-bucket/my-project-production/ \
-e obs.cn-north-4.myhuaweicloud.com \
-i $OBS_AK \
-k $OBS_SK \
--delete -f \
--exclude="*.map" \
--acl public-read

2. cp 上传（不推荐作为主发布命令）

cp -r 递归上传，默认不支持自动清理远端废弃文件，适合一次性上传、备份场景。

bash 复制代码

obsutil cp -r ./dist obs://my-bucket/tmp -f

3. 其他高频命令

bash 复制代码

# 列出OBS目录
obsutil ls obs://my-bucket/path/

# 删除整个目录（谨慎使用）
obsutil rm obs://my-bucket/path/ -r -f

# OBS资源下载到本地
obsutil sync obs://my-bucket/path/ ./local/

4. 设置缓存头（前端静态资源优化）

JS/CSS带哈希，设置长缓存；HTML建议在CDN侧配置不缓存，避免用户拿不到更新。

bash 复制代码

obsutil sync ./my-project-production/ obs://my-bucket/my-project-production/ \
-e obs.cn-north-4.myhuaweicloud.com \
-i $OBS_AK \
-k $OBS_SK \
--delete -f \
--exclude="*.map" \
--meta "Cache-Control:max-age=31536000"

推荐方案：在华为云CDN控制台配置缓存规则，按后缀区分缓存策略，不用每次上传指定meta。

六、IAM最小权限策略（直接复制）

新建IAM用户，绑定这个自定义策略，只允许操作指定OBS桶，最小权限：

json 复制代码

{
    "Version": "1.1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "obs:PutObject",
                "obs:DeleteObject",
                "obs:ListBucket",
                "obs:GetObject"
            ],
            "Resource": [
                "obs:my-bucket",
                "obs:my-bucket/*"
            ]
        }
    ]
}

把 my-bucket 替换成你的OBS桶名称。

七、GitLab CI 完整落地示例（分支驱动环境，Vue项目）

逻辑和阿里云版本完全对齐：main分支 → production；dev分支 → test；其他分支 preview；打包产物目录 项目名-${ENV_NAME}

yaml 复制代码

build_and_upload_obs:
  stage: deploy
  script:
    - |
      # 分支映射环境，一处维护
      if [[ "$CI_COMMIT_REF_NAME" == "main" ]]; then
        ENV_NAME="production"
      elif [[ "$CI_COMMIT_REF_NAME" == "dev" ]]; then
        ENV_NAME="test"
      else
        ENV_NAME="preview"
      fi
      STATIC_DIR="vue-demo-${ENV_NAME}"
      export VUE_APP_ENV="${ENV_NAME}"
      # Vue打包，mode和环境对齐
      npm run build -- --mode ${ENV_NAME}
      mv dist ${STATIC_DIR}
    # obsutil同步上传华为云OBS
    - obsutil sync ./${STATIC_DIR}/ obs://my-bucket/${STATIC_DIR}/ \
        -e obs.cn-north-4.myhuaweicloud.com \
        -i $OBS_AK \
        -k $OBS_SK \
        --delete -f \
        --exclude="*.map" \
        --acl public-read

GitLab后台配置变量：

OBS_AK、OBS_SK，勾选 Masked（掩码），防止密钥打印在CI日志

八、obsutil 与 ossutil64 横向对比

对比项	阿里云 ossutil64(v1)	华为云 obsutil
存储服务	OSS	OBS
同步删除	`--delete`	`--delete`
试运行	`-n`	`--dryRun`
鉴权参数	`-i AK_ID -k AK_SECRET`	`-i AK -k SK`
权限体系	RAM	IAM
访问地址格式	oss://bucket/xxx	obs://bucket/xxx
静态托管	OSS+CDN	OBS+华为CDN

这两套脚本你只需要替换工具名称、endpoint、变量名，业务逻辑完全不用改，多云切换很方便。

九、高频踩坑清单（避坑）

--delete 高危 ：路径写错，OBS内文件全部清空；上线前一定加 --dryRun 试运行
Endpoint 必须和OBS桶地域严格匹配，跨地域会报错、走公网产生流量费用；华为云支持内网Endpoint，ECS内网访问免流量费
目录末尾 / 不要随手省略，目录结构和预期完全不一样
AK/SK 禁止硬编码写在yml，全部放到CI掩码变量
权限最小化：不要给 obs:* 全量权限，只开放PutObject、DeleteObject、ListBucket、GetObject
sourcemap 如果不想对外暴露，一定要 --exclude="*.map"
华为云OBS桶有存储类型（标准/低频/归档），前端静态资源选标准存储；归档存储不能直接在线访问
公共读桶要注意安全，不要把隐私文件放到公共读桶内

十、官方文档链接

obsutil 官方文档入口：https://support.huaweicloud.com/utiltg-obs/obs_11_0001.html

安装下载：https://support.huaweicloud.com/utiltg-obs/obs_11_0003.html
sync同步命令：https://support.huaweicloud.com/utiltg-obs/obs_11_0044.html
cp上传命令：https://support.huaweicloud.com/utiltg-obs/obs_11_0018.html

十一、总结

obsutil 是华为云OBS静态CI发布的利器，和阿里云ossutil使用习惯高度对齐，同样可以替代rsync上传服务器的模式，把静态资源托管交给OBS+华为CDN，免去服务器运维成本。

核心流程不变：分支判断环境 → npm打包 → 目录重命名 → obsutil sync增量同步到OBS 。

安全底线：IAM子用户、最小权限、AK/SK掩码、上线前dry-run试运行。