配置

CertiMan CLI 的配置来自多层来源，按优先级从高到低依次生效：命令行 flag → -c 指定的配置文件 → --profile 模板 → 证书级 cert.yaml → 全局 certiman.yaml → 内置默认值。本页汇总配置文件路径、数据目录结构、全局 flag、环境变量、退出码等所有跨命令共享的参考信息。

数据目录

CertiMan 将配置、凭证、证书文件、日志集中存放在 ~/.certiman/，可通过环境变量 CERTIMAN_HOME 覆盖到其它路径。

text

~/.certiman/                        # 根目录
├── certiman.yaml                   # 全局配置
├── logs/                           # 日志按月分卷，保留 6 个月自动清理
│   └── cc-YYYY-MM.log              # 手动命令与定时轮次同卷
└── cc/                             # CertCloud 模式目录
    ├── credentials                 # OAuth 凭证（权限 0600）
    ├── profiles/                   # 账号级模板目录
    │   └── <name>.yaml
    └── certs/                      # 证书目录
        └── <CN>/                   # 每张证书一个子目录，CN 为主域名
            ├── cert.yaml           # 证书级配置
            ├── state.json          # 订单/证书状态
            ├── cert.pem            # 服务器证书
            ├── privkey.pem         # 现役私钥（权限 0600）
            ├── chain.pem           # 中间证书链
            ├── fullchain.pem       # 服务器证书 + 中间证书链
            └── converted/          # convert 命令产出的其它格式

敏感文件权限

credentials 与各证书目录下的 privkey.pem 权限为 0600。请勿放宽权限，以免其他用户读取凭证或私钥。

Windows 上的访问控制

Windows 使用 DACL 而非 0600 控制文件访问权限。CertiMan 自动将凭证与私钥的 DACL 限制为仅当前用户、SYSTEM 与管理员可访问；所在卷不支持 DACL（FAT32、exFAT 等）时，权限设置失败不会中断命令，certiman doctor 会报告该问题并给出 icacls 修复命令。

配置文件

CertiMan 使用分层的 YAML 配置。

全局配置 `~/.certiman/certiman.yaml`

跨模式共享的顶层偏好，通常通过 certiman config set 写入。

yaml

version: 1                          # schema 版本，CLI 写入时自动填充
default_output: table               # table | json | text；未设按 TTY 自动选择
language: zh-CN                     # zh-CN | en；未设时默认 en
insecure_skip_verify: false         # true | false；CERTIMAN_INSECURE 优先于本字段

字段	类型	允许值	说明
`version`	int	`1`	schema 版本，CLI 自动维护
`default_output`	string	`table` / `json` / `text`	默认输出格式；未设时按 TTY 自动选择
`language`	string	`zh-CN` / `en`	输出语言；未设时默认 `en`
`insecure_skip_verify`	bool	`true` / `false`	跳过 TLS 校验；`CERTIMAN_INSECURE` 优先于本字段，两者均未设置时严格校验证书。对 `certiman upgrade` 无效，升级过程始终严格校验证书

证书级配置 `~/.certiman/cc/certs/<CN>/cert.yaml`

每张证书独立一份，记录该证书的申请参数、验证方式、部署 hook、输出格式等。首次通过 certiman issue 申请时自动生成，后续 renew / reissue / status / download / deploy 命令从该文件读取默认值。完整字段清单参见证书命令 · 证书配置文件。

配置来源与优先级

CertiMan 的配置来自六层来源，同名字段按下图从上到下优先级递减：取优先级最高的非空值，未设置时使用下一层的值。

各层的存放位置与示例：

层	位置 / 示例
命令行 flag	`-o json` / `-d example.com`
`-c` 指定的配置文件	`certiman issue -c ./shop-cert.yaml`
`--profile` 模板	`~/.certiman/cc/profiles/<name>.yaml`
证书级 `cert.yaml`	`~/.certiman/cc/certs/<CN>/cert.yaml`
全局 `certiman.yaml`	`~/.certiman/certiman.yaml`
CLI 内置默认	CLI 自带的默认值

证书申请参数不支持通过环境变量设置：产品、域名、年限、组织信息等只能通过上述六层配置。少数与具体证书无关的本机设置（CERTIMAN_HOME / CERTIMAN_OUTPUT / CERTIMAN_LANG / CERTIMAN_INSECURE）支持环境变量，优先级介于命令行 flag 与 certiman.yaml 之间，见环境变量。

几个常见场景：

certiman issue --profile prod -d example.com -o json：-o json 覆盖任何配置里的 default_output；--profile prod 指定的模板仅在首次生成 cert.yaml 时写入（详见账号命令 · Profile 合并规则）
certiman.yaml 中 insecure_skip_verify 设为 false 时，命令行指定 --force 不会覆盖该设置：名称不同的 flag 与配置项互不覆盖，各层配置只按同名字段合并

全局 flag

所有子命令都可以使用的 flag。

flag	短名	类型	默认值	环境变量	说明
`--output`	`-o`	string	按 TTY 自动	`CERTIMAN_OUTPUT`	输出格式：`table` / `json` / `text`
`--force`	`-f`	bool	`false`		跳过交互确认或强制执行，具体语义随命令
`--quiet`	`-q`	bool	`false`		抑制 stderr 上的进度输出
`--verbose`	`-v`	bool	`false`		打印 debug 日志到 stderr
`--debug`		bool	`false`		打印 HTTP 请求/响应（凭证已脱敏）

只读命令的同步行为

status / login status 等展示类命令每次运行都会从平台同步最新状态；同步失败时使用本地快照，并在输出中标注同步时间与失败原因。写操作类命令（issue / renew / reissue 等）始终实时请求平台。

环境变量

下表是跨命令共享的环境变量。除 CERTIMAN_OUTPUT 有对应命令行 flag 外，其余均没有对应 flag，只能通过环境变量或配置文件设置。这类设置在同一台机器上通常保持不变，通过环境变量设置可避免每次运行时重复指定。

变量	说明
`CERTIMAN_HOME`	覆盖数据目录路径；未设时默认 `~/.certiman`
`CERTIMAN_OUTPUT`	对应 `--output`；优先级低于 `-o` flag、高于 `certiman.yaml` 的 `default_output`
`CERTIMAN_LANG`	输出语言：`zh-CN` / `en`。决定链为 `CERTIMAN_LANG` > `certiman.yaml` 的 `language` > 默认 `en`
`CERTIMAN_INSECURE`	跳过 TLS 证书校验，按布尔解析（`true` 开启、`false` 关闭，非法取值按未设置处理）；优先级高于 `certiman.yaml` 的 `insecure_skip_verify` 字段。对 `certiman upgrade` 无效，升级过程始终严格校验证书
`NO_COLOR`	关闭彩色输出，非空即真（业界通用约定）
`VISUAL` / `EDITOR`	`certiman profile edit` 使用的编辑器；缺省时 Windows 用 `notepad`、其它平台用 `vi`

Hook 脚本运行时还会收到一批以 CERTIMAN_ 开头的上下文变量（如 CERTIMAN_CERT_PATH、CERTIMAN_DCV_FQDN），详见 Hook 命令 · Hook 环境变量。

输出格式

--output / -o 或 default_output 配置项支持三种取值：

值	用途	何时作为默认
`table`	人类可读的表格，含颜色与对齐	交互式 TTY 环境
`json`	结构化 JSON，一次一份完整对象	非 TTY（管道、CI、脚本重定向）
`text`	Tab 分隔的纯文本，无表头，面向 shell 管道	需要手动开启

自动化脚本推荐显式设定 --output json，避免因终端环境不同而得到格式不一致的输出。

时间与时区

CertiMan 输出的所有时间字段（证书有效期 / 订单服务期、checked_at、downloaded_at、cron 下次触发时刻等）一律使用 UTC，尾部带 Z 后缀（RFC 3339）。CLI 不做时区本地化，请自行按本地时区换算。

例：下次触发: 2026-08-17T16:43:00Z 在东八区（北京时间）是 2026-08-18 00:43。

退出码

CertiMan 通过退出码传递结果类别，脚本可据此分支处理。

退出码	名称	含义
`0`	`ExitOK`	成功（包括无需执行任何操作的幂等成功）
`1`	`ExitGeneric`	通用错误（含 deploy hook 执行失败、`output.*_file` 目标不可写、cron 本轮存在被跳过的证书或上一轮扫描停滞、前台命令等证书目录锁超时（默认 20 分钟）、`upgrade` 本地 I/O 失败等）
`2`	`ExitUsage`	参数或用法错误（含配置文件语法错、未知字段、取值超出值域）
`3`	`ExitAuth`	认证失败（未登录、凭证过期、被吊销、`refresh_token` 已失效）
`4`	`ExitNotFound`	资源不存在（证书、订单、Profile）
`5`	`ExitAPI`	OpenAPI 业务错误（含 403 授权不足、`quota_exceeded`、`rate_limit`、平台 5xx 等）
`6`	`ExitNetwork`	网络错误（连接失败 / 超时 / JSON 解析失败）、请求超时，或调度器命令超时（`crontab` / `schtasks` 单命令超过 30 秒）
`7`	`ExitCanceled`	用户取消（`Ctrl-C`、对确认提示回答 `n`）。以证书是否已保存到本机为界：证书保存前的任一提问（包括向导中是否注册定时任务的提问）被取消时退 `7`；证书保存后的可选步骤（如保存模板）被取消时视为跳过，仍退 `0`

判断成败以退出码为准

自动化脚本请以退出码判断结果，不要依赖输出文本。输出文本随语言与输出格式（table/json/text）变化。

账号命令

profile（参数模板）

证书命令

Hook 命令

完整示例

定时任务命令

运维命令

配置

数据目录

配置文件

全局配置 `~/.certiman/certiman.yaml`

证书级配置 `~/.certiman/cc/certs/<CN>/cert.yaml`

配置来源与优先级

全局 flag

环境变量

输出格式

时间与时区

退出码

相关文档

profile（参数模板）

完整示例

配置 ​

数据目录 ​

配置文件 ​

全局配置 ~/.certiman/certiman.yaml ​

证书级配置 ~/.certiman/cc/certs/<CN>/cert.yaml ​

配置来源与优先级 ​

全局 flag ​

环境变量 ​

输出格式 ​

时间与时区 ​

退出码 ​

相关文档 ​

配置

数据目录

配置文件

全局配置 `~/.certiman/certiman.yaml`

证书级配置 `~/.certiman/cc/certs/<CN>/cert.yaml`

配置来源与优先级

全局 flag

环境变量

输出格式

时间与时区

退出码

相关文档