企业官网建设流程全解析

镜像仓库这东西，平时在页面上点两下谁都玩得转，可一旦要把"推镜像、查漏洞、清垃圾、发权限"这些动作塞进流水线，界面就变成了拖累。harbor api v2.0就是把这个仓库的操作面全部摊开成一套 REST 接口，让你用几行 curl 或一段 Python 脚本，把原本要人工点十几分钟的事情变成流水线里的一次调用。它的价值不在"能调"，而在于把权限模型、保留策略、配额、扫描结果这些治理动作变成了可版本化、可审计、可复现的代码资产。这篇文章适合三类人看：正在搭 CI/CD 需要自动建项目推镜像的运维；被"仓库爆盘"和"无用 tag 满天飞"折磨过的平台工程师；以及想给内部做一层仓库管理工具、但不确定接口边界在哪儿的开发者。下面我从对象模型讲到实操脚本，把踩过的坑一并摊开。

1. 先把 harbor api v2.0 的对象模型吃透

1.1 从资源树的角度理解三级结构

刚接触这套接口的人最容易犯的错，是把它当成一堆平铺的 URL 去背。其实它背后是一棵很规整的树：Project（项目）→ Repository（仓库）→ Artifact（制品）→ Tag（标签）。项目是最外层的命名空间和权限边界，仓库对应镜像名里斜杠后面的那一串路径，制品是每一次推送产生的那个具体对象，标签则是挂在上面的可读名字。

理解了这个层级，很多路径就不用记了。你要操作某个东西的标签，路径一定是先定位到项目，再定位到仓库，再定位到制品引用，最后才是标签。比如删除一个标签，路径长这样：/api/v2.0/projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/tags/{tag_name}。这里有个关键的设计意图：制品是物理存在的，标签是逻辑引用。同一个制品可以挂多个 tag，你删掉一个 tag 并不等于删掉镜像层数据。所以清理磁盘的时候删 tag 是没用的，真正的动作是删 artifact 或者让保留策略把 artifact 干掉，再跑垃圾回收把底层 blob 释放。

还有个细节值得说：{reference}这个位置既能填 tag 名，也能填 digest。当你要保证"删的一定是我看到的那个东西"，就该用 digest 而不是 tag，因为 tag 是可变引用，在你查询和删除之间的那几百毫秒里，完全可能被另一条流水线覆盖掉。这个思路跟 Kubernetes 里用镜像 digest 锁定部署是同一个道理。

1.2 认证的三条路径与适用边界

这套接口支持三种认证方式，很多人混着用，结果在权限上栽跟头。第一种是Basic Auth，用户名密码 base64 一下塞进请求头，最省事，适合你本地调试和一次性运维脚本。第二种是机器人账号（Robot Account），本质是一个带作用域和有效期的专用身份，创建时返回一次的 secret 就是它的凭据，同样走 Basic 认证，但权限被严格限制在某个项目或整站范围内。第三种是配合容器运行时用的Bearer Token，走的是/service/token换票流程，一般由 Docker 客户端自己处理，你手写代码对接的场景不多。

选型逻辑很清楚：人用 Basic，机器用 Robot。原因不只是权限最小化，还在于审计。用管理员账号跑定时清理任务，出了事你根本分不清是人点的还是脚本干的；用机器人账号，审计日志里一水儿的robot$项目名+账号名，谁干的、干了什么，一眼就能定位。我见过一个团队把所有自动化脚本都挂在管理员账号上，后来某个脚本写错循环条件，一晚上删掉了几百个制品，追查时日志里全是同一个管理员账号，根本没法复盘。

机器人账号的 secret 只在创建的那一次返回，之后接口再也不吐明文。这一点必须提前跟团队说清楚，否则总有人建完账号把页面一关，然后来问"密码在哪儿看"。答案是没有，只能重建或者刷新。

1.3 为什么 v2.0 的路径设计会让新手翻车

这套接口里最经典的一个坑，是仓库名里的斜杠。假设项目叫demo，镜像地址是registry.internal/demo/team-a/service-x，那么repository_name就是team-a/service-x。这个值直接塞进路径里会破坏路径结构，所以必须做 URL 编码，把/变成%2F。问题来了：很多 HTTP 客户端和网关会再编码一次，实际发出去变成了%252F，服务端解码一次拿到%2F，正好对得上。你自己手拼路径时如果只编一次，反而会 404。

这个现象不是 bug，是设计上让路径参数和路径分隔符能共存付出的代价。我的做法是固定一个规则：先对仓库名做一次完整的 URL 编码，然后交给客户端发出去，不再手动二次处理，如果你的客户端或反代有额外的规范化行为，用curl -v看一眼最终请求行，问题立刻现形。

另一个翻车点是版本演进。v2.0 这个大版本号从发布到现在，内部已经改过好几轮字段和路径。比如项目公开属性早期直接写在请求体的metadata里，后来顶层也开始接受name而不是project_name；配额早期是项目上的storage_limit字段，后来独立成/quotas资源；Webhook 早期的目标字段是单个target对象，后来变成targets数组。这些差异不体现在大版本号上，只能靠在线文档确认。最省事的做法是打开实例自带的 API 文档页（通常在/devcenter-api-2.0路径下），以你手上这台实例的实际文档为准，别照着网上某篇两年前的文章抄。

2. 调通第一个请求：环境确认与鉴权落地

2.1 三条自检命令先摸清底细

在写任何业务代码之前，我习惯先跑三条命令，把"服务活着、认证通、版本对"这三件事一次性确认掉。

export HARBOR_URL="https://registry.example.internal" export HARBOR_USER="admin" export HARBOR_PASS="YOUR_PASSWORD" # 1. 服务是否活着，返回当前组件健康状态 curl -s -o /dev/null -w "%{http_code}\n" \ "$HARBOR_URL/api/v2.0/health" # 2. 无需认证的系统信息，确认接口版本与是否只读 curl -s "$HARBOR_URL/api/v2.0/systeminfo" | head -c 500 # 3. 认证是否通，顺便看看有多少个项目 curl -s -u "$HARBOR_USER:$HARBOR_PASS" -D - \ "$HARBOR_URL/api/v2.0/projects?page=1&page_size=1" -o /dev/null

第二条特别有用。systeminfo是不需要认证的，返回里通常带着版本号、只读标记、是否启用了漏洞扫描之类的信息。如果read_only是 true，你就死了这条心吧，所有写操作都会给你一个 403，这时候别浪费时间怀疑权限配置，去看看实例是不是被切到了只读模式做迁移。

第三条我用-D -把响应头打到标准输出，是因为要确认分页头存不存在。正常情况下你会看到X-Total-Count和Link两个头，后者直接告诉你下一页怎么拼。这两个头是整套接口分页能力的基础，没有它们你就得靠返回条数是否等于 page_size 来猜下一页，那是最不靠谱的判断方式，最后页刚好满的时候你的脚本一定会多循环一次。

2.2 Basic Auth 与 Robot Token 的实测差异

概念上两种都是 Basic Auth，但实际用起来差别不小。管理员账号走 Basic，几乎所有端点都通；机器人账号走 Basic，用户名形如robot$项目名+账号名，注意里面那个$和+在某些 shell 里需要转义，在 URL 里也需要编码，不处理的话会得到 401 而不是更友好的提示。

我做过一个对比，把同一个只读任务分别用两种身份跑一遍：

这张表里最后一行才是最值钱的部分。审计可追溯不是"合规要求"，是事故排查时的唯一抓手。另外注意第三行：机器人账号查不到无关项目时，有些端点返回 403，有些返回 404，别指望统一的语义，判断权限问题的正确姿势是看"你本来应该看到什么"，而不是"返回了什么码"。

2.3 用 Python 封装一个最小可用客户端

直接裸写requests会很快变成一坨重复代码，尤其是分页、重试、错误处理这三件事。我一般先封一个薄薄的一层。

import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry class HarborClient: def __init__(self, base_url, user, password, timeout=15): self.base = base_url.rstrip("/") + "/api/v2.0" self.s = requests.Session() self.s.auth = (user, password) self.s.headers.update({"Accept": "application/json"}) self.timeout = timeout retry = Retry( total=3, backoff_factor=0.8, status_forcelist=[502, 503, 504], allowed_methods=["GET", "HEAD"], ) adp = HTTPAdapter(max_retries=retry, pool_maxsize=16) self.s.mount("https://", adp) def get(self, path, **params): r = self.s.get(self.base + path, params=params, timeout=self.timeout) r.raise_for_status() return r def iter_all(self, path, page_size=100, **params): page = 1 while True: r = self.get(path, page=page, page_size=page_size, **params) items = r.json() or [] for it in items: yield it total = int(r.headers.get("X-Total-Count", "0")) if page * page_size >= total or not items: break page += 1

几个刻意的设计取舍说明一下。重试只给 GET 和 HEAD，写操作绝不自动重试，因为删除类接口通常不幂等，你可能第一次已经删成功了只是响应丢了，重试就会拿到 404 然后脚本报错退出，看起来像失败其实是成功。pool_maxsize调到 16是因为遍历仓库时很多人会开线程池并发，默认的 10 个连接会成为瓶颈，你会看到请求莫名排队。分页终止条件用X-Total-Count而不是"返回条数"，就是为了躲开最后页刚好满的那个边界情况。

超时给 15 秒也有讲究。查扫描结果这种涉及大对象聚合的接口偶尔会慢，但真慢到 15 秒以上，基本说明服务端出问题了，与其干等不如早点抛错让流水线失败，把问题暴露在部署阶段而不是半夜的告警里。

3. 核心场景实操：镜像治理的四个高频任务

3.1 项目创建与配额设置的分步动作

建项目是流水线里最常见的动作，但它其实包含三步：创建项目、设置配额、绑定机器人账号。很多人只做第一步，结果项目跑了两周把磁盘撑爆。

# 第一步：创建项目（私有） curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ -H "Content-Type: application/json" \ -X POST "$HARBOR_URL/api/v2.0/projects" \ -d '{"project_name":"demo","metadata":{"public":"false"}}' # 第二步：拿到项目 id 和它的配额 id curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ "$HARBOR_URL/api/v2.0/projects/demo" curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ "$HARBOR_URL/api/v2.0/quotas?reference=project&reference_id=3" # 第三步：把硬配额改到 50GiB（单位是字节） curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ -H "Content-Type: application/json" \ -X PUT "$HARBOR_URL/api/v2.0/quotas/1" \ -d '{"hard":{"storage":53687091200}}'

配额的单位是字节，不是 GB，也不接受字符串。53687091200 就是 50×1024³，我一般写个换算函数而不手敲数字，手敲错一位就是 5GiB 和 50GiB 的差别，而且错小了不容易发现，等到限制触发才恍然大悟。填-1表示不限制，公共缓存类项目可以这么干，业务项目千万别。

这里有个容易忽略的点：配额独立于项目存在，项目删除后配额记录可能残留，批量删除项目再重建同名项目时，你会看到配额统计是"继承"来的旧数据。处理办法是建项目后按 id 重新查一次配额，把统计值清干净，或者在删项目时确认配额记录一并消失。

第三个动作是绑机器人账号。我给每个项目固定建两个：ci-push只给 push 权限，scan-read只给制品读取和扫描结果读取权限。名字统一格式，好处是遍历所有机器人账号时可以直接按名字前缀筛出哪些项目"漏建了"。

3.2 遍历仓库与制品：编码、分页、字段裁剪三件事

批量清理、批量打标签、批量查漏洞，起点都是同一件事：把某个项目下的所有制品捞出来。这段代码写不对，后面全是错的。

import urllib.parse def list_artifacts(client, project): repo_path = f"/projects/{project}/repositories" for repo in client.iter_all(repo_path): repo_name = repo["name"].split("/", 1)[1] # 去掉项目前缀 encoded = urllib.parse.quote(repo_name, safe="") art_path = (f"/projects/{project}/repositories/" f"{encoded}/artifacts") yield from client.iter_all( art_path, with_tag="true", with_scan_overview="true" )

三个关键点。第一，仓库接口返回的name是带项目前缀的全名，比如demo/team-a/service-x，而后续请求里要的repository_name是去掉前缀的部分，这个转换不做，你会一直 404 而且看不出原因。第二，safe=""保证斜杠也被编码，这就是前面说的那个坑的解法。第三，with_scan_overview这类参数是按需开启的，默认不返回。它对每个制品会多聚合一份漏洞摘要，返回体可能大好几倍。我一般做"先粗查后精查"：遍历列表时不带这个参数，只拿 tag、大小、推送时间；筛出目标制品后再单独查详细漏洞，接口响应能快三五倍。

还有一个坑是标签。制品默认只返回 digest 和一个 tag 列表的引用，要拿到具体的 tag 名和推送时间，必须显式带with_tag=true。曾经有个脚本想删"30 天前的 tag"，结果拿到的 tag 列表是空数组，脚本老老实实跑完，一个都没删，日志里全是成功，第二天被业务方问"为啥旧 tag 还在"。做清理类脚本，一定要在试运行阶段把"预计处理数量"打出来，数量为 0 就先停下来看看是不是取数逻辑有问题。

3.3 保留策略与垃圾回收的联动逻辑

这是所有镜像仓库治理里最难讲清楚的部分，也是最容易出事故的部分。保留策略（Retention Policy）解决的是"哪些制品该被标记出来删掉"，垃圾回收（GC）解决的是"被删掉的制品占的磁盘什么时候真正释放"。这是两个独立动作，必须串联。

保留策略的配置逻辑是"规则 + 算法"。规则形如"保留最近推送的 N 个"或"保留最近 N 天内的"，多个规则之间用or或and组合。or的语义是"命中任一规则就保留"，安全但占空间；and的语义是"必须同时命中才保留"，省空间但危险。经验是清理无 tag 制品用or，清理有 tag 的旧版本用and，并且永远先跑 dry run。

# 先跑一次试运行，只出报告不动数据 curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ -H "Content-Type: application/json" \ -X POST "$HARBOR_URL/api/v2.0/system/gc/schedule" \ -d '{"schedule":{"type":"Manual"}, "parameters":{"delete_untagged":true,"dry_run":true,"workers":3}}' # 拿到执行记录 id 后轮询状态，日志里会列出每条待删记录 curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ "$HARBOR_URL/api/v2.0/system/gc/12/log"

delete_untagged这个参数是开关级别的重要：true 表示"没有 tag 指向的制品一并清掉"。这正好配合一个常见做法——CI 推镜像时先推一个临时 tag，等所有验证通过再打正式 tag。中间失败留下的孤儿制品全是无 tag 的，交给这个开关收拾，不用业务方操心。

workers我一般设 3 到 5。设太大反而慢，因为 GC 的主要瓶颈在存储的随机读，并发太高会把存储打满，顺带影响正在推拉的业务。GC 一定要挑低峰期或者用调度类型排到凌晨，它在跑的时候仓库的写操作可能被短暂阻塞，白天跑会看到流水线偶发超时。

还有一点容易忽略：保留策略本身也是走接口配置的。早期版本的创建路径是/api/v2.0/retentions，后续版本逐渐迁移到项目下的子路径/api/v2.0/projects/{project_name}/retentions。写代码时不要硬编码，先探测一下哪个路径返回 200，再决定用哪个，比在代码里写死版本判断要稳。策略的scope字段需要项目的数字 id，不是项目名，这一层映射别搞错了。

3.4 机器人账号的权限最小化与密钥轮换

机器人账号的设计里有一个细节很能体现工程成熟度：创建时只返回一次 secret。这不是刁难，是逼着你把密钥交给密钥管理系统而不是存在某个文档里。

curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ -H "Content-Type: application/json" \ -X POST "$HARBOR_URL/api/v2.0/robots" \ -d '{ "name": "ci-push", "duration": 90, "level": "project", "permissions": [{ "kind": "project", "namespace": "demo", "access": [ {"resource": "repository", "action": "pull"}, {"resource": "repository", "action": "push"}, {"resource": "artifact", "action": "read"} ] }] }'

duration是有效期天数，90 天是我个人比较喜欢的值。太短了天天轮换受不了，太长了等于永久密钥。设置有效期这件事，关键在于你得有一个到期提醒机制，否则 90 天后流水线集体 401，排查方向会先往网络和证书上跑，浪费半小时。我的做法是把这个信息同步写进配置中心，跟其他凭证一起统一管理，到期前一周自动告警。

返回体里的secret一定要当场落进密钥管理系统，脚本里那行echo输出记得关掉。我见过把创建脚本连同输出一起提交进 Git 的操作，虽然大概率当时还没接生产，但这个习惯一旦养成，出事只是时间问题。

需要注意权限模型在大版本之间改过。早期的资源类型和动作是固定的几十个组合，后来引入了按数据维度的细化控制，同一个"读取"动作在不同资源上能配得更细。升级仓库版本之后，一定要把现有的机器人账号导出核对一遍权限实际生效情况，别假设"升级不改行为"。

4. 可观测与自动化挂钩：把仓库接进现有体系

4.1 Webhook 策略的创建与事件过滤

光靠轮询查状态太低效，正确做法是让仓库主动往外推事件。配置入口是项目级的 Webhook 策略。

curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ -H "Content-Type: application/json" \ -X POST "$HARBOR_URL/api/v2.0/projects/demo/webhook/policies" \ -d '{ "name": "notify-ci", "enabled": true, "event_types": ["PUSH_ARTIFACT", "DELETE_ARTIFACT", "SCANNING_COMPLETED"], "targets": [{ "type": "http", "address": "https://ci.example.internal/hooks/registry", "auth_header": "Bearer YOUR_TOKEN", "skip_cert_verify": false }] }'

两个实操要点。第一，事件类型不要全勾。全勾之后每条推送都会触发一次回调，一个项目一天几万次推送的时候，你的接收端会先垮。按需勾几个关键事件就够了。第二，skip_cert_verify永远保持 false。有人为了图快设成 true，等于把回调内容暴露在明文里，而回调体里是包含仓库名和 tag 的，信息量不小。

targets是数组这一点也值得强调：早期版本是单个target对象，后来为了支持多路投递改成了数组。如果你照着老文档写单对象，接口会返回 422 而不是友好提示，排查起来会绕不少弯。

配置完之后一定要验证。策略查出来之后有个子资源可以看最近执行记录，包含投递时间、返回码、失败原因。我第一版就踩过坑：接收端返回 200 但业务没处理，因为对方框架默认只读 body 不校验签名，而我在发送端配了auth_header，接收端没校验——两边都觉得自己没错，问题在对接约定上。上线前用一次真实推送验证一遍完整链路，比看十遍文档都管用。

4.2 审计日志拉取与增量同步

审计日志的价值在于它是"事实"而不是"状态"。项目列表能告诉你现在有什么，审计日志能告诉你"谁在什么时候把它变成了现在这样"。做安全复盘、追查误删、统计各项目的活跃度，都靠它。

# 系统级日志，按操作类型过滤 curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ "$HARBOR_URL/api/v2.0/audit-logs?page=1&page_size=50&q=operation%3Ddelete" # 项目级日志，只看某个项目 curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ "$HARBOR_URL/api/v2.0/projects/demo/audit-logs?page=1&page_size=50"

q参数的语法是key=value，模糊匹配用~，多条件用逗号分隔。注意 URL 里等号要编码成%3D，不编码在某些反代上会被截断。

做增量同步的正确姿势是按时间窗口拉取，而不是按页码自增。因为审计日志是持续追加的，你翻到第 5 页的时候新的记录已经把前面挤走了，页码自增一定会漏数据。我的做法是每次记录上次同步到的最大时间戳，下一次拉取时用查询参数把这个时间当起点，重叠一小段窗口（比如 5 分钟）防止边界丢数据，重复的部分在入库时按日志 id 去重。

有个细节：审计日志默认有保留天数，超过就自动清理。你要做长期留存，必须自己拉走存起来。这件事最好在仓库刚上线时就定下来，等出事了才想起来"三个月前那次是谁删的"，已经晚了。

4.3 漏洞扫描结果读取与质量门禁

把扫描结果读出来做门禁，是很多人想做的进阶动作。思路是：制品推送后触发扫描，扫描完成后读结果，高危数量超过阈值就让流水线红掉。

# 触发扫描 curl -s -u "$HARBOR_USER:$HARBOR_PASS" -X POST \ "$HARBOR_URL/api/v2.0/projects/demo/repositories/team-a%2Fservice-x/artifacts/latest/scan" # 读扫描概览 curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ "$HARBOR_URL/api/v2.0/projects/demo/repositories/team-a%2Fservice-x/artifacts/latest?with_scan_overview=true" # 读详细漏洞列表 curl -s -u "$HARBOR_USER:$HARBOR_PASS" \ "$HARBOR_URL/api/v2.0/projects/demo/repositories/team-a%2Fservice-x/artifacts/latest/additions/vulnerabilities"

门禁阈值该怎么定，这里说说我的经验。一开始我按"严重级别计数"一刀切，结果发现同一个底层基础镜像的漏洞会在所有制品里重复出现，一百个服务全部红掉，但根因只有一个。后来改成两级：先统计全项目范围内的"唯一漏洞集合"，把基础镜像层面的问题单独聚合出来推动基础镜像升级；再看具体制品层面的增量，只对新增的高危做阻断。这样既能卡住新引入的问题，又不至于让整个交付链停摆。

还有一点：扫描状态不是立刻可用的。刚推完的制品查询扫描结果可能返回空或者 pending 状态，直接断言"高危数大于 3 就失败"会把正常流程卡住。正确做法是轮询到状态为 Success 或 Error 再判断，轮询超时按"不阻断但告警"处理，别因为扫描组件抖动就阻断发布。

5. 常见问题与排查技巧实录

5.1 状态码速查与典型成因

接口出错时第一反应不应该是猜，而是对照状态码把范围缩小。下面这张表是我自己攒的，覆盖了这几年遇到的绝大多数情况。

表里最想强调的是 404 和 422 这两行。404 不一定是没有，更多时候是你路径拼错了；422 是最友好的错误码，它几乎总会告诉你哪个字段不对，值得停下来把响应体完整读一遍，而不是只看状态码就重试。

5.2 分页陷阱与数据一致性

批量操作里的所有诡异问题，一半以上出在分页上。除了前面说的"最后页刚好满"的边界，还有两个坑。

第一个是边遍历边删除。你在第 1 页删了 10 条，翻到第 2 页时，原本在第 2 页的 10 条已经挪到第 1 页去了，于是你正好跳过它们。解法很简单：先全量拉一遍生成待处理清单，再执行删除，不要边翻边删。清单可能很大，但这个内存开销远比漏删或者误删便宜。

第二个是遍历过程中数据在变。你做清理脚本时，另一条流水线正在往同一个仓库推新制品。这时候的清单是"某个瞬间的快照"，执行删除时目标可能已经不在了。删除接口对不存在的资源返回 404，脚本要不要把它当失败？我的处理是把 404 视为幂等成功，记一笔日志继续跑，这样重复执行和并发执行都不会炸。

还有一个隐蔽的问题：不同端点对page_size的上限不一样。大部分容忍到 100，个别端点会限制得更低，你传 200 它可能静默按 100 返回，也可能报参数错误。稳妥的做法是统一用 100，并且永远以X-Total-Count决定翻页次数，别自己算。

5.3 并发控制与幂等设计

做批量清理时并发能显著提速，但开多大有讲究。我在一个两万制品的项目上做过对比，同一台机器、同一个实例，纯删除操作：

拐点非常明显：并发从 4 往上，耗时几乎不再下降，失败率却开始爬升。原因是瓶颈已经从客户端转移到服务端和数据库的锁竞争上了。我用下来 4 到 6 是最舒服的区间，配一个指数退避重试，整体成功率基本能到 100%。

幂等设计上，我坚持三条：删除类操作把 404 当成功；创建类操作失败后先查一次再决定是否重建（避免重复建出两个同名项目导致后面全乱）；配额修改这类覆盖型操作天然幂等，可以放心重试。

最后分享一个排查小技巧。所有写操作我都要求记录完整的请求路径 + 响应状态 + 响应体的前 200 字符，看起来傻，但出事的时候这三样东西能省掉一整轮沟通。有一次一个批量打标签的脚本对同一批制品跑了三次，前两次"成功"，第三次报 409，翻日志发现前两次其实打的是不同标签，409 是因为第三次想覆盖已有标签而接口不允许。如果当初只记了状态码不记路径，这个结论根本推不出来。

我在实际操作中的体会是，这套接口本身不难，难的是把它当成一套有状态的资源管理工具来用，而不是一堆能调通的 URL。真要动手，先拿一个测试项目把所有写操作跑一遍，把每个响应体的结构存成样例，后面写工具有据可依，比边写边试快得多。