ducc-helper

京东 DUCC 配置中心（读 / 改 / 增删 / 发布）

一个 skill 打通 DUCC（泰山配置中心）的日常：查命名空间/配置文件/环境、读配置项、增删改配置项、全量/灰度发布。零配置：认证从本机京ME客户端自动换出 sso.jd.com。

DUCC 结构（理解这个才能用对）

命名空间(namespace)          如 pop_customs_center「跨境-赤道-center」，对应一个应用
  └─ 配置文件(config)         如 center_config
       └─ 环境/profile        如 dev(真预发) / common，即"生产配置""预发配置"
            └─ 配置项(item)    key = value，如 ducc.order.trace.merge.read.switch = true

• 命名空间：一个应用一个，有 code(pop_customs_center) 和中文名(跨境-赤道-center)。
• 配置文件：命名空间下有多个（center_config / common 等）。
• profile：配置文件下的具体环境，就是 UI 里 center_config / dev、center_config / common。
• 配置项：profile 里真正的 key/value，可选「无格式」或「JSON 格式」。

只需给 code：命名空间/配置文件/profile 都可传中文 code，脚本自动调 search 反查内部数字 ID（nsId/cId/profileId）；也可直接传数字 ID。

前置条件（开箱即用的关键）

1. 本机已安装并登录京ME桌面客户端（进程名 JDITDesk）。脚本通过本机 127.0.0.1:8988~9006 端口换取 token，全自动，无需扫码/填 token。
2. Python 3 + requests：pip install -r requirements.txt。
3. 无需浏览器。

认证原理：lib/jme_auth.py 从本机京ME客户端零配置换出 sso.jd.com（唯一 Cookie）， 请求真实域名 pserve.jd.com，每个请求带两个自定义头 config-env + x-proxy-opts（见下）。 token 缓存在 ~/.ducc-helper-cache.json，过期自动刷新，接口走 http。 报未登录/401 → 京ME未登录或token过期，加 --force-refresh。

★ 生产 / 预发环境（关键机制）

DUCC 用 --env 区分环境，脚本转成两个配套 header（必须同时切换）：

• 预发未开放的现象（很常见）：profiles/items 在 --env pre 下读到空 data:[] 或报 503 环境不存在。脚本会提示「预发环境未开放或无 profile」。pop_customs_center 当前预发就未开放。
• 命名空间、配置文件列表是环境无关的元数据（脚本一律用 online 解析 code→ID），只有 profile 和配置项才随 env 切换。

能力一：配置读取

# 列所有命名空间（--search 按 code/中文名过滤）
python scripts/config.py namespaces --search customs

# 列某命名空间下的配置文件
python scripts/config.py configs pop_customs_center

# 列配置文件下的 profile（生产配置/预发配置，如 dev/common）
python scripts/config.py profiles pop_customs_center center_config

# 列 profile 下的配置项（--search 按 key/描述过滤，--all 翻遍所有分页）
python scripts/config.py items pop_customs_center center_config common
python scripts/config.py items pop_customs_center center_config common --search order.trace

# 读单个配置项的值
python scripts/config.py get pop_customs_center center_config common ducc.order.trace.merge.read.switch

# 读预发环境（未开放会提示）
python scripts/config.py items pop_customs_center center_config common --env pre

• namespaces 返回 nsId/code/name/owner；configs 返回 cId/code/name；profiles 返回 profileId/code/name/version。
• items/get 返回配置项 key/value/description/dataType/isReleased/updateBy。
• 找不到配置文件时：可去对应应用的行云分组配置里看该应用挂了哪个 DUCC 命名空间/配置文件（装了 jdos-helper 可用 config.py 读行云配置文件）。

能力二：配置写入（增 / 改 / 删）

# 新增或覆盖配置项（存在则改，不存在则建）
python scripts/write.py set pop_customs_center center_config common ducc.foo.switch true
python scripts/write.py set pop_customs_center center_config common ducc.foo.json '{"a":1}' --format 1 --desc "说明"

# 仅修改已存在项（不存在报错）
python scripts/write.py update pop_customs_center center_config common ducc.foo.switch false

# 删除配置项
python scripts/write.py delete pop_customs_center center_config common ducc.foo.switch

• --format：0=无格式(纯文本/字符串，默认)，1=JSON（value 需是合法 JSON 字符串）。
• 增/改/删只影响「草稿」（未发布内容，不影响线上运行），所以直接执行、不需 --confirm。
• ⚠ 改完必须 release 才真正生效到线上。

能力三：发布（全量 / 灰度分批）

# 列可用的灰度编排模板（灰度发布要用）
python scripts/write.py orchestrates pop_customs_center

# 全量发布（默认；不加 --confirm 只预演打印计划）
python scripts/write.py release pop_customs_center center_config common ducc.foo.switch                # 预演
python scripts/write.py release pop_customs_center center_config common ducc.foo.switch --confirm      # 真发
python scripts/write.py release pop_customs_center center_config common k1 k2 k3 --confirm             # 一次发多个key

# 灰度分批发布（--orchestrate 指定编排模板 code）
python scripts/write.py release pop_customs_center center_config common ducc.foo.switch \
    --orchestrate "1731329960745.69139" --confirm
# 只发第一批就停(人工确认再继续)：加 --batch-pause
python scripts/write.py release ... --orchestrate  --confirm --batch-pause

• 全量发布：两步（submitAuditKeys 建任务 → release/keys 执行），一次发到所有实例。
• 灰度分批发布（用户强调的核心）：按编排模板（如 10%→30%→60%→100%）分批。脚本逐批推进，每批发完自动轮询该批所有 IP 状态，等全部 COMPLETED 才发下一批；某批超时/失败则暂停不再往下发。
• ⚠ 同一 profile 同时只能有 1 个进行中的发布任务（并行上限1个）。上一个没发完（或卡住）时，新发布会报 1606 并行任务超上限。去页面把卡住的任务发完或取消。
• 未加 --confirm 只预演（打印发布计划+批次），确认后再加 --confirm。

输出约定

脚本 stdout 打印 JSON、stderr 打印进度。拿到结果后按用户诉求呈现：清单类先给概览表格；配置项正文/值按需展示。

安全约定（重要）

• 只读命令（namespaces/configs/profiles/items/get/orchestrates）直接执行。
• 增/改/删只改草稿（不影响线上运行），直接执行；但要提醒用户「需 release 才生效」。
• **发布（release）**让配置真正生效到线上运行实例，风险最高：默认只预演，必须显式加 --confirm 才下发。生产环境（--env online 默认）尤其谨慎，灰度发布优先于全量。

接口与实现参考

底层全部接口（真实域名、config-env/x-proxy-opts 头、code→ID 解析、发布链路与批次语义、发现方法论）见 references/api.md，仅在调试或扩展新能力时查阅。lib/jme_auth.py(认证) 与 lib/ducc_client.py(公共HTTP层：sso认证 + online/pre 双环境头切换 + code→ID 解析) 可被新脚本复用。