thorpejosh/truenas-zfs-unlock

TrueNAS ZFS加密密钥自主管理与远程解锁工具

https://img.shields.io/github/license/thorpejosh/truenas-zfs-unlock](https://github.com/ThorpeJosh/truenas-zfs-unlock/blob/main/LICENSE) https://img.shields.io/github/v/release/thorpejosh/truenas-zfs-unlock](https://github.com/ThorpeJosh/truenas-zfs-unlock/releases) https://img.shields.io/docker/pulls/thorpejosh/truenas-zfs-unlock](https://hub.docker.com/r/thorpejosh/truenas-zfs-unlock) https://github.com/ThorpeJosh/truenas-zfs-unlock/actions/workflows/test.yml/badge.svg](https://github.com/ThorpeJosh/truenas-zfs-unlock/actions/workflows/test.yml) https://github.com/ThorpeJosh/truenas-zfs-unlock/actions/workflows/docker-publish.yml/badge.svg](https://github.com/ThorpeJosh/truenas-zfs-unlock/actions/workflows/docker-publish.yml) ![pre-commit.ci status]([***]

镜像概述和主要用途

本工具通过支持密钥异地存储、远程数据集解锁和自主控制解锁时机，让您完全掌控TrueNAS ZFS加密密钥。解决了TrueNAS默认将ZFS数据集加密密钥存储在启动盘的安全隐患，确保密钥不与加密驱动器物理共存，提升数据在运输、失窃等场景下的安全性。

核心功能和特性

• 密钥自主管理：避免密钥本地存储，支持外部安全存储
• 远程解锁：通过TrueNAS API远程解锁加密数据集
• 定时控制：支持基于 cron 表达式的定时解锁策略
• 多架构支持：兼容多种硬件架构，部署灵活
• 安全配置：支持通过Docker Secrets管理敏感密钥信息
• SSL/TLS选项：可配置跳过证书验证，适应自签名证书环境

使用场景和适用范围

• 物理安全增强：保护硬件驱动器在静止、运输、处置或失窃时的数据安全
• 远程管理：从异地设备（云服务器、树莓派、笔记本等）控制TrueNAS数据集解锁
• 自动化部署：配合TrueNAS启动流程，在VM或Kubernetes部署前自动解锁数据集
• 多环境兼容：适用于家庭实验室、企业存储系统等多种场景

镜像变体

支持的架构

!https://img.shields.io/badge/architecture-amd64-blue !https://img.shields.io/badge/architecture-arm64-blue !https://img.shields.io/badge/architecture-arm/v7-blue !https://img.shields.io/badge/architecture-arm/v6-blue !https://img.shields.io/badge/architecture-ppc64le-blue !https://img.shields.io/badge/architecture-s390x-blue !https://img.shields.io/badge/architecture-386-blue

共享标签

• latest：最新版本
• ${IMAGE_VERSION}：特定版本号（推荐生产环境使用）

注意：镜像采用https://semver.org/%E6%A0%BC%E5%BC%8F%E5%8F%91%E5%B8%83%E3%80%82TrueNAS%E5%9C%A825.04%E5%92%8C25.10%E7%89%88%E6%9C%AC%E9%97%B4%E5%AF%B9API%E8%BF%9B%E8%A1%8C%E4%BA%86%E9%87%8D%E5%A4%A7%E5%8F%98%E6%9B%B4%EF%BC%8C%E4%BD%BF%E7%94%A8%E5%89%8D%E8%AF%B7%E5%8F%82%E8%80%83%E5%8F%91%E5%B8%83%E8%AF%B4%E6%98%8E%E7%A1%AE%E4%BF%9D%E5%85%BC%E5%AE%B9%E6%80%A7%E3%80%82%E7%94%9F%E4%BA%A7%E7%8E%AF%E5%A2%83%E4%B8%AD%E5%BA%94%E9%81%BF%E5%85%8D%E4%BD%BF%E7%94%A8%60latest%60%E6%A0%87%E7%AD%BE%EF%BC%8C%E5%BB%BA%E8%AE%AE%E9%94%81%E5%AE%9A%E8%87%B3%E5%85%B7%E4%BD%93%E7%89%88%E6%9C%AC%E3%80%82

镜像仓库

该镜像同时发布于https://hub.docker.com/r/thorpejosh/truenas-zfs-unlock%E5%92%8Chttps://github.com/ThorpeJosh/ssh-agent-docker/pkgs/container/truenas-zfs-unlock%EF%BC%8C%E5%8F%AF%E9%80%9A%E8%BF%87%E4%BB%A5%E4%B8%8B%E5%91%BD%E4%BB%A4%E6%8B%89%E5%8F%96%EF%BC%9A

shell
docker pull docker.xuanyuan.run/thorpejosh/truenas-zfs-unlock:latest
docker pull ***-ghcr.xuanyuan.run/thorpejosh/truenas-zfs-unlock:latest

使用方法和配置说明

前置准备

1. 将ZFS数据集配置为"Passphrase"加密模式，手动设置密钥（避免TrueNAS存储密钥）
2. 在TrueNAS Web UI中生成API密钥（用于工具通过API发送解锁请求）

环境变量配置

从文件读取环境变量（Docker Secrets）

通过在环境变量名前添加FILE__前缀，可从文件中读取敏感配置。例如：

• 若密钥存储在/run/secrets/dataset_key文件中，可设置FILE__ZFS__pool__dataset=/run/secrets/dataset_key

按需运行（手动解锁）

通过覆盖容器入口命令为unlock，手动触发数据集解锁。

docker-compose配置

yaml
---
services:
  truenas_unlock:
    image: docker.xuanyuan.run/thorpejosh/truenas-zfs-unlock:latest
    environment:
      - TRUENAS_HOST=10.0.0.1:443
      - TRUENAS_API_KEY=1-5x23jkKKsy
      - SKIP_CERT_VERIFY=true
      - ZFS__tank__photos=SomeSecureKey
    command: unlock

docker run命令

shell
docker run --rm \
    -e TRUENAS_HOST=10.0.0.1:443 \
    -e TRUENAS_API_KEY=1-5x23jkKKsy \
    -e SKIP_CERT_VERIFY=true \
    -e ZFS__tank__photos=SomeSecureKey \
    docker.xuanyuan.run/thorpejosh/truenas-zfs-unlock:latest unlock

定时运行（自动解锁）

配置CRONTAB环境变量实现定时解锁（如每10秒检查一次，确保TrueNAS启动后自动解锁数据集）。

docker-compose配置

yaml
---
services:
  truenas_unlock:
    image: docker.xuanyuan.run/thorpejosh/truenas-zfs-unlock:latest
    environment:
      - TZ=America/Chicago
      - TRUENAS_HOST=10.0.0.1:443
      - TRUENAS_API_KEY=1-5x23jkKKsy
      - SKIP_CERT_VERIFY=true
      - ZFS__tank__home=someRandomGeneratedKey
      - ZFS__tank__photos=SomeSecureKey
      # supercronic支持vixie cron表达式：秒 分 时 日 月 周 年 命令
      - CRONTAB=*/10 * * * * * * unlock
    restart: unless-stopped

docker-compose使用Docker Secrets

yaml
---
secrets:
  TRUENAS_API_KEY:
    file: ${PWD}/.secrets/.api_key
  ZFS_HOME_KEY:
    file: ${PWD}/.secrets/.home_key
  ZFS_PHOTOS_KEY:
    file: ${PWD}/.secrets/.photos_key

services:
  truenas_unlock:
    image: thorpejosh/truenas-zfs-unlock:latest
    secrets:
      - TRUENAS_API_KEY
      - ZFS_HOME_KEY
      - ZFS_PHOTOS_KEY
    environment:
      - TZ=America/Chicago
      - TRUENAS_HOST=10.0.0.1:443
      - SKIP_CERT_VERIFY=true
      - FILE__TRUENAS_API_KEY=/run/secrets/TRUENAS_API_KEY
      - FILE__ZFS__tank__home=/run/secrets/ZFS_HOME_KEY
      - FILE__ZFS__tank__photos=/run/secrets/ZFS_PHOTOS_KEY
      # supercronic支持vixie cron表达式：秒 分 时 日 月 周 年 命令
      - CRONTAB=*/10 * * * * * * unlock
    restart: unless-stopped