CINC Client 19.4.46 与 Workstation 26.3.0 配置参数详解
CINC 双版本线配置体系详解：节点端 /etc/cinc/client.rb 与 client.d 片段、solo.rb 本地模式，工作站端 config.rb/knife.rb 与 ~/.cinc/credentials 凭据优先级实测（knife 19.3.3），逐项参数对照 CLI 旗标并附生产模板
CINC Client 19.4.46 与 Workstation 26.3.0 配置参数详解
目标：讲清 CINC 双版本线的全部配置文件体系——节点侧（Cinc Client 19.4.46）的
/etc/cinc/client.rb、client.d片段目录与本地模式solo.rb，工作站侧（Cinc Workstation 26.3.0 / knife 19.3.3）的config.rb/knife.rb与~/.cinc/credentials凭据文件；逐项参数含义、加载优先级与查看/修改方式均给出实测回显。全文于 2026-10-27 在 Ubuntu 22.04 真实节点与工作站实测通过。
一、环境信息
- 节点侧：Cinc Client 19.4.46（内置 Ohai 19.1.40），配置根目录
/etc/cinc，运行缓存/var/cinc/cache - 工作站侧：Cinc Workstation 26.3.0（内置 knife 19.3.3、cinc-cli 6.1.40），配置位置
~/.cinc/credentials与<仓库>/.chef/config.rb（旧名knife.rb） - 机器规划：node01.cinc.lab（被管节点，装 Client）、ws01.cinc.lab（管理工作站，装 Workstation）
- 双版本线说明：CINC 各产品线版本号独立演进——Client 走 19.x 线、Workstation 走 26.x 线（Ohai 也有自己的 19.1.x 线）。本文 client.rb/solo.rb 属 Client 19.4.46 线，config.rb/knife.rb/credentials 属 Workstation 26.3.0 线；一篇覆盖两侧，是因为「节点收敛 + 工作站下发」必须成对配置才有意义。
二、前置条件
- 已按安装篇完成两侧安装与首次收敛：《Ubuntu 22.04 安装 CINC Client 19.4.46 与 Workstation 26.3.0 指南》
- 了解 CINC 与上游 Chef「同代码、双分发」的关系：《CINC Client 19.4.46 介绍与选型指南》
- 节点侧写
/etc/cinc需 root（或 sudo）权限。
三、参数查看与修改方式
CINC 的配置文件（client.rb / solo.rb / config.rb / knife.rb）全部是 Ruby DSL：每行一条 参数名 "值" 赋值，注释用 #。唯一例外是工作站的 ~/.cinc/credentials，它是 INI 格式（按 profile 分节）。
四种查看/修改手段：
- 直接编辑配置文件（主要方式）：改完下次运行生效，无热重载概念；
- 命令行临时覆盖：cinc-client / cinc-solo / knife 都支持
--config-option OPTION=VALUE覆盖单项配置，只影响当次运行、不改文件（各自--help实测均可见该选项）； - knife 查看生效值：工作站侧
knife config list（看 profile 列表）、knife config show [OPTION...]（看实际加载源与生效值），实测回显见 7.2； - cinc-client 查看生效值：无独立的 "config show" 子命令，以启动日志为准——收敛开头会打印所用平台、Run List 与 Cookbook 加载情况（安装篇 8.3 回显即为样例）。
⚠️ 注意：cinc-client 另有
--disable-config选项（"Refuse to load a config file and use defaults"），help 中官方明示 "This is for development and not a stable API"——仅调试用，生产勿依赖。
四、参数总览：配置文件地图
| 配置文件 | 所属侧 | 格式 | 用途 |
|---|---|---|---|
/etc/cinc/client.rb | 节点（Client 19.4.46） | Ruby DSL | client/server 模式主配置 |
/etc/cinc/client.d/*.rb | 节点 | Ruby DSL | 片段配置，按文件名字典序并入主配置 |
solo.rb（路径自定，-c 指定） | 节点 | Ruby DSL | 本地模式（cinc-solo / cinc-client --local-mode） |
<chef-repo>/.chef/config.rb | 工作站（Workstation 26.3.0） | Ruby DSL | knife 主配置（19 起新名；旧名 knife.rb 仍兼容） |
~/.cinc/credentials | 工作站 | INI | 多 profile 凭据（knife 19 推荐方式） |
/etc/cinc/ohai/ | 节点 | Ruby/JSON | Ohai 自定义插件与 hints |
生效优先级：
- 节点侧：命令行
--config-option> client.d 片段（字典序后者覆盖前者）> client.rb > 内置默认值； - 工作站侧：命令行旗标 /
--config-option>~/.cinc/credentials当前 profile >config.rb/knife.rb。实测knife config show首行打印Loading from credentials file /root/.cinc/credentials——credentials 是实际加载源（见 7.2）。
五、/etc/cinc 配置根目录与 client.rb 详解
5.1 根目录骨架
deb 安装后自动生成骨架，node01 实测：
drwxr-xr-x 2 root root 4096 Oct 27 09:08 accepted_licenses
-rw-r--r-- 1 root root 36 Oct 27 09:13 cinc_guid
drwxr-xr-x 2 root root 4096 Oct 27 09:08 client.d
-rw-r--r-- 1 root root 169 Oct 27 09:13 client.rb
-rw-r--r-- 1 root root 1679 Oct 27 09:13 node01.pem
drwxr-xr-x 3 root root 4096 Oct 27 09:08 ohai
drwxr-xr-x 2 root root 4096 Oct 27 09:08 trusted_certs
各项含义：
client.rb：主配置文件（5.2 起详解）；client.d/：片段配置目录，出厂为空（见 6.1）；trusted_certs/：服务端自签证书信任区，把 PEM 拷入即被信任（见 5.6）；ohai/：Ohai 自定义插件与 hints（见 5.6）；accepted_licenses/：chef_license "accept"接受许可后的落盘标记；cinc_guid：节点级随机 GUID，安装时生成；node01.pem：本节点在服务端的 client 私钥（client/server 模式注册后才有，本例由 knife 注册流程生成）。
出厂 client.rb 骨架（deb 自带、未改动前的原始内容，逐行照抄）：
# The client.rb file specifies how Chef Infra Client is configured on a node
# See https://docs.chef.io/config_rb_client/ for detailed configuration options
#
# Minimal example configuration:
# node_name "THIS_NODE_NAME"
# chef_server_url "https://CHEF.MYCOMPANY.COM/organizations/MY_CHEF_ORG"
# chef_license "accept"
出厂只有注释与三行最小示例。注意第二行官方注释给出了完整参数清单的权威出处 docs.chef.io/config_rb_client/——CINC 与上游配置项完全一致，本文只讲实测验证过与生产常用的参数。
5.2 身份与接入参数
node01 实际生效的 client.rb（逐行照抄）：
node_name "node01"
client_key "/etc/cinc/node01.pem"
chef_server_url "http://ws01.cinc.lab:8889"
cookbook_path ["/root/cookbooks"]
chef_license "accept"
逐项详解：
| 参数 | 类型/默认 | 说明 | 对应 CLI |
|---|---|---|---|
node_name | 字符串；默认节点 FQDN | 节点在服务端的唯一名，即注册身份 | -N, --node-name |
client_key | 路径；默认 /etc/cinc/client.pem | 节点私钥（PEM），与服务端记录的公钥配对鉴权 | -k, --client_key |
chef_server_url | URL | 服务端地址；正式服务端带组织，形如 https://server/organizations/ORG；本例指向零服务端模式端点 http://ws01.cinc.lab:8889 | -S, --server |
validation_key | 路径 | 新节点自助注册用的 validation 私钥，注册成功后应删除 | -K, --validation_key |
chef_license | 字符串 | 许可接受标记；CINC 无 EULA，但上游代码内置的许可确认机制仍在，填 "accept" 避免运行时提示 | --chef-license |
⚠️ client_key 是私钥：权限必须 0600、属 root；泄露等于节点身份泄露。纳入备份、禁止入库到 git。
5.3 运行与路径参数
| 参数 | 说明 | 对应 CLI |
|---|---|---|
cookbook_path | Cookbook 搜索目录（数组）；本地模式必配 | — |
node_path | 本地模式下节点 JSON 落盘目录（见 6.2） | — |
environment | 节点所属环境，默认 _default | -E, --environment |
json_attribs | 从 JSON 文件或 URL 注入节点属性 | -j, --json-attributes |
file_cache_path | 运行缓存根目录，默认 /var/cinc/cache（实测 cinc-apply 异常栈转储落点为 /var/cinc/cache/cinc-stacktrace.out） | — |
minimal_ohai | 只跑收敛必需的 Ohai 插件，缩短启动 | --minimal-ohai |
lockfile | 收敛锁文件位置，防多个收敛进程并发 | --lockfile |
run_lock_timeout | 等待另一收敛进程释放锁的最大秒数，默认无限等 | --run-lock-timeout |
💡 技术拓展：「环境（environment）」在配置管理里是发布分级概念——同一 Cookbook 可按环境钉不同版本（如 staging 用新版试水、production 钉稳定版）。主流方案对比：Chef/CINC 用服务端 environment 对象；Ansible 靠 inventory 分组加变量；Puppet 用 directory environments。节点侧由
environment参数或-E指定，未指定一律_default（knife node show 实测回显Environment: _default）。
5.4 日志与输出参数
| 参数 | 取值 | 说明 | 对应 CLI |
|---|---|---|---|
log_level | :auto/:trace/:debug/:info/:warn/:error/:fatal | 默认 :auto（终端 info、写文件 warn） | -l, --log_level |
log_location | STDOUT 或文件路径 | 定时托管/守护化运行建议写文件 | -L, --logfile |
color | true/false | 彩色输出，默认开 | --[no-]color |
force_formatter / force_logger | 布尔 | 人类可读格式化输出 vs 纯日志流 | --force-formatter / --force-logger |
always_dump_stacktrace | 布尔 | 任何日志级别都转储异常栈 | --[no-]always-dump-stacktrace |
实测提示：默认 info 级日志常见一行 ERROR: shard_seed: Failed to get dmi property serial_number: is dmidecode installed?——这不是故障，是 Ohai 采集 DMI 信息时系统缺 dmidecode 的提示，仅影响 shard_seed 派生属性（用于按节点分片随机化定时任务），装 dmidecode 即可消除。
5.5 调度参数（周期收敛）
cinc-client 自带 -i/--interval SECONDS 周期运行与 -s/--splay SECONDS 随机抖动（防止全体节点同时打服务端），对应配置项 interval、splay；--once 则取消周期只跑一次。但官方推荐的持续收敛方式是 systemd timer 或 cron 外部调度（deb 包不附带 systemd 单元，安装篇 8.5 已实测 timer 闭环）。内部 interval 与外部 timer 二者择一，不要双层调度叠加。
5.6 Ohai 目录与 trusted_certs
/etc/cinc/ohai/：放自定义 Ohai 插件（Ruby）与 hints（JSON，例如 hint 告知某云厂商元数据端点可达性）；cinc-client 每次收敛前自动加载。/etc/cinc/trusted_certs/：服务端使用自签证书时，把 CA/服务证书 PEM 拷入此目录即被 client 信任，无需改动校验级别。ssl_verify_mode：:verify_peer（默认，严格校验）/:verify_none（仅调试，生产禁用）。fips：对应--[no-]fips，合规场景启用 FIPS 模式。
六、client.d 片段与 solo.rb（本地模式）
6.1 client.d 片段配置
client.d/*.rb 中每个文件都是合法 Ruby DSL 片段，启动时按文件名字典序合并进主配置，后加载者覆盖先加载者。适合「分文件治理」：如 00-base.rb（公共项）、10-logging.rb（日志项）、90-local.rb（本机特例），由不同配置分发通道各自下发。实测出厂为空目录：
/etc/cinc/client.d/:
total 8
drwxr-xr-x 2 root root 4096 Oct 27 09:08 .
drwxr-xr-x 6 root root 4096 Oct 27 09:08 ..
6.2 solo.rb 本地模式配置
cinc-solo 与 cinc-client --local-mode 不读 client.rb，而是用 -c 显式指定的配置文件（惯例命名 solo.rb）。node01 实测配置：
cookbook_path ["/root/cookbooks"]
node_path "/root/nodes"
log_level :info
log_location STDOUT
逐项：cookbook_path 指向 Cookbook 搜索目录（数组，可多个）；node_path 为节点 JSON 落盘目录，收敛后每个节点生成一个 <节点名>.json（实测生成 /root/nodes/node01.cinc.lab.json）；log_level/log_location 同 5.4。
⚠️ 实测细节：带
-o覆盖 Run List 的运行会跳过节点 JSON 的最终保存，日志原文WARN: Skipping final node save because override_runlist was given——此时该 JSON 可能只有{"name": "node01.cinc.lab"}一行，属设计行为而非异常。
七、工作站配置：config.rb / knife.rb / credentials
7.1 config.rb 与 knife.rb
knife 19（Workstation 26.3.0 内置 19.3.3）把主配置文件从 knife.rb 更名为 config.rb，发现路径为 <chef-repo>/.chef/ 与 ~/.chef/。实测 chef-repo 下两文件同内容并存（各 262 字节），旧名仍被兼容识别；但显式 -c 指向不存在的 knife.rb 会直接报错，实测回显：
ERROR: CONFIGURATION ERROR:Specified config file /root/chef-repo/.chef/knife.rb does not exist
实测生效的 config.rb（/root/chef-repo/.chef/config.rb，逐行照抄）：
current_dir = File.dirname(__FILE__)
node_name "admin"
client_key "#{current_dir}/admin.pem"
chef_server_url "http://127.0.0.1:8889"
cookbook_path ["#{current_dir}/../cookbooks"]
chef_license "accept"
逐项：首行取配置文件所在目录为基准，后续路径全部相对它展开——整个 .chef 目录换机器搬运时无需改路径；node_name/client_key 是工作站用户在服务端的身份与私钥（演示用户 admin，工作站服务端账号密码按本站示例规范 q1w2e3r4）；chef_server_url 指向服务端；cookbook_path 指向仓库内 cookbooks 目录。
7.2 ~/.cinc/credentials（INI profile，knife 19 推荐）
knife 19 起推荐用 INI 凭据文件统一管理服务端身份，支持多 profile。实测 ~/.cinc/credentials：
[default]
node_name = "admin"
client_key = "/root/chef-repo/.chef/admin.pem"
chef_server_url = "http://127.0.0.1:8889"
cookbook_path = ["/root/chef-repo/cookbooks"]
查看已配置 profile（knife config list 实测回显）：
Profile Client Key Server
------------------------------------------------------------------
*default admin ~/chef-repo/.chef/admin.pem http://127.0.0.1:8889
查看生效值（knife config show node_name chef_server_url cookbook_path 实测回显）：
Loading from credentials file /root/.cinc/credentials
chef_server_url: http://127.0.0.1:8889
cookbook_path: /root/chef-repo/cookbooks
node_name: admin
首行 Loading from credentials file ... 是关键：credentials 优先于 config.rb/knife.rb 成为实际加载源。多 profile 时在文件中追加 [staging] 等段落，用 knife --profile staging 或 knife config use staging 切换。
⚠️ 注意：credentials 与 config.rb 并存且取值不一致时以 credentials 为准——排障先跑
knife config show看「Loading from」行确认实际来源，避免改错文件。
八、生产配置模板
三套模板，适用场景：中小规模（数十~数百节点）、无专职配置管理团队、允许内网离线分发。
8.1 节点 client.rb 模板（client/server 模式）
node_name "web01.prod.internal"
client_key "/etc/cinc/client.pem"
chef_server_url "https://cinc-server.internal/organizations/prod"
chef_license "accept"
environment "production"
log_level :info
log_location "/var/log/cinc-client.log"
ssl_verify_mode :verify_peer
run_lock_timeout 1800
要点：定时托管时日志落文件便于审计；run_lock_timeout 防上一次收敛卡死导致无限等待；模板中主机名、域名、组织名按实际环境替换。
8.2 节点 solo.rb 模板（本地模式，无服务端）
cookbook_path ["/srv/chef/cookbooks"]
node_path "/srv/chef/nodes"
log_level :info
log_location "/var/log/cinc-solo.log"
要点：Cookbook 用 git 下发到 /srv/chef/cookbooks，配合 systemd timer 周期执行 cinc-solo -c /srv/chef/solo.rb -o web_base，即构成无服务端持续收敛（timer 单元写法见安装篇 8.5）。
8.3 工作站 credentials 模板
[default]
node_name = "admin"
client_key = "/home/ops/chef-repo/.chef/admin.pem"
chef_server_url = "https://cinc-server.internal/organizations/prod"
cookbook_path = ["/home/ops/chef-repo/cookbooks"]
要点：私钥权限 0600；多环境追加 profile 段；有了 credentials 就不再维护 knife.rb，避免双文件漂移。
九、常见问题
Q1：改了 client.rb 不生效？
先确认运行形态：cinc-solo / --local-mode 不读 client.rb（读 -c 指定的 solo.rb），client/server 模式才读 /etc/cinc/client.rb；再查是否有 client.d 片段或 --config-option 覆盖。
Q2：knife 报 CONFIGURATION ERROR:Specified config file ... knife.rb does not exist？
显式 -c 或发现路径指向了不存在的 knife.rb。knife 19 新名为 config.rb——新建 config.rb 或改用 credentials（7.2），实测报错原文见 7.1。
Q3：credentials 和 config.rb 哪个先生效？
credentials。knife config show 首行会打印实际加载源（实测 Loading from credentials file /root/.cinc/credentials）。
Q4：chef_license "accept" 是什么？CINC 不是没有 EULA 吗？
CINC 分发本身无 EULA，但上游代码内置的许可确认机制仍在；填 accept 后标记落盘到 /etc/cinc/accepted_licenses/，之后运行不再提示。
Q5：自签证书的服务端，客户端怎么信任？
把服务端 CA/证书 PEM 拷入 /etc/cinc/trusted_certs/ 即可，不要把 ssl_verify_mode 降级为 :verify_none。
十、参考链接
- client.rb 完整参数清单（上游文档，CINC 同源适用）：https://docs.chef.io/config_rb_client/
- knife 配置官方文档：https://docs.chef.io/workstation/knife/
- CINC 官网：https://cinc.sh
- 本站相关文档：《CINC Client 19.4.46 介绍与选型指南》、《Ubuntu 22.04 安装 CINC Client 19.4.46 与 Workstation 26.3.0 指南》、《Chef Infra Client 19.4.46 介绍与选型指南》
- cinc-client / cinc-solo / cinc-apply / knife / ohai 的逐条命令实测，见本专栏命令篇（CINC 常用 CLI 命令详解）