凭据同步 (`uniqc sync`)¶

在多台机器之间同步 ~/.uniqc/config.yaml 中的量子真机凭据与平台配置。uniqc sync 提供两套相互独立、可各自单独使用的后端：

Infisical 后端（setup / status / push / pull）：把配置扁平化为一组 UNIQC_ 前缀的 secrets，存到 Infisical 密钥管理平台（通过本机 infisical CLI 访问）；
confsync 后端（upload）：把整个配置文件作为一份加密文档上传到自托管的 confsync 服务器（依赖可选的 confsync-client 包）。

两套机制互不依赖：用哪一套、是否都用，完全由你决定。

概述（Infisical 后端）¶

uniqc sync 把配置文件中的平台凭据（以及随之保存的非敏感平台设置，如 task_group_size、available_qubits、IBM 代理等）扁平化为一组 UNIQC_ 前缀的 Infisical secrets，从而实现：

在一台机器上 push 上传凭据，在其他机器上 pull 一键恢复；
服务器端轮换 token 后，各机器 pull 即可拿到新值；
项目里其他非 UNIQC_ 前缀的 secrets 完全不受影响。

子命令	说明
`setup`	保存 Infisical 项目 ID 与默认环境到 `~/.uniqc/config.yaml` 的 `sync` 节
`status`	对比本地与远端差异（不写入任何内容）
`push`	上传本地配置到 Infisical（本地优先，远端同名值被覆盖）
`pull`	下载远端配置覆盖本地（远端优先，自动生成时间戳备份）
`upload`	把整个配置文件上传到 confsync 服务器（独立后端，见下文）

前置条件（Infisical 后端）¶

# 1. 安装 Infisical CLI（https://infisical.com/docs/cli/overview）
# macOS / Linux:
brew install infisical/get-cli/infisical
# 2. 登录
infisical login

在 Infisical 中创建一个项目（例如 uniqc），记下 Project ID（项目设置页可以看到），建议为凭据使用独立项目或独立环境（dev / staging / prod）。

初始设置 (`uniqc sync setup`)¶

uniqc sync setup --project-id 8501c316-2ab9-4d44-959d-73fd119b5736 --env dev

该命令把同步设置写入配置文件的 sync 节（该节属于本机设置，不会被同步）：

sync:
  project_id: 8501c316-2ab9-4d44-959d-73fd119b5736
  env: dev

也可以不用 setup，改用环境变量或命令行参数：

优先级	project_id	env
1（最高）	`--project-id`	`--env` / `-e`
2	`UNIQC_INFISICAL_PROJECT_ID`	`UNIQC_INFISICAL_ENV`
3	配置文件 `sync` 节	配置文件 `sync` 节
默认	—（缺失时报错）	`dev`

查看差异 (`uniqc sync status`)¶

uniqc sync status                # 表格形式
uniqc sync status --format json  # JSON 输出，适合脚本

输出分三个视图：

Would push：仅本地存在（add）或与远端不同（update）的键；
Would pull：仅远端存在或与本地不同的键；
Stale on remote：远端有、本地没有的键——只有 push --prune 才会删除它们。

输出只包含配置键名（如 default.originq.token），永远不会打印任何密钥值。

上传凭据 (`uniqc sync push`)¶

uniqc sync push                 # 上传新增/变更的键
uniqc sync push --prune         # 同时删除远端已不在本地的 UNIQC_ 键
uniqc sync push --dry-run       # 只预览，不写入

push 是本地优先：远端同名键会被本地值覆盖；不询问。
--prune 只删除 UNIQC_ 前缀且符合 uniqc 布局的远端键，项目中的其他 secrets 永远不会被 push 触碰。
首次在新项目上使用时，建议先 status 再 push。

下载凭据 (`uniqc sync pull`)¶

uniqc sync pull                 # 覆盖本地配置（自动备份）
uniqc sync pull --no-backup     # 跳过备份
uniqc sync pull --dry-run       # 只预览

pull 是远端优先：本地 profile 段被远端状态整体替换（镜像语义），本地有而远端没有的键会被丢弃。
本机专属键不会被动：active_profile、always_ai_hints、sync、以及不含平台子键的节（如 gateway）。
写入前会把旧配置备份为 ~/.uniqc/config.yaml.bak-<时间戳>。
若远端环境为空（一个 UNIQC_ 键都没有），pull 会拒绝执行，避免误清空本地配置。
若本地 active_profile 指向的 profile 不在远端，pull 会自动切回 default（或第一个可用 profile）并给出警告。

新机器上恢复凭据的完整流程：

infisical login
uniqc sync setup --project-id <ID> --env dev
uniqc sync pull
uniqc config validate   # 确认配置有效

Secret 布局与值编码¶

每个配置值对应一个 secret，命名规则：

<profile>.<platform>.<field>  ->  UNIQC_<PROFILE>_<PLATFORM>_<FIELD>

例如：

配置键	Secret 名
`default.originq.token`	`UNIQC_DEFAULT_ORIGINQ_TOKEN`
`default.quark.QUARK_API_KEY`	`UNIQC_DEFAULT_QUARK_QUARK_API_KEY`
`default.ibm.proxy.http`	`UNIQC_DEFAULT_IBM_PROXY_HTTP`

值编码规则（保证 push/pull 往返后类型不变）：

字符串原样存储——token 可以直接被其他工具消费（infisical run -- env、infisical secrets get UNIQC_DEFAULT_ORIGINQ_TOKEN）；
数字、布尔、列表、字典等非字符串值存储为 json: 前缀 + JSON 文本（如 json:200、json:[3, 7, 11]）；
以 json: 或 @ 开头、或含换行的字符串同样走 JSON 编码，避免歧义。

空值（空字符串、空列表等）代表”未设置”，不会被同步。

CI / 无人值守场景¶

infisical CLI 登录态之外，还可以使用机器身份 / 服务令牌（Machine Identity Access Token 或 Service Token）：

export UNIQC_INFISICAL_TOKEN=<machine-identity-access-token>
export UNIQC_INFISICAL_PROJECT_ID=<project-id>
uniqc sync pull --env prod

自建 Infisical 实例时，域名沿用 CLI 自带的环境变量 INFISICAL_DOMAIN。

上传到 confsync (`uniqc sync upload`)¶

upload 是独立于上述 Infisical 流程的另一种同步方式：它把本地的 ~/.uniqc/config.yaml 整体上传到自托管的 confsync 服务器，适合在多台机器之间共享同一份配置。

前置条件（confsync 后端）¶

upload 依赖可选的 confsync-client 包；uniqc 本身不强制安装它。如果未安装，执行 uniqc sync upload 时会提示：

✗ confsync-client is not installed. Install it with `pip install confsync-client`,
  then run `confsync login --server <url>`.

安装并登录（只需一次，凭据保存在 ~/.confsync/credentials.json，所有接入了 confsync 的工具共享）：

pip install confsync-client
confsync login --server https://<your-confsync-server>

注意：~/.uniqc/config.yaml 里不需要（也不应该）配置任何 confsync 字段。服务器地址和 API key 全部由 confsync 自己的凭据文件管理， uniqc sync upload 会自动调用 confsync 客户端读取它们。这与 Infisical 后端的 sync 节配置互不影响。

上传配置¶

# 上传 ~/.uniqc/config.yaml 为 confsync 文档 uniqc/config.yaml
uniqc sync upload

# 使用自定义文档名（例如区分多台机器）
uniqc sync upload --name laptop.yaml

每次上传都会在服务器端生成一个新版本（历史版本默认保留最近 20 个，可在 confsync 的 Web UI 中查看和回滚）。文档在服务器端以 AES-256-GCM 加密存储，具体内容由 confsync 服务端保证。

安全说明¶

~/.uniqc/config.yaml 由 uniqc config 统一以 0600 权限原子写入；
CLI 输出（status / push / pull / dry-run）只显示键名，绝不回显密钥值；
pull 前自动备份；任何一次 pull 的旧配置都可以从 ~/.uniqc/config.yaml.bak-* 找回；
请确认 Infisical 项目的访问权限配置（最小权限原则），凭据的可见范围等于项目成员范围。

常见问题¶

Error: infisical CLI failed (exit 1): ... couldn't find your logged in details 先运行 infisical login；CI 中改用 UNIQC_INFISICAL_TOKEN。

Error: No Infisical project configured 运行 uniqc sync setup --project-id <ID>，或设置 UNIQC_INFISICAL_PROJECT_ID。

换了一台机器 pull 后，为什么 task_group_size 这类设置也变了？ sync 镜像的是整个平台配置段（凭据 + 平台设置）。只同步 token 的做法会让两台机器的配置悄悄分叉，更难排查。

Ignored unparsable secret 'UNIQC_...' 警告 项目里存在 UNIQC_ 前缀但不符合 uniqc 布局的 secret。它会被忽略且不会被修改/删除；确认它不是本工具创建的即可。

凭据同步 (uniqc sync)¶