OliveTin 3000.21.0 配置参数详解

目标：把 OliveTin 唯一的配置文件 config.yaml 讲透——文件定位与热重载机制、全局参数分组语义、actions 动作全参数（含 12 类参数类型）、界面组织（dashboards/entities）、认证与 ACL 全链、日志与验证工具。本文以官方 471 行注释版 config.yaml 模板（随 3000.21.0 发行包发布）与官方文档各配置页为准，关键行为均在本机 v3000.21.0 实例上实测佐证（实测过程与回显详见 《OliveTin 3000.21.0 Docker Compose 部署实战》 与 《OliveTin 3000.21.0 常用命令与运维实战（核心篇）》）；选型背景见 《OliveTin 3000.21.0 介绍与选型指南》。

一、环境信息

二、配置文件定位与加载

放置位置（按优先级）：--configdir 启动参数指定目录（默认当前工作目录）→ /config/（编排发行形态约定）→ /etc/OliveTin/（裸机约定）。文件名必须是 config.yaml（config.yml 不识别，实测踩坑见部署篇 Q2）。

热重载：进程监听配置文件变更事件（日志可见 config file changed: WRITE "/config/config.yaml"），变更自动生效。官方 Configuration 文档对每个参数标注 "Live Reloadable"——绝大多数参数支持热重载，监听地址类（listenAddress）与启用认证类等少数项需重启进程*。本机实测中，ACL 新增、execOnWebhook 增加、动作增删均热生效。

两个格式纪律：

1. YAML 缩进错误是致命的：进程 fatal 退出（回显 yaml: line N: did not find expected ...），配合编排的 restart 策略会形成崩溃循环；
2. 未知字段静默忽略：字段名拼错（如 tiemout）不报错、不告警、按默认值运行——本机实测 tiemout: 5 拼错后语法检查照常通过（exit 0）。这两个纪律的对抗工具是 -syntaxcheck，见第七节。

三、全局参数

3.1 服务与界面

实测佐证：defaultPermissions 的「连带效应」是本机踩过的坑——设 authRequireGuestsToLogin: true 后，即便已登录用户也在 defaultPermissions 范畴外，必须显式配 ACL（见 3.3）。

3.2 认证与会话

本地用户（本机实测全链跑通的形态）：

authRequireGuestsToLogin: true   # 强制所有访客登录

authLocalUsers:
  enabled: true
  users:
    - username: admin
      usergroup: admins          # 自由命名的组名，与 ACL 的 matchUsergroups 对应
      password: $argon2id$v=19$m=65536,t=4,p=6$...   # Argon2id 哈希，非明文

• 密码哈希由官方 API PasswordHash 生成（POST 明文返回哈希），也可以用系统 argon2 命令行工具自算；
• 登录会话落盘到配置目录的 sessions.yaml，进程重启后会话保留；
• 实测的失败路径：错误密码返回 {"success":false}；匿名调用受限接口返回 403 {"code":"permission_denied","message":"guests are not allowed to access the dashboard"}。

OAuth2 / JWT（公网部署的正解，本机未展开实测，以官方文档为准）：

• authOAuth2Providers：内置 Authelia、Authentik、Pocket ID 三种预设（填 client id/secret + 端点），配 authOAuth2RedirectHost 指向对外域名；
• authJwtProvider：HMAC（jwtHMACSecret）或公钥（jwtPublicKeys）两种校验方式，适合前面已有统一认证网关的场合。

3.3 权限（accessControlLists）

ACL 是 v3k 权限模型的全部——按「用户组 / 用户名」匹配，授予三类权限，可全局叠加或挂到单个 action：

accessControlLists:
  - name: admin-full
    matchUsergroups:      # 按用户组匹配（authLocalUsers 里的 usergroup）
      - admins
    matchUserNames:       # 按用户名匹配（可叠加；webhook 的固定身份是 "webhook"）
      - webhook
    permissions:          # 三类权限：看（view）、点（exec）、看日志（logs）
      view: true
      exec: true
      logs: true
    addToEveryAction: true   # true=自动挂到所有动作；false=仅挂 aclRecipes 里显式引用的动作
    policy:               # 界面可见性微调
      showDiagnostics: true
      showLogList: true

实测三个关键行为：

1. 不配 ACL 的强制登录等于全禁：登录成功但按钮不可点、日志页为空（API 层 GetLogs 返回空列表）——ACL 必须显式授回；
2. 拦截发生在执行层而非 HTTP 层：无权限的 StartAction 请求 HTTP 仍返回受理（有 executionTrackingId），但执行日志标记 blocked: true、退出码 -1337、回显 ACL check failed. Blocked from executing.——排查时要看日志而非 HTTP 状态码；
3. webhook 触发的执行者是独立身份 webhook：它不在任何 usergroup 里，ACL 要用 matchUserNames: [webhook] 单独授权，否则 webhook 触发同样被拦（本机实测踩中）。

四、actions：动作全参数

每个 action 支持的完整参数面（按官方注释模板与文档页归纳）：

actions:
  - title: Ping 主机                    # 必填：按钮标题
    id: ping-host                       # 可选：自定义 ID（API bindingId 用它，重启不变）
    icon: "\U0001F4F6"                  # 图标一：emoji
    iconUrl: https://.../img.png        # 图标二：图片 URL（与 icon 二选一）
    shell: ping -c {{ count }} {{ host }}   # 执行形态一：shell 字符串（支持模板）
    exec: [ping, -c, "3", "127.0.0.1"]  # 执行形态二：参数数组（不走 shell 解释）
    timeout: 10                         # 超时秒数（默认 3，<3 一律按 3，见下）
    maxRate: [3, 60]                    # 限速：60 秒内最多 3 次
    hidden: false                       # 隐藏动作（不出现在界面，仍可 API 触发）
    justification: true                 # 执行前要求填写执行理由（记录进日志）
    confirmation:                       # 执行前二次确认（确认弹窗）
      title: 确认执行？
      content: 这将 ping {{ host }} 一次
    arguments:                          # 参数表单（按下按钮先填表再执行）
      - name: host                      # 模板变量名（shell 里 {{ host }}）
        title: 目标主机
        type: ascii_identifier          # 输入校验类型（12 类，见下表）
        default: 127.0.0.1              # 默认值
        description: 要 ping 的地址      # 表单提示文字
      - name: count
        title: 次数
        choices:                        # choices=下拉枚举（配合 type 校验）
          - title: 1 次
            value: 1
          - title: 3 次
            value: 3
    execOnStartup: false                # 六种自动触发器（见下）
    execOnCron: "0 2 * * *"
    execOnCalendarFile: /etc/systemd/...
    execOnFileCreatedInDir: /data/inbox/
    execOnFileChangedInDir: /data/conf/
    execOnWebhook:                      # webhook 触发（POST /webhooks 按 header/query 匹配）
      - matchHeaders:
          X-Demo-Token: olive-hook-01

参数类型（12 类）：ascii（普通文本）、ascii_identifier（标识符安全字符集，防注入的第一道闸）、int、email、url、regex（自定义 pattern 校验）、confirmation（确认框）、checklist（多选清单）、dropdown（下拉枚举，配 choices）、textarea（多行）、password（输入遮蔽）、html（纯说明块）。本机实测 dropdown 的 choices 值校验是强制的——传枚举外值直接拒绝执行（退出码 -1337，回显 argument value is not one of the predefined choices）。

timeout 语义（实测证伪直觉）：默认 3 秒；配置值低于 3 秒会被强制提升为 3 秒——本机实测 timeout: 1 后 API 返回的实际 timeout 是 3。需要长跑动作（备份、构建）必须显式调大。超时行为：进程被 kill，日志回显 OliveTin::timeout - this action timed out after 3 seconds. If you need more time for this action, set a longer timeout.、退出码 -1、timedOut: true。

shell 与 exec 的取舍（3k 的重要变化）：shell 走 shell 解释（管道、变量、模板都可用）；exec 参数数组不走解释。webhook 触发的动作强制要求 exec——本机实测给 webhook 动作用 shell，执行直接失败（回显 webhooks cannot use Shell execution; use exec instead，退出码 -1337）。另外 shell 字符串里的 Go 模板花括号与被调用程序自身的模板语法冲突时会炸（实测 docker ps --format '{{ .Names }}' 报 can't evaluate field Names in type *tpl.actionTemplateContext）——这类动作改用 exec 形态或转义。

触发器家族：除点击外六种自动触发（startup/cron/calendarFile/fileCreatedInDir/fileChangedInDir/webhook），语义见上面模板注释。cron 与 calendarFile 互斥使用时以 calendarFile 优先（systemd 定时器语义）。webhook 的匹配头是精确匹配（本机实测错 token 返回 200 但不触发任何动作——webhook 端点永远返回 OK，是否触发只看匹配，外部系统对 webhook 结果的感知需要业务侧自证，比如让命令最后 curl 回执）。

并发与排队（actionGroups）：

actionGroups:
  - title: 备份任务组
    actions: [nightly-backup, snapshot]
    maxConcurrent: 2      # 组内最多 2 个并发
    queueSize: 10         # 超出并发进队列，队满拒绝

五、界面组织（dashboards 与 entities）

dashboards（可选；不配则全部 action 平铺在首页）：

dashboards:
  - title: 主控面板
    type: fieldset          # fieldset 分组框
    contents:
      - title: 常用操作
        type: fieldset
        contents:
          - type: directory     # 目录块（跳转子页）
            directoryName: 服务器操作
          - type: hyperlink     # 外链块
            text: Grafana
            url: https://grafana.example.com

四种块类型：fieldset（分组）、directory（目录导航）、display（自定义展示）、hyperlink（外链）。层级可以嵌套。

entities（把清单文件变成一组按钮）：

entityFiles: /config/entities/*.yml

entities 目录（官方 House of Entities 文档）支持从 YAML/JSON 清单文件生成实体，按钮里用 {{ .CurrentEntity.xxx }} 引用实体字段——典型用法：一台服务器一个 Wake on LAN 按钮、一个磁盘清理按钮，清单里加一台机器按钮自动多一组。

六、日志、可观测与诊断

七、配置验证与排障工具

-syntaxcheck（3000.21.0 起内建的配置自检，D1 篇有完整实测）：

$ OliveTin -configdir /etc/OliveTin -syntaxcheck
... msg="Configuration valid"
$ echo $?
0

三种实测结果：配置正常 → 0 configuration issues found、exit 0；YAML 语法错误 → Configuration load failed: yaml: ...、exit 1；字段拼写错误 → 完全静默、exit 0（未知字段被忽略）。结论：syntaxcheck 能挡住「文件改坏」，挡不住「字段拼错」——字段级核对要对照官方模板。

排障索引（详细回显见部署篇第六节）：

• 配置写坏导致崩溃循环 → 恢复宿主机侧配置文件即自动恢复；
• mkdir /config/custom-webui: permission denied → bind mount 属主问题（chown 1000 或 user: root）；
• 登录后按钮不可点 → ACL 未配；
• webhook 不触发 → 匹配头不一致，或动作用了 shell（必须 exec），或 webhook 身份未被 ACL 授权。

八、参考链接

1. 官方注释版 config.yaml（471 行，本文逐节依据）：https://github.com/OliveTin/OliveTin/blob/main/config.yaml
2. 官方 Configuration 总览（含热重载标注）：https://docs.olivetin.app/configuration/config.html
3. 官方 Argument types 文档：https://docs.olivetin.app/action-arguments/argument-types.html
4. 官方 ACL 文档：https://docs.olivetin.app/access-control-lists.html
5. 官方 House of Entities（实体清单）：https://docs.olivetin.app/house-of-entities.html
6. 官方 Network ports 文档：https://docs.olivetin.app/configuration/ports.html
7. 本专栏相关篇目：《OliveTin 3000.21.0 介绍与选型指南》、《OliveTin 3000.21.0 Docker Compose 部署实战》、《OliveTin 3000.21.0 常用命令与运维实战（核心篇）》