附录 C 配置文件

C.配置文件Configuration Files

C.1.总览General

PVE 大多数配置文件都位于 共享集群文件系统 /etc/pve（详见 第 6 章）—— 修改后自动复制到所有节点。例外是节点级配置文件 ， 例如备份默认值 /etc/vzdump.conf。

这些文件中的字段大多源自 PVE REST API 的 JSON Schema —— 与对应 API 端点同名同义。

C.1.1.属性命名约定（Casing）

历史上 ， 较长的属性（含子属性）常用 snake_case 或写成不分隔的单词 —— 这与 PVE 主要由 Perl 实现有关（Perl 中以 kebab-case 访问属性需额外引号）， 以及早期开发风格未严格统一。

新增属性更倾向 kebab-case， 计划为既有 snake_case 属性引入别名 ， 长期内在 API、 CLI 与配置文件全面切换到 kebab-case， 同时在配置恢复 / 加载时保持向后兼容。

C.2.配置文件清单

C.3.数据中心配置（datacenter.cfg）Datacenter Configuration

/etc/pve/datacenter.cfg 含集群级默认 ， 由所有节点共享。

C.3.1.文件格式

简单的冒号分隔 key/value 格式 ， 每行：

OPTION: value

空行忽略 ， # 开头视作注释。

C.3.2.选项

bwlimit: [clone=<LIMIT>] [,default=<LIMIT>] [,migration=<LIMIT>] [,move=<LIMIT>] [,restore=<LIMIT>]

不同操作的 IO 带宽上限（KiB/s）：

• clone：克隆磁盘
• default：未单独设置时的默认
• migration：迁移客户机（含本地盘）
• move：移动磁盘
• restore：从备份恢复

consent-text: <string>

登录前显示的同意 / 公告文本。

console: <applet | html5 | vv | xtermjs>

默认控制台查看器：

• applet：旧 Java 小程序（VNC， 已弃用 —— 实际映射到 html5）
• vv：外部 virt-viewer 兼容应用（SPICE）
• html5：基于 HTML5 的 noVNC
• xtermjs：基于 HTML5 的 xterm.js 控制台

所选查看器不可用时（如 VM 未启用 SPICE）回退到 noVNC。

crs: [ha=<basic|static>] [,ha-rebalance-on-start=<1|0>]

集群资源调度（CRS）设置：

• ha（默认 basic）：HA 管理器选节点的算法。 basic 仅看服务数量； static 把客户机配置中的静态 CPU / 内存也纳入考量。
• ha-rebalance-on-start（默认 0）：启动停止状态的 HA 服务时 ， 用 CRS 重选最合适节点。

详见 §15.12。

description: <string>

数据中心描述 —— GUI 数据中心备注面板显示 ， 以注释形式存于配置文件。

email_from: <string>

通知邮件的发件地址（默认 root@$hostname）。

fencing: <both | hardware | watchdog>（默认 watchdog）

HA 集群 fencing 模式。 hardware 模式需在 /etc/pve/ha/fence.cfg 配置 fence 设备； both 同时使用两种。

WARN

hardware 与 both 均为 实验性 / 进行中（WIP）。

ha: shutdown_policy=<enum>

集群级 HA 设置。子键：

• shutdown_policy = <conditional | failover | freeze | migrate>（默认 conditional）—— 节点关机 / 重启时的 HA 服务处理策略：
  • freeze：始终冻结节点上的服务 —— 关机期间不被 HA 管理器恢复。
  • failover：不冻结服务 ， 节点不能很快恢复（< 1 分钟）时 ， 服务被恢复到其他节点。
  • conditional：按关机类型自动判断 —— 重启时冻结 ， 关机（poweroff）则保持原状 ， 约 2 分钟后被恢复。
  • migrate：触发关机 / 重启时尝试迁走全部运行中服务 —— 节点上仍有运行中服务时 poweroff 不会继续。节点回来后 ， 若期间未发生其他迁移 / 重定位 / 恢复 ， 服务会迁回原节点。

详见 §15.11.2。

http_proxy: http://...

下载使用的外部 HTTP 代理 ， 例如 http://username:password@host:port/。

keyboard: <布局>

VNC 服务器默认键盘布局。可选值 ：da / de / de-ch / en-gb / en-us / es / fi / fr / fr-be / fr-ca / fr-ch / hu / is / it / ja / lt / mk / nl / no / pl / pt / pt-br / sl / sv / tr。

language: <语言>

GUI 默认语言。可选值 ：ar / ca / da / de / en / es / eu / fa / fr / he / hr / it / ja / ka / kr / nb / nl / nn / pl / pt_BR / ru / sl / sv / tr / ukr / zh_CN / zh_TW。

mac_prefix: <string>（默认 BC:24:11）

自动生成虚拟客户机 MAC 地址的前缀。默认 BC:24:11 是 IEEE 分配给 Proxmox Server Solutions GmbH 的「MA-L」OUI（组织唯一标识）。该前缀允许在本地网络（即不直接面向公网的环境 ， 例如 LAN、 NAT / 伪装网络）中使用。

NOTE

多个集群（部分）共享客户机网络时 ， 强烈建议 扩展默认前缀或自定义合法前缀以减少 MAC 冲突 —— 例如分别使用 BC:24:11:0、 BC:24:11:1 等。也可改用 VLAN 在网络层逻辑隔离。 对于面向公网的客户机 ， 建议从 IEEE 注册自有 OUI， 或与你 / 你的托管商的网络管理员协调。

max_workers: <1 - N>

每节点上诸如 stop all VMs 或 ha-manager 任务等动作可启动的最大 worker 数。

migration: [type=]<secure|insecure> [,network=<CIDR>]

集群级迁移设置：

• type（默认 secure）：默认使用 SSH 隧道加密迁移流量。在完全可信的私网中可设 insecure 以提速。
• network = <CIDR>：用于迁移的子网 CIDR —— 当复制作业未单独设置 replication.network 时也作其回退。

migration_unsecure: <boolean>

已弃用 —— 改用 migration 属性。原作用 ：把迁移从默认的 SSH 隧道改为不加密。

next-id: [lower=<integer>] [,upper=<integer>]

VMID 自动选择的取值范围：

• lower（默认 100）：闭区间下界。
• upper（默认 1 000 000）：开区间上界。

notify: ...

集群级通知设置。子键：

• package-updates = <auto | always | never>（默认 auto）—— 已弃用， 改用数据中心通知设置。原义 ：每日更新作业发出通知的频率 —— auto（有有效订阅的系统每日发）、 always（每次有新更新都发）、 never（从不发）。
• fencing / replication / target-fencing / target-package-updates / target-replication：均已弃用 —— 改用数据中心通知系统（见 第 17 章）。

registered-tags: <tag>[;<tag>...]

列出的标签需要在 / 上有 Sys.Modify 权限才能设置 / 删除。若同时也在 user-tag-access 里 ， 同样需要 Sys.Modify。

replication: [type=]<secure|insecure> [,network=<CIDR>]

集群级复制设置：

• type（默认 secure）：复制流量默认 SSH 隧道加密；可信私网可设 insecure。
• network = <CIDR>：复制使用的子网。

tag-style: ...

标签的视觉样式 ， 子键：

• case-sensitive = <boolean>（默认 0）：更新时去重是否区分大小写。
• color-map = <tag>:<hex-color>[:<hex-color-for-text>][;<tag>=...]：手动颜色映射（分号分隔）。
• ordering = <alphabetical | config>（默认 alphabetical）：Web 界面与 API 更新中标签的排序。
• shape = <circle | dense | full | none>（默认 circle）：Web UI 树中的标签形状 —— full 完整显示标签； circle 仅画含背景色的圆； dense 画一个小矩形（标签很多时合适）； none 不显示。

u2f: [appid=<APPID>] [,origin=<URL>]

U2F 双因素认证。子键：

• appid = <APPID>：U2F AppId URL 覆盖 —— 默认与 origin 相同。
• origin = <URL>：U2F Origin 覆盖 —— 单节点 + 单 URL 部署常用。

详见 §14.6.9。

user-tag-access: [user-allow=<enum>] [,user-allow-list=<tag>[;...]]

用户对资源（如客户机）可设标签的特权选项 —— 在 / 上有 Sys.Modify 的用户始终不受限。子键：

• user-allow = <none | list | existing | free>（默认 free）：
  • none：不可使用任何标签。
  • list：仅可使用 user-allow-list 中的标签。
  • existing：同 list， 同时该资源已有的标签也可继续使用。
  • free：无限制。
• user-allow-list = <tag>[;<tag>...]：当 user-allow 为 list 或 existing 时 ， 用户可设 / 删的标签列表（分号分隔）。

webauthn: [allow-subdomains=<1|0>] [,id=<DOMAINNAME>] [,origin=<URL>] [,rp=<RELYING_PARTY>]

WebAuthn 配置。子键：

• allow-subdomains = <boolean>（默认 1）：允许 origin 是子域 ， 而非完全相同 URL。
• id = <DOMAINNAME>：Relying Party ID —— 必须是裸域名（不含协议、端口、路径）。 修改会让已有 WebAuthn 凭据失效。
• origin = <URL>：站点 origin —— 必须是 https:// URL（或 http://localhost）， 应与用户在浏览器中访问 Web UI 的地址一致。 修改可能让已有凭据失效。
• rp = <RELYING_PARTY>：Relying Party 名 —— 任意文本标识。 修改可能让已有凭据失效。

详见 §14.6.8。