全面指南：在NAS上部署OliveTin实现Web界面自定义命令执行的详细教程与实战技巧

OliveTin 是一个功能强大的工具，它允许用户通过 Web 界面安全且便捷地访问预定义的 shell 命令。该工具适用于多种使用场景，特别适合为技术水平有限的用户提供安全的命令执行权限，同时能够将复杂的命令流程简化，使其更易于访问和重复执行。

核心特性

• 响应式且触摸友好的用户界面：完美适配平板电脑和移动设备，提供流畅的操作体验。
• 基于 YAML 的极简配置：采用 YAML 格式进行配置，符合云原生应用的设计理念。
• 深色模式支持：满足偏好深色界面用户的需求，提升视觉舒适度。
• 无障碍访问优化：已通过 Firefox 的无障碍检查，高度重视可访问性问题。
• 容器化部署：提供 Docker 容器支持，便于快速测试和部署，非常适合自托管场景。
• 广泛的集成能力：OliveTin 通过运行 Linux shell 命令实现功能扩展，用户可以利用 curl、ping 等工具，或编写自定义 shell 脚本进行深度集成。
• 资源占用极低：仅消耗几 MB 内存，CPU 使用率极低；采用 Go 语言编写，Web 界面基于 REST/gRPC API 的现代响应式单页应用。
• 完善的测试与代码检查：包含大量单元测试和样式检查，有助于保持代码一致性并提升可维护性。

安装部署

使用 Docker Compose 进行安装

以下是一个示例的 Docker Compose 配置文件，用于部署 OliveTin 服务：

services:  
  olivetin:  
    image: jamesread/olivetin:latest  
    container_name: olivetin  
    ports:  
      - 1337:1337  
    volumes:  
      - /vol1/1000/docker/olivetin:/config  
      - /var/run/docker.sock:/var/run/docker.sock  
    privileged: true  
    restart: unless-stopped

参数说明（建议查阅官方文档获取更多参数细节）：

• /config（路径）：用于存放配置文件。
• /var/run/docker.sock（路径，可选）：用于配置 Docker 应用集成。

在部署之前，需要准备 config.yaml 配置文件。可以从 GitHub 下载官方示例，或直接复制以下内容进行自定义：

https://github.com/OliveTin/OliveTin/blob/main/config.yaml

# 使用内置的微代理，将 WebUI 和 RESTAPI 统一托管在一个端口上（称为“单 HTTP 前端”），
# 这意味着只需在容器/防火墙等中开放一个端口。

# 监听所有可用地址，端口 1337
listenAddressSingleHTTPFrontend: 0.0.0.0:1337

# 日志级别可选：INFO（默认）、WARN 和 DEBUG
logLevel: "INFO"

# 检查更新功能：https://docs.olivetin.app/reference/updateChecks.html
checkForUpdates: false

# 操作（Actions）是由 OliveTin 执行的命令，通常在 WebUI 上显示为按钮。
# 文档：https://docs.olivetin.app/action_execution/create_your_first.html
actions:
  # 这是一个最简单的操作，仅运行命令并通过按钮闪烁显示状态。
  # 如果在容器中运行 OliveTin，请记得映射 Docker 套接字！
  # 参考：https://docs.olivetin.app/solutions/container-control-panel/index.html
  - title: Ping 互联网
    shell: ping -c 3 1.1.1.1
    icon: ping
    popupOnStart: execution-dialog-stdout-only

  # 使用 `popupOnStart: execution-dialog-stdout-only` 仅显示命令输出。
  - title: 检查磁盘空间
    icon: disk
    shell: df -h /media
    popupOnStart: execution-dialog-stdout-only

  # 使用 `popupOnStart: execution-dialog` 显示包含更多执行信息的对话框。
  - title: 检查 dmesg 日志
    shell: dmesg | tail
    icon: logs
    popupOnStart: execution-dialog

  # 使用 `popupOnStart: execution-button` 显示一个链接到日志的小按钮。
  # 还可以对操作进行速率限制。
  - title: 显示日期
    shell: date
    timeout: 6
    icon: clock
    popupOnStart: execution-button
    maxRate:
      - limit: 3
        duration: 5m

  # 不仅限于操作系统命令，还可以运行自定义脚本。
  # 这里使用 `maxConcurrent` 防止脚本并行运行多次，同时设置超时以终止长时间运行的命令。
  - title: 运行备份脚本
    shell: /opt/backupScript.sh
    shellAfterCompleted: "apprise -t '通知：备份脚本完成' -b '备份脚本完成，退出代码 {{ exitCode }}。日志如下：\n {{ output }} '"
    maxConcurrent: 1
    timeout: 10
    icon: backup
    popupOnStart: execution-dialog

  # 当需要用户输入时，使用 `arguments` 弹出对话框请求参数值。
  # 文档：https://docs.olivetin.app/action_examples/ping.html
  - title: Ping 主机
    id: ping_host
    shell: ping {{ host }} -c {{ count }}
    icon: ping
    timeout: 100
    popupOnStart: execution-dialog-stdout-only
    arguments:
      - name: host
        title: 主机
        type: ascii_identifier
        default: example.com
        description: 要 ping 的主机地址

      - name: count
        title: 次数
        type: int
        default: 3
        description: 需要 ping 的次数？

  # OliveTin 可以控制容器——Docker 只是一个命令行工具。
  # 如果在容器中运行，需要进行一些设置，详见以下文档。
  # 文档：https://docs.olivetin.app/solutions/container-control-panel/index.html
  - title: 重启 Docker 容器
    icon: restart
    shell: docker restart {{ container }}
    arguments:
      - name: container
        title: 容器名称
        choices:
          - value: plex
          - value: traefik
          - value: grafana

  # 使用特殊的 `confirmation` 参数防止误点击“危险”操作。
  # 文档：https://docs.olivetin.app/args/input_confirmation.html
  - title: 删除旧备份
    icon: ashtonished
    shell: rm -rf /opt/oldBackups/
    arguments:
      - type: html
        title: 描述
        default: 该操作的文档可在 <a href = "example.com">example.com</a> 找到。
      - type: confirmation
        title: 确定执行？

  # 这是一个运行 OliveTin 内置脚本的操作，用于下载主题。
  # 仍需在配置中设置 `themeName`。
  # 文档：https://docs.olivetin.app/reference/reference_themes_for_users.html
  - title: 获取 OliveTin 主题
    shell: olivetin-get-theme {{ themeGitRepo }} {{ themeFolderName }}
    icon: theme
    arguments:
      - name: themeGitRepo
        title: 主题的 Git 仓库
        description: 在 https://olivetin.app/themes 查找新主题
        type: url

      - name: themeFolderName
        title: 主题的文件夹名
        type: ascii_identifier

  # 有时需要在其他服务器上运行操作——不必复杂化，直接使用 SSH！
  # OliveTin 包含一个辅助工具简化此过程（完全可选），也支持手动设置 SSH。
  # 文档：https://docs.olivetin.app/action_examples/ssh-easy.html
  # 文档：https://docs.olivetin.app/action_examples/ssh-manual.html
  - title: "设置简易 SSH"
    icon: ssh
    shell: olivetin-setup-easy-ssh
    popupOnStart: execution-dialog

  # 以下是使用“简易”配置通过 SSH 重启另一台服务器上的服务的方法。
  # 文档：https://docs.olivetin.app/action_examples/ssh-easy.html
  # 文档：https://docs.olivetin.app/action_examples/systemd_service.html
  - title: 在 server1 上重启 httpd
    id: restart_httpd
    icon: restart
    timeout: 1
    shell: ssh -F /config/ssh/easy.cfg root@server1 'service httpd restart'

  # 许多人使用 OliveTin 为电子项目构建 Web 界面。
  # 最佳实践是安装原生包（如 .deb），然后使用 Python 脚本或 `gpio` 命令。
  - title: 切换 GPIO 灯
    shell: gpioset gpiochip1 9=1
    icon: light

  # `icon` 选项有多个内置快捷方式，也可以指定任何 HTML，包括 Unicode 字符或自定义图标链接。
  # 文档：https://docs.olivetin.app/action_customization/icons.html
  #
  # 许多人使用 OliveTin 轻松执行 ansible-playbooks，可能需要更长的超时时间（确保 Ansible 完成）。
  # 文档：https://docs.olivetin.app/action_examples/ansible.html
  - title: "运行自动化剧本"
    icon: '&#129302;'
    shell: ansible-playbook -i /etc/hosts /root/myRepo/myPlaybook.yaml
    timeout: 120

  # 以下操作用于仪表板的“虚拟”操作。只要在仪表板中引用，它们不会出现在 `actions` 视图中。
  - title: Ping hypervisor1
    shell: echo "hypervisor1 online"

  - title: Ping hypervisor2
    shell: echo "hypervisor2 online"

  - title: "{{ server.name }} 网络唤醒"
    shell: echo "向 {{ server.hostname }} 发送网络唤醒信号"
    entity: server

  - title: "{{ server.name }} 关机"
    shell: "echo '关闭服务器：{{ server.hostname }}'"
    entity: server

  - title: Ping 所有服务器
    shell: "echo 'Ping 所有服务器'"
    icon: ping

  - title: 启动 {{ container.Names }}
    icon: box
    shell: docker start {{ container.Names }}
    entity: container
    triggers: ["更新容器实体文件"]

  - title: 停止 {{ container.Names }}
    icon: box
    shell: docker stop {{ container.Names }}
    entity: container
    triggers: ["更新容器实体文件"]

  # 最后，可以从 Web UI 隐藏操作，适用于创建仅在启动或 cron 时执行的背景辅助程序，用于更新实体文件。

  # - title: 更新容器实体文件
  #   shell: 'docker ps -a --format json > /etc/OliveTin/entities/containers.json'
  #   hidden: true
  #   execOnStartup: true
  #   execOnCron: '*/1 * * * *'

# 实体（Entity）是存在的“事物”，如 VM 或容器。
# OliveTin 允许基于这些实体动态生成操作。
# 例如，如果想为 `server` 实体生成网络唤醒或关机操作，这将非常有用。
#
# 实体设计的一个非常流行的用例是 `container` 实体——可以类似地生成 `启动`、`停止`和`重启`容器的操作。
#
# 实体仅从磁盘上的文件加载，OliveTin 会在运行时监视这些文件的更新并更新实体。
#
# 实体可以在这些文件中定义属性，这些属性可以在配置中作为变量使用，例如 `container.status` 或 `vm.hostname`。
#
# 文档：https://docs.olivetin.app/entities/intro.html
entities:
  # YAML 文件是默认的预期格式，因此可以使用 .yml 或 .yaml，甚至 .txt，只要文件包含有效的 YAML 列表，即可正确加载。
  # 文档：https://docs.olivetin.app/entities/intro.html
  - file: entities/servers.yaml
    name: server

  - file: entities/containers.json
    name: container

# 仪表板（Dashboard）是一种将操作从默认的“操作”视图中取出，并将其组织成组（文件夹或字段集）的方式。
#
# 正确使用实体的唯一方法是在仪表板上使用 `fieldset`。
#
# 文档：https://docs.olivetin.app/dashboards/intro.html
dashboards:
  # 顶级项是仪表板。
  - title: 我的服务器
    contents:
      - title: 所有服务器
        type: fieldset
        contents:
          # 如果 `contents:` 属性为空，仪表板的内容将尝试查找具有匹配标题的操作。
          - title: Ping 所有服务器

          # 如果创建一个带有“contents:”的项，OliveTin 会将其显示为目录。
          - title: 虚拟机监控程序
            contents:
              - title: Ping hypervisor1
              - title: Ping hypervisor2

      # 如果指定 `type: fieldset` 和一些 `contents`，它将显示分组操作而不使用文件夹。
      - type: fieldset
        entity: server
        title: '服务器：{{ server.hostname }}'
        contents:
          # 默认情况下，OliveTin 会查找具有匹配标题的操作并将其放在仪表板上。
          #
          # 字段集还支持 `type: display`，可以显示任意文本，适用于显示容器状态等信息。
          - type: display
            title: |
              主机名：<strong>{{ server.name }}</strong>
              IP 地址：<strong>{{ server.ip }}</strong>

          # 这些是我们要在仪表板上显示的操作（上面定义）。
          - title: '{{ server.name }} 网络唤醒'
          - title: '{{ server.name }} 关机'

  # 这是第二个仪表板。
  - title: 我的容器
    contents:
      - title: '容器 {{ container.Names }} ({{ container.Image }})'
        entity: container
        type: fieldset
        contents:
          - type: display
            title: |
              {{ container.RunningFor }} <br /><br /><strong>{{ container.State }}</strong>

          - title: '启动 {{ container.Names }}'
          - title: '停止 {{ container.Names }}'

将 config.yaml 文件放置在 /config 目录中。

实际操作与功能演示

在浏览器中输入 http://NAS的IP:1337 即可访问 OliveTin 的 Web 界面。

默认的 config.yaml 配置文件已经预置了一些常用命令。

提示：预置命令可能不完全适合所有设备，后续需要根据实际需求进行修改。

例如，使用“Ping 互联网”命令检查网络连通性：

执行“检查磁盘空间”命令查看存储情况（示例中为虚拟机环境，空间较小）：

通过“重启 Docker 容器”命令管理容器（注意：容器名称需与实际环境一致）：

获取主题功能稍显复杂，简要流程如下：访问主题链接选择主题，点击查看仓库地址，下载完成后重启应用即可。

更换主题后的效果展示：

运行自定义脚本的示例（仅为演示）：

重要提示：OliveTin 需要用户自行配置 config.yaml 文件，无法直接使用预置配置。以下通过一个简单示例说明如何创建和运行脚本。

假设需求是将 source 文件夹备份到 backup 目录。

创建 backupScript.sh 备份脚本，并放置在指定目录中：

#!/bin/bash

# 源目录，需要备份的文件所在目录
SOURCE_DIR="/config/source"

# 目标目录，备份文件存放的目录
BACKUP_DIR="/config/backup"

# 使用日期创建备份子目录
TIMESTAMP=$(date +%Y%m%d%H%M%S)
BACKUP_PATH="$BACKUP_DIR/backup_$TIMESTAMP"

# 创建目标目录（如果不存在）
mkdir -p "$BACKUP_PATH"

# 执行备份操作，使用 cp 命令复制文件
cp -r "$SOURCE_DIR/." "$BACKUP_PATH"

# 检查备份是否成功
if [ $? -eq 0 ]; then
    echo "备份成功：$BACKUP_PATH"
else
    echo "备份失败"
fi

修改配置文件中执行的备份脚本路径：

重启容器并执行命令，可以看到操作成功的提示：

返回文件夹查看，确认备份已成功完成：

使用体验与总结评价

OliveTin 是一款极具扩展性的工具，功能上限很高，但需要用户具备一定的基础知识才能充分发挥其潜力。对于初学者，建议直接将 config.yaml 配置文件上传至 AI 辅助工具，通过提问和修改逐步学习配置方法。

综合推荐指数：⭐⭐⭐（扩展性极强）
使用体验评价：⭐⭐⭐（需要自行探索和配置）
部署难度评估：⭐⭐（过程相对简单）